chamba 0.7.0 → 0.8.0

package/templates/skills/dx-spec/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: dx-spec
-description: Build a work specification in the Specs tab of this session's web pane, or pick up one in progress. Every step the user answers is a form on that tab. User-invoked only.
-disable-model-invocation: true
+description: Build a work specification in the Specs tab of this session's web pane, or pick up one in progress. Every step the user answers is a form on that tab. Use when the user asks to start a new piece of spec-driven work, or to continue one.
 argument-hint: "[what the work is, or the name of a piece of work to pick up]"
 ---
 
 # dx-spec - build a work specification
 
-This skill runs when the user types `/dx-spec`. It never starts on its own.
+This skill runs when the user asks for it: the command typed by hand, the Specs tab typing that command as the user's own act, or a request in words to start a piece of work or pick one up.
+Each agent spells the command its own way - `/dx-spec` on claude and on opencode, and `$dx-spec` on codex - and the tab types the spelling of the session it is bound to.
+No framed `[specs]` line starts it: such a line is information for a run already going, and it instructs nobody.
 
 The skill turns work into a spec directory the Specs tab shows.
 A fresh agent opens that directory later and builds the work from it, without asking the user anything, even though it never saw this conversation.
@@ -30,7 +31,9 @@ The answer holds `root` - the directory the tab serves - and the stage catalog.
 A refusal means there is no pane.
 Say this and stop:
 
-> This works in the chamba web session, where the Specs tab holds your work. Open the browser window this container printed at start, or run `webterm` in the terminal to get the address again. Then run `/dx-spec` there.
+> This works in the chamba web session, where the Specs tab holds your work. Open the browser window this container printed at start, or run `webterm` in the terminal to get the address again. Then ask for this skill there.
+
+Say the command in the spelling of the session's own agent.
 
 Start no flow, and offer no substitute.
 There is one flow, and it needs the tab.
@@ -46,13 +49,33 @@ Three shapes, and one mechanism under all of them:
 
 - A **gate** judges one artifact. The user approves it, or asks for changes with the words that say what to change.
 - A **round** asks questions. Each question carries its options, whether one answer or several are allowed, and a box of its own for anything the options missed.
-- A **decision card** carries a finding that needs the user's judgment: the evidence, the trade-off, and apply or dismiss.
+- A **decision card** carries a finding that needs the user's judgment. It is one question, in a round's own shape, plus a required pointer to the passage it is about: the tab opens that passage and draws the card under it.
 
 Ask, then stop.
 Declaring something is the end of your turn.
 The pane types one line into this terminal when the user answers, and that line is what starts you again.
 Do not poll, and do not carry on with the thing the question was there to settle.
 
+**Nothing else ends your turn.**
+Three things do, and nothing else does:
+
+- An ask on the tab: a gate, a round or a decision card.
+- The collect invitation, which waits for the user to say what the work is.
+- The closing line that ends the run.
+
+`specs post` is not one of them.
+Posting a stage as running, posting an activity, and finishing a stage that has no gate all tell the board something and ask nobody anything, so the turn carries straight on into the work the post announced.
+Saying a line to the user is not one of them either: say it, and go straight on in the same turn.
+
+A stage posted as running with nothing after it is the failure this rule exists to stop.
+The board then tells the user that work is happening while the run is standing still, and no line ever comes back to start it again.
+
+**A line that comes back is not always an answer.**
+The user may ask you about the ask instead, from the same form, and the line says a question was asked and that nothing was answered.
+The ask is still open, and the form is still on their screen.
+Answer the question here, in plain message text, and leave the ask alone: do not declare it again, do not withdraw it, and do not treat the question as the decision.
+The user answers it in the pane when your answer has told them what they needed.
+
 You write to the user in plain messages in exactly four places:
 
 - The **collect invitation** - one short line that asks what the work is.
@@ -72,6 +95,22 @@ Raise a doubt in one of three ways, by where it comes up:
 
 The same rule covers any other guess that has to stand: label it on disk, so no choice stays silent.
 
+## When the steps change under you
+
+The user changes the confirmed protocol from the tab, at any moment, including while you are in the middle of a stage.
+The pane types one line into this terminal when they do, saying what moved.
+
+That line is work, not a status report.
+Read `specs state <spec>` and act on the difference:
+
+- A stage added: run it when its turn comes in catalog order, and run it next where its turn has passed.
+- A stage removed: it was still waiting, so there is nothing to undo. Stop planning for it.
+- Nothing else changed: the protocol is the same, and there is nothing to do.
+
+Finish what you are in the middle of first, unless the change makes that work pointless.
+Say in one line what you are going to do about it, and carry on.
+Never ask the user to confirm a change they just made.
+
 ## The tool owns the state
 
 The Specs tool writes `state.json` and the `README.md` of each spec directory.
@@ -91,7 +130,9 @@ specs stages                              where the specs live, and the stage ca
 specs state <spec>                        where the work stands, and what awaits the user
 echo '<json>' | specs intake              file a new piece of work
 echo '<json>' | specs propose <spec>      recommend a protocol, and put it to the user
+echo '<json>' | specs recommend <spec>    recommend how the run is shaped, for the execute form
 echo '<json>' | specs await <spec>        declare a gate, a round or a decision card
+echo '<json>' | specs withdraw <spec>     take back an ask nobody needs to answer
 echo '<json>' | specs post <spec>         say what is happening
 echo '<json>' | specs review <spec>       post one round of quality review
 echo '{"id":"<id>"}' | specs answers <spec>   read back what the user answered
@@ -105,6 +146,8 @@ echo '{"id":"<id>"}' | specs answers <spec>   read back what the user answered
 
 The answer is `{ "entry": "checkout-discounts", "path": "checkout-discounts/intake.md" }`.
 An attachment is `{ "name": "sketch.png", "type": "image/png", "data": "<base64>" }`.
+An intake may also carry `"wish": { "imagination": true }`, which is what the form's own flavour box files.
+The wish shapes what you recommend, and settles nothing: the steps are where the mode is confirmed.
 
 **Recommending a protocol:**
 
@@ -115,13 +158,42 @@ An attachment is `{ "name": "sketch.png", "type": "image/png", "data": "<base64>
 Name every stage you have an opinion about.
 The form shows the whole catalog either way, so the user sees what you did not recommend.
 
+**Recommending how the run is shaped:**
+
+```json
+{ "commits": "per-phase", "branch": "new", "branchName": "spec/checkout-discounts",
+  "pauses": "chosen", "pausePhases": ["phase-03-the-banner"],
+  "pauseReasons": { "phase-03-the-banner": "the checkout total reads the banner's rules, so a rule you would have written differently sends the next phase wrong" },
+  "noPauseReason": "",
+  "checkpoints": [
+    { "after": "phase-03-the-banner", "why": "later phases build on this one", "panel": ["correctness against the spec", "state and merge safety"] },
+    { "after": "final", "why": "judges the finished work as a whole", "panel": ["correctness against the spec", "docs consistency", "better ways to do this"] } ] }
+```
+
+`commits` is `per-phase`, `single` or `none`, and `branch` is `current` or `new`.
+`pauses` is `none`, `chosen` or `every`, and `pausePhases` names the phases for `chosen`.
+`pauseReasons` holds one line for each pause you recommend, keyed by the phase it sits after.
+`noPauseReason` holds the one line for a recommendation of `none`.
+A recommendation of `chosen` fills `pauseReasons` and leaves `noPauseReason` empty.
+A recommendation of `none` fills `noPauseReason` and leaves `pauseReasons` empty.
+A recommendation of `every` carries neither.
+Both are addressed to the user, and the form shows them under the Pauses field.
+A checkpoint's `after` is a phase id or the word `final`, and its `panel` holds one focus per reviewer.
+A phase id is the name of the phase's own file, without the extension.
+
+It lands in the state as `runRecommendations`, beside the `runDecisions` the form writes.
+This is a recommendation and nothing more.
+The execute form opens on it, the user decides it there, and what they decide is what binds the run.
+Give every panel one focus at least: a checkpoint with nobody on its panel has nobody to run, and is recorded as one that does not run.
+Post it once the plan is written and its phases are posted, and post it again where a later change to the plan makes it wrong.
+
 **Declaring a round:**
 
 ```json
 { "id": "interview-1", "kind": "round", "title": "A few things about the checkout", "file": "",
   "payload": { "kind": "round", "questions": [
     { "id": "scope", "ask": "Which orders can be partly cancelled?", "multi": false,
-      "invite": "Anything the options miss?",
+      "invite": "Where the options are wrong, say so",
       "options": [
         { "id": "any", "said": "Any order, at any time", "recommended": true },
         { "id": "unshipped", "said": "Only an order nothing has shipped from" } ] } ] } }
@@ -137,15 +209,54 @@ The form shows the whole catalog either way, so the user sees what you did not r
 `file` is the artifact the gate judges, relative to the spec directory.
 The tab opens that artifact and puts the gate under it.
 
+A gate may carry one box beside its approval, for one more thing that goes with approving:
+
+```json
+{ "payload": { "kind": "gate", "asks": "Approve it, or say what to change.",
+  "offer": { "said": "also commit the spec", "preset": true } } }
+```
+
+The box rides with the approval, so a gate that offers something is not followed by a gate of its own.
+The answer says `"accepted": true` where the user approved with the box ticked, and `false` for every other answer.
+An offer is for a small act that goes with the approval, and never for a second question.
+
 **Declaring a decision card:**
 
 ```json
 { "id": "rv-04", "kind": "gate", "title": "The plan leans on one mechanism", "file": "plan/PLAN.md",
-  "payload": { "kind": "decision",
-    "evidence": "what was found, and what it rests on",
-    "tradeoff": "what each way costs" } }
+  "payload": { "kind": "decision", "heading": "Phase 05 - the half-width button",
+    "questions": [
+      { "id": "half", "multi": false,
+        "ask": "Phase 05 stores a pixel width when the button is pressed, so a window resized afterwards leaves the pane at that width and no longer at half.\n\n**Trade-off.** A fraction keeps the button true after a resize and adds one more shape a width can take. Pixels keep one kind of width and let the button drift.",
+        "options": [
+          { "id": "fraction", "said": "Store half as a fraction, so the pane stays at half after a resize", "recommended": true },
+          { "id": "pixels", "said": "Keep the pixel width the button computed, as the plan says" } ] } ] } }
 ```
 
+Both parts of the pointer are required, and a declaration missing either one is refused.
+`file` is the artifact, relative to the spec directory, and it has to name a file the spec directory holds.
+`heading` is the `##` section inside it, as written; the tab opens the artifact at that section and draws the card under it.
+A heading no section matches lands on the top of the file, and where two sections share a heading the first one wins.
+
+The card asks exactly one question, with two options at least, and a declaration that holds fewer is refused.
+Mark one of them recommended, which is yours to get right: the door does not count the recommendations, and a card that offers none still opens.
+Write the passage's own words into the `ask`: what was found, and what each way costs.
+Say the proposed change as one option, in exact words, and the alternative as another, each in that finding's own terms.
+
+**Withdrawing an ask:**
+
+```json
+{ "id": "review-gate-1", "reason": "superseded by the second review gate" }
+```
+
+The awaiting list is what the user is told is open, so it must hold only what is genuinely open.
+An ask you supersede is withdrawn in the same act that supersedes it: when you declare a replacement, and when the answer reaches you anywhere else, the terminal included.
+One case the tool does for you: a gate declared on an artifact takes back any open gate on that same artifact, with the reason `superseded by <id>`, because one artifact holds one open judgment.
+A decision card is not a gate in this sense, so cards on one file stack, and a gate takes none of them back.
+Every other replacement is yours to withdraw: a round asked again with a new id, a gate moved to another artifact, and an ask the terminal answered.
+The round file stays on disk as the record of what was asked, and the log carries the reason.
+Withdrawing is your act, not the user's, so it adds nothing to the approvals.
+
 **Posting progress:**
 
 ```json
@@ -156,17 +267,23 @@ The tab opens that artifact and puts the gate under it.
 ```
 
 Post an activity when you start something that takes a while, so the board says what is happening.
+An activity needs no clearing, and there is no verb to clear one with.
+The board shows it while it is current, and stops the moment anything else is posted, or half an hour after it was said.
+So post one for a step that is under way, and post the next thing when that step ends.
+
 Post a stage as `running` when it starts, and as `done` with its artifacts when it ends.
 
 **Reading an answer back:**
 
 ```json
-{ "outcome": "approved", "said": "", "questions": [] }
+{ "answer": { "outcome": "approved", "said": "", "accepted": true, "questions": [] } }
 ```
 
-An outcome is `approved` or `changes` for a gate, `apply` or `dismiss` for a decision card, and `answered` for a round.
+An outcome is `approved` or `changes` for a gate, and `answered` for a round and for a decision card.
+`accepted` says what the gate's own box came back as, and is `false` where the gate offered none.
 A round's answer carries one line per question, and a question the user left alone is there too, marked `"answered": false`.
-Treat that as skipped. It is not a "no".
+Treat such a question as skipped. It is not a "no".
+A decision card's answer carries one line of the same kind, for its one question: the option the user chose, and what they wrote.
 `{ "answer": null }` means the user has not answered yet.
 
 ## Writing a question
@@ -179,10 +296,56 @@ Every question still follows these rules:
 - Put the option you would choose first, and mark it `"recommended": true`.
 - Keep an option's `said` short. Put the reasoning and the trade-off in the question's `ask`.
 - Where a real trade-off exists, lay it out and let the user decide. Never decide it silently.
-- Give every question an `invite` when a typed answer would be worth more than a choice.
+- Give a round's question an `invite` when a typed answer would be worth more than a choice. A question with none gets the plain *Your words*, so write an invite only where it says something that word does not. A decision card is the exception: its one box always says *Your words*, so an `invite` on a card's question is never shown.
 
 Give each round and each gate an id that says what it is: `interview-1`, `spec-gate`, `mocks-gate`.
 An id is answered once. Ask again with a new id.
+An answered ask has already left the "Needs you" list, so there is nothing to take back.
+Withdraw the earlier ask only where the new one replaces an ask the user never answered.
+`references/stages.md` says it in full, under **Asking again**.
+
+## Two rules over everything on disk
+
+These two hold in every stage of this skill and in every phase of `/dx-spec-execute`.
+They are stated here once, and pointed at from the flows that need them.
+
+**Keep what derives from a change true.**
+A change to `spec/SPEC.md` or to `plan/PLAN.md` can make something else wrong: a phase that covers a requirement nobody kept, a review report about a document that moved, a recommendation of how to shape the run that names a phase the plan lost.
+Where you change either document, work out what derives from what you changed, and refresh it in the same act.
+The run recommendations are the easiest one to forget: a change to the phase list makes a pause or a checkpoint that names a phase stale, so post the recommendation again.
+Never leave a derived thing to be found later.
+
+**Cross-check a stored answer against the code.**
+An answer the user gave a form, or gave a round in an earlier stage, gets the check a fresh interview answer gets.
+When you first read the code this work touches, read each stored answer against it, and raise a contradiction to the user rather than building on it:
+
+- "You said both themes, and this app has a dark theme alone."
+- "You said desktop only, and every screen in this app is responsive."
+- "You asked for broad research, and this work touches one function of your own code."
+
+The first two are the interview's answers, in the `Themes and devices` section of `SPEC.md`; the third is the research scope, on the confirmation form.
+
+Raise it the way you raise any doubt, and let the user settle it.
+Never change a stored answer on your own.
+
+## The commit style
+
+Every commit this family makes is written the same way: a type, a colon, then what the commit did.
+
+```
+docs: user-preferences spec ready
+feat: phase 02 - the consuming skills
+fix: user-preferences review fixes
+```
+
+The type says what the commit did to the code, and the list is open - `feat`, `fix`, `docs`, `chore` and `refactor` are the usual ones.
+A commit that touches spec files alone is a `docs` commit.
+A phase commit of a run takes the type that suits what that phase did, and names the phase in its description, as the second line above does.
+
+This is built-in behaviour, and nothing exposes it as a setting, a form field or a run decision.
+A project that wants another shape writes a principle in `principles.md`, which every run reads at start and honors best-effort - the standing every other principle has, and no more.
+
+`/dx-spec-execute` states no style of its own: every commit it makes is written from this one.
 
 ## What a finished spec is
 
@@ -197,7 +360,7 @@ The tab serves one root, and each piece of work is one directory under it.
 
 ```
 <root>/
-  principles.md          the settings and principles, owned by /dx-spec-config
+  principles.md          the engineering principles every run honors, and the user's to edit
   <slug>/
     README.md            written by the tool, from the state - never by you
     intake.md            what the work started as
@@ -225,24 +388,36 @@ Outside spec work, `webpane` and the Pages tab are the right home for a page.
 
 Keep a page standalone: no external stylesheet, no script that fetches anything, and images as data URLs.
 
-## Flow
+## The bootstrap
+
+Settle the root and the principles before step 1, and before the first step of `/dx-spec-execute`.
 
-Run the bootstrap in `../dx-spec-config/SKILL.md` before step 1.
-It resolves the root, reads the principles file, offers the one-time setup when there is none, and gives you the settings for the rest of the run.
+1. Read `root` from `specs stages`. That is the directory the Specs tab serves, and every path in this family resolves against it.
+2. Read `<root>/principles.md`. It is plain markdown: a `# Principles` heading, then one `- <principle>` bullet each, and nothing else.
+3. Where no file is there, write one from `references/principles-template.md` beside this file. Say in one line that you made it, and carry straight on.
+4. Honor every principle the file holds for the rest of the run, best-effort - which is the standing each one has, and no more. A file with no bullets holds no principles, so there is nothing to honor.
+
+A file that is already there produces no message at all.
+Nothing else about how this family works is configurable, and the user changes a principle by editing that file.
+
+## Flow
 
 ### 1. Start
 
-The user reaches this skill in one of three ways.
+Every start is this skill's own command, in the spelling of the session's agent.
+The user types it by hand, or the Specs tab types it for them: the New-spec form files the intake and then types the command with the fresh directory's name, and the pick-up action types it with the name of the work to continue.
+The argument decides where to begin.
 
-**A line arrived from the pane.** The user filed an intake on the tab, and the terminal carries one line naming the file. Read that file, and go to step 3.
+**It names a piece of work that exists.** Read `specs state <spec>`. Where the directory holds nothing but its intake - no confirmed protocol, no stage artifacts - read `intake.md` and go to step 4. Where the work is further along, go to step 3.
 
-**The user passed text.** Treat it as their opening input. When it names a piece of work that already exists, go to step 2.
+**It is anything else.** Treat it as the user's opening input, and go to step 2.
 
-**Nothing.** Read the root with `specs stages`.
+**There is no argument.** Read the root with `specs stages`.
 With one piece of work or more there, declare a round that asks which one, with one option per directory and one for something new.
 Declare it on the piece of work that changed last.
 Every asking verb names a spec, and there is no spec for "which spec" - so the round sits on a real one, and the tab shows it wherever the user is.
-Never name an empty spec or a spec that is not there: the verb refuses it, and the question is not asked at all.
+Never name a spec that is not there: the verb refuses it, and the question is not asked at all.
+Never name an empty directory either - the verb accepts one, so this rule is yours to keep.
 With nothing there, go straight to the collect invitation in step 2.
 
 ### 2. Collect
@@ -298,7 +473,14 @@ Rough rules for what to recommend:
 - Pure thinking, or one decision to make: exploration, maybe research, and no plan.
 - Large or risky work: add the quality review. Many phases, several stages feeding one spec, or anything that touches security, data or money.
 
-The pane offers imagination mode when the confirmed protocol holds exploration or UI mocks.
+**The wish.**
+`wish.imagination` in the state says the intake asked for imagination mode.
+Where it is set, recommend high-level exploration, and recommend UI mocks for work that has a user interface.
+Those two stages are what the mode changes, so a protocol without either one cannot honor the wish.
+Say in the stage's `why` that the user asked to imagine this freely first.
+Recommend neither one against your judgment: where the work plainly needs neither, say so in the `note`, and let the user decide at the form.
+
+The pane offers imagination mode when the confirmed protocol holds exploration or UI mocks, and the form opens with the line ticked where the wish is set.
 Read `references/imagination-guide.md` when the state comes back with `modes.imagination` true, when the user asks for the mode by name, and at no other time.
 
 Save what the user shared into `spec/` under lowercase names of their own.
@@ -347,19 +529,33 @@ Ask any marker still open in `SPEC.md` before the gate.
 The gate does not pass while a marker stays open.
 
 Then declare the finalize gate on `spec/SPEC.md`, saying what the spec covers in a sentence or two.
+Carry the commit with it, as the gate's own offer:
+
+```json
+{ "id": "finalize-gate", "kind": "gate", "title": "Is the spec ready to build from?", "file": "spec/SPEC.md",
+  "payload": { "kind": "gate", "asks": "Approve it, or say what to change.",
+    "offer": { "said": "also commit the spec", "preset": true } } }
+```
+
 On changes: revise, and declare a new gate.
 Loop until the user approves it.
 
-After they approve:
+After they approve, post both lines before you commit anything:
 
 ```
 echo '{"kind":"status","status":"ready"}' | specs post <spec>
+echo '{"kind":"note","said":"Spec ready: partial cancellation of a shipped order, with three mocks and a five-phase plan"}' | specs post <spec>
 ```
 
-Then declare one last gate: whether to commit the spec.
-On approval, stage the spec directory by path and commit it with a one-line message.
-Compose the message from the commit style in the principles file, with "spec ready" as its descriptive part.
+The note is one line saying what the spec holds, in the words a reader who was not here would want.
+It names no commit and no hash: the commit is made after it, so a hash written here would be one the state cannot have yet.
+Both posts move the state file and the rendered `README.md`, which is why they go first - a commit made before them leaves those two changed in the working tree with nothing left to carry them.
+
+Where the answer says `"accepted": true`, stage the spec directory by path and commit it with a one-line message.
+Compose the message from **The commit style** above, with "<spec name> spec ready" as its descriptive part.
 Commit only. Never push.
 Staging by path leaves every other change in the working tree alone.
+The tree is clean over the spec directory once that commit lands, which is the whole point of the order: post, then commit.
+Where it says `false`, commit nothing, and ask nothing more: the user answered this at the gate.
 
 Close with one short message: what the spec covers, where it is, whether it was committed, and, when a plan exists, that `/dx-spec-execute` runs it.

package/templates/skills/dx-spec/references/principles-template.md

@@ -0,0 +1,2 @@
+# Principles
+

package/templates/skills/dx-spec/references/review-guide.md

@@ -1,6 +1,6 @@
 # The quality review
 
-This file holds the reviewer briefs, the detection lenses, the severities, the report format, and the design-blockers loop.
+This file holds the reviewer briefs, the detection lenses, the severities, and the report format.
 The stage itself is defined in `stages.md`.
 Read this file when the stage starts, and not before.
 
@@ -52,9 +52,8 @@ Each lens has one line, so a brief names the lenses that belong to its focus.
 - Terminology drift - reads every artifact for one idea under several names, or one name over several ideas.
 - Principles alignment - reads the artifacts against the principles file and the repo's own rule files.
 - Better ways to do this - reads the design against the codebase for a simpler shape, and for code the repo already ships that does part of the work.
-- Design blockers - reads the design for what would send the build wrong, and reports at HIGH and CRITICAL alone.
 
-The consistency-and-completeness reviewer takes every lens except principles alignment, better ways to do this, and design blockers, which go to the reviewers of those names.
+The consistency-and-completeness reviewer takes every lens except principles alignment and better ways to do this, which go to the reviewers of those names.
 A focus outside this set takes the lenses that touch it.
 Every lens goes to exactly one reviewer on the confirmed panel, so a panel that drops a focus hands that focus's lenses to the reviewer nearest to it.
 
@@ -77,41 +76,6 @@ When the protocol has no execution plan stage, the lens checks instead that ever
 Fix a conflict with a principle by changing the work.
 Never resolve it by softening the principle.
 
-## The design-blockers loop
-
-One reviewer on every panel has the design-blockers focus.
-Its brief is the brief above, with two additions:
-
-- It reports HIGH and CRITICAL findings alone. Anything below that is not its business, and another reviewer has it.
-- It reads for what would send the build wrong: a design that cannot hold, a contract two artifacts read differently, a requirement whose shape makes it unbuildable as written.
-
-**The loop.**
-Run the blockers reviewer.
-Fix what it found.
-Then run it again, with fresh context, over the fixed artifacts.
-Repeat until a round returns nothing.
-A fresh run each time is the point: a reviewer that saw the last round would grade its own fixes.
-
-**The guardrail.**
-A scoped reviewer has no natural zero.
-Given fixed artifacts and a mandate to find HIGH findings, a reviewer finds HIGH findings, and the rounds degrade into ever smaller material dressed in a severity it does not carry.
-
-So judge every returned finding before you loop again, against one criterion:
-
-> A finding an executing agent would likely have resolved on its own is not a true design blocker, whatever severity the reviewer gave it.
-
-An executing agent reads the code, runs the tests, and makes the small calls the spec left open.
-That is its job.
-A finding that names one of those calls is execution's work, and the plan's own review checkpoints cover it.
-
-**The close.**
-A round whose findings all fail that test closes the loop.
-Record the judgment per finding in the report - what it was, and why it failed the test - and leave that material to execution.
-Only a finding that passes the test justifies another round.
-
-Convergence here is judged, never awaited.
-Do not run a further round in the hope of a zero.
-
 ## The report format
 
 `review/REVIEW.md`:
@@ -122,7 +86,6 @@ Do not run a further round in the hope of a zero.
 - Run: YYYY-MM-DD
 - Mode: fresh-context subagents | inline - the session that wrote the spec
 - Panel: <one focus per reviewer>
-- Blockers loop: <n> rounds, closed by <a zero round | judgment>
 - Findings: <total>, of which <n> applied, <n> dismissed, <n> waiting on you
 
 ## <the first reviewer's focus>
@@ -146,16 +109,6 @@ Do not run a further round in the hope of a zero.
 - State: APPLIED
 - Reasoning: <why the reviewer raised it>
 - Note: <the fix that was applied>
-
-## Design blockers
-
-### Round 1
-
-<the findings of that round, in the form above>
-
-### Round 2 - closed by judgment
-
-<each finding, with the judgment against the criterion and where the material was left>
 ```
 
 The running agent assembles this report from the reviewers' replies.
@@ -166,8 +119,9 @@ An id never changes, so a decision that names a finding still points at the same
 
 `State:` holds `APPLIED`, `DISMISSED` or `FOR YOUR DECISION`.
 A finding that waits on the user carries an `Options:` line, recommended option first.
+Those are the same options the finding's decision card offers, said the same way, so the report and the card do not disagree.
 Every other finding leaves that line out.
 The report keeps every finding, applied and dismissed included.
 A finding the user decides on keeps its id and gains the outcome in its `Note:` line.
-Applying that decision changes its `State:` line: `APPLIED` when the decision changed the artifacts, and `DISMISSED` when the user left them as they are.
+Applying that decision changes its `State:` line: `APPLIED` when the option the user chose changed the artifacts, and `DISMISSED` when it left them as they are.
 Either way, drop the `Options:` line and update the counts in the header.

package/templates/skills/dx-spec/references/spec-guide.md

@@ -5,9 +5,15 @@ The technical specs stage of `/dx-spec` uses this guide, and so does every other
 **No fixed template.**
 Write the sections the work needs, and name and order them to fit the work.
 A small chore may need a few lines. A large feature may need many sections.
-Common sections are: goal, context, scope and **non-goals**, requirements or behavior, edge cases and errors, data and contracts, constraints, and acceptance criteria.
+Common sections are: goal, context, scope and **non-goals**, requirements or behavior, edge cases and errors, data and contracts, `Documentation impact`, constraints, and acceptance criteria.
 For the constraints, follow the repo's own rules in `CLAUDE.md` or `AGENTS.md`.
 Drop every section that does not apply.
+
+**`Documentation impact` is the one section that always applies.**
+Read the project's own documents - the README, the guides, and each document that sits beside the code the work touches - and name the ones the work makes not correct.
+Write one line for each: the path to it, and what the work changes in it.
+Where the work leaves every document correct, write one line that says so.
+The execution plan stage reads this section by name, so head it exactly this way.
 Label anything left open as an **assumption** or an **open question**.
 Write each date as an absolute date.
 Reference code as `path:line`.
@@ -47,6 +53,18 @@ Success criteria carry no IDs.
 Write one entry per choice: the choice, the reason for it, and the alternatives the work rejected with the reason for each.
 The research stage produces the comparison behind a decision, and the spec records its outcome.
 
+**Add a `Themes and devices` section** to every piece of user-facing work.
+It holds the two facts the interview settled about the application the work is in: which themes it draws in - dark, light, or both - and which devices it is laid out for - desktop only, responsive, or mobile-first.
+Write one line each, with what the code gives beside the answer where the two differ.
+The UI mocks stage reads this section by name, so head it exactly this way.
+
+```markdown
+## Themes and devices
+
+- Themes: both - every screen in this application draws in dark and light today.
+- Devices: responsive - one layout from a phone width up.
+```
+
 **Add a `Mocks` section** when the UI mocks stage runs.
 Write one line per screen: its id, its title, and the path to its page relative to `SPEC.md`.
 After the user approves the mocks, add a line `Approved: YYYY-MM-DD`.
@@ -82,8 +100,8 @@ Either way, keep it self-contained: no external image, and no script.
 1. At the top of the spec, close to as written:
 
 > **For the implementing agent - read this first.** This spec was written during planning with limited knowledge of the code.
-> Before building anything, review it carefully against the actual codebase and **plan first** (in plan mode, where your environment has one).
-> Treat nothing here as settled: if the spec turns out misaligned with the code, or you see a better path, **push back and raise it** rather than building something you can tell is off.
+> Before building anything, review it carefully against the actual codebase and **plan first** (in plan mode, where the agent's environment has one).
+> Treat nothing here as settled: if the spec turns out misaligned with the code, or a better path shows itself, **push back and raise it** rather than building something the agent can tell is off.
 
 2. Inside a solution sketch, where the spec has one, close to as written:
 
@@ -115,7 +133,9 @@ Keep every fact, every requirement ID, every acceptance criterion, and every lab
 An ID never changes, because a phase and a finding point at it.
 
 **One round of review follows every rewrite.**
-Run one fresh reviewer, once, scoped to the rewrite alone:
+Run one fresh reviewer, once, scoped to the rewrite alone.
+Where your environment gives you no sub-agent, read the rewrite against the copies yourself, in one pass with nothing else in it, and say in the message after it that the reviewer was you.
+The two points below are what that pass covers either way:
 
 - Completeness against the copies in `.rewrite/`, so no meaning was lost. Give the reviewer both paths and let it read them itself. Never summarize the old text for it: a summary of yours is what it is there to check.
 - The repo's own writing rules.