@printpractical/cruze 0.0.10 → 0.0.12

package/README.md

@@ -10,7 +10,7 @@ It works with any agent that supports the [Agent Skills](https://agentskills.io)
 
 ## Status
 
-Version 0.0.10 is the tenth preview. Intent now survives from the first idea to every design: the vision holds the principles every design follows and the capabilities that must stay possible, envision takes in any input and hands each part to the step that takes it up, and the design reviewer checks every design against them. Steps read less, through an element index and lookup, one rubric per review and a word budget on the skills. 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.12 is the twelfth preview. Designs are easier to see and keep lean: the walkthrough shows the types each caller passes and the decisions you didn't make, reviews cut fields nothing reads, questions use plain words and explain a part before asking about it, and a rethink designs for the features ahead. 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.10/printpractical-cruze-0.0.10.tgz
+npm install -g https://github.com/PrintPractical/cruze/releases/download/v0.0.12/printpractical-cruze-0.0.12.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.10
+npm install -g --install-links github:PrintPractical/cruze#v0.0.12
 ```
 
 ### 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.10/printpractical-cruze-0.0.10.tgz
+cruze init --package https://github.com/PrintPractical/cruze/releases/download/v0.0.12/printpractical-cruze-0.0.12.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/domain/journal.js

@@ -24,14 +24,14 @@ const OPTIONAL_FIELDS                           = {
   rethink: ["missed_by"],
   review: ["nits", "checked_by"],
   disposition: ["decided"],
-  verification: ["back_to"],
+  verification: ["back_to", "commit"],
 };
 
 /** The workflow steps and checks that find or miss a problem, so a retro can count them. */
 export const STEPS = ["envision", "architect", "research", "design-review", "walkthrough", "plan", "plan-review", "build", "code-review", "verify", "land", "realign", "improve", "validate", "check", "user"];
 
 export const FIELD_VALUES                           = {
-  level: ["task", "change", "feature", "architecture", "vision"],
+  level: ["task", "detail", "change", "feature", "architecture", "vision"],
   kind: ["defect", "discovery"],
   disposition: ["fixed", "waived", "deferred", "rejected", "rethink"],
   decided: ["agent", "user"],
@@ -94,7 +94,7 @@ 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"])) {
+  if ((event === "checks" || event === "verification") && 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") {

package/dist/domain/skill_budget.js

@@ -11,7 +11,7 @@ export const MAX_FILE_WORDS = 2100;
  * 0.0.10 the skills grew by half while nothing was removed. Lower this when text is cut. Raising it
  * is the maintainer's decision, with the reason in the commit that raises it.
  */
-export const BUNDLE_WORD_BUDGET = 44500;
+export const BUNDLE_WORD_BUDGET = 45450;
 
 /** Data the CLI reads or renders, rather than instructions an agent reads. */
 const NOT_INSTRUCTIONS = /(^|\/)(templates|notes)\//;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@printpractical/cruze",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "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/walkthrough.md

@@ -12,9 +12,9 @@ Write it in the glossary's terms, as what callers can do and what happens when t
 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. **What it looks like.** Illustrated as `.agents/skills/cruze-grilling/illustrating.md` says:
    - A plain-text diagram of the main scenario crossing the design: the inbound adapter, the use case, the domain elements and the ports, marking what is new.
-   - A code sketch, in the project's language, of what the new and changed elements look like: the port operations and use case signatures with their errors, the main entity, and the call an inbound adapter makes.
+   - A code sketch, in the project's language, of what the new and changed elements look like: the port operations and use case signatures with their errors, the main entity, and the call each kind of caller makes, a component in the same process included, with the types it passes as they will be declared. One project approved orchestrators that passed JSON values inside the daemon, which no sketch showed, and rejected it at build a day later.
 4. **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.
-5. **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.
+5. **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. Then, one line each, every decision the design takes that no answer of the user's settled, carried-over ones included, and every value the system's own components pass each other untyped or encoded, such as a JSON value. Approval rests on this overview: one feature's documents ran to 25,000 words.
 
 ## The documents
 

package/skills/build/SKILL.md

@@ -49,12 +49,12 @@ The plan is design. Within a task you decide only what is local and reversible.
   - a new element, port operation or scenario;
   - 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, or a feature of an approved dependency, that the design doesn't name. Ask for it as `.agents/skills/cruze-dependency-approval/SKILL.md` says, and never write around it with hand-written code or a shell command;
-  - a limit, timeout, buffer size, message or error case the design doesn't give. Picking one in code hides a gap in the design: the user decides it, at feature level. Two projects settled 35 of them as deviations.
+  - a dependency, or a feature of an approved dependency, that the design doesn't name. Ask for it as `.agents/skills/cruze-dependency-approval/SKILL.md` says, and never write around it with hand-written code or a shell command.
 
   Explain what you found, with the evidence, and don't work around it. Completed tasks keep their commits.
-- **Read a deviation back before you record it.** One that says the design gives no value, text, error or outcome and names the one you chose, or that the code can't keep a promise a port or use case makes, is a rethink, not a deviation. In one change, two deviations worded that way came back as code-review blockers and sent it back at verify.
-- Never edit `feature.md`, `docs/architecture.md` or `docs/specs/` during build. Design changes go through `rethink`.
+- **Settle a detail with the user,** as "Detail" in `.agents/skills/cruze-rethink/levels.md` says, when the code needs a limit, timeout, buffer size, message or error case the design doesn't give. Never offer a deviation instead: two projects settled 35 details as deviations.
+- **Read a deviation back before you record it.** One naming a value, text, error or outcome the design doesn't give is a detail; one saying the code can't keep a promise a port or use case makes is a rethink.
+- Never edit `feature.md`, `docs/architecture.md` or `docs/specs/` during build. Design changes go through `rethink`, a detail included.
 
 ## Protecting the check
 

package/skills/grilling/SKILL.md

@@ -20,7 +20,7 @@ Interview the user until you both understand the design the same way. Decisions
 ## A round
 
 ````markdown
-Where we are: architect for 2026-09-25-open-console, round 2. Settled: D1 (a console session may cross jump hosts), D2 (credentials come from the vault).
+Where we are: architect for 2026-09-25-open-console, round 2. Settled: a console session may cross jump hosts, and credentials come from the vault.
 
 **Q4. Where the jump-host list lives**
 Per device in the device config, or as named hosts that devices reference. Named hosts avoid repeating a host's address and credentials across devices, but add a second lookup.
@@ -45,6 +45,8 @@ Recommended: named hosts, because the lab config already shares two jump hosts a
 - Ask about behaviour and trade-offs in the user's terms and the glossary's words, not about implementation mechanics. Where the trade-off is in the code's shape, show the shape.
 - When the user answers "you decide" or "I don't know", take your recommendation and record it with "(recommended; the user deferred)".
 - When an answer contradicts an earlier decision, point to that decision and ask which one stands.
+- When the user doubts part of the design, calling it rigid, heavy or messy, one option removes or shrinks it, with what that costs. One user called a status shape rigid, was offered more of it, and stopped a build over its unused fields a day later.
+- When making one answer hold needs new types, rules or error cases, and those need fixes of their own, stop before the next round. Show what the answer has grown beside the simplest alternative that meets the user's need, and let the user choose. One rethink grew four types over eleven questions before a review found five blockers in them; the alternative was 40% smaller.
 
 ## What to ask and what to decide
 

package/skills/grilling/illustrating.md

@@ -4,8 +4,9 @@ The user decides from what they can picture. A question about a port's errors or
 
 ## Reading cold
 
-- Open each round, and each message of review exceptions, with one line saying where things stand: the work item, the step, and the earlier decisions this round builds on, such as `Where we are: architect for 2026-10-08-subscriptions, round 3. Settled: D2 (one stream per session), D4 (events carry revisions).`
-- Say what an ID means in plain words the first time a message uses it, such as `SCN-configuration.reject-taken-priority (a second set asking for a priority already taken is refused)`.
+- The user knows what the product should do, not the design's internals. Before a question about a part of the design, say in a sentence or two what that part is, what it does today and why the question comes up, and show it. Ask about what the user will notice, and explain the mechanism only as far as the choice needs. In one day of one project, the user asked four times what a question meant, from "what's the definition of a condition?" to "give me an ELI5".
+- Open each round, and each message of review exceptions, with one line saying where things stand: the work item, the step, and the earlier decisions this round builds on, such as `Where we are: architect for 2026-10-08-subscriptions, round 3. Settled: one stream per session, and events carry revisions.`
+- The user doesn't know the design's IDs by heart. Name each requirement, scenario, element, decision or task in plain words, and add its ID after them in parentheses only when the user may want to look it up: "a second set asking for a priority already taken is refused (SCN-configuration.reject-taken-priority)". Never let an ID stand alone or be what a sentence is about, as in "D11 forbids this". In one project, 197 of the 215 IDs in 75 questions stood alone, and the user misread what was asked.
 - Each question says what it decides and why it matters now, without pointing back to an earlier message.
 
 ## Choosing the illustration
@@ -22,7 +23,7 @@ Show each option, side by side, with the form that fits what the question decide
 | A stored format or a config file | A sample of the file |
 | A dependency | The code with it and the code without it |
 
-Leave out the illustration only when the question is about a name, a number or the wording of a sentence, where it would repeat the words.
+Leave out the illustration only when the question is about a name, a number or the wording of a sentence, where it would repeat the words. A question asked through a pick-one tool carries it too: in each option's preview where the tool has one, otherwise in a message just before. One build asked through such a tool with only file and function names in its options, and the user had to ask what it meant.
 
 ## Writing it
 

package/skills/realign/notes/0.0.11.md

@@ -0,0 +1,15 @@
+# Realign notes: 0.0.11
+
+## New work only
+
+### review-severity: A blocker is a failure ordinary use reaches, not every gap in the design
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/code-reviewer.md`, "Findings"
+
+### reverify-scope: A verify after a send-back reviews only the code changed since the last verify
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-verify/SKILL.md`, "Steps", steps 1 and 10
+
+### detail-amendments: A missing limit, timeout, message or error case is settled as a detail inside build or verify
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-rethink/levels.md`, "Detail"

package/skills/realign/notes/0.0.12.md

@@ -0,0 +1,31 @@
+# Realign notes: 0.0.12
+
+## New work only
+
+### walkthrough-types: The walkthrough shows the types each caller passes, and the decisions the user didn't make
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-architect/walkthrough.md`, "The overview", items 3 and 5
+
+### design-needed-fields: A field serves a need only when something reads it
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/design-rubric.md`, item 3
+
+### design-typed-inside: Values passed inside the system are typed
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/design-rubric.md`, item 13
+
+### grilling-shrink: Doubt gets an option that shrinks the design, and a growing answer gets a simpler alternative
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-grilling/SKILL.md`, "A round"
+
+### plain-questions: Questions name things in plain words, with an ID only beside them, and illustrate pick-one options too
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-grilling/illustrating.md`, "Reading cold" and "Choosing the illustration"
+
+### grilling-context: Questions explain the part of the design they ask about before asking
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-grilling/illustrating.md`, "Reading cold"
+
+### rethink-forward: A feature or architecture rethink designs for the features ahead, as architect does
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-rethink/SKILL.md`, "Steps", steps 3 and 4

package/skills/realign/notes.md

@@ -13,6 +13,8 @@ Each release that changes what Cruze expects of a project ships a notes file, `n
 - [0.0.8](notes/0.0.8.md)
 - [0.0.9](notes/0.0.9.md)
 - [0.0.10](notes/0.0.10.md)
+- [0.0.11](notes/0.0.11.md)
+- [0.0.12](notes/0.0.12.md)
 
 ## Format
 

package/skills/rethink/SKILL.md

@@ -15,8 +15,8 @@ Finding a design flaw mid-build is information, not failure. Rethink amends the
    - **Discovery:** it is new information no step could have had.
 
    Tell the user the level and the kind in one line, and let them correct it.
-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.
+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`, `.agents/skills/cruze-research/SKILL.md` and `.agents/skills/cruze-dependency-approval/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. At feature level and above, design the amendment as architect designs a feature, following the Rules in `.agents/skills/cruze-architect/SKILL.md`: read the vision's principles and capabilities that must stay possible, the feature map and the roadmap, and design for the features ahead while building only what the work in hand needs. Each option you offer says how the features ahead would use it, which capabilities it keeps open, and what it does to a running device or service, such as across a restart, an upgrade or a downgrade. In one architecture rethink, the user had to ask whether an option would still work for the apps the product plans to host, and point out that refusing to start after a downgrade could brick a router.
 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 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:
    - Run `cruze diff <ref>`. It shows each changed element's approved and current text, and whether the work's delta needs a rebase. Check the work still holds against it. When it doesn't, amend it too, and the user approves it as an amended document.
@@ -26,7 +26,7 @@ Finding a design flaw mid-build is information, not failure. Rethink amends the
 7. **Record the rethink.** Draft the entry and show it to the user in one line. When they confirm, run:
 
    ```sh
-   cruze journal add rethink --set level=<task|change|feature|architecture|vision> --set kind=<defect|discovery> \
+   cruze journal add rethink --set level=<task|detail|change|feature|architecture|vision> --set kind=<defect|discovery> \
      --set summary="<what changed>" --set wrong="<document and element, and what was wrong>" \
      --set found_by=<step> [--set missed_by=<step>] \
      --set agent="<the agent you run in>" [--item <ref>]
@@ -43,6 +43,7 @@ Done when `cruze status` shows every document approved and current, or names onl
 | Level | Example | Amend | Then |
 | --- | --- | --- | --- |
 | Task | A helper belongs in a different file of the same module | Nothing. Record it with `cruze task deviation` | Carry on building. This is not a rethink, so record no rethink entry |
+| Detail | Build or verify needs a limit, timeout, message or error case | The element's text, with the code | The user approves it, with no review. Run from build or verify, as [levels.md](levels.md) says |
 | Change | A test plan row or a task's file is wrong, with no design change | `change.md`: its test plan or tasks | Plan review of the diff, then re-approve the change |
 | Feature | A use case needs a second port operation; a scenario is wrong | `feature.md`: its deltas and Changes table, or a standalone `change.md`'s deltas | Design review of the diff, walkthrough of the changed parts, then re-approve the feature and its changes |
 | Architecture | An entity boundary is wrong, or a new port is needed | `docs/architecture.md` directly, plus an ADR when it passes the ADR test | Design review of the diff when it changes an operation, port, error or `XC` rule, walkthrough of the diff, then `cruze approve architecture`, with `--replan` for built elements whose code must change |

package/skills/rethink/levels.md

@@ -1,5 +1,14 @@
 # Amending each level
 
+## Detail
+
+A detail settles a limit, timeout, buffer size, message or error case that an element of the work in progress doesn't give, with no new element, port operation or dependency, and no change to an approved scenario. Build and verify run it without leaving their step: one message length settled as a full rethink took 75 minutes.
+
+1. Ask the user, recommending a value and showing what the code then does, as `.agents/skills/cruze-grilling/illustrating.md` says.
+2. Amend the element where it lives, in the delta or `docs/architecture.md`, adding at most one failure scenario and its test plan row for a new error case. Run `cruze validate`; done when it reports no errors.
+3. Commit the text with the code and its test, naming the task. Tasks stay ticked.
+4. The user approves the amended document. Re-stamp what went stale, and record the rethink with `level=detail`, as the skill's steps 6 and 7 say.
+
 ## Change
 
 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.

package/skills/roles/SKILL.md

@@ -35,7 +35,7 @@ A review has at most two rounds. Only blockers can force the second one.
    - 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 recommend anything but `fixed`: waiving, deferring or rejecting it, or a rethink because it needs a design change. A fix through a detail amendment is an exception too.
    - 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. Nits are a count, not findings: when a report lists any, they get no disposition and you don't bring them to the user.
@@ -45,7 +45,7 @@ A review has at most two rounds. Only blockers can force the second one.
    - `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`. When the user wants the rethink later, record it as `rethink` instead, with `--item` naming the feature or change it amends: `cruze next` and the build gate hold that work until a rethink is recorded for it.
+   A finding whose fix would change an approved element, such as one marked `Needs design change`, is never `waived`. Recommend `fixed` through a detail amendment when it qualifies, as "Detail" in `.agents/skills/cruze-rethink/levels.md` says, otherwise `rethink` at that element's level now, or `deferred` for a concern later work can carry. Once the rethink is done and the code follows it, record the finding as `fixed`. When the user wants the rethink later, record it as `rethink` instead, with `--item` naming the feature or change it amends: `cruze next` and the build gate hold that work until a rethink is recorded for it.
 
    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|rethink> --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.

package/skills/roles/code-reviewer.md

@@ -5,7 +5,7 @@ You review the code a change adds, before it lands. You work in two lanes. The s
 ## Inputs
 
 - The change's `change.md`, and the output of `cruze show <ref>`: the elements it builds, the scenarios it delivers, the settled decisions and the ledger. Read an element it lists as cited only when the diff calls it, with `cruze show <ID>`.
-- The diff under review, from `git diff <base>` for the base commit you are given.
+- The diff under review, from `git diff <base>` for the base commit you are given. When the base is where an earlier verify stopped, review older code only where the diff changes what it does.
 - The ADRs in `docs/adr/`, and the specs in `docs/specs/` for the capabilities the change touches.
 - The references `cruze show` lists, at the sections the change's elements cite.
 - The settled ledger, as `.agents/skills/cruze-roles/SKILL.md` defines it, with the output of `cruze journal list --event disposition --item <ref>`.
@@ -32,7 +32,7 @@ Review against these items and nothing else. Each finding names one.
 8. **Idiom.** The code is idiomatic for the language, uses its standard tooling, and follows the language file's rules, including where tests live. Tests reuse the fixtures and harnesses in the test support module rather than redefining them. Each `expect`, `unwrap` or panic in the diff has a reason its case can't happen; one a caller, the clock or a concurrent call can reach is a finding.
 9. **Libraries.** Nothing hand-writes what a mature library does without a recorded `build` decision, and every new dependency has a recorded approval. No code works around a dependency or a feature: hand-written code, a shell command or a less idiomatic construct chosen because the clean one needs a dependency is a finding.
 10. **Contracts.** Each adapter honours its port's `Operations`, and each fake passes the same contract tests as the real adapter.
-11. **Deviations.** Each deviation the change recorded is a choice build may make on its own: a private helper or a new file inside the owner's module, a `check.exceptions` entry, a fixture in the test support module, or two tasks swapped. A deviation that added an element, port operation or scenario, wrote a file outside the owner's module, changed an approved scenario's behaviour or its test, worked around a dependency or a feature, or settled a limit, timeout, message or error case the design doesn't give, needed a rethink: a blocker, with `Needs design change` naming the element. Two projects recorded 13 such deviations.
+11. **Deviations.** Each deviation the change recorded is a choice build may make on its own: a private helper or a new file inside the owner's module, a `check.exceptions` entry, a fixture in the test support module, or two tasks swapped. A deviation that added an element, port operation or scenario, wrote a file outside the owner's module, changed an approved scenario's behaviour or its test, worked around a dependency or a feature, or settled a limit, timeout, message or error case the design doesn't give, needed a design amendment: a blocker, with `Needs design change` naming the element.
 
 ## Findings
 
@@ -47,7 +47,8 @@ Each finding has this shape:
 - Needs design change: <the approved element whose text the fix must change, such as a port's `Operations`, or `no`>
 ```
 
-- 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**.
+- 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 failure is also a blocker when a user or client the design serves reaches it in ordinary use, their mistakes and failing disks, networks and peers included, and it loses or corrupts data, crashes, hangs, spins, or holds up someone else's work.
+- Everything else is a **concern**, even when its fix needs a design change, such as a failure only hand-made input reaches that harms only its sender: in one change, such cases were the only blockers of two verifies in a row. Say who reaches the failure, and how.
 - 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: give only their number, never their text. 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>`.

package/skills/roles/design-rubric.md

@@ -4,7 +4,7 @@ The design reviewer's rubric for a design: the architecture at project scope, or
 
 1. **Behaviour.** Every requirement has at least one scenario. Every scenario has concrete values, one WHEN, and a THEN a person could check. Failure behaviour the user will meet has its own scenario.
 2. **Seams.** Every scenario can be driven through a use case, or through an inbound adapter when the outcome is what that adapter shows. Every driven port the use case needs can be faked.
-3. **Placement.** Every new or changed element with code has a `Module` whose `Layer` fits its role and a `File` with a real path. No generic modules, and no file is likely to hold two responsibilities. The layout is the one normal for the kind of system and the language, and every layer, module, package or target split beyond a context's `core` and its adapters has a recorded reason. Every element, fact and value serves a requirement in scope, or a `Future` fact the feature map or a `LATER` capability calls for. Anything reserved for a need nobody stated is a finding, and so is anything built, rather than left room for, for a `LATER` capability.
+3. **Placement.** Every new or changed element with code has a `Module` whose `Layer` fits its role and a `File` with a real path. No generic modules, and no file is likely to hold two responsibilities. The layout is the one normal for the kind of system and the language, and every layer, module, package or target split beyond a context's `core` and its adapters has a recorded reason. Every element, fact and value serves a requirement in scope, or a `Future` fact the feature map or a `LATER` capability calls for. Anything reserved for a need nobody stated is a finding, and so is anything built, rather than left room for, for a `LATER` capability. A field or value serves a need only when a person, a tool or another element reads it in a scenario or a `LATER` row; a scenario that only checks it is written doesn't count. A design carried over from an earlier build or a seed is checked the same way: one project built a clock port and timestamp parsing for a status field nothing read.
 4. **Direction.** Every dependency points inward and is allowed by the `RULE` elements and the `layers:` in `.cruze/config.yaml`.
 5. **Adopt or build.** Every component that isn't domain logic has an adopt-or-build decision with a reason, and every new dependency is named with the features the design uses. Every type, trait, macro, framework or tool the design names from outside the project comes from a dependency and feature the design approves, declared by each crate, package or target that uses it, test support included, and allowed by the import rules in `XC` and the `layers:` in `.cruze/config.yaml`. A choice whose reason is avoiding a dependency, a crate or a feature, where the idiomatic design needs one, is a concern: name the idiomatic design. Every command the design spells out, such as a CI step, is spelled as that version's `--help` or source shows it. A claim the design relies on that the research left unverified is a blocker.
 6. **Contracts.** Every new or changed port's `Operations` state what each operation guarantees, how it fails, and who owns cleanup. Check each use case and each port operation for the values build would otherwise have to pick: a named error for every failure a caller can meet, where a panic, an `expect` or "caller error" counts as missing; a number for every timeout, limit, buffer and poll interval; what a caller observes after each state transition, and what happens to queued or in-flight work at it; and one owner for every message a scenario quotes. Each one missing is a blocker: two projects settled 35 of them during build, as deviations.
@@ -38,3 +38,4 @@ The design reviewer's rubric for a design: the architecture at project scope, or
    - each settled decision of the design that states long-term intent, such as "eventually" or "later": it is a `LATER` row in the vision, since the decision is archived when the work lands.
 
    A departure from a principle with no amendment, a `likely` capability closed off, or a design resting on an open hand-off row, is a blocker; a `possible` one closed off is a concern.
+13. **Typed inside.** Each value one of the system's own components passes another in the same process has its own type, as the standards' domain rules say. A serialization format between them, such as a JSON value, a raw frame or an untyped map, is a concern even when an ADR gives the reason, so the walkthrough brings it to the user.

package/skills/verify/SKILL.md

@@ -9,14 +9,14 @@ 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`.
+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`. The code review's base is the same, unless `cruze journal list --event verification --item <ref>` shows an earlier verify: then it is that entry's commit, or `git rev-list -1 --before=<its at> HEAD` for one without, since the code before it was reviewed.
 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.
+3. **Check the dependencies.** Follow "Checking" in `.agents/skills/cruze-dependency-approval/SKILL.md` against the merge base. An unrecorded dependency is a blocker.
 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 yourself, as round 2 in the roles skill says.
+5. **Review the code.** Run the review in the roles skill with the code reviewer, `review=code`, `--item <ref>` and the code review's base. Fix each finding whose disposition is `fixed` in a commit, through a detail amendment when it needs one, running the tests each fix touches, and `test` when `commands:` has a `test_full`. Then check the fixes yourself, as round 2 in the roles skill says.
 6. **Write the manual test script** as `manual-test.md` in the change folder, following [manual-test.md](manual-test.md). Commit it.
 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:
@@ -25,7 +25,7 @@ Verify answers one question: does this change work when someone uses it? Green t
    - The review's outcome, with each finding's disposition.
    - The path to `manual-test.md`, with a recommendation to run it before accepting.
 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 `--set result=sent-back --set back_to=<build|rethink>`. On sent-back, say what goes back:
+10. **Record it** with `cruze journal add verification --set result=<accepted|sent-back> --set summary="<one line>" --set commit=<commit> --item <ref>`, where the commit is the output of `git rev-parse --short HEAD`, adding `--set back_to=<build|rethink>` when it is sent back. On sent-back, say what goes back:
    - A defect in code a task already built: `back_to=build`, then `cruze task reopen T<n> "<reason>"`.
    - A design that can't deliver the scenario: `back_to=rethink`. Leave the tasks to the rethink, which reopens the ones its amendment changes, and `cruze next` names `rethink` until it is recorded.
 
@@ -34,8 +34,8 @@ Done when the decision is recorded.
 ## Rules
 
 - A scenario the verifier couldn't run isn't passed. Mark it clearly in the report and in `manual-test.md`.
-- Findings from the review are dispositions in the journal, never edits to `change.md`.
-- Fixes made during verify are code commits that stay within the tasks' files. When a fix needs a new file or owner, it is a deviation or a rethink, exactly as in build.
+- Findings from the review are dispositions in the journal. They edit `change.md` only through a detail amendment.
+- Fixes made during verify are code commits that stay within the tasks' files. When a fix needs a new file or owner, or a detail, handle it exactly as build does.
 
 ## Next step
 

package/src/domain/journal.ts

@@ -24,14 +24,14 @@ const OPTIONAL_FIELDS: Record<string, string[]> = {
   rethink: ["missed_by"],
   review: ["nits", "checked_by"],
   disposition: ["decided"],
-  verification: ["back_to"],
+  verification: ["back_to", "commit"],
 };
 
 /** The workflow steps and checks that find or miss a problem, so a retro can count them. */
 export const STEPS = ["envision", "architect", "research", "design-review", "walkthrough", "plan", "plan-review", "build", "code-review", "verify", "land", "realign", "improve", "validate", "check", "user"];
 
 export const FIELD_VALUES: Record<string, string[]> = {
-  level: ["task", "change", "feature", "architecture", "vision"],
+  level: ["task", "detail", "change", "feature", "architecture", "vision"],
   kind: ["defect", "discovery"],
   disposition: ["fixed", "waived", "deferred", "rejected", "rethink"],
   decided: ["agent", "user"],
@@ -94,7 +94,7 @@ 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"])) {
+  if ((event === "checks" || event === "verification") && 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") {

package/src/domain/skill_budget.ts

@@ -11,7 +11,7 @@ export const MAX_FILE_WORDS = 2100;
  * 0.0.10 the skills grew by half while nothing was removed. Lower this when text is cut. Raising it
  * is the maintainer's decision, with the reason in the commit that raises it.
  */
-export const BUNDLE_WORD_BUDGET = 44500;
+export const BUNDLE_WORD_BUDGET = 45450;
 
 /** Data the CLI reads or renders, rather than instructions an agent reads. */
 const NOT_INSTRUCTIONS = /(^|\/)(templates|notes)\//;