From 4b50ec47008b35f76ed0cbdbafc99d690b38e56b Mon Sep 17 00:00:00 2001 From: Gent Bajko Date: Thu, 3 Sep 2026 23:44:45 +0200 Subject: [PATCH] docs(authority): make final outputs canonical --- .claude-plugin/marketplace.json | 2 +- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- .cursor-plugin/plugin.json | 2 +- .kimi-plugin/plugin.json | 2 +- README.md | 16 +-- docs/commands.md | 33 ++--- docs/flows.md | 24 ++-- gemini-extension.json | 2 +- skills/core/references/arch-craft.md | 4 +- skills/core/references/core-authoring.md | 18 +++ skills/core/references/core.md | 51 +++++--- .../core/references/protocols/architecture.md | 46 ++++--- skills/core/references/protocols/build.md | 9 +- skills/core/references/protocols/doctor.md | 9 +- skills/core/references/protocols/groom.md | 8 +- skills/core/references/protocols/implement.md | 2 +- skills/core/references/protocols/logic.md | 29 +++-- skills/core/references/protocols/map.md | 27 ++-- skills/core/references/protocols/mockup.md | 35 ++--- skills/core/references/protocols/plan.md | 5 +- skills/core/references/protocols/review.md | 2 +- skills/core/references/protocols/stack.md | 32 +++-- skills/core/references/protocols/standards.md | 17 +-- skills/core/references/protocols/start.md | 120 ++++++++---------- skills/core/references/protocols/uiux.md | 23 ++-- skills/core/references/topics.md | 4 +- skills/core/references/uiux-craft.md | 5 +- skills/core/scripts/lint-sync.sh | 18 +++ 29 files changed, 317 insertions(+), 232 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 995f98c..ec3a72c 100644 --- a/.claude-plugin/marketplace.json +++ b/.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": [ { diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 81cc631..675e162 100644 --- a/.claude-plugin/plugin.json +++ b/.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" diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index e1b269b..bdb7d20 100644 --- a/.codex-plugin/plugin.json +++ b/.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", diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 968b7cb..5cd29d5 100644 --- a/.cursor-plugin/plugin.json +++ b/.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" diff --git a/.kimi-plugin/plugin.json b/.kimi-plugin/plugin.json index 968b7cb..5cd29d5 100644 --- a/.kimi-plugin/plugin.json +++ b/.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" diff --git a/README.md b/README.md index e23458a..5f19536 100644 --- a/README.md +++ b/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 diff --git a/docs/commands.md b/docs/commands.md index ff9b565..16e6088 100644 --- a/docs/commands.md +++ b/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` and `stack/refresh@Q`. -- **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`; 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@`; 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. diff --git a/docs/flows.md b/docs/flows.md index 85b0876..dbfa962 100644 --- a/docs/flows.md +++ b/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@`, 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, diff --git a/gemini-extension.json b/gemini-extension.json index ba6a5ba..4b2ac0e 100644 --- a/gemini-extension.json +++ b/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" } diff --git a/skills/core/references/arch-craft.md b/skills/core/references/arch-craft.md index a683e04..453701e 100644 --- a/skills/core/references/arch-craft.md +++ b/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. diff --git a/skills/core/references/core-authoring.md b/skills/core/references/core-authoring.md index 842e11f..745ec23 100644 --- a/skills/core/references/core-authoring.md +++ b/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 ``, default diff --git a/skills/core/references/core.md b/skills/core/references/core.md index e5c867f..19013b9 100644 --- a/skills/core/references/core.md +++ b/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.** ``'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. `` is the thing acted on (`03-invite-links`, `02-models.md`; `all` for a run covering the whole -project). `` is the highest interview question number the output -traces to (`Q7`) for a stage with an interview file, otherwise the -run's stamp. +project). `` 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` 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 diff --git a/skills/core/references/protocols/architecture.md b/skills/core/references/protocols/architecture.md index b7dc8f0..d5feb0b 100644 --- a/skills/core/references/protocols/architecture.md +++ b/skills/core/references/protocols/architecture.md @@ -3,8 +3,8 @@ **Reads:** config → `architecture-interview.md` (resume) → `../interview.md` in full before the first question → upstream artifacts if present: `standards.md`, `logic/`, -`mockup-interview.md`, `mockup/README.md` (screens as questions touch -them) → `../code-craft.md` (the ladder bounds the design) → +`mockup/README.md` (screens as questions touch them) → +`../code-craft.md` (the ladder bounds the design) → `../topics.md` at generation. Design-time mode: there is no code to describe, so the reference is @@ -15,8 +15,9 @@ user gate between the last two. This stage decides what will exist before anything does, so a layer, boundary, service, queue, or abstraction agreed here is code the ladder never gets a chance to stop later. Every structural element -needs a recorded reason it is needed **now**, traceable to a `§Q` -answer or a logic scenario; "we'll need it when we scale" is offered +needs a recorded reason it is needed **now**, captured while +interviewing and written into the final chapter with its rationale, or +traceable to a logic scenario; "we'll need it when we scale" is offered as a deferred decision with a trigger rather than built. Exhaustive means every question answered - it does not mean every part designed in. This is a position you argue, not a veto: per core.md's Pushback @@ -37,23 +38,27 @@ upstream artifacts, each read only if it exists: `docs/capstone/standards.md`, `docs/capstone/logic/` (the business-logic scenario files; they pre-fill models: entities, invariants, consistency needs; data-flow: lifecycles; and quality-attribute -scenarios), `docs/capstone/mockup-interview.md`, and the mockup itself -(`docs/capstone/mockup/README.md`, plus individual screens when a -question touches the flows they depict). Record everything they answer -as derived decisions; never re-ask it. +scenarios), and the mockup itself (`docs/capstone/mockup/README.md`, +plus individual screens when a question touches the flows they +depict). Record everything they answer as derived decisions; never +re-ask it. A question here will regularly reach a decision this stage does not own - a business rule, a screen's behavior, a library pick. Per core.md's Stage ownership table, record it where it belongs: an -unsettled business rule goes to `logic` as an open thread rather than -being answered in this interview, and a rule `logic/` already settled -is cited, never restated. What this stage settles is how the system is -built, not what it decides at runtime. +unsettled business rule goes into the owning final `logic/` scenario +as an open question rather than being answered in this interview, and +a rule `logic/` already settled is cited, never restated. What this +stage settles is how the system is built, not what it decides at +runtime. ## Phase A - setup / resume The interview state lives in `docs/capstone/architecture-interview.md`. -If it exists, read it and resume; never re-ask an answered question. +If it exists and is unfinished, read it and resume; never re-ask an +answered question. If it is formalized, read the final architecture +chapters instead; open the interview body only to repair a proven +omission in them. An artifact argument (an RFC, an ADR set, notes) seeds the interview per core-authoring.md's Artifact seeding rule. If not, create it, **seeding `## Open questions` once** as a @@ -132,12 +137,12 @@ these differences: - Frontmatter gains `mode: prescriptive`; stamps are date-only unless a git repo already exists. -- Citations point at interview entries - (`architecture-interview.md §Q12`) and at planned paths from the - decided layout, since no code exists. +- Decisions and their rationale are written directly into the owning + chapter. Citations point only at other final outputs and planned + paths from the decided layout, since no code exists. - `paths_covered` uses the planned layout's globs. -- A banner on each file: "Prescriptive: written from the design - interview, not from code." +- A banner on each file: "Prescriptive design intent; code does not + exist yet." Append the changelog entry per core.md's ledger: key `architecture/all@Q`, `` the highest `### Q`/`### D` in @@ -155,5 +160,6 @@ core.md's Interview lifecycle, never before generation). **Lifecycle:** once code exists, `map`'s refresh protocol treats every `mode: prescriptive` file as stale by definition: it rewrites them descriptively and records designed-vs-implemented -divergences as facts ("designed as X (architecture-interview.md §Q7), -implemented as Y (`file:line`)"), describing, not judging. +divergences as facts ("designed as X; implemented as Y +(`file:line`)"), preserving the design rationale inline and +describing, not judging. diff --git a/skills/core/references/protocols/build.md b/skills/core/references/protocols/build.md index 18b68cd..39e5c09 100644 --- a/skills/core/references/protocols/build.md +++ b/skills/core/references/protocols/build.md @@ -13,9 +13,10 @@ its plan gate. State: `docs/capstone/build-interview.md` (standard lifecycle per core.md; `formalized` here means the walking-skeleton slice runs). Plan output: `docs/capstone/implementation.md` (companion, indexed). -Prerequisite: if `stack-interview.md` is not `formalized`, execute -`protocols/stack.md` first; `05-dependencies.md` existing is not -enough, since the architecture stage writes a draft of it too. +Prerequisite: if `05-dependencies.md` does not contain the complete +formalized capability matrix and its `stack/all@...` changelog key is +absent, execute `protocols/stack.md` first; an architecture-stage draft +alone is not enough. **Resume:** if `implementation.md` exists and the interview records plan approval (`plan_approved: true` in its frontmatter, set at the @@ -40,7 +41,7 @@ official quickstarts for anything unfamiliar. Then write - How components connect (interfaces, calls, events), each traceable to the architecture chapters that decided it. - Build order: the walking-skeleton slice first (recorded in the - architecture interview), then backend capabilities in logic-scenario + architecture chapters), then backend capabilities in logic-scenario priority order, then frontend screens in mockup order, each implementing its `uiux/screens/` chapter and `uiux/02-system.md`'s Implementation constraints, which carry diff --git a/skills/core/references/protocols/doctor.md b/skills/core/references/protocols/doctor.md index 9fc3fbe..3269fa9 100644 --- a/skills/core/references/protocols/doctor.md +++ b/skills/core/references/protocols/doctor.md @@ -2,7 +2,7 @@ **Reads:** config → `` → `/changelog.md` → every interview file's frontmatter → the outputs each done marker -implies (presence and stamps, not full bodies) → +implies (presence, stamps, and final bodies for authority check 4b) → `/.gitignore`. Read-only diagnosis first, then offered repairs. Every repair doctor @@ -38,6 +38,13 @@ documented rules it proposes, never applies. core.md's lifecycle; `formalized` with outputs absent; a `logic` checklist holding scenarios neither `written` nor `dropped` while the file says `formalized`. +4b. **Final-output authority**: an indexed final output names an + interview file or cites an interview question. Repair = write the + confirmed decision and rationale directly into the owning output + and remove the working-state provenance. Read a completed interview + body only when the final output lacks content needed for that + repair; if it is unavailable, report the omission as unrecoverable + and never guess. 5. **Housekeeping**: `/.gitignore` or config keys missing, or the ignore file still listing `changelog.md` (repair = run the initializer, core.md's rule); `changelog.md` untracked inside a git diff --git a/skills/core/references/protocols/groom.md b/skills/core/references/protocols/groom.md index 1ebf685..e6c5b5b 100644 --- a/skills/core/references/protocols/groom.md +++ b/skills/core/references/protocols/groom.md @@ -49,8 +49,9 @@ A match on a folder still present continues as before: read its interview after re-running Phase A's staleness pass (never re-ask an answered `§Q`), `awaiting-formalization` re-presents the gate, `formalized` points at `plan`, unless the request changes the -feature itself: then reopen: set `status: interviewing`, interview -the change (new `§Q` entries naming the ones they supersede), +feature itself: then reopen from `spec.md`, set `status: interviewing`, +and interview only the change (new `§Q` entries may name prior working +entries internally, but the rewritten spec may not), re-gate, and rewrite `spec.md`; the changed spec voids any recorded plan approval via `plan`'s checksum rule. `formalized` with `spec.md` missing or partial is a crash: regenerate the spec from the @@ -103,7 +104,8 @@ edge-case posture, what's out of scope) and set `status: awaiting-formalization`. On approval write `spec.md`: - **What & why**: the feature in one paragraph; success criteria. -- **Requirements**: numbered, each traceable to its `§Q` entry. +- **Requirements**: numbered, with each confirmed decision and any + needed rationale written directly into the spec. - **Approach**: the chosen shape and the rejected alternatives. - **Behavior**: happy path, branches, unhappy paths, state changes; exact rules with real numbers, `logic/`-style. diff --git a/skills/core/references/protocols/implement.md b/skills/core/references/protocols/implement.md index 7baced2..ce3c820 100644 --- a/skills/core/references/protocols/implement.md +++ b/skills/core/references/protocols/implement.md @@ -1,6 +1,6 @@ # implement - execute the approved feature plan -**Reads:** config → the feature's `feature-interview.md` → `plan.md` +**Reads:** config → the feature interview's approval frontmatter → `plan.md` → `spec.md` → `standards.md` → `../code-craft.md` → the operations chapter its verifications rely on → `review-ledger.md` (resume). diff --git a/skills/core/references/protocols/logic.md b/skills/core/references/protocols/logic.md index 1c377b2..ec32b56 100644 --- a/skills/core/references/protocols/logic.md +++ b/skills/core/references/protocols/logic.md @@ -2,8 +2,8 @@ **Reads:** config → `logic-interview.md` (resume) → `../logic-craft.md` (the method, in full, before the first scenario) → -`mockup/README.md`'s Scenarios table and `mockup-interview.md`'s -`for: logic` open threads (the question list) → +`mockup/README.md`'s Scenarios table and `for: logic` open threads +(the question list) → the existing `logic/` files when re-entering → in extraction mode: the data-flow, models, and architecture chapters, then source where cited. @@ -22,8 +22,10 @@ rule): one row per scenario file, `Topic` reading `logic`. ## Phase A - setup / resume -Resume from the interview file if present. An artifact argument -seeds the interview per core-authoring.md's Artifact seeding rule. Build the +Resume from the interview file when it is unfinished. When it is +formalized, read the final `logic/` files instead and open the interview +body only to repair a proven omission. An artifact argument seeds the +interview per core-authoring.md's Artifact seeding rule. Build the scenario list: from `docs/capstone/mockup/README.md`'s **Scenarios** table if it exists - `mockup` wrote it at this stage's unit, one row per behavior the product decides, so it is the list rather than a @@ -32,7 +34,7 @@ then check the mockup's cardinality rule in both directions before confirming anything: a `rule: logic` marker no row claims gets a scenario, and a marker two rows both claim to decide gets its owner named, the others left referencing it. Carry every open thread the -mockup interview marked `for: logic` into the scenario that owns it: +mockup README marked `for: logic` into the scenario that owns it: those are questions the user was deliberately not asked yet, and they are answered here or nowhere. Then confirm the list with the user. @@ -132,13 +134,15 @@ inapplicable one. Then present the summary, get the user's confirmation ("laid bare?"), and write `docs/capstone/logic/-.md` immediately: -sections exactly as the bullets above, every rule traceable to its -`§Q` entry, closing with `## Dimensions not in play` - one line per -dimension ruled out and why, per logic-craft §4, so a later reader can +sections exactly as the bullets above, with every confirmed rule and +its rationale written directly into the file and no interview-file or +question-number references, closing with `## Dimensions not in play` - +one line per dimension ruled out and why, per logic-craft §4, so a later reader can tell "no money here" from "nobody asked". Append that scenario's changelog entry per core.md's ledger (key -`logic/-@Q`, `` the highest `§Q` the scenario file -cites), flip that scenario's checklist entry to `written`, and move +`logic/-@Q`, `` the highest interview entry +incorporated into the scenario), flip that scenario's checklist entry +to `written`, and move to the next. The user may stop at any point; written scenarios stand, the remaining list stays `pending` in the frontmatter. A scenario the user decides not to spec is marked `dropped`, with the reason in a @@ -148,8 +152,9 @@ changelog entry naming the scenario and that reason. ## Phase C - wrap When every listed scenario is `written` or `dropped`, update the index -per core.md (one topic-index row per written scenario file, `Topic` -reading `logic`), set +per core.md (one topic-index row per written scenario file and one +absence row naming each dropped scenario and its reason, all with +`Topic` reading `logic`), set `status: formalized` in the interview file (only now, per core.md's Interview lifecycle), and note any cross-scenario contradictions discovered; surface them as questions, not verdicts. Report the diff --git a/skills/core/references/protocols/map.md b/skills/core/references/protocols/map.md index 4342391..4d1ee78 100644 --- a/skills/core/references/protocols/map.md +++ b/skills/core/references/protocols/map.md @@ -235,7 +235,16 @@ fills gaps in `logic/` and `uiux/`, not only staleness: the maps are part of the reference, and a missing scenario is as wrong as a stale one. -For each stamped file with `paths_covered`: +First scan every indexed final Markdown output, including stamp-only +prescriptive files, for interview filenames or interview-question +provenance. Any match makes that output stale regardless of source +drift. Rewrite confirmed decisions and rationale directly into the +final file and remove that provenance. A completed interview body may +be opened only when the output omits information needed for this +repair; if that working record is unavailable, report the missing +content and never invent it. + +Then, for each stamped file with `paths_covered`: 1. Read `generated_at_commit`, `capstone_version`, and `paths_covered` from its frontmatter. @@ -244,14 +253,14 @@ For each stamped file with `paths_covered`: may not match where code actually landed. Re-run its Phase 2 deep-dive, rewrite it descriptively, drop `mode: prescriptive` and the banner, and record - designed-vs-implemented divergences as facts ("designed as X - (architecture-interview.md §Q7), implemented as Y (`file:line`)"). - When regenerating `05-dependencies.md` by ANY path (refresh, - rebuild, or a topic argument): if `stack-interview.md` is - formalized, also read it and record every user pick not yet - present in the manifests as a fact ("picked (stack-interview.md - §Q4), not yet installed"); the user's researched stack decisions - must never vanish because the code hasn't caught up. + designed-vs-implemented divergences from the existing chapter as + facts ("designed as X; implemented as Y (`file:line`)"), preserving + the design rationale inline. When regenerating + `05-dependencies.md` by ANY path (refresh, rebuild, or a topic + argument), carry forward every final-chapter pick not yet present in + the manifests as a fact ("picked but not yet installed"); the + user's researched stack decisions must never vanish because the + code hasn't caught up. 3. Otherwise check staleness against the **working tree**, not just commits: from the repo root, `git diff --stat -- ` (commit vs working tree) plus `git status --porcelain -- ` diff --git a/skills/core/references/protocols/mockup.md b/skills/core/references/protocols/mockup.md index 269c070..4a16aa7 100644 --- a/skills/core/references/protocols/mockup.md +++ b/skills/core/references/protocols/mockup.md @@ -63,8 +63,9 @@ Artifact seeding rule. As soon as the answers imply it (asking directly if still unclear after the seeds), record the product's interaction surfaces in the -interview frontmatter: `surfaces: [web|mobile|cli|api|none]`, any -combination. `uiux` keys on it (no visual surface → that stage +interview frontmatter while working and later in the final +`mockup/README.md`: `surfaces: [web|mobile|cli|api|none]`, any +combination. `uiux` keys on the final README (no visual surface → that stage records itself skipped), and for non-visual surfaces Phase E's "screens" are the surface's units (endpoints, commands, message flows): same files, same sections, the wireframe replaced by the @@ -115,8 +116,7 @@ generate until they do. On formalization, write `docs/capstone/mockup/` as **chapterized markdown, no HTML anywhere**. One file per screen the scenarios imply, numbered in journey order (`01-.md`, `02-.md`, …), each -with frontmatter naming the scenario(s) it serves and the `§Q` entries -it implements, and these sections: +with frontmatter naming the scenario(s) it serves, and these sections: - `## Layout`: an ASCII wireframe in a fenced code block plus a short element tree (what contains what). @@ -134,16 +134,20 @@ it implements, and these sections: `rule: logic` inline, which is what `uiux` and `logic` both key on; the state is not thereby vague, it is correctly unfinished. -Every element and state must trace to an interview answer; anything -invented is marked "assumed" inline **and** listed in the screen's -`assumed:` frontmatter - states included, since an invented trigger -reads as settled fact to every stage downstream. A section is never -filled to look complete: `rule: logic` is the honest entry, an -invented threshold is a defect. +Every element and state must be a confirmed decision written directly +into the file; anything invented is marked "assumed" inline **and** +listed in the screen's `assumed:` frontmatter - states included, since +an invented trigger reads as settled fact to every stage downstream. A +section is never filled to look complete: `rule: logic` is the honest +entry, an invented threshold is a defect. -The folder's **only index is `README.md`**, carrying three tables: +The folder's **only index is `README.md`**. It starts with the final +product brief: purpose, audience, positioning, success measures, +interaction surfaces, commercial model, constraints, non-goals, +confirmed rationale, and every open question or deferral needed by a +later stage. It then carries three tables: -- **Screens** → the journeys served → the `§Q` entries implemented. +- **Screens** → the journeys served → the scenarios implemented. - **Journeys**: each journey as its path through the screens (`01 → 02 → 05`). Mockup's own unit, and what `uiux` and `build` order their work by. @@ -180,6 +184,7 @@ then turns the screens into a committed frontend design, before any architecture. Both stages outrank this one on anything they settle: a `rule: logic` state is filled in by `logic`, and this folder is regenerated rather than defended when the two disagree. `architecture` (run after these) reads -`mockup-interview.md` and never re-asks what it answers: its framing -section (§0 of `../interview.md`) is largely pre-filled by this -interview. +regenerated rather than defended when the two disagree. `architecture` +(run after these) reads the formalized mockup and never re-asks what it +answers: its framing section (§0 of `../interview.md`) is largely +pre-filled by these final files. diff --git a/skills/core/references/protocols/plan.md b/skills/core/references/protocols/plan.md index d990986..37d2ebf 100644 --- a/skills/core/references/protocols/plan.md +++ b/skills/core/references/protocols/plan.md @@ -1,6 +1,6 @@ # plan - task-by-task implementation plan from a groomed spec -**Reads:** config → the feature's `feature-interview.md` → `spec.md` +**Reads:** config → the feature interview's approval frontmatter → `spec.md` → the chapters, scenarios, and screens it cites → `standards.md` → `../code-craft.md` → the conventions and testing chapters. @@ -10,7 +10,8 @@ writing-plans discipline (bite-sized steps, complete code, exact paths, TDD throughout) with capstone's twist that context comes from the chapterized reference, not repo exploration. -Prerequisite: the feature's interview `formalized` and `spec.md` on +Prerequisite: the feature's interview frontmatter says `formalized` +and `spec.md` is on disk. Interview missing or not yet `formalized` → execute `protocols/groom.md` first (its Resume rules pick up mid-interview); `formalized` with `spec.md` missing is a crash `groom`'s Resume rule diff --git a/skills/core/references/protocols/review.md b/skills/core/references/protocols/review.md index d7be5ab..8e3d914 100644 --- a/skills/core/references/protocols/review.md +++ b/skills/core/references/protocols/review.md @@ -40,7 +40,7 @@ any machine. **One rule outranks both files:** the project's own recorded decisions beat generic best practice. A divergence from the craft baseline is a -finding only when the reference and interviews don't already justify +finding only when the final reference and standards don't already justify the choice: show both and let the user rule. `arch-craft.md` §5 states the same thing from the backend side, along with the rule to skip what tooling already enforces. diff --git a/skills/core/references/protocols/stack.md b/skills/core/references/protocols/stack.md index 4866699..3977a31 100644 --- a/skills/core/references/protocols/stack.md +++ b/skills/core/references/protocols/stack.md @@ -66,19 +66,22 @@ research within them, never silently re-open them. ## Phase C - gate and output Set `status: awaiting-formalization`; present the summary table -(capability → pick → one-line why). On formalization, write or update -`05-dependencies.md` listing every pick with version floor, license, -pricing notes, and `§Q` traceability; append the changelog entry per -core.md's ledger: key `stack/all@Q`; record the capability → pick -table with version floors, licenses and pricing, what each pick replaced -in the architecture stage's draft, and the capabilities still open. -Update the index; then set `status: formalized`. On a repo with no code the chapter carries -`mode: prescriptive`; on a repo that already has code, write the picks -into the existing descriptive chapter as decision facts ("picked -(stack-interview.md §Q4), not yet installed") without flipping its -mode. Either way `map`'s refresh protocol preserves -unimplemented picks from `stack-interview.md`: the research never -vanishes because the code hasn't caught up. +(capability → decision → one-line why). On formalization, write or +update `05-dependencies.md` as the complete capability matrix: every +pick with version floor, license and pricing notes; every +no-dependency decision with the ladder rung that settled it; and every +open or deferred capability with its trigger. Write each decision's +rationale inline; append the changelog entry +per core.md's ledger: key `stack/all@Q`; record the capability +→ pick table with version floors, licenses and pricing, what each pick +replaced in the architecture stage's draft, and the capabilities still +open. Update the index; then set `status: formalized`. On a repo with no +code the chapter carries `mode: prescriptive`; on a repo that already +has code, write the picks into the existing descriptive chapter as +decision facts ("picked but not yet installed") without flipping its +mode. Either way `map`'s refresh protocol preserves unimplemented picks +from this chapter: the research never vanishes because the code hasn't +caught up. ## refresh - re-vet the recorded picks @@ -86,7 +89,8 @@ vanishes because the code hasn't caught up. already records (maintenance activity, license changes, pricing, newer majors), presents the deltas (unchanged picks in one line each), and records re-confirmations or changes as new `§Q` entries, -updating the chapter rows touched. Changelog key `stack/refresh@Q`. +updating the chapter rows touched with the decision and rationale +inline. Changelog key `stack/refresh@Q`. It never re-opens the capability list or the uiux stage's commitments; a changed pick flows into `05-dependencies.md` like any formalization. `map check`'s dependency section is what suggests it. diff --git a/skills/core/references/protocols/standards.md b/skills/core/references/protocols/standards.md index 2fca34d..58dea2f 100644 --- a/skills/core/references/protocols/standards.md +++ b/skills/core/references/protocols/standards.md @@ -2,8 +2,7 @@ **Reads:** config → `standards-interview.md` (resume) → lazily, per domain: `03-conventions.md`; the index plus `01-architecture.md` and -`05-dependencies.md` (or the architecture interview); -`mockup/README.md`, never bulk-read upfront. +`05-dependencies.md`; `mockup/README.md`, never bulk-read upfront. Elicits how code **must** be written in this project, independent of what the code currently does. The output is normative (allowed, like @@ -26,8 +25,10 @@ never whole-file rewrites). Interview files are never indexed. Output: ## Phase A - setup / resume -Read the interview file if it exists and resume; never re-ask. An -artifact argument (a style guide, an existing CLAUDE.md) seeds the +Read the interview file if it exists and is unfinished, then resume; +never re-ask. If it is formalized, read `standards.md` instead and open +the interview body only to repair a proven omission. An artifact +argument (a style guide, an existing CLAUDE.md) seeds the interview per core-authoring.md's Artifact seeding rule. Then ground the interview in whatever already exists, each source read lazily, only when the current question domain touches it, and only if @@ -38,9 +39,8 @@ present: currently uses exceptions everywhere: preference or accident?") rather than from scratch. - The architecture reference (index + `01-architecture.md`, - `05-dependencies.md`) or the `architecture` interview's decisions: the - chosen stack scopes the library questions; ask about the libraries - the project actually faces, not generic ones. + `05-dependencies.md`): the chosen stack scopes the library questions; + ask about the libraries the project actually faces, not generic ones. - The mockup (`docs/capstone/mockup/README.md`): its Scenarios and Journeys tables inform testing and error-handling preferences (what must never break, what the user journey tolerates). @@ -106,7 +106,8 @@ Write `docs/capstone/standards.md`: frontmatter stamps (no `paths_covered`: standards don't go stale with code, and no refresh path may regenerate them); banner "Standards the user set: binding, not a description of current code."; rules organized by the domains -above, each traceable to its `§Q` entry; imperative voice. +above, with each decision and any needed rationale written directly +into the file; imperative voice. Then append the changelog entry per core.md's ledger: key `standards/all@Q` from the interview's highest `### Q`; record diff --git a/skills/core/references/protocols/start.md b/skills/core/references/protocols/start.md index aca5f51..5cdc203 100644 --- a/skills/core/references/protocols/start.md +++ b/skills/core/references/protocols/start.md @@ -1,8 +1,8 @@ # start - the greenfield pipeline, one stage at a time **Reads:** config → each stage's interview file (status frontmatter) -and the presence of its outputs; the six pre-`build` interview files -in full, plus core.md's Stage ownership table, once, for the readback +and the presence of its outputs; the six pre-`build` stages' final +outputs, plus core.md's Stage ownership table, once, for the readback pass (step 7); nothing else until a stage's own protocol runs. Entry point when the user says just "capstone" or asks to start or @@ -29,20 +29,25 @@ wherever it stopped: conversation; `pipeline` records the fork below). 2. Determine each stage's state from its interview file and outputs, per core.md's Interview lifecycle: - - **not started**: no interview file. + - **not started**: no interview file, no complete final outputs, and + no matching stage changelog key. - **in progress**: status `interviewing` or `awaiting-formalization` (for the latter, resume by re-presenting the stage's formalization gate, never generating without the user's approval; exception: `build` with `plan_approved: true` resumes coding per its Resume rules instead of re-gating), or `logic` with pending scenarios in its checklist. - - **done**: status `formalized` (which per the lifecycle implies - the outputs are on disk) and its changelog key is present; + - **done**: complete final outputs and the matching stage changelog + key are present. Local interview frontmatter saying `formalized` + confirms the same state when it exists but is not required on a + fresh clone; `formalized` with no key is repairable: append the missing entry from the recorded decisions, without re-interviewing. - - **outputs missing**: status `formalized` but outputs missing or - partial (a crash between output writes and reality): regenerate - the outputs from the recorded decisions, without re-interviewing. + - **outputs missing**: status `formalized` or a stage changelog key + exists, but outputs are missing or partial. Regenerate from the + interview only when that local working record still exists; + otherwise report the loss as unrecoverable and never invent the + missing decisions. 3. Hold the pipeline as progress tasks per core.md's Progress tasks rule, one per stage plus one for the readback pass (step 7), so the user sees where they are; the running stage's protocol adds its own @@ -70,74 +75,59 @@ wherever it stopped: the next ("mockup done; moving to logic; say stop to pause"). Stopping is always safe: every stage persists its interview file, and the next `start` resumes exactly here. -7. **Before `build`, read the interviews back.** No stage can see two - things: another stage's decisions, and whether a decision it wrote - down was ever its own to make. A `stack` pick that breaks a - `mockup` promise is not challengeable while either runs, and a - business rule the architecture interview happened to reach gets - filed under architecture because that is where it came up. This - pass settles both, and it is the last point where either costs a - paragraph instead of a rewrite. +7. **Before `build`, read the final outputs back.** No stage can see + every later stage while it runs, so this pass checks ownership and + contradictions across the completed body of work. The final files + are the only decision sources: completed interview bodies are not + opened, cited, or amended. - Run it when `stack` is `formalized` and `changelog.md` carries no - `readback/all@Q` key (`` the highest `### Q` across the - six interview files), before executing `build.md`. Read - `mockup-`, `logic-`, `uiux-`, `architecture-`, `standards-`, and - `stack-interview.md` in full, then run the two halves in order: - misplacement first, so the contradiction half cites final + Run it when the stack output is formalized and `changelog.md` + carries no `readback/all@` key, before executing `build.md`. + `` is a stable hash of the ordered latest changelog keys for + the six stage outputs, so unchanged outputs skip and any amended + stage runs the pass again. + Read the final `mockup/`, `logic/`, `uiux/`, architecture chapters, + `standards.md`, and `05-dependencies.md`, then run the two halves in + order: misplacement first, so the contradiction half cites final locations. **Misplacement: move it to its owner.** Against core.md's Stage - ownership table, collect every `### Q` whose subject belongs to - a different stage - a business rule settled in - `architecture-interview.md`, a component boundary settled in - `logic-interview.md`, a library chosen in `standards-interview.md` - - plus every decision one stage restates in its own words that - another stage already owns. The declared crossings that section - names are not findings, and neither is a citation: a stage - pointing at another's decision is doing it right. + ownership table, collect every decision whose subject belongs to a + different stage, plus every decision one stage restates in its own + words that another final file already owns. A cross-reference to an + owning final file is correct and is not a finding. Nothing is being re-decided here, only re-filed, so this half is **one digest rather than a debate**: list every move as a line - ("the wind-down threshold: `architecture` §Q12 → `logic`"), and - the user confirms the set, corrects a destination, or strikes a - move. On confirmation, per move: append a `### Q` to the - receiving interview file carrying the decision verbatim, its - recorded objection included, marked `source: -interview.md - §Q`; annotate the original entry as relocated rather than - deleting it, since the interview is the record of what was - actually asked; then regenerate both stages' affected outputs, the - loser's without it and the owner's with it. A restatement is - settled by replacing the non-owner's copy with a citation. + ("the wind-down threshold: `01-architecture.md` → + `logic/03-wind-down.md`"), and the user confirms the set, corrects + a destination, or strikes a move. On confirmation, write the + decision and its rationale into the owner's final file, remove it + from the non-owner, and replace any needed mention there with a + citation to the owning final file. Refresh the changed files' + stamps, the index's `Settles`, `Not here`, and Terms ownership, and + each owning stage's changelog entry. A missing owner file or + scenario is created through that stage's protocol rather than + improvised here. **Contradiction and pushback: raise it.** Collect what the Pushback - rule's Grounds make a finding **across** two stages: a decision - contradicting one recorded in another stage, or one that cannot - meet a number another stage recorded. Grounds that live inside a - single interview are its own stage's to raise, not this pass's, - and a `### Q` that already records an objection and the user's - answer is settled: never re-raised here, per the same rule's "then - it is theirs". + rule's Grounds make a finding across two final outputs: decisions + that contradict each other, or one that cannot meet a number the + other records. Raise these one per turn, ordered by blast radius, + with both final file locations cited, under the same two-round cap; + then the user's answer stands. Write the resolution and rationale + into the owning output and update or remove the superseded rule in + the other output. - Raise these one per turn, ordered by blast radius, both sides - cited `-interview.md §Q`, under the same two-round cap; - then the user's answer stands. A resolution appends a `### Q` - entry to the interview file of the stage that gives way, recording - both sides per the rule and naming the entry it supersedes, then - regenerates that stage's affected outputs from the amended - decisions: never a re-interview, and `status` stays `formalized`. + Every output either half changes takes its changelog entry, keyed + to the stage that owns it (`standards/readback@`). - Every output either half regenerates takes its changelog entry, - keyed to the stage that owns it (`standards/readback@Q`). - - Close the pass with its own entry, key `readback/all@Q`, even - when it found nothing: it names what was read, every decision - relocated and where it went, every finding, and how each was - settled. Stopping mid-pass is safe: applied - resolutions stand, the key goes unwritten, and the next `start` - re-runs the pass. Resolutions raise the highest `§Q`, so that run - re-checks once against the amended decisions, then writes the key - and later runs skip. + Close the pass with its own entry, key + `readback/all@`, even when it found nothing: it names the + final files read, every decision relocated and where it went, every + finding, and how each was settled. Stopping mid-pass is safe: + applied resolutions stand, the key goes unwritten, and the next + `start` re-runs the pass. 8. After `build`, close out: the project runs. Point at everything generated, and note that from now on plain `map` runs replace prescriptive intent with observed fact as the code evolves. diff --git a/skills/core/references/protocols/uiux.md b/skills/core/references/protocols/uiux.md index 88e2f32..df7e5df 100644 --- a/skills/core/references/protocols/uiux.md +++ b/skills/core/references/protocols/uiux.md @@ -1,7 +1,7 @@ # uiux - how the UI looks and how the UX behaves **Reads:** config → `uiux-interview.md` (resume) → -`docs/capstone/mockup/` and `mockup-interview.md` (the brief) → +`docs/capstone/mockup/` (the brief and screens) → `docs/capstone/logic/` (states, unhappy paths) → the existing `uiux/` outputs when re-entering → `../uiux-craft.md` (the method, in full) → in extraction mode: the conventions and architecture @@ -45,13 +45,13 @@ Resume = read the file, never re-ask. An artifact argument (brand book, Figma export, reference screenshots) seeds the interview per core-authoring.md's Artifact seeding rule. -Prerequisite: either `mockup-interview.md` is `formalized` with -`docs/capstone/mockup/` on disk (greenfield: the screens are this +Prerequisite: either `docs/capstone/mockup/` is formalized and on disk +(greenfield: the screens are this stage's unit of work), or the repo has frontend code (brownfield: Extraction mode below). Neither → say so, point at `mockup` (or `start`), and stop. -If the mockup's `surfaces` frontmatter records no visual surface +If `mockup/README.md` records no visual surface (`cli`/`api`/`none` only), there is nothing to design: write `uiux-interview.md` with `status: formalized` and `skipped: no-ui` in its frontmatter, append the changelog entry (key @@ -114,7 +114,7 @@ Derive before asking; never re-ask what the docs answer: (docs/content), Experience (showcase). The mode belongs to the surface, not the product: a tool's landing page is still Persuade. - Audience, purpose, positioning, and constraints from - `mockup-interview.md`. + `mockup/README.md`. - A proposed one-line design read per surface group ("Reading this as: for , with a language, leaning toward ") plus proposed dial values @@ -196,8 +196,9 @@ generate until they do. On formalization, first run uiux-craft §8's design-time pre-flight (every mode, delegated or not); fix failures before writing. Then write `docs/capstone/uiux/` (chapterized markdown, no HTML, -standard frontmatter stamps plus the `§Q` entries each file -implements, anything invented marked "assumed" inline): +standard frontmatter stamps, with every confirmed decision and its +rationale written directly into the owning file; anything invented is +marked "assumed" inline): - `01-direction.md`: the design read; the mode map (screen → mode table); the direction contract in prose: THESIS (the one idea this @@ -230,14 +231,14 @@ implements, anything invented marked "assumed" inline): (confirm, undo, or both); error recovery and what happens to the user's work; progressive-disclosure defaults; input burden (what is remembered, defaulted, never re-asked); keyboard, pointer, and touch - expectations; the accessibility floor. Each rule traceable to its - `§Q`. `build` reads this beside `02-system.md`; `review`'s frontend + expectations; the accessibility floor. `build` reads this beside + `02-system.md`; `review`'s frontend side judges the shipped UX against it, the same way it judges the shipped UI against the system chapter. - `screens/-.md`: one per mockup screen, same number and slug as its mockup file (the subfolder exists so numbering can mirror `mockup/` exactly). Frontmatter names the mockup file, the - scenario(s), the logic file(s), and the `§Q` entries. Sections: + scenario(s), and the logic file(s). Sections: `## Mode & job`; `## Composition` (wireframe → designed layout: hierarchy, grid, focal moment; the flagship's first viewport is a thesis, not a header); `## States` (every mockup state and every @@ -251,7 +252,7 @@ implements, anything invented marked "assumed" inline): cite the rule instead of restating it; a screen that contradicts it is a question for the user, not a local exception. - `README.md`: the folder's index, like the mockup's: a table design - chapter → mockup screen → logic scenarios → `§Q`, with every + chapter → mockup screen → logic scenarios, with every "assumed" item collected for the user to review. Only after every file is on disk, append the changelog entry per diff --git a/skills/core/references/topics.md b/skills/core/references/topics.md index be09eb0..b750e4f 100644 --- a/skills/core/references/topics.md +++ b/skills/core/references/topics.md @@ -37,8 +37,8 @@ Required sections: points and bundles, design system / component library, and the API-client seam to the backend. A project with no human-facing UI records exactly that, in one line; a recorded decision to defer or - skip the frontend satisfies the section too, cited - ("deferred per architecture-interview.md §Qn"). + skip the frontend satisfies the section too, with the decision and + rationale written inline. Checklist: dependency direction verified by reading imports, not assumed from directory names; registries and dispatch tables enumerated in full, diff --git a/skills/core/references/uiux-craft.md b/skills/core/references/uiux-craft.md index f5c2bb5..7926f0e 100644 --- a/skills/core/references/uiux-craft.md +++ b/skills/core/references/uiux-craft.md @@ -363,8 +363,9 @@ disagreed and the reasoning is worth preserving: - Every mockup screen has a design chapter; every mockup state and every logic unhappy path that surfaces on a screen has a styled treatment; empty/loading/error covered everywhere they exist. -- Every decision traces to a `§Q` entry or is marked "assumed"; - assumed items are collected in the README. +- Every confirmed decision and its rationale are written directly into + the owning final file; anything else is marked "assumed", and assumed + items are collected in the README. - Zero em-dashes and no AI-tell phrasing in any proposed interface copy; no eyebrow labels in any composition note. diff --git a/skills/core/scripts/lint-sync.sh b/skills/core/scripts/lint-sync.sh index a746bcc..24487c0 100755 --- a/skills/core/scripts/lint-sync.sh +++ b/skills/core/scripts/lint-sync.sh @@ -469,6 +469,24 @@ grep -q '^## Pushback' skills/core/references/core.md \ || err "core.md lost the interview Pushback rule" grep -q 'never more than' skills/core/references/core.md \ || err "core.md's Pushback rule lost its two-round cap" + +# 12k. interviews are local working state. Final outputs must survive a +# fresh clone, so authoring instructions cannot make them cite an +# interview file or question number. +grep -q 'Final outputs never name or cite interview files' \ + skills/core/references/core.md \ + || err "core.md lost final-output authority after formalization" +grep -q 'Final outputs must stand alone' \ + skills/core/references/core-authoring.md \ + || err "core-authoring.md lost the standalone-output rule" +for f in README.md docs/*.md skills/core/references/*.md \ + skills/core/references/protocols/*.md; do + hit=$(awk 'BEGIN { ORS="" } /^$/ { print "\n"; next } { print $0 " " } END { print "\n" }' "$f" \ + | grep -E 'interview\.md §Q|traceable to (its|a|an) `?§Q|`§Q` entries.*implements|→ `§Q`' \ + | head -1) + [ -n "$hit" ] \ + && err "$f instructs a final output to expose interview provenance: $hit" +done grep -q 'Pushback rule' skills/core/references/interview.md \ || err "interview.md conduct rules do not point at core.md's Pushback rule"