Specs & evidence

A specification can be beautifully written and wrong about the current system. A passing test can be real and irrelevant to the claim people care about. A merged pull request can change behavior without changing the rationale that future work will read.

Haft keeps four questions separate so one green signal cannot answer all of them by accident.

Start with the contract, not the storage model

Haft normally separates the specification into small sections. The default project specification covers:

• the target system—what the product or service changes for its users and environment;
• the software system—the responsibilities, behavior, interfaces, constraints, and structure that realize it;
• the term map—important local words whose meanings must stay stable.

These are Haft's practical project documents, not vocabulary a beginner must learn before using the product. Ask h-spec to draft, inspect, or repair them when the current contract is the thing in question.

Read health without turning it into a verdict

haft spec status
haft spec check

Status answers where the specification workflow currently stands. Health reports structural problems, missing or changed baselines, drift, and staleness. “Ready” in one view does not erase findings in the other, and neither proves that the implementation is correct.

Draft, review, and exchange specifications

haft spec draft-contract
haft spec validate
haft spec review
haft spec sync
haft spec export ...

• draft-contract prepares the expected project shape.
• validate checks authored structure without approving its meaning.
• review provides advisory semantic findings.
• sync imports supported specification files into the local edition store.
• export renders a deterministic readable projection.

A clean structural check cannot judge whether the product boundary is good or whether a load-bearing claim is true. That still needs engineering judgment and relevant evidence.

When the FPF source changes

h-spec can retrieve the current governing FPF pattern and review which specification meanings may be affected. Compatibility with current FPF, the current project specification, and implementation evidence remain three separate results. Passing one does not promote the others.

Evidence ages

Evidence supports or weakens a particular claim for a particular use. It can also expire. Expiry does not rewrite history and say the old observation never happened; it says the observation is no longer fresh enough for the current reliance.

Use h-verify when the live question is whether a recorded decision or claim still holds. Haft compares the recorded baseline and predictions with current code, tests, measurements, incidents, or other admissible observations.

haft_refresh(action="scan")
haft_refresh(action="scan", verbose=true)

Drift, stale evidence, and missing links are attention signals. They do not automatically invalidate a decision or stop unrelated work.

Advanced: specification baselines

v9.0.2 still exposes three explicit baseline commands. They change the recorded state of one specification section and are never inferred from a successful review, sync, test, or git merge.

haft spec approve SECTION_ID
haft spec rebaseline SECTION_ID --reason "..."
haft spec reopen SECTION_ID --reason "..."

• approve records the reviewed active section as the baseline.
• rebaseline replaces that baseline after an intentional semantic change.
• reopen removes the baseline so the section returns to review.

These commands remain operator-controlled in the current runtime. The separate human-reviewed profile-link repair proposed during v9 development was removed; compatible memory-model successors are activated automatically. Those are different mechanisms.

Keep execution policy out of the product contract

A software specification describes the software realization. Agent rules, team policy, external-runner policy, delivery permission, and release policy have their own objects and should not be smuggled into it merely to make one document contain everything.

The trade-off

Separate specification, rationale, implementation, and evidence produce a more honest picture. They also require links and periodic review. Use this depth for contracts whose drift matters; do not baseline prose that nobody will rely on.

Related pages

• Decisions and execution authority
• Code context and drift
• Specification command reference