haft

haft v7

haft v7 reorders the priorities. In v5 and v6 the artifacts were decisions; specs were a "later" concern. In v7 specs come first. Decisions, work commissions, runtime runs, and evidence are downstream consequences of an explicit, parseable specification — they do not invent meaning by themselves.

The product line is also clearer. v7 ships one Haft Core (the semantic authority for the project) under two production surfaces that speak the same typed contract:

  • MCP Plugin — the embedded host-agent surface for Claude Code and Codex. Same typed tools (haft_problem, haft_decision, haft_commission, haft_spec_section, haft_query, haft_refresh, haft_solution, haft_note).
  • CLI Harness — the operator/runtime surface for init, spec checks, decisions, commissions, and harness execution. CI-friendly.

A Tauri-based desktop app exists as an alpha track outside the v7 production envelope. It is not extensively tested and is not the canonical operator surface; the v7 production surfaces are MCP and CLI.

Surfaces dispatch typed actions to Core. They do not invent semantics. If Claude Code wants to know what's actionable, it asks Core; if CI wants the gate, it runs the same Core helpers.

The shift in priority

A repository becomes "harnessable" only after it carries a parseable ProjectSpecificationSet — TargetSystemSpec, EnablingSystemSpec, TermMap. The CLI knows the difference between ready, needs_init, needs_onboard, and missing. The harness refuses to run broad work on a project that is not ready, except behind an explicit --force-skip-specs "<reason>".

Specs in v7 are not BDD wishlists. They are SoTA system-engineering artifacts: every load-bearing claim carries a statement_type, a claim_layer, a valid_until, and (where the section calls for it) named boundary perspectives or guard locations. FPF and slideument patterns shape the agent's reasoning when drafting; they never appear inside the YAML carrier.

The onboarding loop

repository
  → .haft initialized
  → TargetSystemSpec
  → EnablingSystemSpec
  → TermMap
  → SpecCoverage gaps
  → DecisionRecords (one per coherent architectural choice)
  → WorkCommissions (bounded execution authority)
  → Harness runtime executes commissioned work
  → Evidence flows back; SpecCoverage advances

Haft Core ships a typed SpecOnboardingMethod that walks an operator (with help from the host agent) through the target-system spine first, then the enabling-system spine. Each phase declares which YAML fields the resulting section must carry and which structural Checks it must pass. The host agent applies FPF patterns named in the phase's context_for_agent; the carrier carries the resolved claim, not the citation.

See Spec onboarding for the flow in detail.

Drift and staleness

Hand-edited .haft/specs/*.md stay primary — operators write specs in their editor of choice. Haft mirrors a SHA-256 baseline of every approved SpecSection in SQLite. Carrier edits surface as spec_section_drifted; valid_until expiry surfaces as spec_section_stale. The operator triages: rebaseline (intentional evolution), reopen (needs review), or rollback the carrier edit.

haft check rolls drift, staleness, decision drift, evidence decay, and coverage gaps into a single CI exit code. haft_query(action="check") is the plugin-mode parity for the same JSON shape.

See Enforcement check.

What's new since v6

  • SpecOnboardingMethod with target + enabling spines (10 phases)
  • SpecSectionBaseline + drift + staleness as first-class enforcement
  • WorkCommission as bounded execution authority distinct from DecisionRecord and RuntimeRun
  • ImplementationPlan DAG with dependency and lockset enforcement
  • AutonomyEnvelope core for explicit autonomy bounds
  • ProjectionPolicy and projection debt — local execution evidence is independent of external tracker publishing
  • Open-Sleigh as the first runtime implementation; pre-mutation scope guards
  • Three-surface model documented and contract-tested

Migration from v6: existing .haft/ artifacts (decisions, problems, notes) are forward-compatible. Add .haft/specs/*.md via haft init on a fresh checkout, then drive /h-onboard through the typed flow.

Supported host agents

v7 product support targets Claude Code and Codex as embedded host-agent surfaces. Cursor, Gemini CLI, OpenCode (sst/opencode), JetBrains Air, and other generic MCP clients remain protocol-compatible carriers; their tooling may not match every contract this guide describes.

Where to next

  • Install & init — get a v7 project to ready.
  • Spec onboarding — the typed flow from needs_onboard to verified coverage.
  • Enforcement check — haft check, haft_query(action="check"), and CI exit codes.
  • Batch harness (Beta) — haft harness run --drain --concurrency N, per-commission delivery policy, and discrete revertable apply commits.