Development record

When A Surface Ships, The Brief Describes It — Or The Intent Does Not Reach Shipped

intentshippedmajorstandaloneitd-60

Press Release

Sequenced 2026-09-01 as a delivery rung of Phase 8 — the brief is the shipped state; the phase records the sync rule and its one legitimate lead.

abcd gains a doc-fidelity gate: a change cannot call itself shipped while the brief lags the surface it delivered, and a release cannot be cut while any intent shipped since the last cut leaves its chapter behind. The gate stands at both moments, deliberately. It runs in two layers. The deterministic layer needs no oracle and refuses on its own: every verb, every sub-verb and every agent the binary ships must have a brief chapter naming it. The semantic layer is host-delegated: it reads what the change actually delivered against that chapter and refuses on a confirmed false sentence, and where the reviewer cannot be reached it fails closed rather than reporting a clean brief. When the gate finds the brief lagging, the pass drafts the brief edit and applies it in the shipping change, then flags it for the product thinker to read — so the change is never held hostage to a paragraph, and the paragraph is never left unread.

"I read the verdict, not the source," said a product thinker shipping with abcd. "If the brief is six specs behind the code, my whole picture of what I have built is wrong, and nothing tells me. I want the framework to refuse to call the work shipped until the brief says what is actually true — and to hand me the sentence it wrote so I am reviewing, not writing."

Why This Matters

abcd's external honesty is part of its safety proposition: a product thinker who cannot read code trusts the brief to tell them what they have built. The brief is the shipped state (adr-5), and Phase 8 is what makes that decision enforceable rather than aspirational — a product thinker opens the brief and knows what abcd does today, without opening the command reference, the changelog or the code.

Nothing enforces it today. abcd already grades one artefact against another with discipline: the intent-fidelity reviewer grades delivery against acceptance criteria, fails closed, and never infers a pass from absent evidence. The same discipline applied to the brief closes the loop — built reality against the chapter that claims to describe it. Without it, the framework that most rigorously grades delivery against intention has no guard on documentation against delivery, which is the one surface a non-expert actually reads.

The enforcement point is not arbitrary. abcd spec close is the verb that moves a planned intent to shipped/, and it runs in the change that lands the work — the one moment at which whoever made the change still has the surface in their head. A gate anywhere later is archaeology.

This is the forward direction: built reality drives the brief. The reverse direction — a human editing the brief, with the implied roadmap changes drawn out — is a separate, paired intent ([[itd-61-brief-change-derivation]]).

Decisions (grilled 2026-09-01)

The product thinker resolved the open questions at the planning interview; these are commitments, not options.

The gate refuses at both moments. An intent's move to shipped is refused while the brief lags the surface it delivered, and the release cut refuses again over every shipped intent. Belt and braces, deliberately.
Built reality is checked in two layers. A deterministic layer refuses on its own with no oracle: every verb, sub-verb and agent the binary ships must have a brief chapter naming it. A semantic layer, host-delegated, reads what the intent delivered against the chapter and refuses on a confirmed false sentence; when the reviewer is unavailable the gate fails closed.
Brief only, for Phase 8. A stale public-doc sentence is reported, never refuses; the public docs are a later rung.
Draft and apply, review after. When drift is found the pass edits the brief in the shipping change and flags it for the product thinker's review; the brief may carry a sentence the product thinker did not write until they read it.
Sequenced as Phase 8, the brief is the shipped state, with itd-147 as the other rung; standalone kind, its own spec.
The gate can run fully autonomously (maintainer, 2026-09-02). A flag (the spec names it) lets an unattended run, an autonomous release cut for one, execute both layers without waiting for a person: the deterministic layer refuses on its own, the host-run reviewer is invoked by the routine the way the changelog composer is, the brief edit is drafted and applied, and every applied edit is listed for review after in the change the run produces. Autonomy changes who waits, never what refuses: the gate still refuses on what it can prove and still fails closed when the reviewer is unavailable.

What's In Scope

Two layers, one gate. The pass is two mechanisms stacked. Layer 1 grades coverage and needs nothing but the binary and the brief. Layer 2 grades meaning and is host-delegated. A refusal from either is a refusal.
Layer 1 — the deterministic coverage floor. Every verb, every sub-verb and every agent the binary ships must have a brief chapter naming it. The check is derived from the command tree and the agent set, calls no oracle, and refuses on its own. It is cheap enough to run at every enforcement point and in CI.
Layer 2 — the semantic doc-fidelity pass. Host-delegated review of what the change delivered against the chapter that claims to describe it, refusing on a confirmed false sentence and naming the sentence. Meaning cannot be judged deterministically, which is why this layer is delegated rather than coded.
Fail closed. No reviewer, no reliable comparison, no verdict — the gate refuses. It never reports a clean brief from absent evidence.
Two enforcement points, one mechanism. abcd spec close, the verb that moves a planned intent to shipped/, refuses per intent while the brief lags the surface that intent delivered; the release cut refuses again over every intent shipped since the last cut. Belt and braces, deliberately: the per-intent point catches the change while its author is present, and the cut catches whatever reached main around it.
Draft and apply, review after. When the gate finds the brief lagging, the pass writes the brief edit into the shipping change itself and flags it for the maintainer's review. The brief may carry a sentence the maintainer did not write until they read it; that trade is the ruling, and the flag is what makes it honest.
The per-task pass stays a report. After a task it reports where the brief may lag and blocks nothing. It is an advisory surface, not a gate; the gate is the refusal at the two enforcement points above.
The one legitimate lead is not drift. A brief edited after a cut is ahead of that release until the next cut, and the gate does not report it as wrong for being ahead.

What's Out of Scope

The public docs — a later rung, reported and never refusing. For this phase the gate is brief only. A public-doc sentence that lags is reported, and the move and the cut proceed regardless. Everything the pre-ruling draft claimed here is struck to that later rung: grading the brief against the public docs, drafting audience-adapted public-doc deltas, and the end-user / developer-extending split. The brief has to hold before anything derived from it is worth gating.
The docs-currency lint that already shipped from this draft. abcd docs lint — change-narration, resolvable cross-links, no stray root documents — is decidable without reading the code and runs everywhere already. It is the floor this gate stands on, not a layer of it, and this rung neither changes nor re-claims it.
The reverse direction. Drawing implied intents and principles out of a human-authored brief edit is [[itd-61-brief-change-derivation]], a separate intent that stays adjacent to this phase.
Re-grading delivery against intention. That is the intent-fidelity reviewer's job; this pass consumes "what shipped" as an input and does not re-derive it.
Authoring the brief's prose voice. The pass drafts a delta against an existing chapter; wholesale authorship and information architecture are not its concern.
Deciding sequencing or dependencies relative to the paired intents — that is abcd intent plan's job.

Mechanism

Facilitator-seeded from the phase's expectation. The maintainer stated no mechanism claim at the interview; strike this line and the sentence under it if it is not the claim being made.

We expect a product thinker to be able to read the shipped state from the brief alone because the brief cannot fall behind a surface that has already shipped — the gate refuses the shipped move and the release cut until the chapter names it — and a shipped intent found later whose surface no chapter describes is what would show the expectation wrong.

Scope Conditions

None stated.

Acceptance Criteria

Given-When-Then per the itd-1 discipline.

Given the binary ships a verb, a sub-verb or an agent that no brief chapter names, when the deterministic layer runs, then it refuses and names the undocumented surface, with no oracle call and no wait on a reviewer.
Given a change that delivered a surface, when the intent moves to shipped through abcd spec close, then the semantic layer reads what the change delivered against that surface's chapter and refuses the move on a confirmed false sentence, naming the sentence.
Given the semantic reviewer cannot be reached or returns no usable verdict, when either enforcement point runs, then the gate refuses, rather than reporting the brief clean.
Given a release cut, when the gate runs over every intent shipped since the last cut, then the cut is refused while any of their chapters lags, naming the intent and the lagging sentence.
Given the gate finds the brief lagging, when the shipping change is prepared, then the brief edit is drafted and applied in that same change and flagged for the maintainer's review, so no change lands with the brief left lagging and unflagged.
Given a public-doc sentence that lags the brief, when either enforcement point runs, then it is reported and the move or the cut proceeds — in this rung the public docs never refuse.
Given a task has completed, when the per-task pass runs, then it reports where the brief may lag, with evidence pointing at the divergence, and blocks nothing.
Given a brief edited after a release was cut, when the next cut's gate runs, then the edit is treated as the legitimate lead and nothing between the cuts reported the brief as wrong for being ahead.
Given the gate is invoked with its autonomous flag inside an unattended run, when it finds a lagging chapter, then it drafts and applies the edit, lists every applied edit in the run's own output for review after, and waits for nobody; it still refuses on an undocumented surface, on a confirmed false sentence, and when the reviewer is unavailable.

Open Questions

Every question below was put to the maintainer at the planning interview on 2026-09-01 and answered there; the answers are the rulings in the Decisions section above. The section is kept so a later reader sees what was asked.

Resolved — where the pass hooks. Two points, one mechanism: abcd spec close, which moves the intent to shipped, and the release cut. Not a composition with the intent-fidelity reviewer's surface; a distinct gate at both moments.
Resolved — what "built reality" is as a concrete input. Two layers: the command tree and the agent set for the deterministic layer, and what the change delivered for the semantic layer.
Resolved — the developer-extending public-doc view. Out of scope. The public docs as a whole are a later rung; neither audience view ships here.
Resolved — how the per-task tier avoids noise. By not being a gate. The per-task pass is kept as a report only; the refusal lives at the shipped move and the cut, where a change has a surface to be judged against.
Open, and not gating scope — whether this pass becomes a framework-provided discipline (see [[itd-62-pluggable-safety-gate]]'s two-discipline-kinds question) or stays a reviewer surface like fidelity. Deferred: the answer changes where the pass is configured, not what this rung builds.

Audit Notes

Fidelity review — receipt rcp-7a2c62ab0228 (verifier intent-auditor claude-fable-5-1).

Provenance: intent-auditor@claude-fable-5-1 · rubric_hash sha256:effa65b3e9e88ff29433b443ec2be159522a8b0b71cf1434526514aa61edb13e · prompt_hash sha256:1ff0dc6b7d83c46b223640fffda8404d298f6607b181dd32f8a2caef0cab6cba Input attestations: diff:commits 5992b3846 02ec15acb 662f9c81a b0510748f 7d50be159 9ddfe9d2b d155841e7 accf61856 cf3d3c9a1 cdd78b03b (PRs #? docFidelity + integ 24c), judged at main 7fb52a6b5@sha256:fa44e8580b3d8be5491d02703fc5ee9cd6a692fa46803d4ab5ead27bc906cd4a;

Acceptance rollup: MET 4 · MET_WITH_CONCERNS 5 · NOT_MET 0 · INCONCLUSIVE 0

Per-criterion verdicts:

ac-1 — MET_WITH_CONCERNS: Layer 1 derives every non-hidden, non-moved verb and sub-verb from the live command tree plus every agents/*.md, checks each against the chapter files for a code span of its path, refuses before the reviewer is constructed and names the surface in the reason; the spec-close test proves a matching PROMOTE does not excuse a missing chapter. Concern: the chapter set is every regular *.md under 04-surfaces/, so the index README.md counts as a chapter; at BASE abcd rules, abcd spec, abcd spec close and sota-researcher are named by no numbered chapter and pass the floor on the README alone, and a one-row index entry would satisfy the floor for any new surface. evidence: internal/core/docfidelity/docfidelity.go:209-229 — "if layerOne && !report { v.Refuse = true; return v }" evidence: internal/core/docfidelity/docfidelity.go:220 — "no brief chapter under 04-surfaces/ names the "+string(s.Kind)+" "+s.Name+""" evidence: internal/core/docfidelity/store.go:68-80 — "names, err := regularMarkdown(root, ChaptersDir) ... in.Chapters[name] = string(data)" evidence: internal/core/docfidelity/docfidelity_test.go:44 — "func TestLayerOneCoverageTable" evidence: internal/surface/cli/docfidelity_close_test.go:81-92 — "Even a matching PROMOTE review does not excuse a missing chapter." evidence: .abcd/development/brief/04-surfaces/README.md:241 — "abcd rules renders the rule set the prompt router draws on, read-only."
ac-2 — MET_WITH_CONCERNS: spec close runs the gate over the intents the close would ship before anything moves, and a saved HOLD review refuses naming each false brief sentence with its evidence; the test asserts the spec stays open and the intent planned. Concern: the semantic layer is not invoked at the close — it is a receipt the host saved earlier with docs fidelity record, labelled by HEAD, and it reviews the chapters against the code as a whole, with the population only naming the findings; this shape rests on ruling DR3, which the code cites but the committed decision log does not carry. evidence: internal/surface/cli/cli.go:3463 — "if err := enforceDocFidelity(repoRoot, "abcd spec close", closeShips(repoRoot, args[0])); err != nil {" evidence: internal/core/docfidelity/docfidelity.go:253-271 — "case ReviewHold: ... reason := who + "the docs review confirmed a false sentence in " + f.Chapter + ": "" + f.Sentence + "" (" + f.Evidence + ")"" evidence: internal/core/docfidelity/store.go:112-127 — "SavedReview is layer 2 as ruled: the review the delegated reviewer saved for Commit, found in Root." evidence: internal/surface/cli/docfidelity_close_test.go:68 — "func TestSpecCloseRefusesOnAConfirmedFalseSentence" evidence: internal/core/docfidelity/store.go:4-5 — "the one writer of that review (ruling DR3)"
ac-3 — MET: Every way of not having a usable verdict is a refusing status: no receipt (none), a receipt for another commit (stale), an unreadable or hand-edited one (invalid), a non-PROMOTE non-HOLD verdict (inconclusive), a HOLD naming nothing, and a PROMOTE that names a false brief sentence; the core table, the close tests and the cut tests all assert the refusal, and Record refuses a PROMOTE-with-findings payload before it is saved. evidence: internal/core/docfidelity/docfidelity.go:248-283 — "case ReviewNone: ... case ReviewStale: ... case ReviewInconclusive: ... default: ... is refused" evidence: internal/core/docfidelity/store.go:116-117 — "Every way of not having a usable verdict is a status that refuses; none is a pass." evidence: internal/core/docfidelity/store.go:270-272 — "a PROMOTE names %d false brief sentence(s), so the brief is not current: a verdict with a confirmed brief sentence is HOLD" evidence: internal/core/docfidelity/docfidelity_test.go:117 — "func TestLayerTwoOutcomes" evidence: internal/surface/cli/docfidelity_close_test.go:56 — "func TestSpecCloseRefusesWithNoSavedDocsReview" evidence: internal/core/release/docfidelity_test.go:34 — "func TestEmitRefusesACutWithNoSavedDocsReview"
ac-4 — MET_WITH_CONCERNS: The release emit collects every itd- record added since the base tag and runs the same Gate over them; a refusal carries the population and each reason, which name the intent and the lagging sentence; the cut test asserts it. Concern: the gate runs only when at least one intent shipped, so a cut carrying only issue resolutions runs neither layer — including layer 1, which the spec says is cheap enough to run at every enforcement point; a sub-verb added by an issue fix in such a cut meets no coverage floor at the cut. evidence: internal/core/release/emit.go:266-285 — "if len(shipped) > 0 { fidelity, armed, err := docfidelity.Gate(root, current.Commands, shipped, false)" evidence: internal/core/release/emit.go:278-281 — "Kind: RefusalDocFidelity, Reason: "the brief lags a surface shipped in this cut: " + strings.Join(fidelity.Reasons, "; "), Records: shipped," evidence: internal/core/release/docfidelity_test.go:46 — "func TestEmitRefusesACutWhileAShippedIntentsChapterLags" evidence: internal/core/release/docfidelity_test.go:71 — "func TestEmitWithNoIntentShippedJudgesNoPopulation" evidence: internal/surface/cli/docfidelity.go:55 — "if len(population) == 0 || !docfidelity.Armed(repoRoot) { return nil }"
ac-5 — MET_WITH_CONCERNS: A HOLD finding with a reviewer-drafted replacement becomes a proposed edit; the gate still refuses and names --apply; Apply replaces the sentence (exactly once, one bounded line, or nothing is written) and records a flag in .abcd/work/brief-review-flags.json, which travels in the change's diff; the judge then treats the sentence as applied only when the chapter changed AND a flag names it, so no path completes with the brief lagging and unflagged. Concern: the drafting is the reviewer's optional replacement, not the pass's own, and the apply is a separate docs fidelity --apply invocation rather than a step of the shipping verb; a HOLD with no drafted replacement is refused with nothing drafted. evidence: internal/core/docfidelity/docfidelity.go:266-269 — "if f.Replacement != "" { v.Proposed = append(v.Proposed, Edit{...}); reason += "; the reviewer drafted its correction — abcd docs fidelity --apply applies it and flags it for review" }" evidence: internal/core/docfidelity/apply.go:61-117 — "func Apply(root string, edits []Edit, commit string, at time.Time) ([]Flag, error)" evidence: internal/core/docfidelity/apply.go:28 — "const FlagsPath = ".abcd/work/brief-review-flags.json"" evidence: internal/core/docfidelity/docfidelity.go:303-317 — "All three, so neither a silent hand edit nor a flag over an unedited chapter completes the change with the brief lagging and no flag recorded." evidence: internal/core/docfidelity/apply_test.go:51 — "func TestAnEditWithoutAFlagStillRefuses" evidence: internal/surface/cli/docfidelity_verb_test.go:55 — "func TestDocsFidelityApplyAppliesTheDraftAndTheCloseProceeds"
ac-6 — MET: A finding with doc "public" is collected into public_findings and skipped by the HOLD loop, so it adds no reason and refuses nothing at either point; Record accepts the public doc kind and requires a HOLD to name a brief sentence, so a public-only review is a PROMOTE that is reported; the core test asserts the finding is present and the verdict allows. evidence: internal/core/docfidelity/docfidelity.go:232-236 — "if f.Doc == DocPublic { v.Public = append(v.Public, f) }" evidence: internal/core/docfidelity/docfidelity.go:255-258 — "if f.Doc == DocPublic { continue }" evidence: internal/core/docfidelity/store.go:267-268 — "a HOLD names no false brief sentence, so there is nothing to correct: a verdict with no confirmed brief sentence is PROMOTE" evidence: internal/core/docfidelity/docfidelity_test.go:160 — "func TestPublicDocSentenceIsReportedAndNeverRefuses"
ac-7 — MET: docs fidelity --report runs both layers whatever layer 1 found, states every finding with its evidence, sets Refuse false and exits 0; it refuses to combine with --apply or --autonomous so it can write nothing. evidence: internal/core/docfidelity/docfidelity.go:223-229 — "layerOne := len(v.Reasons) > 0; if layerOne && !report {" evidence: internal/core/docfidelity/docfidelity.go:284 — "v.Refuse = !report && len(v.Reasons) > 0" evidence: internal/surface/cli/docfidelity.go:101-103 — "--report blocks nothing and writes nothing, so it takes neither --apply nor --autonomous" evidence: internal/core/docfidelity/docfidelity_test.go:176 — "func TestReportModeReportsTheSameFindingsAndNeverRefuses" evidence: internal/surface/cli/docfidelity_verb_test.go:28 — "func TestDocsFidelityReportModeStatesFindingsAndExitsZero"
ac-8 — MET: Both enforcement points derive the command tree from the live binary (SurfaceSnapshot at the close, current.Commands at the cut) and the receipt is keyed on HEAD, so the brief is judged against the binary and never against the tag; the core test pins that a chapter ahead of the tag is not a finding. evidence: internal/core/release/emit.go:262-265 — "The brief is judged against the binary, never the tag, so a chapter edited ahead of the last cut is current, not drift." evidence: internal/surface/cli/docfidelity.go:58-62 — "snap, err := SurfaceSnapshot(repoRoot) ... docfidelity.Gate(repoRoot, snap.Commands, population, false)" evidence: internal/core/docfidelity/docfidelity_test.go:201 — "func TestTheLegitimateLeadIsNotDrift"
ac-9 — MET_WITH_CONCERNS: docs fidelity --autonomous applies every drafted edit, lists each applied edit and its flag in the output, adds the reviewer's request (commit, population, chapters, record verb, verdict shape) to the JSON, and still exits 1 with no saved review, an undocumented surface or a confirmed false sentence; the test asserts the request and the refusal. Concern: the flag lives on the standalone verb only — spec close and launch ship have no autonomous form, and the launch page's cut routine names only docs fidelity record, never the autonomous verb — so an unattended cut waits for nobody only if its routine runs docs fidelity --autonomous, the reviewer and record itself before the cut. evidence: internal/surface/cli/docfidelity.go:123-145 — "if (apply || autonomous) && len(v.Proposed) > 0 && v.Review != nil { flags, err := docfidelity.Apply(...) ... if autonomous && (v.Review == nil || v.Review.Status != docfidelity.ReviewMatch) { ... req := docfidelity.NewRequest(head, in)" evidence: internal/surface/cli/docfidelity.go:149-151 — "if v.Refuse { return &exitError{Code: 1} }" evidence: internal/core/docfidelity/apply.go:119-129 — "Request is what an unattended routine hands the delegated reviewer, the way launch ship hands the changelog composer its request block" evidence: internal/surface/cli/docfidelity_verb_test.go:79 — "func TestDocsFidelityAutonomous" evidence: commands/launch.md:421-432 — "The cut needs a docs review for the commit it runs on. ... "${CLAUDE_PLUGIN_ROOT}/abcd" docs fidelity record --verdict-json verdict.json"

Gap audit:

honoured:
- Two layers, one gate: layer 1 refuses on its own with no reviewer constructed, layer 2 is host-delegated and judged by the release gate's own receipt reader evidence: internal/core/docfidelity/docfidelity.go:196-229 — "judge composes the verdict: layer 1 first, and only when it holds, layer 2." evidence: internal/core/docfidelity/store.go:128 — "got, err := lint.CheckGateReceipt(s.Root, ReceiptsDir, s.Commit, GateName)"
- Two enforcement points share one entry point with different populations: the intents a close would ship, every intent shipped since the tag evidence: internal/core/docfidelity/store.go:185-189 — "Gate is the one entry point both enforcement points and the per-task report call, with their own population" evidence: internal/surface/cli/docfidelity.go:27-49 — "func closeShips(repoRoot, specID string) []string"
- Fail closed: no reviewer, no comparison, no verdict all refuse, and the three fail-open shapes found after the first landing are closed evidence: internal/core/docfidelity/docfidelity.go:239-247 — "a receipt edited to carry one after it was saved is still not a pass" evidence: internal/core/docfidelity/store_test.go:201 — "func TestRecordRefusesAFailOpenPayload"
- The judge writes nothing; the writer is a distinct Apply the judge never reaches evidence: internal/core/docfidelity/apply.go:3-8 — "A judge that writes is a judge whose output depends on who ran it, so nothing here is reached by Judge, and nothing in Judge writes." evidence: internal/core/docfidelity/store_test.go:184 — "func TestGateWritesNothing"
- Brief only: a public-doc sentence is reported and never refuses evidence: internal/core/docfidelity/docfidelity.go:255-258 — "if f.Doc == DocPublic { continue }"
- The legitimate lead is not drift: the brief is judged against the binary, never the tag evidence: internal/core/docfidelity/docfidelity_test.go:201 — "func TestTheLegitimateLeadIsNotDrift"
- A remainder close ships nothing and is not gated evidence: internal/surface/cli/docfidelity_close_test.go:106 — "func TestSpecCloseWithARemainderIsNotGated"
- No file exempts a surface from layer 1: the backlog file the first landing read was removed evidence: internal/core/docfidelity/store_test.go:241 — "func TestNoBacklogFileAdmitsAnUndocumentedSurface"
- Wired on both front doors and documented in the brief's own docs chapter evidence: commands/docs.md:75-120 — "## fidelity — the brief describes every surface that ships" evidence: .abcd/development/brief/04-surfaces/10-docs.md:66-100 — "The doc-fidelity gate (itd-60) judges whether the brief describes every surface that ships."
diverged:
- The semantic layer was promised as a review the close and the cut run over what the change delivered; delivered is a receipt the host saves beforehand for HEAD, found automatically, reviewing the chapters against the code as a whole — the shape ruling DR3 chose, which the committed decision log does not carry evidence: internal/core/docfidelity/store.go:3-10 — "the delegated docs review saves a verdict receipt labelled with the commit it reviewed; spec close and launch ship find it automatically" evidence: dcn-2609300000000009 — "The person answered eighteen rulings of autonomous run A on 2026-09-30 (CF1, CF2, CG1, CI1, CI2, CJ1, CK1, CL1, CM1, DR1, DR2, DR4, DR5, DR6, DQ1a, DQ1b, DQ2, DQ3)"
- Layer 1 treats every regular *.md under 04-surfaces/ as a chapter, the index README.md included; four surfaces at BASE are covered by the index alone evidence: internal/core/docfidelity/store.go:70 — "names, err := regularMarkdown(root, ChaptersDir)" evidence: .abcd/development/brief/04-surfaces/README.md:262 — "abcd spec addresses the spec store under .abcd/development/specs/"
- The deterministic floor was promised at every enforcement point; both points skip the whole gate when the population is empty, so a cut or close that ships no intent runs no coverage check evidence: internal/core/release/emit.go:272 — "if len(shipped) > 0 {" evidence: internal/surface/cli/docfidelity.go:55 — "if len(population) == 0 || !docfidelity.Armed(repoRoot) {"
- The pass was to draft the brief edit itself; delivered, the reviewer drafts an optional replacement and a separate --apply invocation applies it evidence: internal/core/docfidelity/docfidelity.go:50-51 — "Replacement is the reviewer's drafted sentence, "" when none was drafted."
- The autonomous flag lives on the standalone verb; the launch page's cut routine does not name it evidence: internal/surface/cli/docfidelity.go:157-158 — "cmd.Flags().BoolVar(&autonomous, "autonomous", false," evidence: commands/launch.md:421-427 — "refuses (doc-fidelity, "run the docs review first") until a review is saved for HEAD"
missing:
- A chapter of their own for abcd spec (and abcd spec close), abcd rules and sota-researcher: no numbered chapter under 04-surfaces/ names them, so their flags appear in no generated appendix, and the gate did not refuse because the index names them evidence: .abcd/development/brief/04-surfaces/README.md:241 — "abcd rules renders the rule set the prompt router draws on, read-only." evidence: internal/core/docfidelity/docfidelity.go:211-216 — "for _, name := range chapters { if names(in.Chapters[name], s) { row.Chapter = name; break } }"

2026-10-02: the press release's sentence and the two Decisions sites (the opening line and the draft-and-apply bullet) name the product thinker, the role each sentence means, in place of the retired role word, under the product thinker's ruling R5 of that day, recorded as iss-2610021446271464; every other word is unchanged, and the retired word's remaining occurrences elsewhere in this record were outside the ruling.

References

Sequenced by Phase 8 — the brief is the shipped state, whose expectation this intent's mechanism claim is derived from, and whose milestone names this pass as the hard gate at the shipped move.
Rests on adr-5: the brief is the current state of the project. This intent is what makes that decision enforceable.
Originating assessment: ~/Desktop/abcd-assessment.html (2026-06-26) — the README-over-promises / brief-honest finding that motivates the forward doc-fidelity loop. Its public-docs half is the later rung.
Builds on itd-80, the intent-fidelity reviewer (delivery-against-intention): this pass is the documentation-against-delivery analogue, it consumes that reviewer's notion of what a change delivered, and it reuses its fail-closed, deterministic-shell, never-silent posture.
Builds on itd-73, derived versioning, whose structural surface diff already runs at the release cut — the second of this gate's two enforcement points.
Paired with: [[itd-61-brief-change-derivation]] (the reverse direction) and [[itd-62-pluggable-safety-gate]] (whose brief change this pass would govern); the other Phase 8 rung is [[itd-147-the-brief-s-surface-chapters-are-a]].
Governing principle: single source of truth — the brief is canonical (.abcd/development/brief/ and the engineering conventions in AGENTS.md).

Grounds

pursued: the brief is the shipped state, so a product thinker reads the shipped state from the brief alone; a shipped intent whose surface the brief does not describe, found after the gate exists, shows the gate was wrong

Frontmatter

id	itd-60
type	intent
lifecycle	shipped
kind	standalone
severity	major

.abcd/development/intents/shipped/itd-60-doc-fidelity-anti-drift.md
open on GitHub ↗ · commit history ↗

References2

itd-73abcd Cuts the Version — You Never Type Onebuilds on
itd-80An Intent Ships Itself: `planned → shipped` Follows Its Spec Closing, With A Fidelity Audit Attachedbuilds on

Referenced by16

adr-2610290238168123The brief states the design and why; each command's page states what abcd does, once, and is the copy checked against the coderelated
iss-2610262032193797The mental model calls itd-60 planned, but itd-60 sits on the shipped shelfrelated
iss-2610262036483439itd-60 names the shipped docs-currency lint `abcd docs lint`; the lint chapter says the docs verb's former check sub-verb is an unknown commandrelated
iss-2610262036495984itd-60 says the gate writes its drafted brief edit into the shipping change itself; the docs chapter says the gate only proposes the edit and still refusesrelated
iss-2610262038097833itd-60 makes `abcd spec close` refuse while the brief lags, failing closed without a reviewer; 34-build's closing lane runs the spec's close with no doc-fidelity review among its stagesrelated
iss-2610262040177541Universal patterns call itd-60 a planned draft that is not yet built; itd-60 is shipped, and its gate refuses at spec closerelated
iss-2610262040192600The lint contract calls the docs-currency gate `abcd lint docs`; itd-60 calls the same gate `abcd docs lint`related
iss-2610262042159336itd-60 is sequenced as a rung of Phase 8; the phase entry says roadmap phases run 0–7, and it retires the phase.related
iss-2610262044453777itd-61 says itd-60 carries built reality into the brief and the public docs; shipped itd-60 covers the brief only and leaves the public docs to a later rungrelated
iss-2610262045454143itd-60 attributes decisions and reviews to the maintainer; itd-2609212137129937 retires the word in favour of the two named rolesrelated
iss-2610262045459641itd-60 calls the docs-currency lint abcd docs lint; itd-2609212130136102 moves every check under abcd lint, as lint docsrelated
iss-2610262045465811itd-60 is sequenced as Phase 8; itd-2609211913453478 retires phases as the sequencing devicerelated
itd-61A Human Edit To The Brief Cannot Commit Until Its Implied Intents And Principles Are Drawn Out And Reconciledbuilt on by
itd-62abcd Routes The Invisible Risks An Amateur Cannot See To A Real, Fail-Closed Gate That Wraps A Trusted Scannerbuilt on by
itd-64abcd Learns From Its Own Runs Which Configurations Work Best, And Tunes Its Configuration Layer Accordinglybuilt on by
spc-2609020903498198The brief describes every surface that ships, or the intent does not reach shippedimplemented by

mentions25

adr-5Brief is the current state; no version label, no archive directory
dcn-26080200000000092026-08-02 — iss-41 (v0.5.0 item D): the interim delivery-state rule is stated as the one the lifecycle already implies — **delivered capability is represented by the intent leaving `drafts/`, and nothing else says it** — because the alternative on offer (a new tier, or a per-intent "partly shipped" field) invents lifecycle vocabulary to describe a citation problem. The ledger's premise that `shipped/` is empty has aged out: thirteen intents live there now, so the mechanism exists and what was missing was the gate holding the changelog to it. `delivery_state` reads each version entry's delivery sections (`Added`, `Changed`; a repo's configured list is unioned with those, never substituted for them) and blocks an `itd-N` citation whose intent is still in `drafts/`. Scoping by section rather than by whole entry is what keeps it precise: the ids under `Fixed` in this corpus are provenance for a defect — which draft two branches minted at once — and blocking them would force either a falsehood or a deletion of real information. It fails closed three ways: no changelog, no intents store, and a store holding no lifecycle bucket — the last being a root pointed one level too deep, which resolves every citation to nothing and reads exactly like a clean corpus. The corpus had TWO instances, not the one filed: itd-60, whose deterministic layer shipped as `abcd docs lint` while its semantic layer is still five open questions, and itd-85, which shipped WHOLE as `abcd audit` and was simply never promoted. They get different treatments because they are different facts. itd-60 stays in `drafts/` and loses the citation — an intent is delivered whole or not at all (split-the-intent doctrine), so citing a partial delivery reads as a promotion that never happened, and splitting itd-60 to make the citation true is editorial work this issue does not carry. itd-85 loses the citation too, but under protest: the honest fix is promotion, and promotion is blocked on the `shipped/` schema wanting a non-null `spec_id` the audit verb has never had. Filed as iss-180 rather than papered over or forced — writing a retroactive spec to satisfy a lint is the failure mode this repo keeps naming. The out-of-scope half is a REUSE, not a new rule: `index_drift` gained one field, `dir_entry`, the mirror of `entry` on the directory side, which reduces a filename stem to the id a document actually enumerates. Without it a hand-written listing can only agree with a directory by transcribing whole slugs, which is a listing nobody writes, and the alternative was a second rule shaped exactly like the first. The list itself had drifted nineteen entries while claiming in its own prose to be derived and "not hand-counted": itd-47, itd-73 and itd-74 had left `drafts/` for three different buckets, and sixteen captures were missing. Regenerated, wrapped in the marked region, and the sentence promising hand-kept lockstep is replaced by the gate that enforces it. The four later-phase items that never had an intent id move OUT of the derived list — a derivation cannot produce them, so their presence was what made the claim false in the first place.
dcn-26081900000000052026-08-19 — Design review of the candidate record extensions (scope
dcn-26090100000000052026-09-01 — The brief is the shipped state, consolidated without a new intent (maintainer). The request "a product thinker must be able to understand the current shipped state of the repository by looking only at the brief" is already adr-5's decision and is delivered by two existing drafts, itd-60 (the doc-fidelity pass that gates spec close on the brief reflecting delivery) and itd-147 (generated surface blocks so a shape claim cannot drift), so no umbrella intent is filed; the drift records from the v0.7.0 receipts link to them and the two exact duplicate pairs close as duplicates. Added to the decision: brief, record and release stay in sync, with one legitimate lead — a brief edited after a release was cut is ahead of that release until the next cut, and the gap closes at the cut rather than between cuts. The work is sequenced as Phase 8, "the brief is the shipped state"; the design branch's unmerged "closed loop" phase takes 9 when it merges. itd-61, the reverse direction, stays adjacent as an open question of the phase.
dcn-26092500000000282026-09-25 — The build's open-question check reads the record's own settled convention and stays fail-closed (lane implementer, autonomous run A, fix round 1 of the loop lane, on iss-2609252053576085; the lane's first ruling, that every list item under `## Open Questions` is a question whatever it says, lived only in its report and refused intents the record had settled). `intent.OpenQuestions` recognises exactly two markers, learned from the 12 planned intents that carry list items there. A section whose first non-blank line is an italic `_All resolved …_`, with at most one count word (`_All four resolved …_`), is settled whole (itd-111, itd-93); `_All but one resolved_` is not. An item explicitly marked resolved or deferred is not a question: a bold span opening with the word (`**Resolved — …**`, `**Deferred**`, `**Deferred to a follow-up intent**`, `**explicitly deferred**`, `**explicit deferral**`) or the word as a label (`resolved:`, `RESOLVED:`, `Deferred:`), anywhere in the item including its continuation lines. Everything else stays a question: an item led `**Open` whatever it goes on to say (itd-60's "Open, and not gating scope"), an item that only points to another record (itd-76's "travel with itd-126"), `**Out of scope …**`, and a question that merely mentions deferral. With the rule, itd-111 and itd-93 pass the check; itd-7, itd-60, itd-65, itd-66, itd-76, itd-82, itd-117, itd-131, itd-2609170822093401 and itd-2609211116005482 still refuse, each on an item the record does not mark settled. Relabelling those items is the product thinker's call through the planning interview, not the loop's.
dcn-26093000000000092026-09-30 — The person answered eighteen rulings of autonomous run A on 2026-09-30 (CF1, CF2, CG1, CI1, CI2, CJ1, CK1, CL1, CM1, DR1, DR2, DR4, DR5, DR6, DQ1a, DQ1b, DQ2, DQ3), relayed by the run's interviewer abcd-23 [b1e81b] and recorded by lane recRulingsDR for orchestrator abcd-8d [5bfdfb]. The answers are kept in the local-tier file `.abcd/.work.local/scratch/reports/rulings-answered-2609-29-b.md`, lines 13 to 30, and are restated here because that file is not committed. SETTLED BLOCKERS: a blocker replaced by an accepted ADR counts as settled, so the waiting intent may start (CF1); a blocker reclassified as a discipline counts as settled too (CF2). Neither is built at this entry's base: the blocked pre-start check still refuses both shapes, and iss-2609300751191426 carries the change. AS BUILT: the App token for the dependency re-authoring workflow is minted in the shell, an openssl-signed JWT exchanged with curl and revoked on exit, with no new action (CG1); when the prompt router cannot evaluate a prompt, its envelope carries the error and leaves the active-domain list out, so the client keeps what it had (CI1); a domain that returns to the active set is re-injected on every host, one that appends to a transcript included, not only on a client that snapshots (CI2); `abcd update` shows progress only when stderr is a terminal, and saved output stays clean (DR4). BUILD: the installer (`hooks/bootstrap.sh`) writes the previous release tag into binary-meta when it swaps a binary, the session hook stays read-only, and that tag replaces the setup_version comparison of the itd-111 update notice (CJ1); the SHELL domain also teaches a repository's own guard entries, generated the same way as the bundled registry's (CK1); `step` in `abcd implement check` is renamed `stage` too, in the same breaking v0.12.0 (CM1); the fix rounds a run spends before it hands a lane back are a per-run setting beside `--pace`, for example `--fix-rounds`, default 3 (DR1); the dependency-bump intent itd-2609221842494980 ships now, with the first live bump recorded as owed until the person has created the App and its secrets (DR2); only a self-contained agent is sent to a paid provider by default, so the cold-reading positions may go while a file-reading agent such as the intent auditor is refused with the reason, and a central override, a machine-level settings list the person keeps that no agent or repository can change, may name providers that take bundled-context requests for file-reading agents (DR5); a run works in parallel, building several pieces and running reviewers at once up to its agent limit, which is new build-loop work that makes the pacing intent's criterion 6 testable (DR6); an undecided fidelity audit reopens the work, sending the feature back to a lane, and never closes like a pass (DQ1a, iss-2608290820473197); the audit moves before the merge, as part of the build loop's last lane (per ruling AI), and until that loop is ready it stays after the merge and reopens on an undecided or failed verdict (DQ1b, iss-2608290822140563); the filing-time duplicate check covers every route, the promoted inbox report, the consistency pass and the reading ingest, in a lane after remedyRequired (DQ2, iss-2609281911024185); `abcd ahoy` offers to install gh on an explicit yes (DQ3, iss-2609281911024838). KEEP: a promoted inbox report's own remedy is kept but not usable: the sender's suggestion stays in the issue's text for reference, the remedy field is `none (filed automatically)`, and a drain skips the record until a person writes the fix, so the conservative default recorded above on 2026-09-30 stands and is not widened (CL1). The person added to CL1 that when a person comes to write the real fix for such an issue, the agent offers a state-of-the-art research pass first (principle `prefer-sota`), which `commands/capture.md` says under the `capture remedy` verb. The three rulings of 2026-09-29 owed to this ledger by earlier sessions of the run, the ceilings of five and of eight sub-agents and the remedies ruling, already have their entries above, so this entry adds none.
dcn-26100200000000032026-10-02 — Ruling DR3 of the person (2026-09-29, in the human-step interview run for autonomous run A by its interviewer abcd-23 [b1e81b]; recorded by lane rd2, records only). The answers of that interview are kept in the local-tier file `.abcd/.work.local/scratch/reports/rulings-answered-2609-29-b.md` and are restated here because that file is not committed. DR3, verbatim: "itd-60 docs-fidelity verdict: FOUND AUTOMATICALLY by spec close and launch ship (a saved verdict labelled with the reviewed code's fingerprint; match -> proceed; none/stale -> refuse 'run the docs review first'), like the preflight receipt." Built: itd-60 shipped with it; a `spec close` that ships an intent, and `launch ship` for every intent shipped since the last tag, find the docs review saved for HEAD through `internal/core/docfidelity` and refuse until `abcd docs fidelity record` has saved one (`internal/core/lint/gatereceipt.go`).
dcn-26100700000000012026-10-07 — Ruling DR3 of the person (2026-09-29, in the human-step interview run for autonomous run A and relayed by its interviewer abcd-23 [b1e81b]), restated for iss-2610020728128805 (recorded by lane-1 of run-2610071733272557, records only). The answers of that interview are kept in the local-tier file `.abcd/.work.local/scratch/reports/rulings-answered-2609-29-b.md`, line 31, and are restated here because that file is not committed. DR3, verbatim: "itd-60 docs-fidelity verdict: FOUND AUTOMATICALLY by spec close and launch ship (a saved verdict labelled with the reviewed code's fingerprint; match -> proceed; none/stale -> refuse 'run the docs review first'), like the preflight receipt." It is the ruling the doc-fidelity gate's shape rests on (itd-60, ac-2: the semantic layer is a saved review for HEAD that `spec close` and `launch ship` find automatically, rather than a review run at the close), cited by `internal/core/docfidelity/store.go`, `internal/core/docfidelity/docfidelity.go` and `internal/core/lint/gatereceipt.go`. The issue was captured on 2026-10-02 against the 2026-09-30 entry above, which restates DR1, DR2, DR4, DR5 and DR6 and skips DR3; that entry is left as written (DA002). The 2026-10-02 entry of lane rd2 above already restated DR3 later the same day, after the capture, together with CB1, CC1, CD1 and CD2, and DQ2b and CJ1b have their own 2026-09-30 entries, so none of the rulings the issue names as owed is still missing; this entry adds the issue's own pointer to the ruling and changes no earlier line.
iss-2609020906544088Found while readying Phase 8: the generated CLI reference (docs/reference/cli/commands.md), the surface_coverage record-lint rule and the brief-to-surface crosscheck gate were all shipped under issue ids with no intent record, and itd-60 and itd-85 each shipped substantial code while sitting in drafts/ (itd-60's deterministic docs lint is live as abcd docs lint; itd-85's delivery is on main). Phase 8's expectation is that the record is the shipped state, and these are shipped capabilities the record does not name as intents, so a product thinker reading the brief and the intents together still cannot see them as delivered. Directions, none adopted: file a shipped intent per capability by hand with an audit note saying it was delivered before the ceremony existed; or list them in the Phase 8 file as pre-ceremony deliveries and leave the intents as is; or resolve the gap through the doc-fidelity gate itself once it exists, since it will name every surface the brief describes without an intent.
iss-2609252053576085The build's open_questions check (intent.OpenQuestions, read by internal/core/implement/loop/check.go) counts every list item under '## Open Questions' as a question whatever it says, so it refuses records that follow the record's own settled convention: 12 of 50 planned intents carry list items there, and some are settled by their own words, itd-111's section opening '_All resolved or explicitly deferred at planning_' and itd-93's '_All four resolved_', itd-76's item marked '**explicitly deferred**', itd-60's items marked '**Resolved', itd-117's '**Deferred**' items. 'abcd build next' (itd-2609211116005482) would meet refusals nobody planned, and the ruling lives only in a lane report. Keep the check fail-closed, but read the markers the record actually uses.
iss-2609300839021188Twelve shipped surfaces have no brief chapter under 04-surfaces/ naming them: the verbs abcd rules, abcd spec and abcd spec close, and the agents cold-reading-comparative, cold-reading-detection, cold-reading-entailment, cold-reading-widening, graveyard-interpreter, press-release-composer, ruthless-reviewer, security-reviewer and sota-researcher. The doc-fidelity gate's layer 1 (itd-60) found them on its first run over this repository; they are recorded in the gate's baseline so spec close stays usable, which reports them on every run and refuses nothing for them.
iss-2610020728118137Both enforcement points of the doc-fidelity gate (itd-60, ac-1 and ac-4) skip the whole gate when the population is empty: enforceDocFidelity returns nil on len(population)==0 (internal/surface/cli/docfidelity.go:55) and the release emit runs docfidelity.Gate only inside 'if len(shipped) > 0' (internal/core/release/emit.go:272). So a spec close that ships no intent and, more consequentially, a release cut carrying only issue resolutions (a patch release) run neither layer, layer 1 included: a sub-verb or agent added by an issue fix in such a cut meets no coverage floor at the cut, while the spec says the deterministic floor 'is cheap enough to run at every enforcement point and in CI'. The bare 'abcd docs fidelity' with no --intent does run layer 1, so only the enforcement points have the gap.
iss-2610020728118183The doc-fidelity gate's layer 1 (itd-60, ac-1) counts 04-surfaces/README.md, the surfaces index, as a chapter: ReadInputs lists every regular *.md under 04-surfaces/ (internal/core/docfidelity/store.go:70) and names() accepts a code span in any of them, so at main 7fb52a6b5 the verb 'abcd spec', its sub-verb 'abcd spec close', the verb 'abcd rules' and the agent 'sota-researcher' pass the coverage floor on the README alone (abcd docs fidelity --json: coverage rows with chapter README.md), while no numbered chapter names them and no generated appendix (invariant 18) states their flags. A one-row index entry satisfies the floor for any new surface, which is the placeholder the spec's 'named by a chapter under 04-surfaces/' exists to refuse.
iss-2610020728128805Ruling DR3, on which the doc-fidelity gate's shape rests (itd-60, ac-2: the semantic layer is a saved receipt for HEAD that spec close and launch ship find automatically, rather than a review invoked at the close), is cited by three source files (internal/core/docfidelity/store.go:4, internal/core/docfidelity/docfidelity.go:14, internal/core/lint/gatereceipt.go:10) but recorded nowhere in the committed record: the 2026-09-30 entry [dcn-2609300000000009](../../decisions/dcn-2609300000000009-the-person-answered-eighteen-rulings-of.md) restates DR1, DR2, DR4, DR5 and DR6 and skips DR3, whose text lives only in a local-tier rulings file this checkout cannot cite. The fidelity audit of itd-60 therefore grades ac-2 as a signed-off divergence on the strength of an uncommitted ruling; a reader of the record alone cannot see why the gate reads a receipt instead of running the reviewer.
iss-2610021446271464The site's landing page composes its hero quote from the press release of the newest shipped intent whose fidelity audit is MET (internal/core/site/compose.go:1251 newestMetIntent, 1153), and the first ingested audit of itd-60 (shipped 2026-09-30, two days after the role-vocabulary sweep b4df4f25d, which rewrote no intent body) makes that intent the hero: its press release says 'flags it for the maintainer to read', so 'abcd lint site' refuses the render with roles/retired-role-word on index.html and the site-render gate of make preflight exits 2 on a branch that only recorded the audit (chore/audit-v012-gaps at 373d8b5f9, over main 7fb52a6b5). The sweep intent itd-2609212137129937 scoped intent bodies out, yet a press release is abcd's own text the moment the composer renders it publicly; the retired word stands nine times in itd-60 and ten in the sweep intent's own record, so any later MET audit of an intent carrying it reproduces the refusal, and the landing page's text is decided by which audit was ingested last rather than by a guarded source.
iss-2610021502084298No check meets the retired role word in an intent's press release at the record: the docs-lint rule roles/retired-role-word roots at the docs, the command pages and the rules, so a shipped or planned intent's press release carrying it is refused only when the site composer renders it as the landing page's hero quote, which is how itd-60's first MET audit broke the site-render gate (iss-2610021446271464). After the R5 reword of itd-60, thirteen shipped press releases still carry the word (itd-65, itd-66, itd-67, itd-69, itd-73, itd-74, itd-93, itd-102, itd-111, itd-114, itd-125, itd-2609111003026787, itd-2609212137129937), so the next MET audit ingested for any of them refuses the render again on a branch that only recorded an audit; the product thinker's ruling R5 (2026-10-02) accepted that a future slip breaks the build and did not ask for this check. Related to iss-2610020731591808, which names the brief, the principles and the personas registry as swept but unguarded.
iss-261025221529948704-universal-patterns.md:144-154 calls doc-fidelity 'planned under draft intent itd-60 … not yet built', keyed `logs/doc-fidelity/<input_fingerprint>/`; itd-60 is in intents/shipped/, and the gate saves `.abcd/.work.local/doc-fidelity/<commit>/doc-fidelity.json` (internal/core/docfidelity/store.go:32-35)
iss-2610262030559592The mental model calls the itd-60 doc-fidelity loop planned and not yet exercised; the docs chapter describes the itd-60 doc-fidelity gate as a working gate in the present tense.
iss-2610262033335346The intent chapter runs the doc-fidelity gate on every close that ships an intent, while universal patterns calls that pass a draft that is not yet built.
iss-2610262035265656The docs chapter ships the itd-60 doc-fidelity gate, saving receipts keyed by commit; universal patterns calls the itd-60 pass a draft that is not yet built, keyed by input fingerprint.
iss-2610262036509587itd-65 calls its change-narration detector the `doc_fidelity` surface; the docs chapter uses doc-fidelity for the gate that checks the brief against the shipped surface
iss-2610262039169067itd-61 says abcd already carries built reality forward into the brief (itd-60), but universal patterns says that forward pass is planned and not yet built
iss-2610262043106501The brief-realisation draft treats the brief as the target design in the present tense; itd-147 sequences the brief as the shipped state.
itd-1Every Intent Has Acceptance Criteria; Every Audit Verifies Them
itd-147The brief's surface chapters are a generated reflection of the shipped surface, so a shape claim cannot drift