chamba 0.6.1 → 0.8.0

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

@@ -0,0 +1,561 @@
+---
+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. 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 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.
+Everything is on disk, so the work stops at any point and continues in a later session, with any agent.
+
+**This skill plans. It does not build.**
+Do not edit application code while it runs, whatever the request asks for.
+`/dx-spec-execute` builds the work after the spec is ready.
+
+## The web session
+
+This family runs inside a chamba web session, where the Specs tab holds the work.
+Check for one before anything else:
+
+```
+specs stages
+```
+
+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 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.
+
+## The one hard rule
+
+**Everything you ask the user goes on the Specs tab.**
+The tab draws the form, the user answers it there, and the answer comes back as a file.
+`specs await` is how you ask.
+Nothing you ask the user is a message in this terminal, and nothing is an `AskUserQuestion` call.
+
+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. 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.
+- The **exploration stage** - thinking out loud is its whole point.
+- A **line of fact** the user needs before a form makes sense, sent in the same turn as the form.
+- The **closing line** that ends the run.
+
+**Raise a doubt. Never guess at it.**
+Do not settle a doubt on your own while a spec is being built, however small it looks.
+A fresh agent builds from this spec without asking anything, so a doubt this session swallows becomes a wrong build later.
+
+Raise a doubt in one of three ways, by where it comes up:
+
+- Outside a stage that writes `SPEC.md`: ask it in the next round.
+- Inside a stage that writes `SPEC.md`: queue it in place as a `[NEEDS CLARIFICATION: ...]` marker, and ask it at the next round or gate, once it clears the bar in `references/spec-guide.md`.
+- Below that bar: write it to disk as a labeled assumption, naming the guess you made.
+
+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.
+**Never edit either one.**
+Never write a protocol list, a stage checkbox, a status line or a log line by hand.
+You move the work with the verbs below, and the tool writes both files in the same act, so the board in the pane and the file in git cannot disagree.
+
+Everything else in the spec directory is yours: `spec/SPEC.md`, the research, the mocks, the plan, the review, and the visuals beside them.
+
+## The verbs
+
+`specs <verb> [<spec>]` takes JSON on stdin where a verb needs a payload, and answers JSON on stdout.
+`<spec>` is the directory name the tab shows.
+
+```
+specs stages                              where the specs live, and the stage catalog
+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
+```
+
+**Filing an intake:**
+
+```json
+{ "name": "Checkout discounts", "text": "everything the user said, in their words", "attachments": [] }
+```
+
+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:**
+
+```json
+{ "stages": [{ "id": "interview", "recommended": true, "why": "the scope has open edges" }], "note": "" }
+```
+
+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": "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" } ] } ] } }
+```
+
+**Declaring a gate:**
+
+```json
+{ "id": "spec-gate", "kind": "gate", "title": "Does the spec look right?", "file": "spec/SPEC.md",
+  "payload": { "kind": "gate", "asks": "Approve it, or say what to change." } }
+```
+
+`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", "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
+{ "kind": "activity", "said": "Reading the checkout code" }
+{ "kind": "stage", "stage": "codebase-analysis", "status": "done", "artifacts": ["spec/SPEC.md"] }
+{ "kind": "status", "status": "ready" }
+{ "kind": "note", "said": "one dated line for the log" }
+```
+
+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
+{ "answer": { "outcome": "approved", "said": "", "accepted": true, "questions": [] } }
+```
+
+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 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
+
+The pane's form has no limit on questions or options, so ask the whole round at once rather than in a chain of small ones.
+Every question still follows these rules:
+
+- Write for someone who has never used these skills.
+- Do not use internal terms - directory layout, phase files, stage names - unless the option explains them in the same breath.
+- 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 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
+
+A complete spec lets a fresh agent open the directory with no other context and know what to build.
+That agent learns where the edges are, how to tell the work is done, and roughly where the code goes.
+No question for the user is left.
+Aim for a production-grade spec every time.
+
+## What is on disk
+
+The tab serves one root, and each piece of work is one directory under it.
+
+```
+<root>/
+  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
+    spec/
+      SPEC.md            the specification
+      *.md, *.svg        what the user shared, and visuals written beside the spec
+    research/RESEARCH.md written by the research stage
+    mocks/<mock-id>.html one standalone page per screen
+    plan/PLAN.md         the execution plan, plus one file per phase during the run
+    review/REVIEW.md     the quality review report
+  archive/
+    YYYY-MM-DD-<slug>/   work that is finished and signed off
+```
+
+A stage directory appears when its stage writes something. Nothing is created empty.
+
+## A page you make during this work
+
+You may draw a page to explain something - a flow, a comparison, a diagram.
+During spec work, that page belongs to the spec, so save it into the spec directory under a lowercase name.
+The tab lists it beside the other artifacts and renders it, and the user comments on it there.
+Do not publish it to the Pages tab: a page on Pages belongs to this conversation, and this one belongs to the work.
+
+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.
+
+## The bootstrap
+
+Settle the root and the principles before step 1, and before the first step of `/dx-spec-execute`.
+
+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
+
+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.
+
+**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.
+
+**It is anything else.** Treat it as the user's opening input, and go to step 2.
+
+**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 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
+
+Let the user say everything they have before you ask anything.
+
+Send this invitation as one short message, in these words:
+
+> Tell me about the work. Paste everything you have - notes, links, screenshots, file paths, snippets, examples, prior art - in one go, and I'll take it from there.
+
+Then end your turn and wait.
+Skip the invitation when their opening input already covers it.
+
+With their input in, file it:
+
+```
+echo '{"name":"<a working name>","text":"<everything they said>","attachments":[]}' | specs intake
+```
+
+The tool makes the directory, writes `intake.md`, and starts the state file.
+The tab opens on it.
+
+### 3. Pick up work in progress
+
+Read `specs state <spec>` and every artifact in the directory.
+The state says which stages were confirmed, where each one stands, and what is waiting for the user.
+
+`.specs/user-feedback.json` in the directory holds annotations the user sent that nobody has applied.
+Apply them as `references/stages.md` defines, before anything else.
+
+Then declare a round: what the work is, where it stands, and what happens next - continue, redo something, or change the steps.
+
+### 4. Choose the protocol
+
+Read what the input points to in the codebase, enough to judge the shape and the size of the work.
+
+Then recommend the stages this work needs:
+
+```
+echo '{"stages":[...],"note":""}' | specs propose <spec>
+```
+
+Give every stage you recommend a `why` of one sentence, in the user's terms.
+The form shows the whole catalog, recommended or not, so the user sees the choice whole.
+Confirming writes the protocol into the state, in catalog order.
+
+Rough rules for what to recommend:
+
+- A bug fix: codebase analysis and an execution plan.
+- A small feature or a chore: interview, codebase analysis, execution plan.
+- A new user-facing feature: exploration, interview, codebase analysis, technical specs, UI mocks, execution plan.
+- Work in a subject you or the user do not know well: add research.
+- 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 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.
+
+### 5. Run the stages
+
+Run the stages in the order the confirmed protocol lists.
+`references/stages.md` defines each one.
+Read a stage's section when the stage starts, and run the stage from that definition: it carries gates and rules the stage name alone does not state.
+
+Every stage that writes into `SPEC.md` also uses `references/spec-guide.md`.
+
+Post the stage as `running` when it starts.
+Post it as `done` with its artifacts when its gate is approved.
+Every stage ends at a gate, except codebase analysis, which feeds the next stage and has none.
+
+Every gate also clears the open markers.
+Before you declare a gate, read `SPEC.md` for open `[NEEDS CLARIFICATION: ...]` markers.
+Put them in the same round as the gate, in the priority order in `references/spec-guide.md`.
+Each answer replaces its marker in `SPEC.md` in the same round.
+This is what makes every marker reach the user.
+Codebase analysis has no gate, so what it opens is asked at the gate of the stage after it.
+The interview asks its own markers in its own rounds.
+
+### 6. The coherence rewrite
+
+Before the finalize gate, rewrite what the work changed after it was first written.
+`references/spec-guide.md` defines this step: when it runs, what it produces, and the one round of review that follows it.
+
+### 7. Finalize
+
+Read every file in the spec directory from start to end, and check:
+
+- Every assumption and open question is labeled.
+- No two files disagree.
+- Each requirement carries its own acceptance criterion, where the spec carries requirement IDs.
+- Every ID appears in some phase's `Covers` line, where the protocol includes the execution plan.
+
+Skip `mocks/candidates/`: it holds directions nobody chose.
+
+When `review/REVIEW.md` is there, this read covers less ground.
+Read the parts no reviewer saw: the fixes the stage made, and the edits that came from the user's decisions at the review gate.
+Treat the rest as covered, because the review stage ran the deeper version of this check over it.
+
+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, 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>
+```
+
+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.