haft

FPF project memory and governance for AI-assisted engineering.

Haft is a local governance layer for AI coding agents. It gives your agent a durable project memory: what problem is being solved, which options were compared, which decisions the human made, what evidence supports them, and what has gone stale. Small, reversible reasoning can stay in conversation; results that later work must rely on become typed project records.

Haft is built on the First Principles Framework (FPF) by Anatoly Levenchuk. FPF is a rigorous architecture for thinking about systems, and it is not small. Haft is the practical handle: it brings the versioned FPF source into your agent’s working context and adds the project-local skills, MCP gates, and memory needed to use it in engineering work.

---

Install

curl -fsSL https://raw.githubusercontent.com/m0n0x41d/haft/main/install.sh | bash

This installs the current haft release. The separate experimental haft10 alpha for macOS arm64 has its own archive and setup path; see Haft10 alpha. The alpha does not replace this installer.

For a project that has not used Haft before, initialize it once. Bare haft init opens an interactive multi-select when stdin and stdout are terminals; no host is preselected. Scripts and CI must name their intent explicitly:

haft init                    # Interactive host multi-select (TTY only)
haft init --core-only        # Project core/ledger, no host carriers
haft init --claude           # Claude MCP + skills + CLAUDE.md section
haft init --claude --local   # Claude integration with repo-local skills
haft init --codex            # Codex MCP + skills + AGENTS.md section
haft init --codex --local    # Codex integration with repo-local skills
haft init --codex --mcp-only # Compatibility: Codex MCP config only
haft init --agents           # Global .agents/skills only
haft init --agents --local   # Repo-local .agents/skills only
haft init --codex --agents   # Codex integration; shared skill target coalesces
haft init --grok             # Grok CLI project MCP + skills
haft init --hermes           # Hermes MCP + external skills directory
haft init --zed              # Zed global MCP context server
haft init --agy              # Google Antigravity MCP + shared skills
haft init --all              # Full Claude + Codex integrations
haft init --all --mcp-only   # Claude + Codex MCP configs only

Any explicit init flag skips the menu and executes its declared behavior. Bare non-interactive invocation fails before writing files instead of guessing a host or waiting for terminal input. --mcp-only is a compatibility modifier: it requires an explicit host flag or --all and suppresses that host’s skills and managed instruction section.

Codex publishes its transformed skills to ~/.agents/skills, or project .agents/skills with --local, as part of the full Codex integration. --agents addresses the same location as an independent skills-only target without MCP or instruction publication. It may compose with host flags; with --codex, the identical .agents/skills projection is coalesced into one write rather than treated as two competing targets. --all means exactly the full Claude and Codex integrations; it does not add a second independent --agents target.

For an already initialized project, install the new binary and fully restart or reconnect the coding-agent host. A new haft serve process automatically applies only migration boundaries that the release explicitly marks as startup-safe. The current chain covers 57 -> 58 and 58 -> 59; Haft first publishes a verified 0600 SQLite snapshot beside the project ledger at each boundary it crosses. A current database is a no-op. Re-running haft init is not routine database maintenance.

If startup reports a manual migration boundary, use the exact fallback command from that diagnostic:

haft project migrate --project-root /absolute/project/root --project-id qnt_........

It verifies the exact project binding, shares the same migration lease as haft serve and haft init, and changes no agent-host config, skill, instruction, hook, or package carrier. Future-schema, missing-binding, integrity, and stale WAL/SHM diagnostics have different recovery paths; do not replace them with a generic migration run.

Claude Code and Codex are the stable supported hosts. Grok, Pi, Hermes, Zed, Antigravity, Cursor, Gemini CLI, and OpenCode remain experimental or legacy adapters with additional config flags (--grok, --pi, --hermes, --zed, --agy, --cursor, --gemini, --opencode). Please report host-specific issues with a PR or issue.

Grok: use haft init --grok (optionally --local). Native project .grok/config.toml takes precedence over Claude/Cursor compat MCP sources, so a stale global haft entry in ~/.claude.json no longer shadows the project server. Reload MCP in Grok (/mcps → r) or start a new session after init.

Cursor: after init, open Settings -> MCP -> find haft -> enable the toggle. Cursor adds MCP servers disabled by default.

What init does per tool

The binary is the same; host adapters differ in MCP config, transformed skill location, and instruction carrier. Re-init replaces recognized legacy Haft skills and updates only the content between <!-- haft:start --> and <!-- haft:end --> in project instruction files. Content outside those markers remains project-owned. A foreign file colliding with a desired Haft-owned skill path fails before writes instead of being overwritten.

Tool	MCP config	Skills	Project instructions
Claude Code (stable)	.mcp.json	~/.claude/skills/ or .claude/skills/ with --local	managed section in CLAUDE.md
Codex CLI / App (stable)	.codex/config.toml	~/.agents/skills/ or .agents/skills/ with --local	managed section in AGENTS.md
Agent skill bundle (--agents)	n/a	~/.agents/skills/ or .agents/skills/ with --local	none
Grok CLI (experimental)	.grok/config.toml (mcp_servers.haft)	~/.grok/skills/ or .grok/skills/ with --local	host adapter
Hermes (experimental)	~/.hermes/config.yaml (or $HERMES_HOME/config.yaml; profile via --profile)	generated Hermes-adapted skills through skills.external_dirs	host adapter
Zed (experimental)	~/.config/zed/settings.json (context_servers.Haft)	n/a	none
Antigravity (experimental)	~/.gemini/config/mcp_config.json (mcpServers.haft)	~/.gemini/skills/ or .gemini/skills/ with --local	host adapter

Project-scoped configs (.mcp.json, .codex/config.toml, .grok/config.toml) use portable project-root paths, so they are safe to commit for shared repositories. Zed and Antigravity settings are global and may start MCP/context servers outside the workspace cwd. haft init --zed writes HAFT_PROJECT_ROOT and HAFT_EXPECTED_PROJECT_ID for the project where you ran init. haft init --agy writes serve --project-root <root> --expected-project-id <id> args so the Antigravity entry does not depend on cwd or env propagation. Re-run the host-specific init command in another project to point the global host entry there.

Local footprint

Haft is local-first, but it is not a zero-footprint prompt pack. haft init creates markdown carriers in .haft/ and a project SQLite database under ~/.haft/projects/<id>/. Those databases are where Haft keeps the structured artifact graph, baselines, indexes, and runtime state that agents query through CLI/MCP.

The Rust haft-embed sidecar is retained as an optional compatibility component for older semantic-recall paths; core v9 governance does not depend on it. If one of those paths uses it, Haft may start a shared local EmbeddingGemma process and cache models under ~/.haft/; a warm sidecar can reasonably take around 1-2 GB of RAM depending on platform, model, and workload. If the sidecar is absent or disabled, the compatibility path falls back to keyword/graph recall. Set embedding.provider: none in ~/.haft/config.yaml to keep that path off.

v9 no longer ships Elixir, OTP, BEAM, or the Open-Sleigh runtime. During a successful upgrade the installer removes only the exact legacy managed path ~/.haft/runtimes/open-sleigh/current. It preserves user-owned ~/.open-sleigh/ data and the independent haft-embed runtime.

---

How to Start

FPF is powerful and genuinely complex. You do not need to learn it all before Haft becomes useful.

Install Haft, run haft init for your agent, and keep working normally. When a concern benefits from FPF, the agent can retrieve the relevant source and use the smallest applicable method. Call /h-reason when you want a deliberate source-supported reasoning pass.

The narrower skills are independent application surfaces, not stages in a mandatory workflow:

• /h-frame — clarify the real problem and acceptance criteria
• /h-explore — generate genuinely different solution variants
• /h-compare — compare options under explicit parity rules
• /h-decide — route a direct operator request for a binding decision
• /h-verify — check whether a past decision still holds
• /h-status — read the compact project cockpit

Haft makes actual gates explicit: when a human decision is needed, when evidence has gone stale, when spec drift needs review, and when execution needs an authorized plan or commission. It does not infer a universal next step from the order of skills or artifacts.

Existing codebase that has never been initialized with Haft? Run haft init --core-only. A complete, non-truncated, supported singleton detector result is admitted as origin=detector_default; Haft then installs only the specification and MethodPack carriers applicable to that scope. Mixed, multiple-scope, insufficient, truncated, or manually reviewed bases remain profile-review work, and init never changes an existing canonical profile. A later direct, unambiguous operator request may supersede only a current detector_default profile; onboarding status reports profile_override_eligible, and successful application appends a host_routed_operator_request admission. TargetSystemSpec is Required for every declared realization scope; an optional entity_reference strengthens exact EntityOfConcern memory and traceability but does not gate specification applicability or lifecycle. The bounded profile_change_prepare route remains available only when changing that relation is itself current, and is never a prerequisite for spec work. Onboarding ready covers only the canonical profile and structured project memory; it is not a spec-applicability, health, lifecycle, or release-readiness verdict.

Check spec carriers locally:

haft spec status
haft spec status --json
haft spec check
haft spec check --json
haft spec migrate
haft spec migrate --json # read-only state for agents and automation

haft spec status keeps two read-only results explicit: workflow.state reports the next onboarding lifecycle action, while health reports current structural, baseline, drift, and staleness findings. A terminal workflow state such as ready therefore does not erase health findings and is not a release readiness claim; use haft spec check --json for the full health report.

SoftwareSystemSpec describes the software that realizes the target system: its role, responsibility allocation, behavior, interfaces, constraints, and selected structure. Agent, commission, external-runner, and delivery policies are deliberately outside this spec. Development-version enabling-system.md carriers are migrated with one state-driven haft spec migrate command. Haft resolves the internal exact candidate itself, records semantic review on one invocation, performs the already reviewed migration on a later invocation, and continues a sealed recovery journal when needed. Humans never pass packet paths, hashes, refs, targets, or recovery modes.

haft spec check is deterministic L0/L1/L1.5 only: it parses fenced yaml spec-section blocks, checks required structural fields, validates known carrier shapes, and confirms the term-map carrier parses. It makes no L2 semantic judgment, no LLM review, and no L3 runtime claim.

---

What is Haft?

Haft sits between the human principal, the coding agent, and the repository. It brings the versioned FPF source into the agent’s working context, keeps project reasoning connected to the code it governs, and makes durable records only when later work needs to rely on them.

Haft is not a coding agent or an AI documentation generator. It is the handle that keeps problems, options, human decisions, specifications, work authority, and evidence connected as the project changes.

What Makes It Different

• Source-native FPF delivery — agents can retrieve the versioned FPF source with provenance instead of relying on a Haft-owned substitute catalog.
• Reliance-bearing memory — ordinary local reasoning may stay in chat; records enter the project graph for handoff, replay, authority, automation, evidence, or another explicit downstream reliance.
• Kernel gates, not prompt-only discipline — skills carry the procedure; the MCP kernel validates required fields, parity gaps, missing evidence, and authority boundaries server-side.
• Reasoning fused with code — haft_query can show the decisions and invariants governing a file or symbol while the agent reads or changes it.
• Evidence decays — old proof is not treated as forever current; Haft surfaces stale claims and drift for review.
• Human authority stays explicit — agents can frame, compare, verify, and prepare records, but binding decisions and commissions require the human principal.
• Agent guidance is built in — status, method cards, spec checks, and structured errors tell the agent what is missing.

Three surfaces, one artifact graph

Haft is consumed through three surfaces over one .haft/ artifact graph:

• Skills in your agent. Capability skills may trigger from the current operator request; h-decide may route a direct unambiguous binding request, while h-commission still requires manual invocation.
• CLI (haft artifact, haft decision, haft spec, haft memory, haft commission, …) — direct manual access to the current command families.
• MCP server (haft serve) — programmatic access for any LLM agent over the Model Context Protocol

The kernel MCP server is the cross-host enforcement surface: it validates arguments server-side and returns structured errors for FPF violations (missing required fields, parity gaps, weakest-link omissions, predictions without verify_after, and so on).

Skills carry the procedure; the kernel carries the gates. The same graph also gives agents retrieval over project-local reasoning: notes for small facts, decision records for authority, problem cards for open work, spec sections for target/software-system shape, MethodRuns for execution discipline, and evidence for verification.

FPF source and project-local application

The FPF source defines the available concepts and methods. Haft pins and indexes that source, carries it into the host agent, and supplies project-local records and gates where later work needs them. Retrieval is not application, evidence, approval, or performed work.

FPF is relation-first: the order of text, graph edges, cards, skills, or a demonstrative walkthrough does not by itself prescribe causal, temporal, method, or performed-work order. Such order exists only when an explicit, separately governed causal claim, U.MethodDescription, WorkPlan, or work relation states it. This does not make FPF acausal. Causal reasoning remains available, but causality must be carried as a claim rather than inferred from layout.

Planning remains a separate current task. A U.WorkPlan may state dependencies and execution order whenever planning is the concern; an FPF source lookup, application record, or reasoning capability does not prescribe that order. A WorkCommission carries bounded execution authority and must not stand in for the plan. Decision binding requires a direct unambiguous operator request; execution-authority grants through h-commission remain manual-only.

haft fpf query|lookup|inspect and haft_query(action="fpf", mode="concern|lookup|inspect", ...) expose the versioned source as addressable publication units. Concern retrieval reports observable authored-phrase, heading/keyword, and role-local FTS grounds; lookup tries exact identity before returning compact candidates; inspect is exact-only. Source roles (practical_use_card, toc_row, preface, pattern_body, pattern_section, pattern_scope) control progressive disclosure. Candidates are not selected patterns, and their order is not a causal or work order.

Maintaining the pinned FPF publication

Start with task fpf-refresh-check. It fetches and resolves one exact upstream candidate, builds private temporary artifacts, and writes .context/fpf-refresh/latest-report.json without changing the checked-out source, embedded database, integration lock, typed-memory candidate, or specs. The report has one closed result:

Result	Meaning	Next action
no_change	Candidate and current publication are the same.	Nothing to apply.
apply_ready	The technical compatibility checks admit the candidate.	Run task fpf-refresh.
review_ready	A complete candidate built and verified, while parser, semantic, Query-behavior, token-budget, or expectation findings need later review.	task fpf-refresh prints a prominent warning, applies the fresh source baseline, and retains every finding for downstream review.
candidate_rejected	The required source publication is missing, its structure is unsupported, or no deterministic and internally coherent source/index publication could be built and verified.	Adapt the source parser/compiler or repair the integrity failure, then check again.

task fpf-refresh repeats the check, pins the resolved candidate SHA, and recoverably applies the coherent source, database, and generated integration-lock publication for both apply_ready and review_ready. review_ready is an auditable semantic-delta classification, not a veto on adopting fresh FPF as Haft’s source baseline. Query/token fixture drift is also review_ready: the command prints a large FPF REFRESH REVIEW WARNING, keeps the exact diagnostics and reproduction commands in the report, and continues the recoverable apply. Exact PatternID/query-smoke drift, token fixtures, and semantic compatibility gaps belong here when the generic source-query runtime and derived publication are still coherent. A new recognizable result-label family is indexed with its exact raw source, flagged as degraded parser review, and does not veto refresh. Such findings may block release or query-quality claims, but they do not leave Haft on stale FPF source. Applying the candidate records no semantic approval and grants no release authority. A hard rejection is reserved for the absence of a complete structurally supported candidate — for example a missing required publication, source structure too incomplete to derive the required roles/categories, a derived source-unit projection below 50% of the preceding verified count, failed derivation, or failed source/DB/lock integrity verification. The apply also rebases only the repo-owned Local-Practice compiled memory basis and FPF-Spec.md source pins, then proves that the carrier parses, compiles, seals, verifies, and links against the fresh basis. task fpf-refresh finishes with the exact read-only integration verification. After a low-level recovery, run task fpf-verify. If an apply is interrupted, keep the receipt unchanged and use task fpf-refresh-resume to continue or task fpf-refresh-restore to restore its exact predecessor; never delete or hand-edit the receipt.

Generated hashes, counts, and compatibility results remain distinct from human-reviewed semantic and changelog claims. None of these commands commits, binds a decision, changes a SpecSection lifecycle, changes the active project-memory model, installs or restarts Haft, runs P13/P14, pushes, tags, or releases.

Fused code and reasoning graph

Explore accepts exactly one input shape: an exact symbol, or a bounded concern query. The concern route returns advisory candidates and never selects a code identity from rank alone.

haft graph explore --symbol PublishIndexEpoch --view working --json
haft graph explore --query "where is the index epoch published?" --view working --json

The equivalent MCP calls are haft_query(action="explore", symbol="PublishIndexEpoch") and haft_query(action="explore", query="where is the index epoch published?"). Both surfaces execute one canonical ExploreEnvelope and use the same JSON encoder. working is bounded, score-free, and omits retrieval and per-edge provenance. trace adds bounded provenance plus an opaque replay basis; diagnostic adds retrieval and traversal internals. A replay after the index, request, or canonical result changes returns replay_mismatch.

Use Explore when area or flow orientation is current. Before a non-mechanical edit to governed code, use code_context or impact on the actual target. Purely mechanical work may abstain explicitly. Code-graph orientation and typed-memory orientation are separate; neither substitutes for the other.

Code-graph indexing is automatic and shared by concurrent haft serve processes for the same project. Several host tasks can remain open: one server publishes a changed source epoch while followers stay responsive and recheck the completed result. A request that cannot establish freshness within its bounded wait reports the retained complete epoch as degraded, or reports the index unavailable when no complete epoch exists. Distinct projects continue indexing independently; no single-server setup or manual cleanup is required.

What changed in v8 and v9

v8 dropped the standalone interactive agent (haft agent), its coding-agent TUI, and the desktop wrappers. v9 completes that boundary by removing the built-in haft run and haft harness executors and the bundled Open-Sleigh BEAM runtime. haft board, the governance CLI, MCP server, and skills remain. Haft records runner-neutral WorkCommissions; execution belongs to the host agent or another separately operated runner.

Upgrading from the published v8.1.0 release, or still migrating a v7 project? See MIGRATION-v8.md for backup, forward-upgrade, host restart, and rollback boundaries.

How It Works

Twelve MCP tools

Tool	What it does
haft_note	Non-binding facts, observations, caveats, and rationale with typed anchors, validation, and optional freshness
haft_problem	Frame problems, declare comparison dimensions with indicator roles
haft_solution	Explore variants with diversity check, compare under parity
haft_decision	Decision contracts: invariants, claims, evidence, baseline lifecycle
haft_refresh	Lifecycle management for every artifact kind
haft_query	Project search/status, code graph, source-native FPF query/lookup/inspect, and typed-memory resolve/neighborhood/recall
haft_method	Task-local SWE MethodRun cards: pull gates before non-trivial work, close with evidence or waivers
haft_commission	Runner-neutral WorkCommission authority and lifecycle records
haft_spec_section	Typed SpecSection lifecycle projection over project SQL editions; FPF source compatibility is assessed separately; manual CLI gates approve, rebaseline, or reopen baselines
haft_onboard	Read setup status, prepare a non-binding initial profile review, or prepare an explicitly requested predecessor-pinned scope relation change; a missing relation never gates TargetSystemSpec lifecycle; haft init automatically admits only a complete supported singleton as origin=detector_default and installs default project memory
haft_entity	Proactively establish one minimum non-binding EntityOfConcern when current Work supplies a concrete operator-named or agent-inferred durable receiving use; known absence alone is insufficient
haft_memory	Expert raw MemoryChangeSet validation/admission through a nested request envelope; ordinary agents use haft_entity, and validation never admits automatically

The v9 public identity-change contract is alias-only: admit_alias adds a context-bound alias and supersede_alias replaces one while retaining provenance. Entity merge and split are not v9 MemoryChange variants; their reviewed reconciliation contract is deferred to v9.1. Exact-ID and alias collisions return explicit candidates—retrieval rank or similarity never selects or merges an identity.

Twelve skills installed by haft init

Haft installs 12 skills with independent trigger conditions:

Skill	Mode	What it does
h-reason	auto (umbrella)	Minimum FPF distillate and source-query entry point. It helps choose one current capability without imposing a project sequence.
h-frame	auto	Shape the current problem conversationally; persist a ProblemCard only on explicit save intent or a named durable receiving use.
h-diagnose	auto	Diagnose a failure with parallel hypothesis testing (one Agent subagent per hypothesis to prevent anchoring)
h-explore	auto	Generate genuinely distinct candidate variants when exploration is the current task; record only when durability is warranted.
h-compare	auto	Compare an existing candidate set under declared parity and return a Pareto front, not a scalar winner.
h-decide	auto router	Bind a DecisionRecord only from a direct, unambiguous operator request; the skill token is not a receipt.
h-verify	auto	Baseline → measure → evidence loop with drift detection
h-status	auto	Read-only project FPF cockpit with explicit drill-down calls
h-onboard	auto	Bootstrap Haft and typed spec carriers when project state is absent or incomplete.
h-spec	auto	Spec lifecycle and source-currentness repair: inspect readiness, draft/clarify carriers, repair FPF semantic fanout, and route approve/rebaseline/reopen gates
h-note	auto	Persist an explicitly requested non-binding fact, observation, caveat, or rationale in project memory.
h-commission	manual	WorkCommission lifecycle — manual per Transformer Mandate (disable-model-invocation)

Auto-triggering skills fire when their description matches operator context. h-decide is a host-side router: a manual invocation remains a compatible shortcut, but invocation itself creates no communicative act and adds no authority. h-commission remains manual-only because it grants bounded execution authority. Boundary unpacking, abductive checks, and semantic fanout review are internal routines, not extra public stages.

For a DecisionRecord, one direct, unambiguous operator request must identify the effect, readable subject, selected option, and scope. The host then runs the CLI/input-file effect sink without another confirmation and records host_routed_operator_request; it does not claim independent proof of U.SpeechAct. If anything is ambiguous, the agent presents one Human Gate Brief and accepts the natural-language answer. Bare yes or да works only for one current brief with one unambiguous effect and selection. Quotations, pasted text, agent recommendations, hypotheticals, and tool output do not bind.

MCP haft_decision(action="decide", ...) remains fail-closed with operator_confirmation_required until a verifiable host receipt exists. Project-profile application, incompatible project-memory model selection, and rollback use the same direct-request rule through their own effect sinks. Compatible bundled ProjectTypeEnv successors are different: haft init and the mutation-capable TypeEnv reconciliation path activate them automatically under compatible_successor_policy, after transaction-current compatibility, assertion, profile, runtime, graph, and head checks. No prompt, review carrier, or host-routed operator request is created. A stale, incompatible, incomplete, or underdetermined successor leaves the head unchanged with an exact diagnostic. The activation audit path is equally disjoint: current activation deltas and typed-memory graph events record compatible_successor_policy for that automatic branch and host_routed_operator_request for an explicit branch. Legacy manual_type_env_activation rows remain readable history and are never emitted by the v9 writer. The automatic singleton profile bootstrap is another separate system policy and stays detector_default.

Project-local .haft/config.yaml is no longer an authority-policy carrier. Fresh haft init does not create it. Init removes only the exact historical Haft-generated authority-only file after digest revalidation; changed or unrecognized bytes are preserved, ignored, and reported as legacy. Global ~/.haft/config.yaml and project .haft/project.yaml are unchanged.

Evidence workflow

Attach evidence with haft_decision(action="evidence", ...). Evidence carries formality levels (F0–F9), congruence levels (CL0–CL3), and expiry dates. Trust scores (R_eff) degrade as evidence ages; stale evidence triggers refresh. Use haft_decision(action="measure", ...) for post-implementation verification.

Each EvidenceRecord is also published as its own .haft/evidence/<evidence-id>.md carrier. SQLite is the local query projection; the Markdown carrier is the version-controlled collaboration surface. An evidence attachment changes its own carrier and does not rewrite the parent carrier solely to add evidence.

After pulling another engineer’s changes, run haft sync. Haft imports each evidence carrier only after its exact parent exists, preserves its identity and evidence metadata, and never reconstructs an absent WorkCommission or MethodRun from evidence. A carrier write that fails after the SQLite row commits is reported as evidence carrier projection debt by haft check; a later haft sync imports valid pulled carriers before retrying any remaining publication debt. If an existing carrier conflicts with the exact pending SQLite projection, sync preserves both sides and requires explicit reconciliation.

External runners and WorkCommission lifecycle

Haft v9 deliberately has no built-in coding-agent executor. It does not spawn an agent, create an isolated worktree, apply a patch, merge, push, or publish. The host agent can perform already-authorized work directly, and a future integration can consume the same runner-neutral lifecycle without becoming part of Haft Core.

h-commission remains manual-only because creating a WorkCommission grants bounded execution authority. The CLI can create and inspect that record:

haft commission create-from-decision dec-20260414-001
haft commission list-runnable
haft commission show wc-...
haft commission claim wc-... --runner external:my-runner
haft commission complete-external wc-... --runner external:my-runner \
  --verdict pass --payload-file evidence.json

An external runner uses the typed haft_commission lifecycle operations to claim a commission, record preflight/start/events, and submit its terminal result. complete-external is the operator shortcut when the work was already performed elsewhere. Recording a lifecycle result does not make its claims true and does not grant local-apply or publication authority.

Commissions retain scope, lockset, evidence requirements, and delivery_policy as runner-facing governance data. The values workspace_patch_manual and workspace_patch_auto_on_pass do not cause Haft Core to apply anything; an external runner must enforce its own effect-specific authority and scope checks.

MCP creation actions fail closed by default with operator_confirmation_required; every authorized commission action must come through the manual authority boundary and becomes a typed artifact transition. Model-supplied MCP arguments or prompt text are not proof of operator authorization:

SpecSection(s) --may-govern--> DecisionRecord
DecisionRecord --may-authorize--> WorkCommission
WorkCommission --may-start--> RuntimeRun
Evidence --supports-or-weakens--> claim / SpecSection
current relations --derive--> SpecCoverage

This is the commissioned execution path after explicit authority, not a universal FPF or planning sequence.

---

Cookbook — common workflows

Record an architectural choice

operator (to agent): "we need to pick a queue for the new ingestion path"
↓ agent retrieves the relevant FPF source and checks whether a durable record is needed
↓ agent uses only the applicable methods; framing, exploration, and comparison are available but not a fixed sequence
↓ when downstream work depends on a binding choice, the operator directly says which exact option to bind
↓ h-decide routes that request; a skill token is optional and is not authority
↓ kernel validates required DRR fields; missing fields → structured error
↓ on pass: DRR written to .haft/decisions/, ready for host-agent work or an explicit WorkCommission

Diagnose a failure with rival hypotheses

operator: "tests are failing on the schema migration after the deploy"
↓ h-diagnose auto-triggers, spawns 3+ parallel Agent subagents, one per hypothesis
↓ each subagent reads only what its hypothesis needs (no anchoring)
↓ results merged, ranked by the FPF B.5.2 filter chain
↓ the diagnosis stays in chat unless the operator explicitly asks to save it
  or names a reliance-bearing receiving use that needs a durable record
↓ when that persistence condition holds: /h-note records the diagnosis
↓ /h-frame is used only if the evidence shows the problem itself needs reframing

Verify a decision still holds

operator: "did dec-20260420-cache-redesign actually work"
↓ h-verify auto-triggers
↓ reads decision predictions + valid_until + baseline file hashes
↓ measures observable claims (test output, metric query, ...)
↓ writes evidence with CL/freshness; updates R_eff
↓ if R_eff < 0.5 → marks stale; if predictions failed → reopens the problem

Quick operator status

haft check          # CI-friendly governance verification (exit 0 clean / 1 findings)

From the host agent: /h-status for the compact cockpit; use explicit drill-down calls for full status, coverage, drift/stale detail, and maintenance plans.

Shipped history lives in CHANGELOG.md.

---

License

MIT