From b08feb06469c211165a3eebf758982d7ce4c4528 Mon Sep 17 00:00:00 2001 From: REPPL <77722411+REPPL@users.noreply.github.com> Date: Thu, 29 Oct 2026 02:58:57 +0000 Subject: [PATCH 1/4] docs: record the ADR for one home of behaviour, and file the brief rewrite The product thinker's rulings of 2026-10-27 (dcn-2610271112331508, dcn-2610271112339516, dcn-2610271112330235) reverse two accepted rules, and they are one coupled change, so one ADR records both: - adr-2610290238168123: each command's behaviour lives once, in its command page, which the documentation-fidelity check reads; the brief states the design and why, as the target design with a status tag where built. It supersedes adr-2609231028044006, whose shape rule (the generated appendix, prose that states no flag or sub-verb) it carries forward unchanged. - The brief-size study of 2026-10-25 moves into the research notes as the ADR's evidence, with the outcome of its three rulings. - itd-2610290239150589 is the draft intent for the rewrite itself, which the 45 consistency majors deferred past v0.15.1 wait on. The filing match proposed refines links to two unrelated records; both were removed. The ADR index is regenerated. Assisted-by: Claude:claude-opus-5-5 --- ...urface-chapter-shape-claims-are-derived.md | 4 +- ...he-brief-states-the-design-and-why-each.md | 90 +++++++++ .abcd/development/decisions/adrs/README.md | 3 +- ...9-the-brief-reads-as-the-design-and-why.md | 56 ++++++ .../notes/2026-10-25-brief-size-study.md | 176 ++++++++++++++++++ 5 files changed, 326 insertions(+), 3 deletions(-) create mode 100644 .abcd/development/decisions/adrs/2610290238168123-the-brief-states-the-design-and-why-each.md create mode 100644 .abcd/development/intents/drafts/itd-2610290239150589-the-brief-reads-as-the-design-and-why.md create mode 100644 .abcd/development/research/notes/2026-10-25-brief-size-study.md diff --git a/.abcd/development/decisions/adrs/2609231028044006-surface-chapter-shape-claims-are-derived.md b/.abcd/development/decisions/adrs/2609231028044006-surface-chapter-shape-claims-are-derived.md index d0a5980e4d..fc62742048 100644 --- a/.abcd/development/decisions/adrs/2609231028044006-surface-chapter-shape-claims-are-derived.md +++ b/.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] diff --git a/.abcd/development/decisions/adrs/2610290238168123-the-brief-states-the-design-and-why-each.md b/.abcd/development/decisions/adrs/2610290238168123-the-brief-states-the-design-and-why-each.md new file mode 100644 index 0000000000..ee752fdd4e --- /dev/null +++ b/.abcd/development/decisions/adrs/2610290238168123-the-brief-states-the-design-and-why-each.md @@ -0,0 +1,90 @@ +--- +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 filed 1,301 records over the brief and the intents, most of them +from that second copy. + +## Decision + +The product thinker ruled on 2026-10-27 (dcn-2610271112331508, +dcn-2610271112339516, dcn-2610271112330235): + +1. **Always a single source of truth.** Every fact, rule, behaviour and list has + one home; every other place points to it. +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: "always SSOT". +- **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. diff --git a/.abcd/development/decisions/adrs/README.md b/.abcd/development/decisions/adrs/README.md index 24606ad79d..e23b3c3cba 100644 --- a/.abcd/development/decisions/adrs/README.md +++ b/.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 | diff --git a/.abcd/development/intents/drafts/itd-2610290239150589-the-brief-reads-as-the-design-and-why.md b/.abcd/development/intents/drafts/itd-2610290239150589-the-brief-reads-as-the-design-and-why.md new file mode 100644 index 0000000000..4bc79e5d81 --- /dev/null +++ b/.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, most from that second copy, and 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 always-SSOT 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. diff --git a/.abcd/development/research/notes/2026-10-25-brief-size-study.md b/.abcd/development/research/notes/2026-10-25-brief-size-study.md new file mode 100644 index 0000000000..c44904f8b7 --- /dev/null +++ b/.abcd/development/research/notes/2026-10-25-brief-size-study.md @@ -0,0 +1,176 @@ +# Is a brief this size required? A single-source-of-truth study of `.abcd/development/brief/` + +Date: 2026-10-25. Tree: origin/main `2e03c61e4`. Asked for by the product thinker during the +low-CPU run of 2026-10-25. The readers' raw outputs (the brief they were given, the section +groups, one classification file per reader and the shingle comparison) were kept on the machine +that ran the study, not in the record; this note is their synthesis. It is the evidence for +adr-2610290238168123. + +**Outcome.** The product thinker ruled all three on 2026-10-27: R1 answer A, the command page is the +home of behaviour (dcn-2610271112339516); R2 and R3 as recommended, under the standing rule that +everything has one home (dcn-2610271112331508). + +## The answer + +**Not at this size.** The brief holds about 247,000 words over 116 pages. Thirteen +read-only readers classified every section against the files that state the same thing. +They put about **170,000 words (69%) as removable**: restated elsewhere (and replaceable by +a pointer), history that ADRs and git already hold, or stale text that is wrong today. +Only about 31,000 words (13%) are the brief's own: rationale held nowhere else (13,600) and +current behaviour no other prose file states (17,600). + +The size is not a style problem. It is a second copy problem. **Verb behaviour has two +hand-maintained homes:** + +- the brief's surface chapters (`04-surfaces/`, 159,000 words, 76% removable); +- the command pages (`commands/*.md`, 132,000 words). + +No rule says which one is the source of truth. They have drifted apart in both directions. + +## Two tests + +1. **Verbatim (cheap, mechanical).** Ten-word shingles of every brief page were compared + with `commands/`, `docs/`, the ADRs, `agents/`, the principles, the intents and the root + files. Only **15%** of the brief repeats another file word for word (4% another brief + page, 2% a command page), so the duplication is not copy-paste. +2. **Paraphrase (13 readers, one or more chapters each).** Each section was classified as + restates, conflicts, unique-rationale, unique-behaviour, history or stale, with its + counterpart cited as `path:line`. This found the duplication the shingles cannot: + +| Class | Words | Share | +|---|---|---| +| restates another file | 165,742 | 69% | +| unique behaviour | 17,558 | 7% | +| unique rationale | 13,604 | 6% | +| conflicts with a counterpart or the code | 10,649 | 4% | +| stale (the code moved) | 8,356 | 3% | +| history (belongs to git or an ADR, per adr-5) | 7,359 | 3% | +| not assessed (security) | 18,018 | 7% | + +By folder: + +| Folder | Pages | Words | Removable | +|---|---|---|---| +| 04-surfaces | 35 | 159,219 | 121,603 (76%) | +| 05-internals | 11 | 35,020 | 19,743 (56%) | +| glossary | 47 | 19,690 | 6,483 (33%) | +| 02-constraints | 5 | 12,367 | 7,417 (60%) | +| 06-delivery | 4 | 10,163 | 8,825 (87%) | +| 01-product | 7 | 6,637 | 4,535 (68%) | +| 03-evidence | 5 | 2,332 | 1,116 (48%) | +| README and 00-meta | 2 | 1,884 | 622 (33%) | + +Largest single cuts: `05-intent.md` 14,030 of 17,296; `01-ahoy.md` 12,150 of 14,737; +`34-build.md` 8,866 of 10,269; `04-launch.md` 8,838 of 10,510; `03-configuration.md` +7,000 of 13,860; `35-drain.md` 6,774 of 7,973; `17-guard.md` 6,677 of 10,018; +`06-capture.md` 6,460 of 7,045; `08-abcd.md` 6,260 of 6,728; `27-implement.md` 5,765 of +6,641; `06-delivery/02-verification-matrix.md` 4,532 of 5,295. + +## The structural finding + +Every surface reader reached the same conclusion independently. These rules make the +chapter the home for behaviour: + +- "a chapter is where a claim about behaviour belongs" (`04-surfaces/README.md:3-7`); +- adr-2609231028044006:102: behavioural claims stay hand-maintained in the chapter; +- invariant 18 (`02-constraints/03-invariants.md:173`); +- the generated appendix's "behaviour is the prose's to state" (`internal/core/surface/appendix.go:54`). + +**None of them says anything about the command pages**, which state the same behaviour +in full, for the agents that actually run the verbs. + +The two homes are not equal: + +- **The brief chapter is the gated copy.** The doc-fidelity gate (`04-surfaces/10-docs.md:66-82`, + `commands/docs.md:92`) checks it against the code, and a false sentence there holds a + spec close or a release cut. +- **The command page is the operative copy, and nothing checks it.** Agents load and + follow it. Several readers found it wrong where the brief was right (for example + `commands/intent.md:232`, `commands/launch.md:533`). +- **Equally often the brief is the stale one** (the ahoy uninstall and re-founding passages, + `34-build.md` on hooks and validators, `17-guard.md`'s carried-value example, the + superseded itd-20, itd-27, itd-33 and itd-72 designs still staged). + +Two copies maintained by hand, with a gate on only one, drift by construction. + +## Rulings needed (recommended answers first among the options, as reasons) + +### R1. Which file is the single home of a verb's behaviour? + +The thing being decided: today `04-surfaces/-.md` and `commands/.md` +both state each verb's behaviour (refusals, exit codes, outputs, sequences) in full prose, +and the fidelity gate checks only the first. + +- **A. The command page is the home.** The chapter keeps why the surface exists, the + trade-offs, what is refused and why, its `## Sub-verbs` table and its generated appendix, + and points to the command page for behaviour. The doc-fidelity gate moves to the command + pages (and `docs/`). +- **B. The chapter is the home.** The command page keeps only the agent's operating steps + and points to the chapter for behaviour. +- **C. Keep both, and add a gate** that reads the two against each other. +- **Decide later.** + +Recommended: **A.** The command page is the one agents execute, so making it the gated +copy puts the check where a falsehood does harm. It is already the fuller copy for most +verbs (`commands/reading.md`, `commands/capture.md`, `commands/implement.md` cover more +than their chapters). And B would strip the page an agent loads of what it needs to act. +C doubles the maintenance the readers measured instead of removing it. A reverses the +behaviour half of adr-2609231028044006 and invariant 18, so it needs a superseding ADR, +not a silent edit. + +### R2. What happens to the other brief-wide copies? + +These need no new rule beyond adr-5 ("history lives in git; inflection rationale in +ADRs"), so the recommended answers follow from it: + +- **Invariants** (`02-constraints/03-invariants.md`): 21 of 24 restate their ADR at + paragraph length. Reduce each to one line naming the rule and its ADR. +- **The verification matrix** (`06-delivery/02-verification-matrix.md`, 4,532 of 5,295 + removable): its rows paraphrase command pages and name no test. Generate it from the + tests, or remove it. +- **Out of scope** (`06-delivery/03-out-of-scope.md`): mostly a generated copy of the + draft intents' titles (the shingle pass found 38% verbatim). Generate it, or point to the + drafts shelf. +- **The machine-folder inventory**, kept twice (`01-ahoy.md:419-522` and + `03-configuration.md:621-692`, each saying the two are one list): keep one copy. +- **Superseded designs still staged** (itd-20, itd-27, itd-33, itd-72, the grill and PRD + material, the retired phase vocabulary): delete them, since git and the ADRs keep the + history. + +### R3. Does the glossary stay as it is? + +The glossary is the least duplicated folder (33%). It is the canonical terminology store, +and most of its 47 pages are their own home. Recommended: keep it, and fix the 17 entries +S11 found out of date or contradictory (spec, record, voyage, loop, transport, +reading-position, and the retired phase, roadmap and milestone bodies). + +## What a smaller brief would hold + +On the readers' figures, the brief after R1 and R2 is about 70,000 to 80,000 words. + +- **Kept:** the product chapters, the constraints as one-line rules with their ADRs, the + glossary, and each surface chapter's purpose, trade-offs and refusal reasons, with its + `## Sub-verbs` table and generated appendix. +- **Reached by a pointer:** everything else, now held in the command pages, the ADRs, the + code's doc comments and git. + +That fits one reader's context window, where today's corpus needs 66 chunks for a single +consistency pass (the 2026-10-26 pass over the brief and every intent). It also cuts the second copy that causes most of the +`inconsistency` findings the ledger keeps receiving. + +## Findings + +The readers recorded **125 findings** (117 minor, 8 nitpick). These are conflicts and stale +passages in the brief, in command pages and in a few code comments. About 15 are already +held by open records, and the readers named those. The rest were filed with `abcd capture` on +2026-10-25, deduplicated against the ledger. Security sections (122) were counted and not +assessed. + +## Limits of the measure + +- "Removable" is each reader's estimate, section by section. It counts conflict and stale + text, which should be fixed at its single home rather than simply deleted. +- It does not count the generated appendices, which adr-2609231028044006 requires. +- A section the reader called "restates" was checked against a named counterpart, but + nobody re-read the counterpart to confirm that every clause survives. R1's change should + move the few unique sentences (each reader named them) before it deletes anything. From 70ee587e49abacae38c2ee48e685d1c09c825550 Mon Sep 17 00:00:00 2001 From: REPPL <77722411+REPPL@users.noreply.github.com> Date: Fri, 30 Oct 2026 01:20:46 +0000 Subject: [PATCH 2/4] docs: say what the consistency pass compared, in the ADR and the rewrite intent Both said most of the pass's 1,301 records came from the command chapters' second copy. The pass read the brief and the intents against each other and compared no command page; what its summary supports is that 1,080 of its 1,307 findings had a passage of the brief at one end. The ADR's rejected alternative also cited the ruling in a quoted phrase; it now names the ruling's first point instead. Assisted-by: Claude:claude-opus-5-5 --- ...90238168123-the-brief-states-the-design-and-why-each.md | 7 ++++--- ...10290239150589-the-brief-reads-as-the-design-and-why.md | 4 ++-- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/.abcd/development/decisions/adrs/2610290238168123-the-brief-states-the-design-and-why-each.md b/.abcd/development/decisions/adrs/2610290238168123-the-brief-states-the-design-and-why-each.md index ee752fdd4e..e37d142b00 100644 --- a/.abcd/development/decisions/adrs/2610290238168123-the-brief-states-the-design-and-why-each.md +++ b/.abcd/development/decisions/adrs/2610290238168123-the-brief-states-the-design-and-why-each.md @@ -32,8 +32,9 @@ that costs. The brief held about 247,000 words; readers put about 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 filed 1,301 records over the brief and the intents, most of them -from that second copy. +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 @@ -67,7 +68,7 @@ above it states none. `TestSurfaceAppendicesMatchCommandTree` and 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: "always SSOT". + 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 diff --git a/.abcd/development/intents/drafts/itd-2610290239150589-the-brief-reads-as-the-design-and-why.md b/.abcd/development/intents/drafts/itd-2610290239150589-the-brief-reads-as-the-design-and-why.md index 4bc79e5d81..6b7f8609d4 100644 --- a/.abcd/development/intents/drafts/itd-2610290239150589-the-brief-reads-as-the-design-and-why.md +++ b/.abcd/development/intents/drafts/itd-2610290239150589-the-brief-reads-as-the-design-and-why.md @@ -22,7 +22,7 @@ production_mode: hand-written ## 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, most from that second copy, and 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. +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 @@ -32,7 +32,7 @@ We expect moving each behaviour claim to its command page, and checking the page - **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 always-SSOT 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 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. From eaa80a70ee8d971f57d02fc8da2e91c3ddd59803 Mon Sep 17 00:00:00 2001 From: REPPL <77722411+REPPL@users.noreply.github.com> Date: Fri, 30 Oct 2026 01:20:48 +0000 Subject: [PATCH 3/4] docs: file the rules-domain paths that nothing resolves A rules domain names its home with a bare path, and the link check reads markdown links only, so a renamed principle leaves a dead pointer that the loader keeps injecting while every check stays green. Refs: iss-2610300120250873 Assisted-by: Claude:claude-opus-5-5 --- ...50873-rules-domain-paths-are-never-resolved.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 .abcd/work/issues/open/iss-2610300120250873-rules-domain-paths-are-never-resolved.md diff --git a/.abcd/work/issues/open/iss-2610300120250873-rules-domain-paths-are-never-resolved.md b/.abcd/work/issues/open/iss-2610300120250873-rules-domain-paths-are-never-resolved.md new file mode 100644 index 0000000000..28059e9e60 --- /dev/null +++ b/.abcd/work/issues/open/iss-2610300120250873-rules-domain-paths-are-never-resolved.md @@ -0,0 +1,15 @@ +--- +schema_version: 1 +id: "iss-2610300120250873" +slug: "rules-domain-paths-are-never-resolved" +severity: "minor" +category: "tech-debt" +source: "review-followup" +found_during: "one-home principle review (PR #1243), 2026-10-30" +origin: researcher-authored +production_mode: hand-written +found_at: "internal/core/rules/defaults/rules.json" +remedy: "Add a lint that resolves every repository path named in a rules domain (the bundled defaults in internal/core/rules/defaults/rules.json and a repository's own .abcd/rules.json) and fails on one that does not exist, so a moved home breaks the check that names its pointer." +--- + +A rules domain points at its home with a bare repository path, and nothing checks that the path still resolves. The link check reads markdown links only, and the one test that reads an OPINIONS path checks the users-directory principle alone. So renaming or moving a principle leaves its OPINIONS rule pointing at a file that is gone, the loader keeps injecting the dead pointer into every matching prompt, and every check stays green. From 28a716f29375ef7c9cb0864a986a5e9452703bd8 Mon Sep 17 00:00:00 2001 From: REPPL <77722411+REPPL@users.noreply.github.com> Date: Fri, 30 Oct 2026 03:08:54 +0000 Subject: [PATCH 4/4] docs: point the one-home ruling and the ADR at their homes instead of restating them The decision kept the brief-specific answers of the ruling because the rewrite intent that carries them was not yet in the record; it now is, so the decision points to the intent's scope and to the study, and keeps the dated event. The ADR's first decision restated the rule the principle holds, and now names the principle. Assisted-by: Claude:claude-opus-5-5 --- ...0290238168123-the-brief-states-the-design-and-why-each.md | 5 +++-- ...10271112331508-the-product-thinker-ruled-on-2026-10-27.md | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/.abcd/development/decisions/adrs/2610290238168123-the-brief-states-the-design-and-why-each.md b/.abcd/development/decisions/adrs/2610290238168123-the-brief-states-the-design-and-why-each.md index e37d142b00..5f02a31f67 100644 --- a/.abcd/development/decisions/adrs/2610290238168123-the-brief-states-the-design-and-why-each.md +++ b/.abcd/development/decisions/adrs/2610290238168123-the-brief-states-the-design-and-why-each.md @@ -41,8 +41,9 @@ end. The product thinker ruled on 2026-10-27 (dcn-2610271112331508, dcn-2610271112339516, dcn-2610271112330235): -1. **Always a single source of truth.** Every fact, rule, behaviour and list has - one home; every other place points to it. +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 diff --git a/.abcd/work/decisions/dcn-2610271112331508-the-product-thinker-ruled-on-2026-10-27.md b/.abcd/work/decisions/dcn-2610271112331508-the-product-thinker-ruled-on-2026-10-27.md index 6a3250bc81..9a34f34a69 100644 --- a/.abcd/work/decisions/dcn-2610271112331508-the-product-thinker-ruled-on-2026-10-27.md +++ b/.abcd/work/decisions/dcn-2610271112331508-the-product-thinker-ruled-on-2026-10-27.md @@ -3,4 +3,4 @@ id: dcn-2610271112331508 slug: the-product-thinker-ruled-on-2026-10-27 date: 2026-10-27 --- -2026-10-27 — The product thinker ruled that every claim in the record has a single home, and settled the brief-size study's second question with its recommended answers. The rule and its bounds now live in [every claim has one home](../../development/principles/every-claim-has-one-home.md). For the brief, the ruling means: 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; the machine-folder inventory keeps one copy; superseded designs still staged in the brief are deleted, with git and the ADRs keeping their history; and the glossary stays the one home for terms. +2026-10-27 — The product thinker ruled that every claim in the record has a single home, and settled the second question of the [brief-size study](../../development/research/notes/2026-10-25-brief-size-study.md) with its recommended answers. The rule and its bounds live in [every claim has one home](../../development/principles/every-claim-has-one-home.md); what the ruling means for the brief, answer by answer, is in the scope of the brief-rewrite intent, itd-2610290239150589.