m0n0x41d/haft v4.1.0

on GitHub

Added

• DRR Linking (FPF E.9): Decision records now create graph relations to hypotheses.

  • quint_decide accepts new rejected_ids parameter for rejected alternatives.
  • Creates selects relation: DRR → winner hypothesis.
  • Creates rejects relations: DRR → each rejected alternative.
  • Enables queries: "What alternatives were considered for this DRR?"

• Context Markdown Formatting: quint_record_context now normalizes input to proper markdown.

  • Vocabulary entries formatted as definition list (- **Term**: definition).
  • Invariants formatted as numbered list with line breaks.

• Audit Tree Shows MemberOf Relations: quint_audit_tree now displays memberOf groupings.

  • Decision context alternatives are shown under [members] section.
  • Member R scores displayed for comparison (no WLNK propagation per FPF spec).

• Improved Tool Descriptions: quint_propose parameters now have actionable descriptions.

  • depends_on: Explains WLNK impact and when to use.
  • decision_context: Explains grouping purpose and when to use.
  • q1-hypothesize.md: Added "Linking Checklist" before proposing hypotheses.

• Merged /q-audit into /q-query: Simplified command set.

  • /q-query now shows R_eff and dependency trees for found holons.
  • Removed standalone /q-audit utility (redundant with enhanced /q-query).
  • /q4-audit (FPF phase) remains unchanged.

• sqlc Integration: Type-safe database queries generated from SQL.

  • All database operations now use sqlc-generated code with proper type safety.
  • New db/store.go wrapper provides clean API while preserving schema bootstrap.
  • Added comprehensive test suite for database operations (db/store_test.go).

• GetHolon Query: Added query to fetch hypothesis metadata by ID (foundation for future Kind-CAL work).

• New MCP Tools for Trust Calculus (B.3):

  • quint_audit_tree: Visualize assurance tree with R scores, dependencies, and CL penalties.
  • quint_calculate_r: Compute R_eff with detailed breakdown (self score, weakest link, decay penalties).
  • quint_check_decay: Identify holons with expired evidence (epistemic debt detection).

• Parent ID Chain (FPF Enforcement):

  • Added parent_id foreign key to holons table for L0→L1→L2 progression tracking.
  • New queries: GetHolonsByParent, GetHolonLineage for traversing hypothesis chains.
  • CreateHolon now accepts parent_id parameter for linking hypothesis progression.
  • Enables auditable chain from L2 decision back to original L0 hypothesis.

• Derived Phase (FPF Enforcement):

  • Phase is now computed from holons.layer data instead of stored in state.json.
  • New DerivePhase() method computes phase from database state.
  • New GetPhase() returns derived phase when DB available, falls back to State.Phase.
  • Prevents AI bypass of FPF phase controls via direct file manipulation.

• Audit Logging (FPF Enforcement):

  • New audit_log table tracks all MCP tool invocations.
  • Captures: tool name, operation, actor, target ID, input hash, result, and details.
  • Instrumented tools: quint_propose, quint_verify, quint_decide, quint_move.
  • Enables detection of FPF bypasses through audit trail analysis.
  • Context-aware logging supports multi-session isolation.

• Self-Healing Signed Projections (FPF Enforcement):

  • All hypothesis/evidence/DRR files now include content_hash in YAML frontmatter.
  • New WriteWithHash() function adds cryptographic hash (SHA-256 truncated) on write.
  • New ValidateFile() detects tampering by comparing stored vs computed hash.
  • New ReadWithValidation() on Tools automatically detects and logs tampering.
  • When tampering detected: regenerates file from DB (DB is source of truth).
  • Tampering events logged to audit_log for violation tracking.

• DRR Holon Tracking:

  • FinalizeDecision now creates DRR holon in database (enables derived phase detection).
  • DRR holons linked to winner hypothesis via parent_id.

• Tool Preconditions (FPF Enforcement):

  • All MCP tools now validate preconditions before execution.
  • quint_propose: Validates title, content, and kind fields.
  • quint_verify: Confirms hypothesis exists in L0, validates verdict.
  • quint_test: Ensures hypothesis is in L1 (not L0), validates verdict.
  • quint_audit: Confirms hypothesis is in L2 before audit.
  • quint_decide: Requires L2 hypotheses exist, validates winner_id and title.
  • quint_calculate_r / quint_audit_tree: Validates holon existence in DB.
  • Precondition failures logged to audit_log with BLOCKED status.
  • Each error includes actionable suggestion for the user.

• Command Contracts (FPF Enforcement):

  • All FPF command prompts (q0-q5) now include formal enforcement contracts.
  • YAML frontmatter with pre, post, invariant, and required_tools fields.
  • RFC 2119 bindings (MUST, MUST NOT, SHALL) for mandatory behaviors.
  • "Invalid Behaviors" section explicitly lists protocol violations.
  • "Checkpoint" section with verification checklist before phase transition.
  • Success/failure path examples with few-shot learning.
  • "State machine executor" mechanical persona to reduce AI improvisation.
  • Defense in depth: soft gate (prompts) + hard gate (preconditions).

• Inline Schema Migrations:

  • Existing databases automatically upgraded on startup.
  • Adds parent_id and cached_r_score columns to existing holons table.
  • Safe to run multiple times (idempotent).

• Holon Linking in quint_propose:

  • New depends_on parameter to declare dependencies on other holons.
  • New decision_context parameter to group alternatives under a decision.
  • New dependency_cl parameter (1-3) for congruence level of dependencies.
  • Creates ComponentOf relations for system holons, ConstituentOf for episteme.
  • Creates MemberOf relations for decision grouping (no R propagation).
  • Added SQL indexes for efficient WLNK traversal.
  • Documented structural relations (B.1.1) in CLAUDE.md.

• Evidence Freshness Management (FPF B.3.4):

  • New waivers table for tracking temporary risk acceptance with full audit trail.
  • quint_check_decay now supports three modes:
    • Report mode (default): Shows freshness report with STALE/FRESH/WAIVED holons.
    • Deprecate mode: Downgrades hypothesis (L2→L1 or L1→L0) when evidence is terminally stale.
    • Waive mode: Records explicit risk acceptance with rationale and expiration date.
  • quint_test now accepts L2 hypotheses for evidence refresh (L2 + PASS stays L2 with fresh evidence).
  • Freshness report now shows individual evidence IDs (not just counts) for actionable output.
  • Implements WLNK principle: one expired evidence item = entire holon is STALE.
  • Natural language support: users can say "waive the benchmark until February" and the agent handles ID resolution.
  • New documentation: docs/evidence-freshness.md — practical guide to managing stale evidence.
  • Updated command documentation: q-decay.md and q3-validate.md.

• CI/CD Pipeline:

  • New GitHub Actions workflow (.github/workflows/ci.yml) for pull requests.
  • Triggers on PRs and pushes to main and dev branches.
  • Runs tests with race detector and coverage reporting.
  • Runs golangci-lint for code quality (errcheck, govet, staticcheck, unused, misspell).
  • Uses golangci-lint-action@v7 with golangci-lint v2 config schema.
  • Added .golangci.yml configuration for consistent linting.

• Pre-commit Hooks:

  • Added .pre-commit-config.yaml for use with pre-commit tool.
  • Added .githooks/pre-commit for simple git-native hooks (no dependencies).
  • Hooks include: gofmt, goimports, go build, go test, golangci-lint.
  • Setup via ./scripts/setup-hooks.sh or ./scripts/setup-hooks.sh --precommit.
  • Also checks: trailing whitespace, end-of-file, yaml syntax, large files, merge conflicts, private keys.

Changed

• Updated FPF Commands: Commands now leverage new MCP tools for computed data:

  • /q4-audit: Now calls quint_calculate_r and quint_audit_tree before recording findings.
  • /q5-decide: Now uses quint_calculate_r for final R_eff comparison before decision.
  • /q-audit: Updated to use visualization tools.
  • /q-decay: Updated to use quint_check_decay for proactive decay detection.
  • /q-status: Now proactively checks for expired evidence.

• SQLite Driver Migration: Replaced CGO-based mattn/go-sqlite3 with pure Go modernc.org/sqlite.

  • Enables CGO_ENABLED=0 builds for simplified cross-compilation.
  • Cross-compilation now works for linux/amd64, linux/arm64, darwin/*, windows/amd64.
  • Unblocks single-runner GoReleaser builds.
  • No functional changes to database behavior.

• FSM Phase Derivation: CanTransition() now uses GetPhase() (derived from DB) instead of State.Phase.

  • Phase transitions are validated against actual database state.
  • Hardens FPF enforcement against state.json manipulation.

Fixed

• Evidence Decay Bug: Evidence was stored with NULL valid_until, making /q-decay always report "no expired evidence."

  • ManageEvidence now sets a default 90-day validity period when validUntil is empty.
  • Affects all evidence added via quint_verify, quint_test, and quint_audit.

• Go Module Import Paths: Standardized import paths to use the correct module name across all packages. (PR #16, @blib)