docs: record the ADR for one home of behaviour, and file the brief rewrite

.abcd/development/decisions/adrs/2609231028044006-surface-chapter-shape-claims-are-derived.md

@@ -1,10 +1,10 @@
 ---
 id: adr-2609231028044006
 slug: surface-chapter-shape-claims-are-derived
-status: accepted
+status: superseded
 date: 2026-09-23
 supersedes: null
-superseded_by: null
+superseded_by: adr-2610290238168123
 related_intents: [itd-147]
 related_rfcs: []
 related_adrs: [adr-30, adr-40]

.abcd/development/decisions/adrs/2610290238168123-the-brief-states-the-design-and-why-each.md

@@ -0,0 +1,92 @@
+---
+id: adr-2610290238168123
+slug: the-brief-states-the-design-and-why-each
+status: accepted
+date: 2026-10-29
+supersedes: adr-2609231028044006
+superseded_by: null
+related_intents: [itd-147, itd-60, itd-2610290239150589]
+related_rfcs: []
+related_adrs: [adr-2609231028044006, adr-5]
+---
+
+# ADR-2610290238168123: The brief states the design and why; each command's page states what abcd does, once, and is the copy checked against the code
+
+## Context
+
+Each abcd command's behaviour (what it refuses, what it prints, the steps it takes,
+its exit codes) was written out twice by hand: in the brief's chapter for the
+command under `04-surfaces/`, and in the command page under `commands/` that an
+agent loads and follows when it runs the command. adr-2609231028044006 settled
+the shape half of a chapter (flags and sub-verbs come from a generated appendix,
+and the prose states none) and left behaviour "hand-maintained", as "a
+review-grain claim", in the chapter. The documentation-fidelity gate of itd-60
+checks the brief against the code; nothing checks the command pages. itd-147 and
+itd-60 made the brief the shipped state.
+
+The brief-size study of 2026-10-25
+(`.abcd/development/research/notes/2026-10-25-brief-size-study.md`) measured what
+that costs. The brief held about 247,000 words; readers put about
+69% of it as restating another file, and the command chapters alone at 76%
+(about 121,000 words). Only about 15% repeated another file word for word, so
+the duplication was paraphrase, not copy-paste, and the two copies had drifted
+apart in both directions: some command pages were wrong where the chapter was
+right, and some chapters wrong where the page was right. The consistency pass
+of 2026-10-26 read the brief and the intents against each other and filed
+1,301 records; 1,080 of its 1,307 findings had a passage of the brief at one
+end.
+
+## Decision
+
+The product thinker ruled on 2026-10-27 (dcn-2610271112331508,
+dcn-2610271112339516, dcn-2610271112330235):
+
+1. **Every claim has one home**, as the principle
+   [every claim has one home](../../principles/every-claim-has-one-home.md)
+   states.
+2. **A command's behaviour lives in its command page.** The page under
+   `commands/` is the one home of what the command does: its refusals, its
+   output, its steps and its exit codes. The documentation-fidelity check moves
+   to the command pages: a false sentence there holds a spec close and a release
+   cut, as a false sentence in the brief does today.
+3. **The brief states the design and why.** Each chapter under `04-surfaces/`
+   keeps why the command exists, the trade-offs taken and why it refuses what it
+   refuses, its `## Sub-verbs` table and its generated appendix, and points to
+   the command page for behaviour. The brief as a whole states the target design
+   in the present tense; a part that is built carries a status tag saying so,
+   rather than an unbuilt part being marked as staged.
+
+The shape rule of adr-2609231028044006 is carried forward unchanged: every flag
+and sub-verb a chapter states comes from its generated appendix, and the prose
+above it states none. `TestSurfaceAppendicesMatchCommandTree` and
+`TestSurfaceChapterProseStatesNoShape` keep holding it.
+
+## Alternatives Considered
+
+- **The chapter as the home, with the command page keeping only the agent's
+  steps.** Keeps the design record complete in one place, but the copy agents
+  follow loses what they need to act, and the copy that does harm when wrong
+  stays unchecked. Rejected by the ruling.
+- **Both copies, and a check that reads each pair against the other.** Moves
+  nothing, but every change is still written twice and the measured upkeep
+  stays. Rejected by the ruling's first point.
+- **The brief as the shipped state, unbuilt parts marked (itd-147, itd-60).**
+  Kept checkable against the code, but once behaviour moves to the command pages
+  the brief has nothing left to check against the code, and the person wants it
+  to read as the product they are building. Superseded.
+
+## Consequences
+
+- The behaviour passages of every `04-surfaces/` chapter move to their command
+  page, or are cut where the page already says it; this is the brief's
+  single-home rewrite the 45 deferred consistency majors wait on.
+- The documentation-fidelity gate, its review instructions and its receipts read
+  the command pages, and no longer the brief, for claims about behaviour.
+- itd-147's and itd-60's statement that the brief is the shipped state, the
+  phase document that says so (`roadmap/phases/phase-8-brief-currency.md`), and
+  invariant 18's wording are amended by the rewrite, pointing here.
+- adr-5 ("the brief is the project's current state") still holds: the target
+  design is the decided state. The truth rule in `00-meta.md` changes its one
+  variance from "shipped vs staged" to "built or not yet", tagged on the built.
+- A command page now carries the claims the gate checks, so its prose is held to
+  the same review grain as a chapter's was.

.abcd/development/decisions/adrs/README.md

@@ -188,7 +188,7 @@ The intent lint (a Go implementation) extends to verify these reciprocally.
 | [adr-2609212115255771](2609212115255771-phases-and-milestones-are-retired.md) | Phases and milestones are retired: sequencing is dependencies rendered as status, the checkpoint is the derived release (supersedes adr-9; superseded by adr-2609292012006845) | superseded | 2026-09-21 |
 | [adr-2609221009491186](2609221009491186-a-provider-adapter-serves-only-the.md) | A provider adapter serves only the models it lists, under a vendor denylist no listing overrides; everything else runs on the host (superseded by adr-2609300107513982) | superseded | 2026-09-22 |
 | [adr-2609221017021499](2609221017021499-every-external-credential-abcd-holds-is.md) | Every external credential abcd holds is named in configuration and kept in one store the person chose; never the harness, never the repository | accepted | 2026-09-22 |
-| [adr-2609231028044006](2609231028044006-surface-chapter-shape-claims-are-derived.md) | Shape claims in the brief's surface chapters are derived, never hand-authored | accepted | 2026-09-23 |
+| [adr-2609231028044006](2609231028044006-surface-chapter-shape-claims-are-derived.md) | Shape claims in the brief's surface chapters are derived, never hand-authored (superseded by adr-2610290238168123) | superseded | 2026-09-23 |
 | [adr-2609231048308186](2609231048308186-the-catalog-pins-the-latest-release-s.md) | The catalog pins the latest release's plugin archive | accepted | 2026-09-23 |
 | [adr-2609291342092738](2609291342092738-a-drain-takes-an-issue-alone-only-when.md) | A drain takes an issue alone only when its fields say it needs no decision | accepted | 2026-09-29 |
 | [adr-2609292012006845](2609292012006845-now-next-and-later-list-an-intent-in-a.md) | Now, Next and Later list an intent in a lane under Now only; phases stay retired (supersedes adr-2609212115255771) | accepted | 2026-09-29 |
@@ -232,5 +232,6 @@ The intent lint (a Go implementation) extends to verify these reciprocally.
 | [adr-2610241057124151](2610241057124151-abcd-installs-the-tools-it-needs-from.md) | abcd installs the tools it needs from downloads pinned in its own release | accepted | 2026-10-24 |
 | [adr-2610241101463288](2610241101463288-setup-asks-short-questions-and-lists-its.md) | Setup asks short questions and lists its defaults on one plan | accepted | 2026-10-24 |
 | [adr-2610281718537125](2610281718537125-a-release-publishes-with-no-approval.md) | A release publishes with no approval step | accepted | 2026-10-28 |
+| [adr-2610290238168123](2610290238168123-the-brief-states-the-design-and-why-each.md) | The brief states the design and why; each command's page states what abcd does, once, and is the copy checked against the code (supersedes adr-2609231028044006) | accepted | 2026-10-29 |
 | [adr-2610291037481588](2610291037481588-the-contributors-page-counts-people-and.md) | The contributors page counts people and names none | accepted | 2026-10-29 |
 <!-- /index -->

.abcd/development/intents/drafts/itd-2610290239150589-the-brief-reads-as-the-design-and-why.md

@@ -0,0 +1,56 @@
+---
+id: itd-2610290239150589
+slug: the-brief-reads-as-the-design-and-why
+spec_id: null
+kind: null
+suggested_kind: null
+reclassification_history: []
+builds_on: []
+related_adrs: [adr-2610290238168123]
+severity: major
+origin: researcher-authored
+production_mode: hand-written
+---
+
+# The brief reads as the design and why, and each command's behaviour is written once, in the page agents follow
+
+## Press Release
+
+> **abcd's brief now reads as the product being built and the reasons for it, and every command's behaviour is written once, in the command page an agent follows when it runs the command.** A product thinker opening a command's chapter finds why the command exists, the trade-offs taken and why it refuses what it refuses, with a pointer to the page for exactly what it does. The page is the copy the documentation check now reads against the code, so the copy that does harm when it is wrong is the one that cannot drift unnoticed. The brief shrinks by about two-thirds, and a second hand-kept copy no longer exists to contradict the first.
+>
+> "I used to find the same rule written three ways and no way to tell which one the agents were following," said a product thinker who read the brief after a consistency pass filed thirteen hundred conflicts. "Now the brief tells me what we are building and why, and when I want to know exactly what a command does, it sends me to the one place that says so."
+
+## Why This Matters
+
+The brief-size study of 2026-10-25 measured the brief at about 247,000 words, about 69% of it restating another file; the command chapters alone were 76% restatement (about 121,000 words), and the paraphrased copies had drifted apart in both directions. The 2026-10-26 consistency pass filed 1,301 records, and 1,080 of its 1,307 findings had a passage of the brief at one end; 45 major ones are deferred until this rewrite lands. The product thinker ruled on 2026-10-27 that everything has one home (dcn-2610271112331508), that behaviour lives in the command page (dcn-2610271112339516) and that the brief states the target design (dcn-2610271112330235); the ADR that records the reversal is adr-2610290238168123.
+
+## Mechanism
+
+We expect moving each behaviour claim to its command page, and checking the pages against the code instead of the brief, to remove the class of contradiction the pass found, because a claim with one home has nothing to disagree with.
+
+## What's In Scope
+
+- **The command chapters**: each chapter under `04-surfaces/` keeps why the command exists, its trade-offs, why it refuses what it refuses, its `## Sub-verbs` table and its generated appendix; each behaviour passage moves to the command page under `commands/`, or is cut where the page already says it, keeping any sentence only the chapter held.
+- **The documentation-fidelity check** reads the command pages for behaviour claims, its review instructions and receipts with it.
+- **The brief's other copies**, as the one-home ruling settles: invariants become one line naming the rule and its ADR; the verification matrix is generated from the tests or removed; the out-of-scope list points to the drafts shelf; one machine-folder inventory; superseded designs still staged are deleted.
+- **The status overlay**: the brief states the target design in the present tense, and a built part carries a tag saying so; the truth rule in `00-meta.md` is amended to that one variance.
+- **The deferred consistency majors**: each of the 45 is resolved by the change that rewrites its passage, or closed if the passage is gone.
+
+## What's Out of Scope
+
+- The glossary, which stays the one home for terms (its 17 stale entries are fixed under their own records).
+- The generated appendices and the shape rule, which are unchanged.
+- `docs/`, the user-facing documentation, which has its own currency review.
+
+## Decisions
+
+1. **One home per claim** (dcn-2610271112331508).
+2. **The command page is the home of behaviour** (dcn-2610271112339516).
+3. **The brief is the target design with a status overlay** (dcn-2610271112330235).
+
+## Acceptance Criteria
+
+- **Given** a command chapter under `04-surfaces/`, **when** the rewrite lands, **then** it states no refusal, output, step or exit code that its command page does not hold, and it points to the page for behaviour.
+- **Given** a behaviour claim in a command page that the code contradicts, **when** the documentation-fidelity review runs, **then** the claim is a finding that holds a spec close and a release cut, as a false brief sentence does today.
+- **Given** the brief after the rewrite, **when** its words are counted, **then** it holds about a third of today's, and every section the brief-size study marked as restating another file is a pointer.
+- **Given** each of the 45 deferred consistency majors, **when** the rewrite lands, **then** it is resolved by the change that rewrote its passage, or closed because the passage is gone.