chamba 0.8.0 → 0.10.0

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

@@ -5,15 +5,22 @@ 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, `Documentation impact`, 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`, `Migrations`, 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.
+**`Documentation impact` and `Migrations` are the two sections that always apply.**
+The user confirms both in a round, as `references/stages.md` describes under **Documentation and migrations**.
+
+Under `Documentation impact`, 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.
+
+Under `Migrations`, name each migration the work needs.
+Write one line for each: what is stored in the old shape, and what moves it to the new one.
+Where the work needs none, write `None needed` and one line saying why.
+
+The execution plan stage reads both sections by name, so head each one 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`.
@@ -30,7 +37,7 @@ To clear a marker, ask the user. The answer replaces the marker in `SPEC.md`, in
 A doubt anywhere outside these stages does not wait: ask it in the next round.
 The finalize gate does not pass while a marker stays open.
 
-**Requirements carry IDs and acceptance criteria** when the protocol includes the execution plan stage or the quality review stage.
+**Requirements carry IDs and acceptance criteria** when the protocol includes the execution plan stage or the specs quality review stage.
 With neither stage, write the requirements in plain language instead.
 Number each ID in writing order, as `FR-01`, `FR-02`, and so on.
 Never renumber an ID after you write it, so a phase or a finding that names one still points at the same requirement.

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

@@ -125,6 +125,28 @@ Either way, keep it self-contained: no external image, no script, nothing fetche
 This is a judgment call, never a rule.
 Most documents need no visual, and a visual nobody would look at is not worth writing.
 
+## Documentation and migrations
+
+Two readings of the work are the user's to confirm: which of the project's own documents the work makes not correct, and whether the work needs a migration.
+Ask both once, in a round, whichever stages the protocol holds.
+No form asks them.
+
+Neither one can be answered before the code is read, so the round waits for that.
+Codebase analysis is where the code is read, and it has no gate, so the round belongs to the first stage that runs after it.
+Where the protocol holds no codebase analysis, it belongs to the first stage that reads the code.
+
+Read the code that answers each one before you ask, and mark what the code gives as recommended.
+That is what makes the recommendation an accurate one rather than a guess, and it is usually the answer: the user confirms what is already there.
+
+For the migrations, judge what a migration means for the work in hand.
+There is no fixed definition, and the judgment is yours: stored data, a file on disk, a saved shape, a contract something outside this build already holds.
+Report the judgment whichever way it falls.
+`None needed`, with a short reason, is an answer the user can argue with.
+A question nobody asked gives the user nothing to argue with at all.
+
+Write both answers into the `Documentation impact` and `Migrations` sections of `SPEC.md`, which the execution plan stage reads by name.
+`references/spec-guide.md` holds the shape of each one.
+
 ## High-level exploration
 
 Think together before you commit to anything.
@@ -228,6 +250,7 @@ Read the project's own documents while you map the code: the README, the guides,
 Find the ones the planned work makes not correct, and write them into the `Documentation impact` section of `spec/SPEC.md`, as `references/spec-guide.md` describes it.
 Name each document, and say which part of it the work makes not correct.
 Where the work leaves every document correct, write that, so the stages after this one know the question was asked.
+What is written here is a reading of the code, and the user confirms it in the round under **Documentation and migrations**.
 
 This stage is where the code is read as a whole, so it is where **Cross-check a stored answer against the code** in `SKILL.md` runs.
 Read every answer the user has given against what the code says, and raise what disagrees: the stage settings the protocol form carries, and what a round settled earlier, the interview's own answers included.
@@ -291,7 +314,7 @@ This stage recommends them as data, and writes none of them into `PLAN.md`.
 
 Break the work into phases.
 **Each phase fits one session, and leaves the repo in a working state.**
-Write `plan/PLAN.md`: the goal, the principles check, and the phase list with checkboxes.
+Write `plan/PLAN.md`: the goal and the phase list with checkboxes.
 Give each phase its goal and its definition of done.
 Decide the phase boundaries, the goals and the definitions of done now, for every phase. They are cheap to get right in advance.
 
@@ -300,13 +323,6 @@ Prefer quality, simplicity, robustness, scalability and long-term maintainabilit
 When something has grown unwieldy, restructure it by judgment: refactor, split, or extract.
 Never restructure by a number set in advance.
 
-Check the plan against the principles the bootstrap read.
-Record the outcome as a `## Principles check` section: one line per principle the work touches, saying how the plan honors it.
-When a plan must break a principle, record it in a table with the columns `Deviation | Why needed | Simpler alternative rejected because`.
-Look for the simpler alternative before you record a deviation, and say why you rejected it.
-A deviation is an exception the user decides on at the gate.
-It is not a way to soften a principle, so the usual fix for a conflict is a different plan.
-
 When `SPEC.md` carries requirement IDs, end every phase entry with a `Covers: FR-03, FR-04` line.
 Every ID appears in one phase's `Covers` line at least, and a requirement may span several phases.
 An ID no phase covers means a missing phase, or scope that belongs in the non-goals.
@@ -316,6 +332,10 @@ Add the phase, or move the requirement, before the gate. Ask the user when the c
 Name the document in the definition of done of the phase that changes what it describes, so the run makes the document correct as it changes the code.
 Do not collect the documents into a phase of their own at the end.
 
+**A phase covers each migration the spec's `Migrations` section names.**
+Name the migration in the definition of done of the phase that makes it necessary, so the run moves what is stored as it changes the shape.
+Do not collect the migrations into a phase of their own at the end.
+
 **Post the phases as soon as `PLAN.md` is on disk:**
 
 ```
@@ -339,7 +359,7 @@ Recommend `per-phase` for a plan of several phases, because a phase that is comm
 Recommend `single` for small work that reads as one change.
 Recommend `none` where the user is likely to want to read the whole thing before any of it lands.
 Recommend a new branch for work of any size that touches shared code, and the current branch for a small change on a branch that is already the work's own.
-Name the branch `spec/<slug>`, with this spec's own slug, unless a principle in the principles file names another shape.
+Name the branch `spec/<slug>`, with this spec's own slug.
 
 **The pauses.**
 A pause is where the run stops and waits for the user.
@@ -387,7 +407,7 @@ An executing agent loads `PLAN.md` and its one phase file, never the whole plan.
 
 `PLAN.md` follows this layout.
 Copy the opening note roughly as written, and adapt the rest to the work.
-Include the deviation table only when the plan breaks a principle, and the `Covers:` bullets only when `SPEC.md` carries IDs:
+Include the `Covers:` bullets only when `SPEC.md` carries IDs:
 
 ```markdown
 # <Title of the work>
@@ -400,14 +420,6 @@ Include the deviation table only when the plan breaks a principle, and the `Cove
 
 <what the work achieves, in a line or two>
 
-## Principles check
-
-<one line per principle the work touches, saying how the plan honors it>
-
-| Deviation | Why needed | Simpler alternative rejected because |
-| --- | --- | --- |
-| <the principle the plan breaks> | <why the plan needs to> | <the simpler alternative, and why it was rejected> |
-
 ## Phases
 
 - [ ] Phase 1 - <name>
@@ -419,13 +431,13 @@ Include the deviation table only when the plan breaks a principle, and the `Cove
 ```
 
 Consider a visual beside the plan.
-Then gate on `plan/PLAN.md`, saying the phases in a line each, how the plan honors the principles, and any deviation with its reason.
+Then gate on `plan/PLAN.md`, saying the phases in a line each.
 Say in one line what you recommended for the run, and that the user settles it when they press Execute.
 On changes: revise the plan, post the phases again where they moved, recommend the run again where the change made the recommendation wrong, and gate again.
 Loop until the user approves it.
 The rule over that last part is **Keep what derives from a change true**, in `SKILL.md`.
 
-## Quality review
+## Specs quality review
 
 This is the last stage before the coherence rewrite and finalize.
 It reviews everything the spec produced - `spec/SPEC.md`, the research, the plan, and the mocks the spec lists - and whether those documents agree with each other.
@@ -436,9 +448,13 @@ It holds the reviewer briefs, the lenses, the severities, and the report format.
 Ask who reviews the work, in a round.
 Propose a panel sized to the work and its risk, one reviewer per focus, and mark your proposal recommended.
 Give a short line saying what each reviewer looks at.
-The default proposal has three reviewers: consistency and completeness, principles alignment, and better ways to do this.
+The default proposal has three reviewers: consistency and completeness, repo rules, and better ways to do this.
 **Include the "better ways to do this" reviewer in every proposal.**
-Bigger or riskier work may add a focus of its own - security, performance, the work's own subject - and small work may run with two reviewers.
+**The repo-rules lens is on every panel, with or without a reviewer of that name.**
+Work of any size is judged against what the repo asks of it, so that lens is never what a smaller panel loses.
+Bigger or riskier work may add a focus of its own - security, performance, the work's own subject.
+Small work may run with two reviewers: consistency and completeness, and better ways to do this.
+`references/review-guide.md` says which reviewer then takes up the lenses of a focus that is not on the panel, the repo-rules lens included.
 Always offer an option that turns the review off.
 Say in its description that nothing gets checked independently, and that the spec goes straight to the rewrite and finalize.
 
@@ -457,16 +473,20 @@ It never downgrades quietly.
 Post each round of review as it lands, so the board shows it:
 
 ```
-echo '{"round":1,"verdict":"holds, two for you","findings":9,"judgments":2}' | specs review <spec>
+echo '{"verdict":"holds, two for you","findings":9,"judgments":2}' | specs review <spec>
 ```
 
+The number and the source are the tool's own.
+It reads where the work stands when the round lands, decides which review the round belongs to - the spec's own review, the checkpoint the run is at, or the execution with no place, which is where a round posted at no checkpoint lands - and numbers the round within that review, so the spec's round 1 and a checkpoint's round 1 are two rounds.
+Carry a `round` in the payload for one purpose only: to replace a round of the same review that you posted before, which is how a round is corrected.
+
 **Handling the findings.**
 Merge the findings, and remove the duplicates.
 Dismiss a finding you disagree with, and say why in the report.
 Fix a finding that is plainly right, apply the fix, and mark it applied.
 Bring a taste or scope finding to the user, "better ways" suggestions included, with the reviewer's reasoning.
 Bring a finding to the user too when it is right but the fix is not obvious, or when acting on it would undo something the user approved at an earlier gate.
-Resolve a conflict with a principle by changing the work, never the principle.
+Resolve a conflict with a repo rule by changing the work, never the rule.
 
 **The report and the gate.**
 Write `review/REVIEW.md` in the format `references/review-guide.md` defines.

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

@@ -28,6 +28,7 @@ specs stages
 ```
 
 The answer holds `root` - the directory the tab serves - and the stage catalog.
+Every path in this family resolves against that root.
 A refusal means there is no pane.
 Say this and stop:
 
@@ -60,11 +61,25 @@ 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>
+echo '{"verdict":"holds, one for you","findings":6,"judgments":1}' | specs review <spec>
 ```
 
+The number and the source are the tool's own.
+It reads where the work stands when the round lands, decides which review the round belongs to - the spec's own review, the checkpoint the run is at, or the execution with no place, which is where a round posted at no checkpoint lands - and numbers the round within that review, so the spec's round 1 and a checkpoint's round 1 are two rounds.
+Carry a `round` in the payload for one purpose only: to replace a round of the same review that you posted before, which is how a round is corrected.
+
 A phase's id is its file's name without the extension, which is what you already write and tick.
 
+**A phase report names a phase the plan holds, and the tool refuses one that does not.**
+The refusal names the phases the plan does hold, so a report the tool would not take says in its own words what to do.
+Where the plan changed while the run was going - a phase renamed, split in two, or added - post the whole phase list first, in plan order, and report the phase after that:
+
+```
+echo '{"kind":"plan","phases":[{"phase":"phase-01-the-state","title":"The state"},{"phase":"phase-02-the-rail","title":"The rail"}]}' | specs post <spec>
+```
+
+The list is the plan's own: a phase it drops leaves the board, and a phase that survives keeps the status it had, so a finished phase is never set back to waiting.
+
 ## The run does not stop on its own
 
 The `pauses` decision is the only thing that stops this run for the user.
@@ -132,13 +147,9 @@ So where the state holds decisions they bind you, and where it holds none there
 
 ## The plan is the user's instruction
 
-The user chose everything in the plan at spec time: the phases, the verify steps, and the principles check with its recorded deviations.
+The user chose everything in the plan at spec time: the phases, and the definition of done of each one.
 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.
@@ -148,24 +159,12 @@ A choice of your own that changes nothing - which of two equal ways to read a fi
 An instruction from the user in this conversation overrides the plan.
 The plan loses to the user, and never to you.
 
-## 0. Bootstrap
-
-Settle the root and the principles first:
-
-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 `../dx-spec/references/principles-template.md`. 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.
-
 ## 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.
+The user may name one, and the tab names one by its path.
+An argument 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:
@@ -203,7 +202,7 @@ The user then knows from the start where this run stops and where it gets review
 - 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.
+- Each round in the state carries the review it belongs to. A chosen checkpoint whose phases are all done, and which no stored round names, has not run. Run it before you move on.
 
 **The commits.**
 `commits` is `per-phase`, `single` or `none`.
@@ -257,6 +256,10 @@ Every phase goes through the same steps, and you carry out every one yourself.
 
 2. **Build.** Keep the changes scoped to this phase, and tick each task as it completes.
 
+   Write the rule in the comment's own words.
+   Never name a requirement id, a phase or a spec in a comment.
+   The user can delete the spec directory, and a comment that names it then points at nothing.
+
 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`.
@@ -334,8 +337,7 @@ An agent that has the capability but cannot make it work is a different case: th
 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.
+- Which files to read: `spec/SPEC.md`, `plan/PLAN.md`, the phase files written so far, and the repo's own rule files, `CLAUDE.md` and `AGENTS.md`, wherever they exist.
 - 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.
@@ -351,6 +353,7 @@ Then, yourself:
 - When commits are on, land the fixes in one follow-up commit, in **The commit style**, with "<spec name> review fixes" as its descriptive part.
 
 Post the round with `specs review`, so the board carries its verdict.
+Post it before you report the next phase as running: the tool reads where the run stands to work out which review a round belongs to, so a round that lands after the next phase has started belongs to the execution and to no checkpoint.
 Bring a finding that is the user's to judge to the tab as a decision card, rather than settling it yourself.
 A card names the passage it is about by file and by section, asks one question, and offers the ways out as its own options, one of them recommended.
 `../dx-spec/SKILL.md` carries the shape, under **The verbs**.
@@ -366,7 +369,7 @@ 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.
+On "stop": end the turn with the message of **section 6**, and write no report file - the run has not reached its end.
 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.
@@ -409,24 +412,70 @@ echo '{"kind":"status","status":"complete"}' | specs post <spec>
 
 The post moves the state file and the rendered `README.md`, so it goes before the commit that carries them.
 
+Then write the run report to `<root>/<spec>/run-report.md`.
+**Section 6** holds its title, its headings and what goes under each one.
+Write it here, before the closing commit, so the commit carries it.
+A later run of the same spec writes the file again, over the report of the run before it.
+A run that stops before its end writes no report at all: the message of **section 6** is the whole of what such a run gives.
+
 Then, unless `commits` is `none`, stage the spec directory by path and commit it.
 Compose the message from **The commit style** in `dx-spec/SKILL.md`, with "<spec name> complete" as its descriptive part, which makes it a `docs` commit.
-This one commit covers the phase files, the ticked plan, the spec the run kept true, and the rendered board.
+This one commit covers the phase files, the ticked plan, the spec the run kept true, the report and the rendered board.
 Staging by path leaves every other change in the working tree alone, and the tree is clean over the spec directory once it lands.
 Commit only. Never push.
 
 With `"commits": "none"`, post the status and commit nothing.
 The report then says the closing status was left uncommitted, so the user knows the state file and the `README.md` are changed and theirs to keep or to drop.
 
-Then give the report below, which is what ends the turn and says what the closing commit did.
+Then give the message of section 6, which is what ends the turn and says what the closing commit did.
 
 ## 6. Report
 
-This report is what ends a turn.
+A run that reaches its end has two homes for its report, and they hold the same run.
+A run that stops before its end has one: the message.
+
+`run-report.md` at the top of the spec directory is the whole of the report.
+The closing step of section 5 writes it, the Specs tab lists it beside the other artifacts and renders it, and it stays with the work for whoever reads the spec later.
+It is written at the end of the run and nowhere else, so a pause and a stop condition write no file at all.
+
+The message in this terminal is the short form.
+It is what ends the turn, and the user reads it now rather than later.
+
+### The file
+
+Write it as Markdown, with this title and these headings, in this order:
+
+```markdown
+# <spec name> - run report
+
+## Bottom line
+
+## Must know
+
+## The details
+```
+
+The title names the spec.
+The title and the three headings are fixed word for word.
+Nothing else about the report is fixed.
+The text under each heading is yours to write, so two reports share the headings and differ in their words alone.
+
+- **Bottom line**: a few sentences on what landed, and whether the run is complete.
+- **Must know**: the decisions that carry weight, the departures from the plan and from the mocks, and the critical issues a checkpoint found.
+  Write this section only where the run holds something the user must know.
+  Where it holds none, leave the heading out, and never write the section to fill it.
+- **The details**: the phases finished and the overall progress, every checkpoint with what it found, what was fixed and what was dismissed with the reason, what you settled on your own, the branch and the commits of the run, and the commit mode.
+  Say that the report rides in the closing commit, or, with `"commits": "none"`, that it sits uncommitted in the tree.
+
+Bottom line and The details are in every report.
+
+### The message
+
+The message is what ends a turn.
 Give it at the end of the run, at a pause, or at a stop condition, and nowhere else.
 What you say between phases is a progress line: say it and keep building.
 
-Report in a normal message:
+Say it in normal message text:
 
 - 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 no checkpoint was chosen, say so.
@@ -435,3 +484,4 @@ Report in a normal message:
 - Whether the run decisions were committed, and where they were not, that the spec directory was never committed.
 - Why the run stopped, when it stopped at a pause or a stop condition, and what you need from the user.
 - Whether the closing commit landed, and under `"commits": "none"`, that the closing status was left uncommitted.
+- Where the run reached its end, that `run-report.md` in the spec directory holds the whole of the report.

package/templates/startup.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // =============================================================================
-// startup.mjs -- Container startup: AI CLI updates + readiness checks
+// startup.mjs -- Container startup: agent CLI updates + readiness checks
 // Baked into the container image at /home/devuser/startup.mjs
 // Must run as root (npm global install requires root).
 // Must use only Node.js built-ins -- no external packages available in container.
@@ -45,15 +45,15 @@ const fail = (label, detail) => {
 };
 // Non-fatal notice: always prints (even in summary), but does NOT increment errors, so it never aborts
 // the session. Used for things the user should know about but that must not block connecting (e.g. a
-// transient AI CLI update failure -- the existing versions still work).
+// transient agent CLI update failure -- the existing versions still work).
 const warn = (label, detail) => console.log(`${yellow("!")} ${label.padEnd(24)}${detail ? yellow(detail) : ""}`);
 const section = summary ? () => {} : (title) => console.log(`\n${bold(title)}`);
 
 // -- Header -------------------------------------------------------------------
 if (!summary) console.log(`\n${bold("chamba - Sandbox for AI Agents")}\n`);
 
-// -- AI CLI update (requires root - skipped when run via 'status' alias as devuser) -
-section("AI CLI update");
+// -- Agent CLI update (requires root - skipped when run via 'status' alias as devuser) -
+section("Agent CLI update");
 
 const isRoot = process.getuid?.() === 0;
 const TIMESTAMP_FILE = "/home/devuser/.ai-cli-updated";
@@ -148,7 +148,7 @@ const doUpdate = (label) =>
         child.on("error", (err) => {
             finish(() => {
                 printIndented(String(err?.message ?? err));
-                warn("AI CLIs", "update failed -- continuing with existing versions");
+                warn("agent CLIs", "update failed -- continuing with existing versions");
             });
         });
         child.on("close", (code) => {
@@ -156,10 +156,10 @@ const doUpdate = (label) =>
                 if (code === 0) {
                     printIndented(out);
                     writeFileSync(TIMESTAMP_FILE, `${new Date().toISOString()}\n`);
-                    ok("AI CLIs", "updated");
+                    ok("agent CLIs", "updated");
                 } else {
                     printIndented(`${out}${errOut}`);
-                    warn("AI CLIs", "update failed -- continuing with existing versions");
+                    warn("agent CLIs", "update failed -- continuing with existing versions");
                 }
             });
         });
@@ -176,7 +176,7 @@ const promptSkipUpdate = (seconds) =>
         let remaining = seconds;
         let tick;
         let timer;
-        const line = (s) => `\r\x1b[K${blue("●")} ${dim(`Updating AI CLIs in ${s}s... SPACE to skip, ENTER to update now`)}`;
+        const line = (s) => `\r\x1b[K${blue("●")} ${dim(`Updating agent CLIs in ${s}s... SPACE to skip, ENTER to update now`)}`;
         const cleanup = () => {
             clearInterval(tick);
             clearTimeout(timer);
@@ -218,19 +218,19 @@ const promptSkipUpdate = (seconds) =>
     });
 
 if (Number.isFinite(lastUpdate) && Date.now() - lastUpdate < THROTTLE_MS) {
-    ok("AI CLIs", "up to date");
+    ok("agent CLIs", "up to date");
 } else if (!isRoot) {
-    skip("AI CLIs", "update skipped (requires root)");
+    skip("agent CLIs", "update skipped (requires root)");
 } else {
     // About to show update activity (the skip prompt and/or install/update output). In summary mode that is the
     // first thing after the host's "Starting dev container...", so add a blank line to separate it.
     if (summary) console.log("");
     if (!timestampFileExists) {
-        await doUpdate("Installing AI CLIs...");
+        await doUpdate("Installing agent CLIs...");
     } else if (await promptSkipUpdate(5)) {
-        skip("AI CLIs", "update skipped by user");
+        skip("agent CLIs", "update skipped by user");
     } else {
-        await doUpdate("Updating AI CLIs to latest...");
+        await doUpdate("Updating agent CLIs to latest...");
     }
 }
 

package/templates/tool-helper.sh

@@ -38,7 +38,7 @@ Verbs:
   await    <spec>        Declare a gate, a round or a decision card. { id, kind, title, file, payload }
   withdraw <spec>        Take back an ask nobody needs to answer. { id, reason }
   post     <spec>        Say what is happening. { kind: activity | stage | phase | plan | status | note, ... }
-  review   <spec>        Post a round of quality review. { round, verdict, findings, judgments }
+  review   <spec>        Post a round of review. { verdict, findings, judgments }, and { round } to replace one already posted
   answers  <spec>        Read back what the user answered. { id }
 
 A payload is JSON on stdin, where the verb takes one. The answer is JSON on stdout.
@@ -53,7 +53,9 @@ Verbs:
   stages                 Where the reviews live, and what a review may hold.
   state    <review>      The state, the baseline's summary, and what awaits whom.
   start                  File a review from this terminal. { name, selection }
-  metadata <review>      Post the grouping and the notes for the baseline. { fingerprint, groups, notes }
+  metadata <review>      Post the whole grouping and its notes, replacing what is there. { fingerprint, groups, notes }
+  group    <review>      Add or replace one group, and the notes on its hunks. { fingerprint, group, notes }
+  ungroup  <review>      Remove one group; the notes on its hunks stay. { fingerprint, id }
   reply    <review>      Append one reply to a thread. { thread, text }
   activity <review>      Say what you are doing. { said }
   done     <review>      End your act; the tool recomputes the baseline where one is due.