@printpractical/cruze 0.0.4 → 0.0.6

package/skills/architect/walkthrough.md

@@ -1,29 +1,32 @@
 # The design walkthrough
 
-The walkthrough is where the user comes to understand the design well enough to explain it without you. It is the one heavy gate before code. Show the design as it stands in the files, one part at a time, in the order below. Pause after each part for questions.
+The walkthrough hands the design to the user in one message: a short overview in plain terms, then the documents to review in full. The documents are the design, and the user reads them faster than you can retell them, so present the whole design at once and wait for one answer: approval, or comments.
 
-At feature scope, show only what the feature adds, changes or removes, next to the current elements it touches. At project scope, show the whole architecture.
+At feature scope, cover only what the feature adds, changes or removes. At project scope, cover the whole architecture, the layer rules, the roadmap and the walking skeleton.
 
-## Order
+## The overview
 
-1. **What it does.** The intent in two sentences, then each requirement with its scenarios' titles.
-2. **Where it sits.** The `VIEW-context` diagram, or at feature scope, the contexts the feature touches.
-3. **The domain.** The domain-model class diagram, then each new or changed entity: its invariants, its states and who owns it.
-4. **How it runs.** For each key flow, show its `sequenceDiagram` and walk one scenario through it step by step, including one failure path. This is the part the user must be able to retell.
-5. **The seams.** Each new or changed port with its operations and their contracts, then the adapter behind each one and the library it adopts.
-6. **Dependencies.** Every new dependency, named out loud with its purpose and the approval behind it. Also the components you chose to build yourself, with the reason.
-7. **Where the code goes.** Each new element next to its module, file path and layer, and the layer rules those files must obey. At project scope, also the `layers:` in `.cruze/config.yaml`.
-8. **The slices.** The changes in order, with what each delivers and builds, and why the first is first. At project scope, the roadmap's phases and the walking skeleton instead.
-9. **Decisions and review.** The settled decisions and ADRs, each review finding with its disposition, and the points where a fresh implementer could still build something different.
+Write it in the glossary's terms, as what callers can do and what happens when they do, not as a list of elements. Keep it to what the user can read in a minute.
 
-## Showing diagrams
+1. **What it does.** The intent in two sentences. Then one line per use case, or at feature scope per requirement: who asks for what, what they get, and the main way it fails.
+2. **What it touches.** Each new external system, and each new dependency named with its purpose and the approval behind it. Also each component you chose to build yourself, with the reason.
+3. **The slices.** The changes in order, one line each, saying what each delivers and why the first is first. At project scope, the roadmap's phases and the walking skeleton instead.
+4. **What is yours to decide.** The review findings the roles skill brings to the user, any `cruze validate` warning still standing, such as a change over its size limit, any point where a fresh implementer could still build something different, and any rule you challenged that the user overrode.
 
-Mermaid diagrams live in the documents, so point to the file and line of each one, and paste its source into the conversation. When the user can render Mermaid (an editor preview, or GitHub), say where to open it. Keep each diagram under 15 nodes; split a bigger picture instead of shrinking it.
+## The documents
+
+List each file the user should read in full, with the sections that changed:
+
+- Feature scope: the feature's `feature.md`, and the ADRs it adds.
+- Project scope: `docs/architecture.md`, the `layers:` in `.cruze/config.yaml`, `docs/roadmap.md`, the walking-skeleton `change.md`, and the ADRs in `docs/adr/`.
+
+The diagrams are Mermaid inside those files. Say where the user can render them, such as an editor preview or GitHub, rather than pasting them.
+
+End the message with: "Read these in full, then tell me what to change, or approve. Do you approve this design?"
 
 ## Ending
 
-1. Ask the user to explain one flow back in their own words, or to name what they would still find surprising in the code. Treat their answer as the check that the walkthrough worked, and go back over any part they can't retell.
-2. Ask for approval in these words: "Do you approve this design?"
-3. A request for changes is not an approval. Apply the changes and run `cruze validate`. When they touch placement, dependency direction, adopt-or-build decisions, port contracts or flows, run a new design review on the diff alone. Then walk through only the parts that changed, and ask again.
-4. When the user rejects the design outright, don't approve anything. Ask what is wrong. When the problem is what to build, go back to `envision`; when it is the whole approach, restart this step's design; when the user wants to stop, leave the work unapproved and say how to resume.
-5. Done when the user says they approve.
+1. Answer a question from the documents, pointing to the file and section, and answer only what was asked.
+2. A request for changes is not an approval. Apply the changes and run `cruze validate`. When the user edited the documents themselves, read their diff and run `cruze validate` on it. When the changes touch placement, dependency direction, adopt-or-build decisions, port contracts or flows, run a new design review on the diff alone. Then say in a few lines what changed and where, and ask again.
+3. When the user rejects the design outright, don't approve anything. Ask what is wrong. When the problem is what to build, go back to `envision`; when it is the whole approach, restart this step's design; when the user wants to stop, leave the work unapproved and say how to resume.
+4. Done when the user says they approve.

package/skills/build/SKILL.md

@@ -19,10 +19,11 @@ Build turns an approved plan into code, one task at a time. Each task starts wit
 3. **Read the plan and the design.** Read the change's `change.md` and its feature's `feature.md`. Read the full body of every element the change builds, and every scenario it delivers. Read `commands:` in `.cruze/config.yaml`.
 4. **Build each open task in order,** following the task loop below. Skip the tasks already ticked in `## Progress`.
 5. **Finish.** When every task is ticked:
-   - Run the full test suite, the formatter and the linter, using the project's commands.
+   - Run the format, lint and build commands and the full suite, as `.agents/skills/cruze-formats/reference/config.md` defines it under `commands`.
    - Run `cruze check` and `cruze trace`, and quote their results.
+   - When all of them pass, record the commit they ran at with `cruze journal add checks --set commit=<commit> --item <ref>`, where the commit is the output of `git rev-parse --short HEAD`. Verify quotes this instead of running the suite again.
    - Commit the progress record with a message such as `chore: record progress on <change>`.
-   - Done when all of them pass.
+   - Done when all of them pass and the checks are recorded.
 
 ## The task loop
 
@@ -31,7 +32,7 @@ For task `T<n>`:
 1. **Read it.** Note its owner, its files, the IDs it proves, and the test plan rows for those IDs.
 2. **Red.** Write the tests for the IDs it proves, at the seams the test plan names, carrying the IDs. Run them, and see them fail for the reason you expect.
 3. **Green.** Write the least code that makes them pass, in the task's files. Code that belongs to another task, or another change, waits for it, even when the next change will need it.
-4. **Check.** Run `cruze check <the task's files>`, the formatter and the linter, and fix what they report. Run the tests the task touched, and the rest of the suite when they are quick.
+4. **Check.** Run `cruze check <the task's files>`, the formatter and the linter, and fix what they report. Run the tests the task touched. When `commands:` has a `test_full`, run `test` too, since it is the fast tier. Otherwise run the rest of the suite only when it is quick.
 5. **Commit** with a Conventional Commit message naming the task, such as `feat(access): console session state machine (T2)`.
 6. **Tick it.** Run `cruze task done T<n>`, which records the commit. Its progress edit rides along in the next commit.
 
@@ -43,10 +44,10 @@ Done for a task when its tests pass, `cruze check` passes for its files, the com
 
 The plan is design. Within a task you decide only what is local and reversible.
 
-- **Record it and carry on** for a task-level choice: a private helper in another file of the same module, a private type, or two tasks' commits swapped for a reason. Run `cruze task deviation T<n> "<what you did and why>"`.
+- **Record it and carry on** for a task-level choice: a private helper in another file of the same module, a private type, a fixture or harness added to the test support module that the task's tests need, or two tasks' commits swapped for a reason. The test support module is in every test-writing task's scope, so extend it rather than writing a private helper in a test file. Run `cruze task deviation T<n> "<what you did and why>"`.
 - **Stop and offer `rethink`** when the code needs any of these:
   - a new element, port operation or scenario;
-  - a file outside the owner's module;
+  - a file outside the owner's module, other than the test support module;
   - a change to an approved scenario's behaviour, or to its test;
   - a dependency the design doesn't name.
 

package/skills/formats/SKILL.md

@@ -66,7 +66,7 @@ The CLI owns some content so that routine bookkeeping never changes a design:
 - A block between `<!-- cruze:managed -->` and `<!-- /cruze:managed -->` is written only by the CLI.
 - A `- Status: planned` or `- Status: built` item in an element body is written only by the CLI. Elements that have code (`ENT`, `UC`, `PORT`, `ADP`, `FLOW`, `MOD`) and scenarios (`SCN`) carry one.
 - Both are excluded from every hash. Read them freely; change them only through `cruze` commands:
-  - `cruze approve` adds missing statuses to the architecture, sets built elements back to planned with `--replan`, and binds a change to its branch.
+  - `cruze approve` adds missing statuses to the architecture, sets built elements back to planned with `--replan`, and binds a change to its branch. With `--by-agent` it approves a change whose plan review closed, and with `--restamp-unchanged` it re-stamps work a rethink left unchanged, recording that the agent gave the approval.
   - `cruze task` records progress, and `cruze features` edits the feature map.
   - `cruze land` merges work, marks it built and fills the Commands and Layout sections of `AGENTS.md`.
   - `cruze roadmap prune` and `cruze abandon` update the roadmap's status.

package/skills/formats/reference/config.md

@@ -27,6 +27,12 @@ commands:
 
 review:
   command: ["claude", "-p", "--allowedTools", "Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(git show:*) Bash(cruze:*) Bash(cargo:*)"]
+  decide: exceptions
+
+changes:
+  min_builds: 3
+  max_scenarios: 30
+  max_tasks: 25
 
 layers:
   - name: inventory-domain
@@ -50,8 +56,12 @@ layers:
 | `check.max_types` | Budget of top-level types per source file. |
 | `check.exceptions` | Files allowed past a budget, or Rust test files allowed under `src/` (`test-placement`), each with a `path` and a `reason`. `realign` adds entries whose reason ends `scheduled in <ref>`, and landing that change removes them. |
 | `layers` | Each layer has a `name`, the `paths` it covers, and `may_import`, the layers it may depend on. |
-| `commands` | The project's commands by name, such as `test` or `run`. The walking-skeleton change fills them in, and `cruze land` copies them into the Commands section of `AGENTS.md`. |
+| `commands` | The project's commands by name, such as `test` or `run`. The walking-skeleton change fills them in, and `cruze land` copies them into the Commands section of `AGENTS.md`. When the suite has a slow tier, such as UI, device or end-to-end tests, `test` runs only the fast tier and `test_full` runs everything. The full suite is `test_full` when it is set, and `test` otherwise. |
 | `review.command` | The program and arguments `cruze review` runs to start an agent in a fresh context, with the prompt on standard input. Optional. `cruze init` sets it for Claude Code to run in print mode, allowed to read the project and run `git diff`, `git log`, `git show` and `cruze`. The verifier runs the system, so add the project's build and run commands. When it is unset, or its program isn't installed, `cruze review` hands the role's prompt back to the calling agent to run in a helper. |
+| `review.decide` | Which review findings the user decides. `exceptions`, the default: only findings whose fix changes behaviour, a designed port or contract, or another decision the user owns, and any the agent wouldn't simply fix as proposed. The agent fixes the rest and lists them. `all`: the user decides every finding. |
+| `changes.min_builds` | A feature's change that builds fewer elements than this gets a `change-too-small` warning: merge it into the change it continues. Default `3`. |
+| `changes.max_scenarios` | A change that delivers more scenarios than this gets a `change-too-large` warning: split it. Default `30`. |
+| `changes.max_tasks` | A plan with more tasks than this gets a `plan-too-large` warning. Default `25`. |
 
 Rules for layers:
 

package/skills/formats/reference/work-items.md

@@ -35,7 +35,7 @@ Templates: [../templates/feature.md](../templates/feature.md), [../templates/cha
 
 A standalone change adds `## Intent`, `## Adopt or build`, `## Spec delta` and `## Architecture delta` before its `## Scope`, in the same format as a feature's. Its scope covers every ID in its own deltas, plus any `planned` elements from the living docs that it builds.
 
-A feature is designed in two steps. Feature-scope `envision` writes the intent, settled decisions and spec delta, and leaves `## Architecture delta` as `None.` and the Changes table empty. `architect` writes the architecture delta and the changes. Until the Changes table has a row, `cruze validate` reports the feature as `not-designed` (a warning), skips the coverage rules, and `cruze approve` refuses it. A feature of more than 6 changes gets a `feature-size` warning: split it, because one design review can't hold it.
+A feature is designed in two steps. Feature-scope `envision` writes the intent, settled decisions and spec delta, and leaves `## Architecture delta` as `None.` and the Changes table empty. `architect` writes the architecture delta and the changes. Until the Changes table has a row, `cruze validate` reports the feature as `not-designed` (a warning), skips the coverage rules, and `cruze approve` refuses it. A feature of more than 6 changes gets a `feature-size` warning: split it, because one design review can't hold it. A change outside the size band in `changes:` of `.cruze/config.yaml` gets `change-too-small` (it builds fewer than 3 elements, in a feature of several changes) or `change-too-large` (it delivers more than 30 scenarios), and a plan of more than 25 tasks gets `plan-too-large`.
 
 `architect` writes a standalone change's design sections and its scope, and leaves the test plan table empty and the tasks section blank. Until `plan` fills them, `cruze validate` reports the change as `not-planned` (a warning), skips the task and test plan rules, and `cruze approve` refuses it.
 

package/skills/formats/templates/change.md

@@ -1,6 +1,6 @@
 ---
 id: {{id}}
-title: {{title}}
+title: {{title_quoted}}
 ---
 
 # Change: {{title}}

package/skills/formats/templates/feature.md

@@ -1,6 +1,6 @@
 ---
 id: {{id}}
-title: {{title}}
+title: {{title_quoted}}
 roadmap: <roadmap item slug>
 ---
 

package/skills/formats/templates/standalone-change.md

@@ -1,6 +1,6 @@
 ---
 id: {{id}}
-title: {{title}}
+title: {{title_quoted}}
 roadmap: <roadmap item slug, when the change is on the roadmap>
 ---
 

package/skills/land/SKILL.md

@@ -13,7 +13,7 @@ Land makes finished work part of the living model. `cruze land` merges the chang
 2. **Bring in main.** Merge or rebase the branch onto an up-to-date main, and resolve conflicts.
    - `journal.jsonl` files merge by keeping every line; `cruze init` sets that up in `.gitattributes`. When that file lacks the rule, keep both sides' lines.
    - When an `approvals.json` conflicts, take main's version of it. Then run `cruze status`, and re-approve what it shows stale, as step 3 describes.
-   - Resolve code conflicts as usual, then run the tests.
+   - Resolve code conflicts as usual, then run the full suite. When main came in without code conflicts, leave the full suite to CI.
 3. **Run `cruze status`.** When the change or its feature shows `upstream changed`, another branch landed changes to elements it cites. Then:
    - Show the user the diff of each changed element, and check that the change's code and tests still hold against it.
    - When they still hold, re-approve the stale documents: the feature first, then the change. The change's verification carries over when its own design didn't change.

package/skills/plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cruze-plan
-description: Turns the next change into a test plan and ordered tasks with file targets, reviews the plan in a fresh context, and records your approval on the branch that will build it.
+description: Turns the next change into a test plan and ordered tasks with file targets, reviews the plan in a fresh context, and approves it on the branch that will build it once the review closes, leaving you to object or go straight to build.
 ---
 
 # Plan
@@ -26,7 +26,7 @@ Plan turns one designed change into work an implementer can do without guessing:
 10. **Record decisions and risks.** Put task-level choices you made under `## Settled decisions`. Under `## Risks`, name the riskiest task and how its test catches the failure. Remove every template guide.
 11. **Validate.** Run `cruze validate`. Done when it reports no errors for the change.
 12. **Review the plan.** Commit the plan, then run the review in `.agents/skills/cruze-roles/SKILL.md` with the design reviewer and its plan rubric, `review=plan`, and `--item <ref>`.
-13. **Approve.** Show the user the test plan table, the tasks in order and the risks. When they approve, run `cruze approve <ref>` on this branch and quote its result. The approval binds the change to the branch.
+13. **Approve.** Run `cruze approve <ref> --by-agent` on this branch and quote its result. The plan carries no design of its own, so once its review has closed, with no blocker open and a disposition for every finding, you approve it for the user. The approval binds the change to the branch. When it refuses with `plan-review-open`, do what it names. A blocker still open after round 2 goes to the user, and once they decide it, they approve the plan themselves with `cruze approve <ref>`.
 14. **Commit** with a message such as `docs: plan <change>`.
 
 ## When the plan needs design
@@ -44,9 +44,9 @@ Say what is missing and why, then send the change to `rethink` at feature level.
 
 The walking-skeleton change also makes CI and the project's tooling real. Its plan adds:
 
-- `commands:` in `.cruze/config.yaml`: the format, lint, build, test and run commands, as the language's standard tooling runs them.
+- `commands:` in `.cruze/config.yaml`: the format, lint, build, test and run commands, as the language's standard tooling runs them. When some tests are much slower than the rest, such as UI or device tests, `test` runs the fast tier and `test_full` the whole suite, so build can run `test` after every task.
 - A task that adds the language's format, lint, build and test steps to CI (`.github/workflows/ci.yml`), before the Cruze steps `cruze init` put there. The task proves the flow its smoke test runs.
 
 ## Next step
 
-`build`, on this branch.
+Show the user the test plan table, the tasks in order and the risks, and say the plan is approved. They can object, and you amend the plan, run its review on the diff, and approve again. Otherwise the next step is `build`, on this branch.

package/skills/plan/tasks.md

@@ -9,6 +9,7 @@ A task is one owner, the files it writes, and the IDs it proves. Build does them
    - The composition root comes last.
    - Put fakes just before the first task whose test needs them.
    - Each task's test can fail first and then pass, using only what earlier tasks built.
+   - A test that expects a default or empty result, such as no prompt, an empty list, `nil` or `0`, passes against a stub that returns it. Name in the task the break it is first seen failing against, such as "fails against a model that always shows the prompt".
    - When the project's lint rejects unused code, such as `cargo clippy -- -D warnings`, put each new item in the task of its first user, or in a task whose own test uses it. Each task then commits green on its own.
 3. **Write one line per task:**
 
@@ -17,7 +18,7 @@ A task is one owner, the files it writes, and the IDs it proves. Build does them
    - T7: `OpenConsole` in `src/access/app/open_console.rs`, proves UC-access.open-console, SCN-access.direct-serial
    ```
 
-   - Owner and paths in backticks. Every path is a file the architecture assigns to that owner, or a test or support file.
+   - Owner and paths in backticks. Every path is a file the architecture assigns to that owner, or a test or support file. List the test support files the task extends, such as a shared harness or fixture, so its tests reuse them.
    - A task proves the elements it builds, and each scenario whose test goes green in it.
    - A task that only sets up tooling proves the flow or scenario its checks run.
 4. **Find the callers.** For each signature, default or setting a task changes, search the code for every use of it, including tests that start the real binary or read the setting. Add each file that must change to the task. Done when no task will need a file it doesn't list.

package/skills/realign/notes/0.0.5.md

@@ -0,0 +1,38 @@
+# Realign notes: 0.0.5
+
+## New work only
+
+### review-exceptions: The user decides only the review findings that are theirs
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/SKILL.md`, "Running a review", round 1, steps 3 to 5
+
+### plan-approved-by-agent: A plan is approved once its review closes, without stopping for the user
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-plan/SKILL.md`, "Steps", step 13
+
+### rethink-restamps: A rethink re-stamps the work it didn't change
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-rethink/SKILL.md`, "Steps", step 6
+
+### change-too-small: A feature's change builds at least 3 elements
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-architect/feature.md`, step 12
+- Detect: validate:change-too-small
+
+### change-too-large: A change delivers at most 30 scenarios
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-architect/feature.md`, step 12
+- Detect: validate:change-too-large
+
+### plan-too-large: A plan has at most 25 tasks
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-architect/feature.md`, step 12
+- Detect: validate:plan-too-large
+
+### concerns-per-size: Reviewers list concerns in proportion to the work
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/code-reviewer.md`, "Findings"
+
+### reverify-changed-plan: A plan changed after verify needs verifying again, whoever approved it
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-verify/SKILL.md`

package/skills/realign/notes/0.0.6.md

@@ -0,0 +1,44 @@
+# Realign notes: 0.0.6
+
+## New work only
+
+### suite-once-per-commit: The full test suite runs once per commit, and verify quotes build's result
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-verify/SKILL.md`, "Steps", step 2
+
+### test-tiers: A project with slow tests can split them into test and test_full
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-formats/reference/config.md`
+- Fix: when the full suite takes more than a few minutes, move it to `test_full` under `commands:` and make `test` the fast tier
+
+### test-support-in-scope: Build extends the test support module without a rethink
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-build/SKILL.md`, "Deviations"
+
+### name-the-break: Plan names the break for a test that passes against a stub
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-plan/tasks.md`, step 2
+
+### round-2-by-agent: The agent checks round 2 when every blocker was fixed as proposed
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/SKILL.md`, "Running a review", round 2
+
+### size-before-approval: Size warnings are cleared or accepted before a feature is approved
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-architect/feature.md`, step 12
+
+### verify-every-claim: Research checks claims about the language, platform and external systems
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-research/SKILL.md`, "Adopt or build", step 7
+
+### cross-section-consistency: The design reviewer checks cross-cutting rules, interleavings and stale prose
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/design-reviewer.md`, "Rubric", item 8
+
+### one-message-walkthrough: The design walkthrough is one overview, then the documents in full
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-architect/walkthrough.md`
+
+### quoted-titles: New features and changes quote their title in the header
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-formats/templates/change.md`

package/skills/realign/notes.md

@@ -7,6 +7,8 @@ Each release that changes what Cruze expects of a project ships a notes file, `n
 - [0.0.2](notes/0.0.2.md)
 - [0.0.3](notes/0.0.3.md)
 - [0.0.4](notes/0.0.4.md)
+- [0.0.5](notes/0.0.5.md)
+- [0.0.6](notes/0.0.6.md)
 
 ## Format
 

package/skills/research/SKILL.md

@@ -17,7 +17,13 @@ Run these steps for each component in a design that isn't domain logic. Domain l
 4. Recommend one. Adopt a library, or build with a concrete reason: the behaviour is specific to this product, no candidate meets a stated constraint, every candidate brings disproportionate risk or complexity, or the capability is the product itself. Avoiding a dependency is not a reason on its own.
 5. Record the result as a row in the `## Adopt or build` table of the feature or standalone change, as Component, Decision, Choice and Reason. At project scope, record it as the adapter's `Adopts` fact, and put rows for anything no adapter owns in the walking-skeleton change's `## Adopt or build`. When the evidence runs longer than the reason, write it to `.cruze/notes/<date>-<slug>.md` and cite that note in the reason.
 6. Take the recommendation to the user. Adopting means a new dependency, which follows `.agents/skills/cruze-dependency-approval/SKILL.md`. Building commodity functionality is the user's call as well.
-7. Verify what the design will rely on. List each claim the design makes about an adopted library or tool: the features or flags it needs, and each command the design spells out, such as a CI step. Once the user has approved the dependency, check each claim by running it: build a scratch project outside the repository with exactly the declared features, and run each command there or with `--help`. When a claim can't be run, check it in that version's source. Write the features into the `Adopts` fact or the row's Choice.
+7. Verify what the design will rely on. List each claim the design or its testing approach makes about anything it doesn't build:
+   - an adopted library or tool: the features or flags it needs, and each command the design spells out, such as a CI step;
+   - the language or runtime, such as whether a trait with async methods can be used as a trait object;
+   - the platform's test environment, such as which permissions a test process gets;
+   - an external system the product talks to, such as what a broker logs or how it answers.
+
+   Once the user has approved any dependency involved, check each claim by running it: build a scratch project outside the repository with exactly the declared features, and run each command there or with `--help`, or run the external system and watch it. When a claim can't be run, check it in that version's source, and say so. Write the features into the `Adopts` fact or the row's Choice.
 
 Done when every non-domain component in the design has a row with a decision and a reason, and every claim the design relies on is verified, with how.
 

package/skills/rethink/SKILL.md

@@ -18,7 +18,11 @@ Finding a design flaw mid-build is information, not failure. Rethink amends the
 3. **Load the standards.** Read `.agents/skills/cruze-grilling/SKILL.md`. At feature or architecture level, also read `.agents/skills/cruze-hexagonal-design/SKILL.md`. Also read the format reference for the document you will amend: `.agents/skills/cruze-formats/reference/architecture.md`, `specs.md`, `work-items.md` or `durable-docs.md`.
 4. **Amend that level,** following the level's section in [levels.md](levels.md). Settle any decision the amendment needs with the user, and record it as that level records decisions.
 5. **Keep completed work.** A ticked task stays ticked unless the amendment changes its owner, its files, or what it proves. Reopen each task that changed with `cruze task reopen T<n> "<what changed>"`. Its commits stay in history, and build redoes the task.
-6. **Re-approve what went stale.** Run `cruze status` and work from the top down: the amended document first, then each document it lists as `upstream changed`. For each one, show the user the diff of the elements it names, and re-approve it with `cruze approve <ref>` once they agree. A change's verification carries over when its own design didn't change.
+6. **Re-approve what went stale.** Run `cruze status` and work from the top down. The amended document comes first, and the user approves it as its level says. Then take each feature or change it lists as `upstream changed`, whose own text you didn't edit:
+   - Read the diff of the elements it names, and check the work still holds against them. When it doesn't, amend it too, and the user approves it as an amended document.
+   - When it holds, re-stamp it with `cruze approve <ref> --restamp-unchanged`. The CLI refuses work whose own text changed, a project document, and a change with a task reopened since its approval; the user re-approves those.
+
+   Tell the user, in one line each, what you re-stamped and why it still holds. They can object, and that document goes to them. A change's verification carries over when its own design didn't change.
 7. **Record the rethink.** Draft the entry and show it to the user in one line. When they confirm, run:
 
    ```sh

package/skills/rethink/levels.md

@@ -5,14 +5,14 @@
 1. Edit the change's `## Test plan` or `## Tasks` so they are right. The scope doesn't change at this level; a scope change is a feature-level rethink.
 2. Run `cruze validate`. Done when it reports no errors for the change.
 3. Run the plan review from `.agents/skills/cruze-roles/SKILL.md` on the diff alone, with the design reviewer's plan rubric and `review=plan`.
-4. Re-approve with `cruze approve <change>`.
+4. Re-approve with `cruze approve <change> --by-agent` once the review has closed, as plan does.
 
 ## Feature
 
 1. Edit the feature's `## Spec delta`, `## Architecture delta` or `## Changes`. For a standalone change, edit its own deltas and scope. Write complete bodies, as `architect` does, and keep the scope rules.
 2. Run `cruze validate`. Done when it reports no errors for the feature or its changes.
-3. Run the design review from the roles skill on the diff alone, with `review=design`. Walk the user through the changed parts, following `.agents/skills/cruze-architect/walkthrough.md`.
-4. Re-approve the feature. For each of its changes that shows as stale, update the change's scope, test plan and tasks to match. Reopen touched tasks, and re-approve the change.
+3. Run the design review from the roles skill on the diff alone, with `review=design`. Run the walkthrough of the changed parts, following `.agents/skills/cruze-architect/walkthrough.md`.
+4. Re-approve the feature. For each of its changes that shows as stale, check it against the diff. When the amendment touches the change's scope, test plan or tasks, update them to match, reopen touched tasks, run the plan review on the diff, and re-approve it with `cruze approve <change> --by-agent`. When it doesn't, re-stamp the change as the skill's step 6 describes.
 5. When a change hasn't been created yet, only the feature's Changes row changes; `plan` picks it up.
 
 ## Architecture
@@ -26,7 +26,7 @@
    - **A prefactor**, otherwise. From an up-to-date main, run `architect "<prefactor>"`, which designs it as a standalone change, then `plan`, `build`, `verify` and `land` it before the current change continues.
 6. Run `cruze status`. Every document citing a changed element shows `upstream changed`:
    - When the document's own delta changes that element, rewrite the delta so it keeps your amendment. `cruze approve` refuses it with `rebase-required` until you do. Then approve it with `--rebase <ID>`.
-   - Otherwise, show the user the element's diff, and re-approve the document as the skill's step 6 describes.
+   - Otherwise, check the document against the element's diff, and re-stamp it or amend it as the skill's step 6 describes.
 
 ## Vision
 

package/skills/roles/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cruze-roles
-description: Prompts for Cruze's fresh-context roles (the design reviewer, code reviewer, verifier and researcher), how to run one, and how to take a review through its two rounds to a disposition for every finding. Use when a Cruze workflow step says to run a role, a review or research in a fresh context.
+description: Prompts for Cruze's fresh-context roles (the design reviewer, code reviewer, verifier and researcher), how to run one, and how to take a review through its two rounds to a disposition for every finding, with the user deciding only the exceptions. Use when a Cruze workflow step says to run a role, a review or research in a fresh context.
 ---
 
 # Roles
@@ -30,26 +30,38 @@ A review has at most two rounds. Only blockers can force the second one.
 
 1. Commit the documents under review (`docs: <artifact> for design review`), so the fixes in round 2 have a diff. Then run the reviewer on the complete artifact.
 2. Record the round: `cruze journal add review --set review=<design|plan|code> --set round=1 --set blockers=<n> --set concerns=<n> --set nits=<n>`, with the counts from the report's last line, adding `--item <ref>` for a feature or change.
-3. Present every finding to the user with your recommended disposition and why:
-   - `fixed`: you will change the design as the finding proposes.
+3. **Sort the findings.** A finding is an **exception**, which the user decides, when any of these holds:
+   - Its fix changes behaviour: it adds, removes or rewrites a requirement or scenario, or changes what a person sees or does beyond what the spec says. Making the code or the plan meet a scenario as written is not a change of behaviour.
+   - Its fix changes a port, a port's `Operations` or a public contract that the approved design names.
+   - Its fix changes another decision the grilling skill leaves to the user: a context, dependency direction or a dependency.
+   - You recommend anything but `fixed`: waiving, deferring or rejecting it, or a rethink because it needs a design change.
+   - You would fix it differently from the reviewer's proposed fix.
+
+   Every other finding is yours, blockers included: you fix it as the reviewer proposes. When `review.decide` in `.cruze/config.yaml` is `all`, every finding is an exception.
+4. **Present them in one message.** First each exception, with your recommended disposition and why:
+   - `fixed`: you will change the work as the finding proposes.
    - `waived`: the finding is right, but the user accepts the risk.
    - `deferred`: it belongs to later work. When it is future scope, add it with `cruze features add <slug> --summary <text> --goals <ids>`.
    - `rejected`: the finding is wrong, with the reason.
 
    A finding whose fix would change an approved element, such as one marked `Needs design change`, is never `deferred` or `waived`. Recommend `rethink` at that element's level now. Once the rethink is done and the code follows it, record the finding as `fixed`.
-4. The user decides each one. Record each decision: `cruze journal add disposition --set finding="<rubric item>: <summary>" --set disposition=<fixed|waived|deferred|rejected> --set reason="<reason>" --set review=<design|plan|code>`, with the same `--item`. A recorded disposition is never raised again.
-5. Apply every `fixed` change, then run `cruze validate`. Done when it reports no errors.
-6. When a finding could be caught by a tool, such as a layering, naming or size rule, tell the user which `cruze check` rule or linter setting would catch it next time.
+
+   Then one line for each finding you are fixing yourself. When there are no exceptions, say what you are fixing and carry on without waiting. The user can object to any line until the work is approved, and that finding becomes an exception: revert its fix and let them decide it.
+5. **Record every disposition:** `cruze journal add disposition --set finding="<rubric item>: <summary>" --set disposition=<fixed|waived|deferred|rejected> --set reason="<reason>" --set review=<design|plan|code> --set decided=<agent|user>`, with the same `--item`. Use `decided=user` for each exception, once the user decides it, and `decided=agent` for each finding you fixed yourself. The CLI refuses `decided=agent` for anything but `fixed`. A recorded disposition is never raised again.
+6. Apply every `fixed` change, then run `cruze validate`. Done when it reports no errors.
+7. When a finding could be caught by a tool, such as a layering, naming or size rule, tell the user which `cruze check` rule or linter setting would catch it next time.
 
 ### Round 2
 
-Run round 2 only when a round-1 blocker was fixed.
+Run round 2 only when a round-1 blocker was fixed. It checks only whether those blockers are fixed, and raises nothing new.
 
-1. Run the reviewer again with its usual inputs, plus the round-1 blockers and the diff of their fixes. It may be the round-1 reviewer resumed, since that context never saw the conversation that produced the work (with `cruze review`: `--round 2 --blockers <file> --base <round-1 commit>`). It checks only whether those blockers are fixed, and raises nothing new.
-2. Record the round with `round=2`.
-3. Take any blocker still open to the user, who fixes it now, waives it or starts a rethink. There is no round 3.
+1. **Choose who checks.** When every blocker was fixed exactly as the reviewer proposed, check the fixes yourself: a fresh reviewer re-reading a fix it proposed finds nothing new. When any blocker was fixed differently from the proposal, or its fix reaches past what the finding names, run the reviewer.
+2. **Check them yourself:** read each blocker's finding against the diff of its fix, and run `cruze validate`. A blocker is fixed when the diff does what the proposal says and validate reports no new errors.
+3. **Or run the reviewer** again with its usual inputs, plus the round-1 blockers and the diff of their fixes. It may be the round-1 reviewer resumed, since that context never saw the conversation that produced the work (with `cruze review`: `--round 2 --blockers <file> --base <round-1 commit>`).
+4. Record the round with `round=2`, the blockers still open, `concerns=0`, and `checked_by=agent` or `checked_by=reviewer`.
+5. Take any blocker still open to the user, who fixes it now, waives it or starts a rethink. There is no round 3.
 
-Done when every finding has a journaled disposition and no blocker is open without the user's decision.
+Done when every finding has a journaled disposition, and every exception, and every blocker left open in round 2, has the user's decision.
 
 ## The settled ledger
 

package/skills/roles/code-reviewer.md

@@ -46,7 +46,7 @@ Each finding has this shape:
 ```
 
 - A **blocker** means a scenario fails or is untested, a protected test was weakened, a layering rule is broken, an unapproved dependency was added, or an adapter can't honour its port's `Operations`. A finding that needs a design change is a blocker. Everything else is a **concern**.
-- List every blocker. List at most 5 concerns, the most important first. Count the rest as nits without listing them.
+- List every blocker. List at most 5 concerns, or one per 5 tasks of the change when that is more, the most important first. Count the rest as nits without listing them. Report only what would go wrong: no concerns is a valid report, and a small change usually has few.
 - Drop any finding that contradicts the settled ledger. The only exception is a blocker with new evidence, which you mark `New evidence:` and explain.
 - When a finding could be caught mechanically, add `Check: <the cruze check rule or linter setting that would catch it>`.
 - In round 2, report only whether each round-1 blocker is fixed, as `fixed` or `open` with the reason. Raise nothing new.

package/skills/roles/design-reviewer.md

@@ -28,8 +28,11 @@ Review against these items and nothing else. Each finding names one.
 8. **Consistency.** The design agrees with `docs/architecture.md`, the accepted ADRs and what earlier changes landed, or changes them explicitly through a `MODIFIED` operation or a new ADR. Its own elements agree with each other. Check every pair, not a sample:
    - each use case's `Output` and `Errors` against the `FLOW`s that serve it and the `XC` rules that apply to it;
    - each adapter's duties against the port it implements and the `XC` rules it follows;
-   - each guarantee, such as "always fits" or "never returns", against the limits and failures that bound it.
-9. **Slicing.** Each change is a vertical slice that delivers scenarios end to end and can land on its own. The order respects `Depends on`, and the first change is the thinnest useful tracer bullet. A change `Builds` an element only when its delivered scenarios prove the whole body; an element whose duties arrive in several changes is split into elements that each arrive whole. `Depends on` names every earlier change that builds something this change's scenarios need. At project scope, the roadmap starts with the walking skeleton, and every goal in the release is covered.
+   - each guarantee, such as "always fits" or "never returns", against the limits and failures that bound it;
+   - each `XC` rule against the other `XC` rules, the `RULE` elements and the `layers:` in `.cruze/config.yaml`, such as a logging rule that every module logs against a build rule that forbids the logging import;
+   - each pair of use cases that change the same state, for an interleaving that leaves it wrong, against the concurrency rule in `XC`;
+   - at feature scope, the prose in `docs/architecture.md` the delta makes untrue, such as an Overview sentence or a `D<n>` line describing an element the delta splits or replaces.
+9. **Slicing.** Each change is a vertical slice that delivers scenarios end to end and can land on its own. The order respects `Depends on`, and the first change proves the design end to end. Each change carries enough work to be worth its own plan review, code review and verify: changes that build one or two elements each on the same adapters or screens, in a chain, are one change split too fine. A change that one verifier run can't hold is split too coarse. A `change-too-small`, `change-too-large` or `feature-size` warning from `cruze validate` is a finding, unless a decision records the user accepting it. A change `Builds` an element only when its delivered scenarios prove the whole body; an element whose duties arrive in several changes is split into elements that each arrive whole. `Depends on` names every earlier change that builds something this change's scenarios need. At project scope, the roadmap starts with the walking skeleton, and every goal in the release is covered.
 10. **Ambiguity.** Name each point where a fresh implementer could reasonably build something different from what the user expects.
 
 ## Plan rubric
@@ -56,7 +59,7 @@ Each finding has this shape:
 ```
 
 - A **blocker** means building from the design as written would produce wrong behaviour, a layering violation or an untestable scenario. Two elements that contradict each other are always a blocker, because an implementer has to pick one. Everything else is a **concern**.
-- List every blocker. List at most 5 concerns, the most important first. Count the rest as nits without listing them.
+- List every blocker. List at most 5 concerns, or for a plan one per 5 tasks when that is more, the most important first. Count the rest as nits without listing them. Report only what would go wrong: no concerns is a valid report, and a small artifact usually has few.
 - Drop any finding that contradicts the settled ledger. The only exception is a blocker with new evidence, which you mark `New evidence:` and explain.
 - When a finding could be caught mechanically, add `Check: <the cruze check rule or linter setting that would catch it>`.
 - In round 2, report only whether each round-1 blocker is fixed, as `fixed` or `open` with the reason. Raise nothing new.

package/skills/roles/verifier.md

@@ -6,11 +6,12 @@ You check that a change actually works when someone uses it. The tests passing i
 
 - The change's `change.md`, and its `feature.md` when it belongs to a feature. The scenarios it delivers are listed under `Delivers` in its scope, and written out in the spec delta.
 - The project's commands, from `commands:` in `.cruze/config.yaml`, and from `README.md` when they aren't there.
+- The mechanical checks' results, with the commit they ran at.
 - The flows in `docs/architecture.md` that serve those scenarios.
 
 ## Work
 
-1. **Build.** Build the system and run the full test suite with the project's commands. Record each command and whether it passed.
+1. **Build.** Build the system with the project's build command, and record whether it passed. The test suite already ran at the commit in your inputs, and CI runs it again before the merge, so don't run it. Run a single test only when it is how a scenario reaches its real front door, such as a UI test that drives the app.
 2. **Trace.** Run `cruze trace --change <ref>` and record its result.
 3. **Run each scenario.** For every scenario the change delivers:
    - Set up its GIVEN with real things where you can: configuration files, directories, a local test server, a pseudo-terminal. Put them in a temporary directory outside the project.
@@ -35,4 +36,4 @@ One block per scenario:
 - Notes: <surprises from probing, or what a person needs to run it>
 ```
 
-Before the blocks, list the build, test and trace commands with their results. End with one line: `Pass: <n>. Fail: <n>. Could not run: <n>.`
+Before the blocks, list the build and trace commands with their results, and the commit the mechanical checks ran at. End with one line: `Pass: <n>. Fail: <n>. Could not run: <n>.`

package/skills/verify/SKILL.md

@@ -10,18 +10,22 @@ Verify answers one question: does this change work when someone uses it? Green t
 ## Steps
 
 1. **Check it is ready.** Run `cruze next`. It must name `verify` for this change, on this branch. Find the base commit the change branched from with `git merge-base main HEAD`.
-2. **Run the mechanical checks.** Run the project's format, lint, build and test commands from `commands:` in `.cruze/config.yaml`, then `cruze validate`, `cruze check --ci` and `cruze trace --change <ref>`. Quote each result. When one fails, fix the code in a commit and run them again. When a fix needs design, stop and offer `rethink`.
+2. **Run the mechanical checks.** Run `cruze validate`, `cruze check --ci` and `cruze trace --change <ref>`, and quote each result.
+   - Run `cruze journal list --event checks --item <ref>`. When its last entry's commit has no code changes since, that is when `git diff --quiet <commit> HEAD -- . ':(exclude)docs' ':(exclude).cruze'` succeeds, quote that entry for the format, lint, build and test commands instead of running them again.
+   - Otherwise run the format, lint and build commands and the full suite, as `.agents/skills/cruze-formats/reference/config.md` defines it under `commands`. When they pass, record them with `cruze journal add checks --set commit=<commit> --item <ref>`, where the commit is the output of `git rev-parse --short HEAD`.
+   - When one fails, fix the code in a commit and run them again. When a fix needs design, stop and offer `rethink`.
 3. **Check the dependencies.** Follow "Checking" in `.agents/skills/cruze-dependency-approval/SKILL.md` against the base commit. An unrecorded dependency is a blocker.
-4. **Run the verifier.** Run the verifier role from `.agents/skills/cruze-roles/SKILL.md` for the change. It must be able to build and run the system. When it runs through `cruze review`, check that `review.command` in `.cruze/config.yaml` allows the project's build and run commands, and add them with the user's agreement. Done when you have its report, with a result for every delivered scenario.
-5. **Review the code.** Run the review in the roles skill with the code reviewer, `review=code`, `--item <ref>` and the base commit. Fix each finding the user marks `fixed` in a commit, then check the fixes in round 2.
+4. **Run the verifier.** Run the verifier role from `.agents/skills/cruze-roles/SKILL.md` for the change, with the mechanical checks' results and the commit they ran at. It must be able to build and run the system. When it runs through `cruze review`, check that `review.command` in `.cruze/config.yaml` allows the project's build and run commands, and add them with the user's agreement. Done when you have its report, with a result for every delivered scenario.
+5. **Review the code.** Run the review in the roles skill with the code reviewer, `review=code`, `--item <ref>` and the base commit. Fix each finding whose disposition is `fixed` in a commit, running the tests each fix touches, and `test` when `commands:` has a `test_full`. Then check the fixes in round 2.
 6. **Write the manual test script** as `manual-test.md` in the change folder, following [manual-test.md](manual-test.md). Commit it.
-7. **Report.** Show the user four things:
+7. **Check the fixes once.** When code changed since the last `checks` entry, run the format, lint and build commands and the full suite once more, and record them as in step 2. Done when the last `checks` entry is at a commit with no code changes since.
+8. **Report.** Show the user four things:
    - The mechanical checks, one line each.
    - The verifier's result for every scenario.
    - The review's outcome, with each finding's disposition.
    - The path to `manual-test.md`, with a recommendation to run it before accepting.
-8. **Ask for the decision:** "Do you accept this change, or send it back?"
-9. **Record it** with `cruze journal add verification --set result=accepted --set summary="<one line>" --item <ref>`, or `result=sent-back`. On sent-back, say what goes back:
+9. **Ask for the decision:** "Do you accept this change, or send it back?"
+10. **Record it** with `cruze journal add verification --set result=accepted --set summary="<one line>" --item <ref>`, or `result=sent-back`. On sent-back, say what goes back:
    - A defect in code a task already built: `cruze task reopen T<n> "<reason>"`, then `build`.
    - A design that can't deliver the scenario: `rethink`.
 

package/src/adapters/inbound/cli/cli_context.ts

@@ -52,6 +52,8 @@ export interface Options {
   full: boolean;
   replan: string[];
   rebase: string[];
+  byAgent: boolean;
+  restampUnchanged: boolean;
   round?: string;
   package?: string;
   base?: string;

package/src/adapters/inbound/cli/commands/documents.ts

@@ -13,8 +13,12 @@ export async function runValidate(context: CliContext): Promise<CommandResult> {
 
 export async function runApprove(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
   requireArgs(args, ["document"]);
-  const report = await approveArtifact(context, args[0] ?? "", { replan: options.replan, rebase: options.rebase });
+  if (options.byAgent && options.restampUnchanged) throw new UsageError("--by-agent and --restamp-unchanged are alternatives");
+  const agent = options.byAgent ? "plan-review" : options.restampUnchanged ? "rethink" : undefined;
+  const report = await approveArtifact(context, args[0] ?? "", { replan: options.replan, rebase: options.rebase, ...(agent === undefined ? {} : { agent }) });
   const lines = [`Approved ${report.artifact} (${report.hash.slice(0, 19)}), pinned to ${report.upstream.length} upstream element(s).`];
+  if (report.basis === "plan-review") lines.push("Approved for the user: its plan review closed with no blocker open.");
+  if (report.restamped !== undefined) lines.push(`Re-stamped for the user: its own design is unchanged, and only ${report.restamped.join(", ")} changed.`);
   if (report.stamped.length > 0) lines.push(`Marked ${report.stamped.length} element(s) planned.`);
   if (report.bound !== undefined) lines.push(`Bound the change to branch ${report.bound}.`);
   if (report.replanned.length > 0) lines.push(`Set back to planned: ${report.replanned.join(", ")}.`);