docs(authority): make final outputs canonical

.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Capstone: architecture reference docs for AI-first codebases",
-    "version": "5.2.0"
+    "version": "5.2.1"
   },
   "plugins": [
     {

.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "capstone",
   "displayName": "Capstone",
   "description": "Architecture reference generator: a lean docs/capstone/ index plus topic files stamped to the commit they were derived at, built and kept current by one command, map. Companion commands: doctor, an opt-in two-sided review, a greenfield pipeline from mockup to running code with a frontend-design stage, and a doc-grounded feature chain.",
-  "version": "5.2.0",
+  "version": "5.2.1",
   "author": {
     "name": "Gent Bajko",
     "email": "gent.bajko@gmail.com"

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "capstone",
-  "version": "5.2.0",
+  "version": "5.2.1",
   "description": "Architecture reference docs: a docs/capstone/ index plus topic files stamped to commits, built and kept current by one command, map, plus doctor/review, a greenfield pipeline from product mockup to running code with a frontend-design stage, and a doc-grounded feature chain.",
   "author": {
     "name": "Gent Bajko",

.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "capstone",
   "displayName": "Capstone",
   "description": "Architecture reference docs: a docs/capstone/ index plus topic files stamped to commits, built and kept current by one command, map, plus doctor/review, a greenfield pipeline from product mockup to running code with a frontend-design stage, and a doc-grounded feature chain.",
-  "version": "5.2.0",
+  "version": "5.2.1",
   "author": {
     "name": "Gent Bajko",
     "email": "gent.bajko@gmail.com"

.kimi-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "capstone",
   "displayName": "Capstone",
   "description": "Architecture reference docs: a docs/capstone/ index plus topic files stamped to commits, built and kept current by one command, map, plus doctor/review, a greenfield pipeline from product mockup to running code with a frontend-design stage, and a doc-grounded feature chain.",
-  "version": "5.2.0",
+  "version": "5.2.1",
   "author": {
     "name": "Gent Bajko",
     "email": "gent.bajko@gmail.com"

README.md

@@ -223,14 +223,14 @@ implementation plan, stops for your approval, then writes the code:
 one subagent per step with fresh context, or inline, whichever you
 pick when it starts.
 
-Between the two, the pipeline reads all six interviews back. It moves
-what landed in the wrong stage to the stage that owns it - a business
-rule the architecture interview happened to reach belongs to `logic` -
-and it raises what one stage decided that contradicts another. Neither
-check can be made by a single interview, because none of them can see
-the others. Same terms as everywhere else: evidence and a citation,
-two rounds at most, then your answer stands. It is the last point
-where either costs a paragraph instead of a rewrite.
+Between the two, the pipeline reads all six stages' final outputs. It
+moves what landed in the wrong file to the stage that owns it - a
+business rule in an architecture chapter belongs in `logic` - and
+raises contradictions between final files. Same terms as everywhere
+else: evidence and final-file citations, two rounds at most, then your
+answer stands. The corrected decisions and rationale are written into
+their owning final outputs; completed interview bodies are not read or
+amended.
 
 ## The feature chain
 

docs/commands.md

@@ -129,8 +129,8 @@ section. **Gitignored by default:** it is judgment, not reference.
 ### `start`
 
 Runs the seven stages in order, detecting what is finished and
-resuming at the first incomplete one, then reads every interview back
-before `build`. Also what a bare `capstone`
+resuming at the first incomplete one, then reconciles every final
+stage output before `build`. Also what a bare `capstone`
 triggers. On a repo that already has code it asks once whether you
 want the pipeline or `map`, and records the answer.
 
@@ -178,20 +178,19 @@ dead session loses nothing, and re-running never re-asks.
 - **`stack`** researches real options per capability with licenses and
   pricing; you pick. `stack refresh` re-vets recorded picks later.
   Ledger keys `stack/all@Q<n>` and `stack/refresh@Q<n>`.
-- **Between `stack` and `build`** the pipeline reads all six
-  interviews back, in two halves. First it **re-files what landed in
-  the wrong stage** against core.md's Stage ownership table - a
-  business rule settled in the architecture interview belongs to
-  `logic`, a library chosen in the standards interview belongs to
-  `stack` - as one digest you confirm, since nothing is being
-  re-decided, only moved. Then it **raises what one stage decided
-  that contradicts another**, the check no single interview can make,
-  since each sees only its own answers. Same terms as any interview's
-  pushback (core.md's Pushback rule): evidence and a citation, two
-  rounds at most, then your answer stands. Either way the affected
-  interviews are amended and their outputs regenerated without
-  re-interviewing. Ledger key `readback/all@Q<n>`; later runs see it
-  and skip.
+- **Between `stack` and `build`** the pipeline reads all six stages'
+  final outputs in two halves. First it **re-files what landed in the
+  wrong stage** against core.md's Stage ownership table - a business
+  rule in an architecture chapter belongs in `logic`, while a library
+  in `standards.md` belongs in `05-dependencies.md` - as one digest you
+  confirm, since nothing is being re-decided. Then it **raises what one
+  final output says that contradicts another**. Same terms as any
+  interview's pushback: evidence and final-file citations, two rounds
+  at most, then your answer stands. The affected final outputs, index,
+  stamps, and changelog entries are updated directly. Completed
+  interview bodies are not read or amended. Ledger key
+  `readback/all@<stamp>`; unchanged outputs produce the same stable
+  stamp and skip.
 - **`build`** requires a formalized `stack`. It writes an
   implementation plan, **stops for your approval**, then writes code -
   in subagents (fresh context per step) or inline, asked once before
@@ -300,6 +299,8 @@ out to subagents, and where an unrequested full build asks first.
 **Interview lifecycle.** `interviewing` → `awaiting-formalization` →
 `formalized`. The final state is written only *after* outputs are on
 disk, so a crash can never strand a "done" marker over missing files.
+After formalization, those outputs are the source of truth. Interviews
+remain local resume and repair state; final files never cite them.
 
 **The ledger.** Every run that writes appends to `changelog.md` before
 setting its done marker. Newest first, bullets only, append-only.

docs/flows.md

@@ -67,8 +67,8 @@ marked `mode: prescriptive` - decisions, not observations. Once any
 tracked source exists, such a file is stale *by definition*: the plan
 said where code was going to land, and code lands where it lands. The
 refresh rewrites it descriptively and records divergences as facts,
-citing both sides ("designed as X per `architecture-interview.md` §Q7,
-implemented as Y at `file:line`").
+preserving the design decision and rationale inline beside the observed
+implementation (`file:line`).
 
 **`map check` writes nothing**, including no changelog entry - nothing
 was done, only read. Six parts: staleness, pointer drift, absorption
@@ -90,28 +90,30 @@ Typing bare `capstone` runs this.
 | 4 | `architecture` | How the system is built | The 8 chapters, `mode: prescriptive` |
 | 5 | `standards` | How code is written here | `standards.md` |
 | 6 | `stack` | What it is built with | `05-dependencies.md` |
-| — | *readback* | Nothing. It re-files and reconciles what stages 1-6 recorded | Amended interviews |
+| — | *readback* | Nothing. It re-files and reconciles what stages 1-6 recorded | Amended final outputs |
 | 7 | `build` | The implementation plan, then the code | `implementation.md`, source |
 
 Each stage feeds the next, and skipping ahead is not possible: `uiux`
 requires a formalized `mockup`, `build` requires a formalized `stack`.
 
-**The readback, between `stack` and `build`.** No interview can see
-another's answers, which leaves two things nobody catches. It runs in
-two halves, misplacement first so the second cites final locations:
+**The readback, between `stack` and `build`.** Earlier stages cannot
+see every later final output, which leaves two things nobody catches.
+It runs in two halves, misplacement first so the second cites final
+locations:
 
 1. **Re-file.** Against core.md's Stage ownership table, every decision
-   whose subject belongs to another stage - a business rule settled in
-   the architecture interview, a library chosen in the standards one.
+  whose subject belongs to another stage - a business rule in an
+  architecture chapter, a library choice in `standards.md`.
    Re-filing is not re-deciding, so it arrives as one digest you
    confirm, not a finding per turn.
 2. **Reconcile.** Every decision contradicting one recorded elsewhere,
    raised one per turn with both citations, under the usual two-round
    cap. Then your answer stands.
 
-Either half amends the interview that gives way and regenerates its
-outputs - never a re-interview. The pass records itself under
-`readback/all`, so later runs see the key and skip.
+Either half amends the owning final outputs, their index boundaries,
+stamps, and changelog entries. Completed interview bodies are not read
+or amended. The pass records a stable hash of the six latest stage
+keys under `readback/all@<stamp>`, so unchanged outputs skip.
 
 **`build` is the only pipeline stage that writes source code**, and only
 after you approve its plan. `implementation.md` maps every scenario,

gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "capstone",
   "description": "Architecture reference docs: a docs/capstone/ index plus topic files stamped to commits, built and kept current by one command, map, plus doctor/review, a greenfield pipeline from product mockup to running code with a frontend-design stage, and a doc-grounded feature chain.",
-  "version": "5.2.0",
+  "version": "5.2.1",
   "contextFileName": "GEMINI.md"
 }

skills/core/references/arch-craft.md

@@ -132,7 +132,7 @@ suppress the smell), and **skip anything tooling already enforces**.
 4. Grade each candidate **Strong / Worth exploring / Speculative**,
    and say what deleting or merging it concentrates. Benefits are
    stated as leverage and locality, never as "cleaner".
-5. The project's recorded decisions (the reference, the interviews,
-   `standards.md`) are ADR-equivalents: a candidate contradicting
+5. The project's final reference and `standards.md` are ADR-equivalents:
+  a candidate contradicting
    one is surfaced only when the friction justifies reopening the
    decision, and says so explicitly.

skills/core/references/core-authoring.md

@@ -66,6 +66,24 @@ remains. One-way doors (irreversible decisions per `interview.md`'s
 conduct rules) are never taken from an artifact silently: each is
 re-confirmed individually.
 
+## Interviews are working state, not references
+
+An interview is the resumable working record for its stage. While the
+stage is `interviewing`, use it to resume questions and to generate the
+stage's outputs. Once the stage is `formalized`, those outputs are the
+source of truth: every confirmed decision, rationale, constraint, open
+question, and deferral needed by a later reader must be written into
+them.
+
+Final outputs must stand alone. They never cite, link to, name, or
+instruct a reader to consult an interview file or one of its `§Q`,
+`### Q`, or `### D` entries. Question numbers may remain in the
+changelog key required by `core.md` and in the interview itself; they
+do not appear in the final output. Downstream stages read formalized
+outputs, not completed interviews. If a needed decision exists only in
+a completed interview, repair the owning output from that record before
+continuing.
+
 ## Index maintenance
 
 The index is `<index_file>`, default

skills/core/references/core.md

@@ -162,11 +162,13 @@ questions.
 
 Every subcommand reads in the same order, before doing anything else:
 
-1. **Own state first.** A protocol with an interview or state file
-   reads it before anything else; a protocol whose prior outputs
-   exist (`uiux/`, `logic/`, `spec.md`, `review.md`, ...) reads
-   them before regenerating or extending. Never write blind over your
-   own docs.
+1. **Own state first.** A protocol with an unfinished interview or
+   state file reads it before anything else. For a formalized stage,
+   read only interview frontmatter needed for lifecycle metadata, then
+   read its final outputs; open the completed body only to repair a
+   proven omission. A protocol whose prior outputs exist (`uiux/`,
+   `logic/`, `spec.md`, `review.md`, ...) reads them before regenerating
+   or extending. Never write blind over your own docs.
 2. **Discovery through the index, never by globbing.**
    `<index_file>`'s tables say what exists and where; open only the
    files this run's purpose needs. Freshness comes from each file's
@@ -218,8 +220,9 @@ Five bounds on it:
   say so and stop. Never loop.
 - **The greenfield stages are exempt** (`mockup`, `logic`, `uiux`,
   `architecture`, `standards`, `stack`, `build`): they build the
-  reference from interviews rather than reading one, and their
-  prerequisites are upstream *interviews*, not the index. `uiux`
+  reference through interviews rather than reading one, and their
+  prerequisites are upstream formalized outputs, with interview
+  frontmatter used only to resume an unfinished stage. `uiux`
   without a mockup still points at `mockup`; `build` without a
   formalized stack still runs `stack`.
 - **`map` and `doctor` are exempt.** `map` is what the rule
@@ -272,9 +275,10 @@ wrong even when every fact in it is right: this file is scanned by a
 later run hunting one key, never read start to finish.
 `<target>` is the thing acted on (`03-invite-links`,
 `02-models.md`; `all` for a run covering the whole
-project). `<rev>` is the highest interview question number the output
-traces to (`Q7`) for a stage with an interview file, otherwise the
-run's stamp.
+project). `<rev>` is the highest interview question number incorporated
+when the output was formalized (`Q7`) for a stage with an interview
+file, otherwise the run's stamp. The revision belongs in the key only;
+the output never cites the interview or its question numbers.
 
 Before appending, search the file for the key: if it is already there,
 this is a resumed run and the entry stands; never append a second. A
@@ -323,6 +327,13 @@ rather than racing it.
 
 ## Interview lifecycle (shared by all interviews)
 
+Interview files are resumable working state. After formalization, the
+stage's outputs are the source of truth and every later stage consumes
+those outputs. Completed interview bodies are read only to repair a
+proven omission in an owning output; the repair lands before work
+continues. Final outputs never name or cite interview files or question
+numbers. See core-authoring.md's Interviews are working state rule.
+
 An interview file's `status` moves `interviewing` →
 `awaiting-formalization` (set when the summary gate is presented) →
 `formalized`, and **`formalized` is written only AFTER the stage's
@@ -368,15 +379,15 @@ though it is commercially motivated, because it is a lifecycle
 transition; "unused credits expire monthly" is priced in the mockup
 and enforced in a scenario.
 
-**Referencing is not owning.** Any stage may cite another's decision and
-should: `logic` naming the commercial model the mockup settled is
+**Referencing is not owning.** Any stage may cite another final output
+and should: `logic` naming the commercial model the mockup settled is
 correct, and restating it instead would be the defect. A decision is
 misplaced only where the non-owning stage is its **only** record, or
 states it a second time in its own words.
 
 **Declared crossings, which are not misplacement:** the mockup settles
-the commercial model for everyone; the architecture interview's framing
-section is pre-filled from `mockup-interview.md` by design; `logic` and
+the commercial model for everyone; architecture's framing questions are
+pre-filled from the formalized mockup by design; `logic` and
 `uiux` in extraction mode record observed fact from code rather than
 decisions.
 
@@ -392,8 +403,8 @@ twice.
 
 **Grounds.** Push back only when you can name the conflict:
 
-- it contradicts a decision already recorded in this project (cite the
-  file and `§Q`);
+- it contradicts a decision already recorded in this project's final
+   outputs (cite the owning file);
 - it contradicts a craft file the stage answers to (`code-craft.md`'s
   ladder or TDD cycle, `arch-craft.md`, `uiux-craft.md`), which for
   the ladder is the case core.md's precedence rule calls an override;
@@ -429,9 +440,11 @@ while it runs, so the conflict was never raisable here.
 **Record both sides.** The `### Q<n>` entry records the decision *and*
 the objection: what you raised, what they chose, and the reason they
 gave if they gave one. The stage's changelog entry gets one bullet for
-it. This is the whole point of pushing back - a later reader, human or
-agent, can tell a considered trade-off from an oversight, and `review`
-will not re-raise a question already settled on purpose.
+it. The final output carries the accepted decision and any rationale a
+later reader needs, without interview provenance. This is the whole
+point of pushing back - a later reader, human or agent, can tell a
+considered trade-off from an oversight, and `review` will not re-raise
+a question already settled on purpose.
 
 Vocabulary follows `expertise`: level 1 hears the consequence in plain
 words ("that would slow down every page for your users - want me to