@printpractical/cruze 0.0.5 → 0.0.6

package/README.md

@@ -10,7 +10,7 @@ It works with any agent that supports the [Agent Skills](https://agentskills.io)
 
 ## Status
 
-Version 0.0.5 is the fifth preview. It cuts the ceremony per change: reviews bring you only the findings that are yours to decide, plans are approved once their review closes, a rethink re-stamps the work it didn't change, and changes are sized to be worth their review and verify. Early development. The CLI is complete for the V1 lifecycle. The document formats ship as the `cruze-formats` skill, the standards an agent designs and codes to ship as knowledge skills, and the whole workflow, from explore to land, ships as workflow skills. Claude Code is the agent tested so far.
+Version 0.0.6 is the sixth preview. It cuts the waiting per change: the full test suite runs once per commit, with an optional fast tier for the task loop, the design walkthrough is one overview followed by the documents to read in full, the agent checks a review's round 2 when the fixes follow the proposals, and research checks every claim the design relies on. Early development. The CLI is complete for the V1 lifecycle. The document formats ship as the `cruze-formats` skill, the standards an agent designs and codes to ship as knowledge skills, and the whole workflow, from explore to land, ships as workflow skills. Claude Code is the agent tested so far.
 
 ## Why
 
@@ -35,7 +35,7 @@ The skills run `cruze` commands, so the agent needs `cruze` on its path. Install
 From a GitHub Release, without npm. Each release attaches the packed package:
 
 ```sh
-npm install -g https://github.com/PrintPractical/cruze/releases/download/v0.0.5/printpractical-cruze-0.0.5.tgz
+npm install -g https://github.com/PrintPractical/cruze/releases/download/v0.0.6/printpractical-cruze-0.0.6.tgz
 ```
 
 From npm, once a version is published there:
@@ -47,7 +47,7 @@ npm install -g @printpractical/cruze
 From the git repository, at a tag or `#main`. This needs git and access to the repository. npm 11 needs `--install-links` for a global git install, and the first `cruze` command builds the CLI, which takes a moment:
 
 ```sh
-npm install -g --install-links github:PrintPractical/cruze#v0.0.5
+npm install -g --install-links github:PrintPractical/cruze#v0.0.6
 ```
 
 ### 2. Set up a repository
@@ -61,7 +61,7 @@ cruze init
 When you didn't install from npm, tell `init` where Cruze came from, so the CI it writes runs the same source instead of the npm package:
 
 ```sh
-cruze init --package https://github.com/PrintPractical/cruze/releases/download/v0.0.5/printpractical-cruze-0.0.5.tgz
+cruze init --package https://github.com/PrintPractical/cruze/releases/download/v0.0.6/printpractical-cruze-0.0.6.tgz
 ```
 
 `init` asks for the project name, and which coding agent you use: `claude` for Claude Code, or `other` for any agent that reads `AGENTS.md` and `.agents/skills/`, such as Codex or OpenCode. It doesn't ask when you pass `--agent claude` or `--agent other`, or when the repository already has `CLAUDE.md` or `.claude/`. With `--yes`, or without a terminal, it sets up Claude Code. Then it creates:

package/dist/app/use_cases/new_work_item.js

@@ -28,7 +28,7 @@ import { appendJournal, loadView,                  } from "../project_context.js
 export async function createWorkItem(deps             , request            )                     {
   const view = await loadView(deps.files);
   const date = deps.clock.today();
-  const values = { id: "", title: request.title, date, project_name: "" };
+  const values = { id: "", title: request.title, title_quoted: JSON.stringify(request.title), date, project_name: "" };
   if (request.title.trim() === "") throw new CruzeError("missing-title", "a title is required");
 
   if (request.kind === "adr") {

package/dist/domain/journal.js

@@ -15,12 +15,13 @@ export const RECORDED_EVENTS                           = {
   override: ["gate", "reason"],
   bug: ["summary", "cause"],
   verification: ["result", "summary"],
+  checks: ["commit"],
 };
 
 /** Fields an event may carry beyond its required ones, checked when present. A defect rethink must say which step missed it. */
 const OPTIONAL_FIELDS                           = {
   rethink: ["missed_by"],
-  review: ["nits"],
+  review: ["nits", "checked_by"],
   disposition: ["decided"],
 };
 
@@ -34,6 +35,7 @@ export const FIELD_VALUES                           = {
   decided: ["agent", "user"],
   review: ["design", "plan", "code", "realign"],
   result: ["accepted", "sent-back"],
+  checked_by: ["agent", "reviewer"],
   found_by: STEPS,
   missed_by: STEPS,
 };
@@ -79,6 +81,9 @@ export function recordedEventProblems(event        , fields
     if (allowed !== undefined && !allowed.includes(value)) problems.push(`${field} must be one of ${allowed.join(", ")}`);
     if (COUNT_FIELDS.includes(field) && !/^\d+$/.test(value)) problems.push(`${field} must be a whole number`);
   }
+  if (event === "checks" && fields["commit"] !== undefined && !/^[0-9a-f]{7,40}$/.test(fields["commit"])) {
+    problems.push("commit must be a commit hash, such as the output of git rev-parse --short HEAD");
+  }
   if (event === "disposition" && fields["decided"] === "agent" && fields["disposition"] !== "fixed") {
     problems.push("the agent decides only fixes; the user waives, defers or rejects a finding (decided=user)");
   }

package/dist/domain/status/next_step.js

@@ -66,7 +66,7 @@ function projectStep(view             )                  {
     {
       path: PATHS.architecture,
       missing: { step: "architect", reason: "the project has no architecture yet" },
-      unapproved: { step: "architect", reason: "finish the architecture, walk through it and approve it" },
+      unapproved: { step: "architect", reason: "finish the architecture, review it and approve it" },
       changed: { step: "rethink", target: "architecture", reason: "the architecture changed since its approval" },
     },
     {
@@ -89,7 +89,7 @@ function itemSteps(view             , item          , branch               )
   if (item.kind === "standalone") return [changeStep(view, item, branch)];
   const state = evaluateApproval(view, item.path);
   if (readChangesTable(item.doc).length === 0) return [{ step: "architect", target: item.ref, reason: "the feature has no design or changes yet" }];
-  if (state.state === "unapproved") return [{ step: "architect", target: item.ref, reason: "review the feature's design, walk through it and approve it" }];
+  if (state.state === "unapproved") return [{ step: "architect", target: item.ref, reason: "review the feature's design and approve it" }];
   if (state.state !== "approved") return [{ step: "rethink", target: item.ref, reason: `the feature changed since its approval${state.changed.length > 0 ? ` (${state.changed.join(", ")})` : ""}` }];
   const changes = changesOf(view.items, item);
   const landed = new Set(changes.filter((c) => readProgress(c.doc).landed !== undefined).map((c) => c.folderName));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@printpractical/cruze",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Spec-driven development for coding agents: one living model of the system, small deltas, convergent review.",
   "license": "Apache-2.0",
   "author": "Chris Buchter",

package/skills/architect/SKILL.md

@@ -5,7 +5,7 @@ description: Decides how to build and how big, at project scope (domain model, c
 
 # Architect
 
-Architect decides the how and the how big. It designs the domain, the ports and adapters, and where every element lives in the source tree, before any code exists. It ends with the one heavy human gate, the design walkthrough, where the user sees the entities, their interactions, the ports and the files, and approves the design.
+Architect decides the how and the how big. It designs the domain, the ports and adapters, and where every element lives in the source tree, before any code exists. It ends with the one heavy human gate, the design walkthrough: a short overview in plain terms, after which the user reads the design documents in full and approves or comments.
 
 ## Steps
 
@@ -25,7 +25,7 @@ Architect decides the how and the how big. It designs the domain, the ports and
    - `.agents/skills/cruze-formats/reference/architecture.md`
 5. **Design.** Follow the scope's procedure: [project.md](project.md), [feature.md](feature.md) or [tweak.md](tweak.md). Tweak scope ends there and hands off to `plan`.
 6. **Review the design.** Run the design review in `.agents/skills/cruze-roles/SKILL.md`, with the design reviewer role. Done when every finding has a journaled disposition and no blocker is open without the user's decision.
-7. **Walk the user through it.** Follow [walkthrough.md](walkthrough.md). Apply what the user changes, run `cruze validate` again, and repeat the parts of the walkthrough those changes affect.
+7. **Hand the design to the user.** Follow [walkthrough.md](walkthrough.md): one overview message, then the documents to read in full. Apply what the user changes, run `cruze validate` again, and say what changed.
 8. **Record the approval.** Only after the user says they approve, run the scope's `cruze approve` command and quote its result, then commit. At project scope, the roadmap follows as its own approval, described in [project.md](project.md).
 
 ## Rules

package/skills/architect/feature.md

@@ -33,4 +33,6 @@ The result is a `feature.md` with a complete architecture delta and an ordered l
 
     The thresholds are the defaults under `changes:` in `.cruze/config.yaml`; a project can tune them.
 
+    Done when `cruze validate` reports no `change-too-small`, `change-too-large` or `feature-size` warning, or the user has accepted one and a `D<n>` line under the feature's `## Decisions` records why. After approval, only a rethink can split a change.
+
 Then continue with the review and walkthrough steps of the skill. When the user approves, run `cruze approve <feature>` and quote its result. The command takes the feature's full ID, such as `2026-09-25-open-console`, or its slug when no other active item shares it.

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/reference/config.md

@@ -56,7 +56,7 @@ 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`. |

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

@@ -44,7 +44,7 @@ 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

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.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

@@ -8,6 +8,7 @@ Each release that changes what Cruze expects of a project ships a notes file, `n
 - [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/levels.md

@@ -11,7 +11,7 @@
 
 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`.
+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.
 

package/skills/roles/SKILL.md

@@ -53,11 +53,13 @@ A review has at most two rounds. Only blockers can force the second one.
 
 ### 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 every exception, and every blocker left open in round 2, has the user's decision.
 

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 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 `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

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 whose disposition is `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/app/use_cases/new_work_item.ts

@@ -28,7 +28,7 @@ export interface NewReport {
 export async function createWorkItem(deps: ProjectDeps, request: NewRequest): Promise<NewReport> {
   const view = await loadView(deps.files);
   const date = deps.clock.today();
-  const values = { id: "", title: request.title, date, project_name: "" };
+  const values = { id: "", title: request.title, title_quoted: JSON.stringify(request.title), date, project_name: "" };
   if (request.title.trim() === "") throw new CruzeError("missing-title", "a title is required");
 
   if (request.kind === "adr") {

package/src/domain/journal.ts

@@ -15,12 +15,13 @@ export const RECORDED_EVENTS: Record<string, string[]> = {
   override: ["gate", "reason"],
   bug: ["summary", "cause"],
   verification: ["result", "summary"],
+  checks: ["commit"],
 };
 
 /** Fields an event may carry beyond its required ones, checked when present. A defect rethink must say which step missed it. */
 const OPTIONAL_FIELDS: Record<string, string[]> = {
   rethink: ["missed_by"],
-  review: ["nits"],
+  review: ["nits", "checked_by"],
   disposition: ["decided"],
 };
 
@@ -34,6 +35,7 @@ export const FIELD_VALUES: Record<string, string[]> = {
   decided: ["agent", "user"],
   review: ["design", "plan", "code", "realign"],
   result: ["accepted", "sent-back"],
+  checked_by: ["agent", "reviewer"],
   found_by: STEPS,
   missed_by: STEPS,
 };
@@ -79,6 +81,9 @@ export function recordedEventProblems(event: string, fields: Record<string, stri
     if (allowed !== undefined && !allowed.includes(value)) problems.push(`${field} must be one of ${allowed.join(", ")}`);
     if (COUNT_FIELDS.includes(field) && !/^\d+$/.test(value)) problems.push(`${field} must be a whole number`);
   }
+  if (event === "checks" && fields["commit"] !== undefined && !/^[0-9a-f]{7,40}$/.test(fields["commit"])) {
+    problems.push("commit must be a commit hash, such as the output of git rev-parse --short HEAD");
+  }
   if (event === "disposition" && fields["decided"] === "agent" && fields["disposition"] !== "fixed") {
     problems.push("the agent decides only fixes; the user waives, defers or rejects a finding (decided=user)");
   }

package/src/domain/status/next_step.ts

@@ -66,7 +66,7 @@ function projectStep(view: ProjectView): NextStep | null {
     {
       path: PATHS.architecture,
       missing: { step: "architect", reason: "the project has no architecture yet" },
-      unapproved: { step: "architect", reason: "finish the architecture, walk through it and approve it" },
+      unapproved: { step: "architect", reason: "finish the architecture, review it and approve it" },
       changed: { step: "rethink", target: "architecture", reason: "the architecture changed since its approval" },
     },
     {
@@ -89,7 +89,7 @@ function itemSteps(view: ProjectView, item: WorkItem, branch: string | null): Ne
   if (item.kind === "standalone") return [changeStep(view, item, branch)];
   const state = evaluateApproval(view, item.path);
   if (readChangesTable(item.doc).length === 0) return [{ step: "architect", target: item.ref, reason: "the feature has no design or changes yet" }];
-  if (state.state === "unapproved") return [{ step: "architect", target: item.ref, reason: "review the feature's design, walk through it and approve it" }];
+  if (state.state === "unapproved") return [{ step: "architect", target: item.ref, reason: "review the feature's design and approve it" }];
   if (state.state !== "approved") return [{ step: "rethink", target: item.ref, reason: `the feature changed since its approval${state.changed.length > 0 ? ` (${state.changed.join(", ")})` : ""}` }];
   const changes = changesOf(view.items, item);
   const landed = new Set(changes.filter((c) => readProgress(c.doc).landed !== undefined).map((c) => c.folderName));