chamba 0.6.1 → 0.7.0

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

@@ -0,0 +1,313 @@
+---
+name: dx-spec-config
+description: View and change the settings and principles the dx-spec skills honor - commit style, saved planning answers, and the engineering principles - and define the one-time setup the other dx-spec skills offer at start. User-invoked only.
+disable-model-invocation: true
+---
+
+# dx-spec config - the user's preferences
+
+This skill runs when the user types `/dx-spec-config`. It never starts on its own.
+
+The skill owns one file: the principles file beside the specs.
+It writes that file the first time, it runs a wizard to change it, and it runs a doctor that checks it against the shape below.
+`/dx-spec` and `/dx-spec-execute` only read it.
+The init flow is the one flow this skill offers the other two.
+
+## The web session
+
+Every skill in this family runs inside a chamba web session.
+Check for one before anything else:
+
+```
+specs stages
+```
+
+The answer holds `root` - the directory the Specs 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-config` there.
+
+Start no flow, and offer no substitute.
+
+## Asking questions
+
+The questions in this skill belong to no piece of work, so they do not go on the Specs tab.
+The tab's forms belong to one spec, and settings belong to none.
+Ask them with `AskUserQuestion`.
+When that tool is absent, or refuses a call, ask the question as a normal message and end your turn.
+Then wait. Do not do the thing the question was there to confirm.
+
+Write a question whose options do not depend on the work as a fenced block tagged `question`, and ask it exactly as written.
+
+````markdown
+```question
+Question: <the question text, verbatim>
+Header: <the short chip label, verbatim>
+- <option label>
+  <option description>
+- <option label>
+  <option description>
+```
+````
+
+How to read a block:
+
+- Copy the question text, the header, the labels, the descriptions and their order exactly.
+- Angle brackets mark the parts you fill in.
+- A line marked `only when ...` is conditional. Every other line is always there.
+- Never reword a block to fit the moment. Never add an option.
+- `AskUserQuestion` adds its own free-text choice, so no block carries an option that only means "something else".
+
+Every question shows 2 options at least and 4 options at most.
+Put the recommended option first, and end its label with `(Recommended)`.
+Keep labels short, and put the reasoning in the descriptions.
+Write for someone who has never used these skills.
+
+## The specs root
+
+`specs stages` answers with `root`.
+That is the directory the Specs tab serves, and every path in this family resolves against it.
+The principles file is `<root>/principles.md`.
+
+## The principles file
+
+`<root>/principles.md` is plain markdown.
+It holds a settings section and a principles section, and nothing else.
+
+The settings sit under a `## Settings` heading, one `- <key>: <value>` bullet each, under one note line that points at `/dx-spec-config`.
+The principles sit under a `## Principles` heading, one `- <principle>` bullet each.
+The file carries no explanation of a setting, no guidance on writing a principle, and no examples.
+Every run of every skill in this family reads this file, so it holds only what an agent must honor.
+The meaning of each setting lives here, in the skill that writes the file.
+
+What each setting holds:
+
+- `commit_style` - the shape of every commit message this family makes. `default` names the default style below. Any other value is a plain description of the project's own shape, with an example message in it.
+- `commit_mode` - a saved answer to "should the run commit as it goes?". `prompt` keeps the question, `current-branch` commits on the current branch, `new-branch` commits on a new branch, and `no-commits` leaves the changes in the working tree.
+- `commit_grouping` - a saved answer to "how are those commits grouped?". `prompt` keeps the question, `per phase` commits each phase, and `single` commits once at the end. This setting counts only when the run commits at all.
+- `branch_naming` - the branch name pattern for `commit_mode: new-branch`. `<slug>` in the pattern becomes the spec's own slug.
+
+The principles section holds plain engineering principles that every run honors best-effort.
+A principle states its reason when the reason is not obvious.
+A principle states its own scope when it does not apply everywhere.
+When the project's own documents already carry a rule, the principle points at that rule and declares it binding.
+It does not restate the rule.
+The section ships empty, so an empty section means no principles.
+Use this form:
+
+```markdown
+- Always recommend two code reviewers at least in an execution plan, because one reviewer shares too many blind spots with the author.
+- Never add a dependency without asking first: a dependency is a cost the project carries for years.
+```
+
+A saved answer skips its question, and says nothing.
+The execution-plan stage still records the resolved `Commits:` and `Branch:` lines in `PLAN.md`, whatever their source.
+The plan gate still shows the whole setup, so the user can make an exception for one spec there.
+That exception changes that plan alone, and never this file.
+
+The shipped template is `references/principles-template.md`, beside this file.
+A fresh file starts as a copy of it.
+
+## The default commit style
+
+The default style is the spec name, then a colon, then what the commit did:
+
+```
+user-preferences: spec ready
+user-preferences: phase 02 - the consuming skills
+user-preferences: review fixes
+```
+
+This skill and its template are the only places that spell the pattern out.
+Every other mention of it says "the default style".
+
+The commits this skill makes use `dx-spec` in place of the spec name: `dx-spec: set up config` and `dx-spec: update config`.
+A `commit_style` that is not `default` restyles these the same as any other message.
+
+When `commit_style` describes a type-prefixed convention, two families apply:
+
+- A spec-level commit touches only spec files, so its type is fixed - `docs`, for example.
+- A work-level commit carries code, so its type comes from what the phase did.
+
+## The bootstrap
+
+Before its first step, `/dx-spec` and `/dx-spec-execute` do this:
+
+1. Read `root` from `specs stages`.
+2. Read `<root>/principles.md` when it is there, and take what parses: the settings it knows, and the principles bullets.
+3. When a setting is missing, unreadable, or holds a value this file does not list, use its default. Say so once, in one line, and name `/dx-spec-config` as where it gets sorted out. Repair nothing here: a run the user is waiting on is not the place to fix a settings file.
+4. With no file there at all, ask the question below. On "set it up now", run the init flow before the run continues.
+5. Apply the settings and the principles for the rest of the run.
+
+```question
+Question: You have no settings file for this yet. Should I set one up now?
+Header: Setup
+- Set it up now (Recommended)
+  A few questions about how you like to work - how commits are written, and what I may do without asking - and I write the file before we carry on. You answer them once.
+- Carry on without it
+  I use the built-in defaults for this run and ask again next time. You can also set it up whenever you like, with /dx-spec-config.
+```
+
+A file that reads cleanly produces no message at all.
+The init flow is the only flow a bootstrap runs.
+Checking the file, repairing it and changing it all belong to a direct run of this skill.
+
+## Init flow
+
+This flow runs when a direct `/dx-spec-config` run finds no principles file, and when a bootstrap offers it and the user agrees.
+
+1. Send one short intro message: this family keeps a small settings and principles file beside the specs, this is its one-time setup, and anything chosen here changes later through `/dx-spec-config` or by editing the file.
+2. Work out the project's commit style. Read the project's own commit rules and its recent commit subjects. A clear shape - a type prefix, a ticket key, any consistent pattern - becomes the first option below, written in plain words with an example message from this project. Drop that option when the project shows no consistent shape. A commit this family made in the default style is not a project convention.
+3. Ask the three questions below in one `AskUserQuestion` call.
+
+```question
+Question: How should the commits I make be written?
+Header: Commit style
+- <the project's own style, in a few words> (Recommended) (only when the project's commits or rules show a clear shape)
+  <the shape found, in plain words, with an example message from this project>.
+- The default style
+  The spec name, a colon, then what the commit did.
+- Conventional prefixes (only when the first option is not itself a type-prefix shape)
+  A type prefix, then what the commit did: "feat: ...", "fix: ...", "docs: ...", and so on.
+```
+
+When the first option is absent, the default style comes first and carries the marker.
+Save the answer as `commit_style`: `default` for the default style, and otherwise a plain description of the shape with an example message in it.
+
+```question
+Question: Should runs save their work with git commits as they go?
+Header: Commits
+- Decide per piece of work (Recommended)
+  Each execution plan asks this when it is written.
+- Yes, on the current branch
+  Every run commits as it goes, on whatever branch is checked out.
+- Yes, on a new branch
+  Every run commits on a branch of its own, named by a pattern you can change later.
+- No commits
+  Runs leave their changes in your working folder for you to handle.
+```
+
+```question
+Question: And when a run commits, how should the commits be grouped?
+Header: Grouping
+- Decide per piece of work (Recommended)
+  Each execution plan asks this when it is written.
+- One commit per phase
+  Each finished phase is committed on its own.
+- A single commit
+  All the work lands in one commit at the end.
+```
+
+4. Ask the question below in a second `AskUserQuestion` call, right after those three. It gets its own call, because the answer starts a task and leads to another question.
+
+```question
+Question: Should I read your project now and draft the principles I should follow?
+Header: Principles
+- Draft them from the project (Recommended)
+  I read your rule documents, the README, the lint and CI setup, and recent commits, and propose a short list for you to look over.
+- Start with none
+  The file is written with an empty principles section. You can add principles any time through /dx-spec-config, which offers the same draft from your project.
+```
+
+On "draft them from the project": read `CLAUDE.md` and `AGENTS.md`, the README, the lint and CI configs, and recent commits.
+Draft the principles from what they show.
+Point at a rule the project already documents, and declare it binding, rather than restating it.
+Write down the undocumented conventions alone.
+Keep the draft to five or six principles, because every run reads this file.
+Write nothing to disk in this step. Step 5 writes it.
+
+On "start with none": keep the template's empty principles section for step 5.
+
+5. Write `<root>/principles.md` once: the template, with each setting's value replaced by the answer, and the principles section either drafted or empty.
+6. Only when you drafted principles, ask the user to read them:
+
+```question
+Question: I wrote the principles into <root>/principles.md - please read them there. Keep them as they are?
+Header: Principles
+- Keep them (Recommended)
+  The file stays as it is.
+- Change them
+  Tell me what to add, reword or drop. I rewrite the principles section and ask again.
+```
+
+On "change them": rewrite the section from what the user typed, then ask this question again. Loop until they keep it.
+
+7. Offer the commit gate below, with the message `dx-spec: set up config` in the confirmed style.
+8. Carry on with whatever the skill was invoked to do.
+
+```question
+Question: Should I commit your principles file to git?
+Header: Commit file
+- Commit it (Recommended)
+  I commit only <root>/principles.md, with the message "<the composed message>". I never push.
+  (only when the working tree holds unrelated changes) Everything else you have changed is left exactly as it is.
+- Don't commit
+  The file stays in your working folder for you to handle.
+```
+
+On "commit": stage the principles file by path, and commit it. Commit only. Never push.
+
+## The doctor
+
+The doctor is the check a direct `/dx-spec-config` run makes on an existing file.
+It is the one place file trouble is dealt with.
+No other skill runs it, and it never runs during someone else's work.
+
+Compare the user's file against the shape above, by meaning rather than by bytes:
+
+- A setting the shape has and the file lacks: propose adding it with its default, and say what it does.
+- A setting whose value is not one this file lists: say what the setting does, name the values that exist, and ask which one is meant.
+- A setting the file holds that this shape no longer has: propose dropping it, because nothing reads it.
+- Text this shape does not have - an opening note, an explanation under a setting, example principles: propose dropping it, because every run reads this file and that material belongs in this skill. Never touch a line under `## Principles` this way. A principle belongs to the user, however it is worded.
+- A whole section the file lacks: treat it as something the user removed. Name what is on offer, and put back only what they ask for.
+- A file that does not read as markdown at all: say so plainly, and offer to write a fresh one, keeping every setting and principle the current file still lets you read.
+
+Nothing here is an error, and nothing is applied without asking.
+Say what you found in one short message, then ask:
+
+```question
+Question: I compared your settings file with the shape this version expects: <what differs, in a line each>. Bring it up to date?
+Header: Settings file
+- Apply these (Recommended)
+  I make those changes. Every setting you chose and every principle you wrote stays exactly as it is.
+- Leave it as it is
+  Nothing is changed, and everything keeps working on what your file already says.
+```
+
+A partial answer - one change and not another - comes through free text.
+Write into the file whatever the user accepts.
+The commit gate at the end of the run covers it.
+
+## Running directly - the wizard
+
+When the user types `/dx-spec-config`, read `root` and look at `principles.md`:
+
+- No file: run the init flow, minus its last step, and stop there. A file just written needs no doctor.
+- A file there: run the doctor, then the wizard below.
+
+Show one short message: the commit style, the saved planning answers, and a short summary of the principles.
+When the section is empty, say plainly that no principles are written yet.
+Then ask:
+
+```question
+Question: Anything you want to change?
+Header: Settings
+- Nothing - keep it as it is (Recommended)
+  The wizard ends here.
+- The commit style
+  How the commits I make are written. I can also work out a fresh proposal from your project's commits.
+- The planning answers
+  Whether runs commit as they go, how commits are grouped, and the branch name pattern.
+- The principles
+  The principles every run reads at start and honors. I show you the ones you have, and you add, reword or drop them by typing what you want.
+```
+
+A setting change reuses the init-flow question for that setting.
+The commit style change offers the same fresh derivation the init flow makes.
+The principles area offers the same derivation too.
+Change the principles and the branch pattern through free text: the user types, you restate, they confirm.
+After each change, ask this question again, so several things change in one run.
+
+When the doctor or the wizard changed anything, write the file, then end with the commit gate from the init flow and the message `dx-spec: update config`.
+When nothing changed, end without touching the file.

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

@@ -0,0 +1,12 @@
+# Principles
+
+## Settings
+
+Run `/dx-spec-config` to change these.
+
+- commit_style: default
+- commit_mode: prompt
+- commit_grouping: prompt
+- branch_naming: spec/<slug>
+
+## Principles

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

@@ -0,0 +1,324 @@
+---
+name: dx-spec-execute
+description: Run the execution plan of a spec the Specs tab holds, phase by phase, with the run's progress on that tab as it goes. User-invoked only.
+disable-model-invocation: true
+argument-hint: "[the name of the piece of work to run]"
+---
+
+# dx-spec execute - build the work from its plan
+
+This skill runs when the user types `/dx-spec-execute`. It never starts on its own.
+
+Your job is to move through the phases of one spec's plan, and to keep every bit of progress on disk, so a later session restarts from this point.
+
+Write, build, verify, record and commit each phase yourself.
+The only subagents are reviewers, and they exist so somebody who did not do the work judges it.
+
+## 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 run `/dx-spec-execute` there.
+
+Start no flow, and offer no substitute.
+
+## Asking and telling
+
+**Everything you ask the user goes on the Specs tab**, through `specs await`.
+A pause, a blocked run, a choice of spec: each one is a gate or a round on the tab.
+Declaring one ends your turn.
+The pane types one line into this terminal when the user answers, and that line starts you again.
+
+`/dx-spec` carries the payload shapes, under **The verbs**.
+Read that section for the exact JSON.
+
+**Everything you tell the user while building is normal message text.**
+A progress report is not a question.
+
+**Post the run as it moves**, so the board shows it live:
+
+```
+echo '{"kind":"status","status":"executing"}' | specs post <spec>
+echo '{"kind":"phase","phase":"phase-02-the-consuming-skills","title":"The consuming skills","status":"running"}' | specs post <spec>
+echo '{"kind":"activity","said":"Running the verify steps"}' | specs post <spec>
+echo '{"kind":"phase","phase":"phase-02-the-consuming-skills","title":"The consuming skills","status":"done"}' | specs post <spec>
+echo '{"round":1,"verdict":"holds, one for you","findings":6,"judgments":1}' | specs review <spec>
+```
+
+A phase's id is its file's name without the extension, which is what you already write and tick.
+
+## The tool owns the state
+
+The Specs tool writes `state.json` and each spec's `README.md`.
+**Never edit either one.**
+The status, the phase list, the review rounds and the dated log are the tool's, and the verbs above are how they move.
+
+`plan/PLAN.md` and the phase files are yours, and you write them by hand as always.
+
+## A page you make during the run
+
+A page that explains this piece of work belongs to the work, so save it into the spec directory under a lowercase name.
+The tab lists it beside the other artifacts and renders it.
+A page about anything else goes to the Pages tab with `webpane`.
+Either way, keep it standalone: no external stylesheet, no script that fetches anything, and images as data URLs.
+
+## The plan is the user's instruction
+
+The user chose everything in the plan at spec time: the commits and the branch, the pauses, the review checkpoints, the verify steps, and the principles check with its recorded deviations.
+All of it binds this run.
+
+A recorded deviation is an approved exception.
+Build the work to match it, and never return it quietly to the principle it excepts.
+A principle the plan does not except stays binding.
+
+Your own limits do not justify a change to the plan.
+When you cannot do what the plan asks, that is a stop condition, and the **Stop and ask** section says how to raise it.
+Never replace the plan's instruction with a weaker one and carry on.
+
+Two things fall outside this rule.
+A choice of your own that changes nothing - which of two equal ways to read a file - is yours.
+An instruction from the user in this conversation overrides the plan.
+The plan loses to the user, and never to you.
+
+## 0. Bootstrap
+
+Run the bootstrap in `../dx-spec-config/SKILL.md` first.
+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. Choose the spec
+
+A candidate is a piece of work under the root, outside `archive/`, whose plan still holds an unticked phase.
+
+The user may name one.
+A name that matches one spec exactly is an instruction, not a guess.
+Start on it, and ask nothing.
+
+In three cases the spec is a guess of yours:
+
+- A name that matches no spec exactly.
+- A spec you infer from the conversation.
+- The one candidate, when there is only one.
+
+Confirm a guess in a round before you do any work, even when one candidate exists.
+Give the round one option per candidate, carrying how many phases are done and what comes next, and one option that means none of these.
+Declare the round on the likeliest candidate, because every asking verb names a spec and it has to be one that is there.
+Change nothing until the user answers.
+
+With no candidate at all, ask nothing.
+Say there is no open work, name `/dx-spec` as where a spec gets written, and stop.
+
+Then read, in this order: `specs state <spec>`, `spec/SPEC.md`, and `plan/PLAN.md`.
+Do not read a phase file yet. Read or write one when its phase starts.
+
+Handle these two states before anything else:
+
+- No `plan/` directory: say this spec has no execution plan, say `/dx-spec` adds one, and stop.
+- Every phase ticked: say so, and stop.
+
+## 2. Work out where things stand
+
+Work it out from disk alone.
+Say it in a message before you do anything, together with what the plan asks for: its `Pauses:` line and its `Review checkpoints:` line.
+The user then knows from the start where this run stops and where it gets reviewed.
+
+**The phases.**
+
+- A phase ticked in `PLAN.md` is done.
+- The first unticked phase is next.
+- A phase file that exists carries a `Status:` line: `in progress` or `done`.
+- A file at `in progress` under an unticked phase means an earlier session stopped mid-phase. Treat it as suspect: check `git status` for half-done work, re-run the verify steps of the ticked tasks, and carry on from where the evidence points.
+- The state file carries a dated line for each completed review checkpoint. A checkpoint whose phases are all done with no such line has not run. Run it before you move on.
+
+**The commits.**
+Read the `Commits:` line: `per phase`, `single` or `none`.
+It says how much of the record the repository itself shows:
+
+- `per phase`: a completed phase is a committed phase, and uncommitted changes belong to the phase that was interrupted.
+- `single` or `none`: nothing is committed before the run ends, if at all. The phase status lines and the ticked boxes are the only record.
+
+Read the `Branch:` line with it.
+`current` means the commits land on the current branch.
+Any other value names a branch for this run.
+
+**A state that does not match.**
+When the disk does not hold what this skill expects, settle it with judgment and say what you chose in the report.
+Do not stop, and do not follow a fixed rule.
+
+## 3. The loop
+
+Every phase goes through the same steps, and you carry out every one yourself.
+
+1. **The phase file.**
+
+   Check for a phase file an interrupted run left, and never rewrite one.
+   Check it against the actual code before you change anything.
+   Keep its ticked tasks: they show what got done.
+   Adapt a small change and note it. Treat a design change as a stop condition.
+
+   With no such file, write `plan/phase-NN-<slug>.md` right before you build the phase, against the code as it stands after the earlier phases.
+   Take the goal and the definition of done from `PLAN.md`:
+
+   ```markdown
+   # Phase 02 - <name>
+
+   Status: in progress
+
+   ## Tasks
+
+   - [ ] <task>
+   - [ ] <task>
+
+   ## Verify
+
+   - <command or check that proves the definition of done>
+   ```
+
+   Do not give much weight to development cost when you write it.
+   Prefer quality, simplicity, robustness, scalability and long-term maintainability.
+   When something grows too large, restructure it by judgment: refactor, split, or extract.
+   Never restructure by a number set in advance.
+
+   Post the phase as `running`.
+
+2. **Build.** Keep the changes scoped to this phase, and tick each task as it completes.
+
+3. **Verify.** Run the Verify section, and make it pass.
+
+4. **Record.** Set the phase's `Status:` to `done`, tick its box in `PLAN.md`, and post the phase as `done`.
+
+   With `Commits: per phase`: commit the phase's changes with a one-line message in the commit style from the principles file, using "phase NN - <name>" as its descriptive part. Commit only. Never push.
+
+   With `single` or `none`: commit nothing here.
+
+   Finish the whole record before the next phase starts, so an interrupted session loses nothing.
+
+Then, in this order:
+
+- The review checkpoint after this phase, when the plan puts one there.
+- The pause after this phase, when the plan puts one there.
+
+A pause therefore always reports a result that is already reviewed and fixed.
+
+**On the first phase of a run**, post the status as `executing`.
+
+**Before that first phase, when `Branch:` names a branch**, put the run on it:
+
+- Already on it: carry on.
+- It exists but is not checked out: switch to it.
+- It does not exist: create it from the current `HEAD`.
+
+When the working tree holds changes that do not belong to this work, gate it on the tab before you switch or create: move to the branch and bring those changes along, or stay where you are and commit on the current branch.
+When the user stays, say in the report that this run's commits did not go to the planned branch.
+
+Never merge, and never push. Merging the work back is the user's job.
+
+**The final commit with `Commits: single`.**
+Once the last phase passes its verify steps and finishes its record step, commit everything this work produced, in one commit.
+Compose the message from the commit style, with the `PLAN.md` title as its descriptive part.
+That commit also covers earlier runs of the same work, which committed nothing.
+Make it before the final review checkpoint: a final checkpoint must never read an uncommitted tree when commits are on.
+
+With `Commits: none`, commit nothing at any point.
+
+**Keep the spec true.**
+When what gets built differs from `spec/SPEC.md` or the plan, update those files as part of the phase.
+The spec is the documentation of what was actually built.
+When the solution departs noticeably from an approved solution sketch, that is a stop condition: the sketch does not bind you, but the user approved it and has to stay informed.
+
+### Review checkpoints
+
+The `Review checkpoints:` line says where fresh reviewers judge the work.
+Each sub-bullet names one checkpoint: where it sits, how many reviewers, a focus each, and why it is there.
+`Review checkpoints: none` means no review runs, and the report says the plan chose none.
+
+Run a checkpoint once you record the phase it sits after, and once any commit the plan asks for has landed.
+Run the `final` checkpoint once the last phase is recorded, any required commit has landed, and before the end-of-run report.
+
+**Start one reviewer subagent per focus the checkpoint names.**
+The reviewers share no context: each gets its own prompt, none sees this conversation, none learns what the others found, and you are never one of them.
+A reviewer's whole value comes from judging work it did not do.
+Treat an inability to start reviewers as a stop condition, and never review the work yourself instead.
+
+Tell each reviewer:
+
+- Its focus, and to check the work against what was asked.
+- Which files to read: `spec/SPEC.md`, `plan/PLAN.md`, the phase files written so far, and the principles file.
+- That the plan's principles check records deviations as approved exceptions, not as findings.
+- How to see the changes: name the commit the work started from, so it can diff against that, and point at the working tree when nothing is committed.
+
+Each reviewer returns a verdict with concrete findings, each pointing at a file and a line.
+
+Then, yourself:
+
+- Merge the findings, and remove the duplicates.
+- Dismiss what you judge wrong, and say why in the report.
+- Fix the rest yourself.
+- Re-run the Verify steps of every phase the fixes touch.
+- Have each reviewer who rejected a fix re-check it once.
+- When a reviewer still objects after that re-check, you settle it: fix it once more when the objection names something real, and otherwise record the finding as knowingly accepted and move on.
+- When commits are on, land the fixes in one follow-up commit, with "review fixes" as the descriptive part.
+
+Post the round with `specs review`, so the board carries its verdict.
+Bring a finding that is the user's to judge to the tab as a decision card, rather than settling it yourself.
+
+### Pauses
+
+The `Pauses:` line says when the run stops for the user: `none`, a list of phases, or `every phase`.
+
+At a pause, once the phase is built, reviewed where a checkpoint sits there, recorded and committed, report what the phase produced in a message.
+Then declare a gate: carry on, or stop here.
+Point the gate at the artifact the phase produced, where one exists, so the user reads it and answers in the same place.
+
+On "carry on": start the next phase in this session.
+On "stop": end the run with the report below.
+A later run finds from disk where this one stopped, resumes at the next unfinished phase, and pauses only at the pauses ahead of it.
+
+A pause after the last phase has nothing to carry on to.
+Run the final checkpoint, and give the end-of-run report instead of asking.
+
+## 4. Stop and ask
+
+Stop and ask when one of these three holds. Otherwise keep going on your own.
+
+1. **The work deviates significantly from the spec.**
+   - What you build contradicts `spec/SPEC.md`.
+   - A fact you found makes the approved shape no longer fit.
+   - The solution departs noticeably from an approved solution sketch.
+
+2. **A blocker only the user can resolve.**
+   - A scope or design decision with no single right answer.
+   - An action that is destructive or hard to reverse: a data migration, a deletion, a call to an external service.
+   - Missing access only the user can grant.
+
+3. **The run cannot carry on for technical reasons.**
+   - A verify step that still fails after a real attempt to fix it.
+   - A tool the plan needs, and your environment refuses to give.
+
+For the third one, declare a gate saying what the plan asks for and why you cannot do it here.
+Offer stopping and carrying on without it, and say plainly that the report will name what never happened.
+
+**Everything else is yours to settle**: a review finding, a wording call, an unclear task, which of two fixes reads better.
+Settle it, keep the run moving, and say in the report what you settled.
+A run that stops to ask about something it could have settled has failed.
+Quality is yours to hold, and the user is waiting for the finished work.
+
+## 5. Report
+
+At the end of the run, or at a pause, report in a normal message:
+
+- The phases finished this run, and the overall progress, such as "5/7 phases done".
+- What the verification showed, and the outcome of every checkpoint this run ran: what the reviewers found, what was fixed, what was dismissed and why. When the plan asked for no review, say so.
+- What you settled on your own, where it matters to the user.
+- The branch, when the run committed to one of its own, that it is unmerged, and that merging it back is the user's job.
+- Why the run stopped, when it stopped at a pause or a stop condition, and what you need from the user.
+
+When every phase is done, post the status as `complete`.