@printpractical/cruze 0.0.7 → 0.0.9

package/skills/formats/reference/config.md

@@ -13,8 +13,8 @@ source: ["src/**/*.rs"]
 tests: ["src/**/*.rs", "tests/**/*.rs"]
 
 check:
-  max_lines: 250
-  max_types: 5
+  max_lines: 600
+  max_types: 12
   exceptions:
     - path: src/cli/args.rs
       reason: the clap derive struct lists every flag in one place
@@ -33,6 +33,13 @@ changes:
   min_builds: 3
   max_scenarios: 30
   max_tasks: 25
+  exceptions:
+    - item: 2026-09-25-open-console/02-ssh-hops
+      reason: every scenario runs through one reconcile, which can't be split without building it twice
+
+references:
+  - path: third_party/rfc4254.txt
+    use: the SSH connection protocol every hop speaks; channels and their failures must follow it
 
 layers:
   - name: inventory-domain
@@ -52,9 +59,10 @@ layers:
 | `tracker` | Where work items live. `markdown` is the only value in V1. |
 | `source` | Globs of the source files `cruze check` inspects. |
 | `tests` | Globs of the files `cruze trace` searches for scenario IDs. |
-| `check.max_lines` | Line budget per source file. Test files outside `source` have no budget. |
-| `check.max_types` | Budget of top-level types per source file. |
+| `check.max_lines` | Line budget per source file, a backstop against a file that has outgrown one responsibility. `cruze init` sets `600`. Test files outside `source` have no budget, and a Rust file's `#[cfg(test)]` modules don't count. |
+| `check.max_types` | Budget of top-level types per source file. `cruze init` sets `12`. |
 | `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. |
+| `references` | External documents the design must comply with, such as a protocol specification or a standard, each with its `path` in the repository and its `use`: what it governs. Optional. `cruze show` lists them, and architect, plan, build and the reviewers read the parts their scope relies on and cite them, such as `RFC 4254 §5.2`, in the design. |
 | `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`. 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. |
@@ -62,6 +70,7 @@ layers:
 | `changes.min_builds` | A feature's change that builds fewer elements than this gets a `change-too-small` warning: merge it into the change it continues. Default `3`. |
 | `changes.max_scenarios` | A change that delivers more scenarios than this gets a `change-too-large` warning: split it. Default `30`. |
 | `changes.max_tasks` | A plan with more tasks than this gets a `plan-too-large` warning. Default `25`. |
+| `changes.exceptions` | Features and changes the user accepted outside the band, each with the `item` (a feature's ID, `<feature>/<change>`, or a standalone change's ID) and the `reason`. The item's size warning stops. `cruze approve` refuses an item whose size warning still stands (`size-unaccepted`) until it is listed here or split. |
 
 Rules for layers:
 

package/skills/formats/reference/specs.md

@@ -60,6 +60,6 @@ The full new requirement text.
 
 - `ADDED CAPABILITY` creates a new spec file, with its title and purpose paragraph. It is only needed for a capability that has no file yet.
 - `ADDED` introduces a new requirement with all its scenarios.
-- `MODIFIED` replaces a requirement's whole block, including every scenario it keeps. A scenario left out is removed.
+- `MODIFIED` replaces a requirement's whole block, including every scenario it keeps. A scenario left out is removed, so no part of the work may cite it by ID (`cites-dropped`); describe it in words.
 - `REMOVED` retires a requirement and its scenarios, and needs a `Reason` and a `Migration`.
 - `land` shifts heading levels to fit the spec file and keeps the managed status of scenarios that were already built.

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

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

package/skills/grilling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cruze-grilling
-description: How to interview the user until design decisions are settled. Questions go in rounds over a tree of decisions, facts are looked up rather than asked, each question carries a recommendation, and challenges the user overrides are recorded. Use when a design step needs decisions from the user, when shaping an idea, vision, feature, architecture or plan with them, when the user steers toward something that breaks a rule, or when the user asks to be grilled or to stress-test a plan.
+description: How to interview the user until design decisions are settled. Questions go in rounds over a tree of decisions, facts are looked up rather than asked, each question carries a recommendation and shows what each option looks like, and challenges the user overrides are recorded. Use when a design step needs decisions from the user, when shaping an idea, vision, feature, architecture or plan with them, when the user steers toward something that breaks a rule, or when the user asks to be grilled or to stress-test a plan, and when showing the user review findings or a design to decide on.
 ---
 
 # Grilling
@@ -12,25 +12,37 @@ Interview the user until you both understand the design the same way. Decisions
 1. List the open decisions this step must settle, as a tree in which each decision hangs off the ones it depends on. Take them from the sections of the document the step writes and from what the user has already said. Done when every section the step writes has its decisions listed.
 2. Settle the facts yourself. Anything the repository, the living docs, a `cruze` command or a primary source can answer is a fact, so look it up rather than asking. Where the agent can run a helper in parallel, send it to look while you ask about everything that doesn't depend on the answer.
 3. Find the frontier: every open decision whose prerequisites are settled. A question that depends on another open question waits for a later round.
-4. Ask the frontier as one round, in the format below. Every question carries your recommended answer and the reason for it.
+4. Ask the frontier as one round, in the format below. Every question shows what each option looks like and carries your recommended answer and the reason for it. Read [illustrating.md](illustrating.md) before the first round.
 5. Wait for the answers. Record each settled decision as described under Recording, then recompute the frontier.
 6. Repeat until the frontier is empty: every branch visited, and nothing silently assumed.
-7. Write the sections the step produces from the settled decisions, then summarize them and ask the user to confirm that they match their understanding. Done when the user confirms. Decisions and glossary terms are recorded as they settle, and nothing is approved before the confirmation.
+7. Write the sections the step produces from the settled decisions, then summarize them, illustrated as [illustrating.md](illustrating.md) says, and ask the user to confirm that they match their understanding. Done when the user confirms. Decisions and glossary terms are recorded as they settle, and nothing is approved before the confirmation.
 
 ## A round
 
-```markdown
+````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).
+
 **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.
+
+```yaml
+# A: per device                    # B: named hosts (recommended)
+devices:                           jump_hosts:
+  core-sw-01:                        lab-gw: { address: 10.0.0.5 }
+    jump: { address: 10.0.0.5 }    devices:
+  core-sw-02:                        core-sw-01: { jump: lab-gw }
+    jump: { address: 10.0.0.5 }      core-sw-02: { jump: lab-gw }
+```
+
 Recommended: named hosts, because the lab config already shares two jump hosts across 30 devices.
 
 **Q5. What a refused second hop reports**
 ...
-```
+````
 
 - Number questions across the whole session, not per round, so an answer such as "Q7: yes" is never ambiguous.
-- Keep a round to what the user can answer in one reply, about 3 to 7 questions. When the frontier is bigger, ask first the questions that others depend on.
-- Ask about behaviour and trade-offs in the user's terms and the glossary's words, not about implementation mechanics.
+- Keep a round to what the user can answer in one reply, about 3 to 5 questions. When the frontier is bigger, ask first the questions that others depend on.
+- 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.
 

package/skills/grilling/illustrating.md

@@ -0,0 +1,37 @@
+# Illustrating a question
+
+The user decides from what they can picture. A question about a port's errors or a module's place is hard to answer from words alone, and the user is often coming back from other work. So every question, review exception and confirmation shows what each option looks like, and reads on its own without the conversation before it.
+
+## 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)`.
+- Each question says what it decides and why it matters now, without pointing back to an earlier message.
+
+## Choosing the illustration
+
+Show each option, side by side, with the form that fits what the question decides:
+
+| The question decides | Show |
+| --- | --- |
+| What a user does or sees | The command they type and its exact output, or a plain-text sketch of the screen, using the scenario's concrete values |
+| A port, a use case's input and errors, or a public API | A code sketch in the project's language: the types and signatures, and the call a caller writes |
+| Where something lives: contexts, modules, dependency direction | A box-and-arrow diagram, or the directory tree with the files the option adds |
+| An order of steps, or what happens on failure | A numbered sequence or a plain-text sequence diagram, with the failure branch |
+| States and what moves between them | The states with their transitions, one per line |
+| 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.
+
+## Writing it
+
+- Use the design's names and the glossary's words, and the values of a real scenario, so the user sees this project's code, not a generic example.
+- A code sketch shows shape: types, signatures, the error variants, and one call site. Leave bodies out, writing `...` or the language's placeholder. Keep each option to about 15 lines.
+- Draw diagrams in plain text, so they read in a terminal, where Mermaid shows only as source. The documents keep their Mermaid diagrams; the illustration is for the conversation.
+- At envision, show behaviour only: interactions and screens, never code, since envision keeps implementation out.
+- Mark your recommended option in the illustration itself, and show the failure case when the options differ in how they fail.
+
+## After the answer
+
+A shape the user chose from a sketch is part of the decision. Write it into the document in that document's format: the port's `Operations`, the entity's facts, the module's `Path`, or the scenario's values. Build follows the documents, so the code comes out as the user saw it.

package/skills/hexagonal-design/SKILL.md

@@ -89,7 +89,8 @@ Layers are dependency boundaries, not runtime hops. A port can be a plain functi
 ## Many small modules
 
 - Give each responsibility its own module, grouped by domain concept, with the hexagonal roles inside. A context's core is usually one module, with each port beside the use cases that define it, and grows submodules by concept, not by layer. A file may hold a few closely related types.
-- When a file passes its budget (`check:` in `.cruze/config.yaml`, enforced by `cruze check`) or gains a second responsibility, split it into a submodule named for what it owns.
+- When a file gains a second responsibility, split it into a submodule named for what it owns. Never split a file by length: one that grows with its one responsibility stays whole.
+- The budgets (`check:` in `.cruze/config.yaml`, enforced by `cruze check`) are a backstop against a file that has outgrown one responsibility, never a shape to write code to. Write the code as you would with no budget: no type alias, string where an error type belongs, merged types or function moved away from its owner to stay under a limit. When a file over budget holds one responsibility, such as the related types of one grammar, list it under `check.exceptions` with that reason.
 - Entry-point and namespace files, such as `main`, `lib.rs`, `mod.rs` and `index.ts`, hold only wiring and declarations.
 - Don't create generic modules such as `utils`, `helpers`, `common`, `services`, `models`, `types` or `manager`. Shared behaviour belongs with the concept that owns it.
 - Duplication is semantic. Two implementations of one rule are duplication even when the text differs, so consolidate them in the owner, not in a helper.

package/skills/hexagonal-design/languages/rust.md

@@ -40,6 +40,7 @@ These add to the hexagonal design rules for Rust projects. The module map decide
 - No `unsafe` unless the user approves it or an unavoidable low-level boundary needs it, with a `// SAFETY:` comment giving the reason.
 - Format with `cargo fmt`, lint with `cargo clippy -- -D warnings`, and test with `cargo test`.
 - Behaviour, contract and smoke tests live in the crate's `tests/` directory and reach the code through the library's public API. Domain tests sit in a `#[cfg(test)] mod tests` beside the code and need no fakes.
-- When a module's inline tests would take its file past the budget, move them to the crate's `tests/`, named for the module: `tests/<module>.rs`, or `tests/<module>/main.rs` declaring one file per topic, such as `tests/generation/add_generation.rs`. Cargo builds each `tests/*.rs` and each `tests/*/main.rs` as a test binary, and nothing deeper. Never move them to `src/<module>/tests.rs` or `src/<module>/tests/`: `cruze check` reports those as `test-placement`. A test that needs a private item is testing structure, so drive the public API instead. When a private seam really is the contract, such as a filesystem trait a crash test injects, list the file under `check.exceptions` with that reason.
+- `cruze check` leaves a file's `#[cfg(test)]` modules out of its budgets, so domain tests stay inline however long they grow. Never move them to `src/<module>/tests.rs` or `src/<module>/tests/`: `cruze check` reports those as `test-placement`.
+- Name test files in `tests/` for what they cover: `tests/<module>.rs`, or `tests/<module>/main.rs` declaring one file per topic, such as `tests/generation/add_generation.rs`. Cargo builds each `tests/*.rs` and each `tests/*/main.rs` as a test binary, and nothing deeper.
 - Group integration tests into a few binaries by area, `tests/<area>/main.rs` with one module per topic, since every binary links the crate again.
 - Share fakes, fixtures and harnesses within a crate through `tests/support/mod.rs`, which each test binary declares with `mod support;`. In a workspace, put what several crates' tests share in one dev-only crate, such as `<project>-test-support`, listed under `[dev-dependencies]`. Never share them with `#[path]` includes.

package/skills/improve/SKILL.md

@@ -22,14 +22,14 @@ Realign is different. It applies what each release's notes expect of existing co
 5. **List the candidates** in one message, numbered, merging candidates that share a cause across modules. For each, give:
    - the problem in one sentence, and its evidence;
    - the standard it departs from, or the friction it causes;
-   - the target shape;
+   - the target shape, sketched beside today's as `.agents/skills/cruze-grilling/illustrating.md` says;
    - its size in prefactor changes, and its risk.
 
    Recommend which to take and why, then ask the user to pick any or all of them.
 6. **Record each decision:** `cruze journal add disposition --set review=improve --set finding="<module or area>: <summary>" --set disposition=<fixed|waived|deferred> --set reason="<reason>" --set decided=user`. A picked candidate is `fixed`. The rest are `waived`, with the user's reason, or `deferred`. A recorded waiver is never raised again.
 7. **Design the target** for every picked candidate together, as a rethink at architecture level, following `.agents/skills/cruze-rethink/SKILL.md` with `kind=discovery` and `found_by=improve`:
    - Amend `docs/architecture.md`: the module map and layers, the moved elements' `Module` and `File` facts, the `layers:` in `.cruze/config.yaml`, and a `D<n>` or an ADR for each structural decision. Change no requirement, scenario or port contract unless the user decided that in step 5.
-   - When a candidate changes an interface, such as a port or a module's public API, sketch two or three shapes, compare them, and recommend one before writing it.
+   - When a candidate changes an interface, such as a port or a module's public API, sketch two or three shapes as code, compare them, and recommend one before writing it.
    - Before the rethink's walkthrough, run the design review from the roles skill on the diff, with `review=design`.
    - Approve it as the rethink's architecture level says, with `--replan` for each built element that moves.
 8. **Schedule the moves.** Group the replanned elements into prefactor changes, as "A prefactor" in `.agents/skills/cruze-architect/tweak.md` describes, each sized as step 12 of `.agents/skills/cruze-architect/feature.md` says.
@@ -48,4 +48,4 @@ Done when every candidate has a journaled disposition, the target architecture i
 
 ## Next step
 
-`plan` for the first prefactor change. When the user picked nothing, `next`.
+`plan` for the first prefactor change. When the user picked nothing, `next`. Start it in a new session, so its context starts empty.

package/skills/land/SKILL.md

@@ -24,7 +24,7 @@ Land makes finished work part of the living model. `cruze land` merges the chang
    - A `merge-invalid` means the merged docs, or the feature and changes being landed, wouldn't validate, such as a decision citing an ID the change removes. Nothing was written. Stop and run `rethink`.
 5. **Update the changelog.** Under `## [Unreleased]` in `CHANGELOG.md`, add one line per user-visible behaviour the change delivers, in the user's words, under `### Added`, `### Changed` or `### Removed`. Name the behaviour, not the code, including any rule a user can now run into that no scenario covers yet.
 6. **Update the README** when the change altered how someone installs, runs or uses the product. Run every command you add, to check it works.
-7. **Check the pitfalls.** Run `cruze journal list --event disposition`, `cruze journal list --event rethink` and `cruze journal list --event bug`. When findings under the same rubric item with the same root cause, or two defects with the same cause, have now happened twice, add one line under `## Known pitfalls` in `AGENTS.md` saying what to do instead. Keep `AGENTS.md` under one page. When the pitfalls outgrow it, propose to the user a `cruze check` rule or a knowledge-skill change for the oldest ones.
+7. **Check the pitfalls.** Run `cruze journal list --event disposition --all --text | grep -i "<rubric item>"` for each rubric item this change's findings named, and `cruze journal list --event rethink --all` and `cruze journal list --event bug --all`; `--all` includes landed work, which the default leaves out. When findings under the same rubric item with the same root cause, or two defects with the same cause, have now happened twice, add one line under `## Known pitfalls` in `AGENTS.md` saying what to do instead. Keep `AGENTS.md` under one page. When the pitfalls outgrow it, propose to the user a `cruze check` rule or a knowledge-skill change for the oldest ones.
 8. **Commit** the land with a message such as `docs: land <change>`. `cruze land` keeps the Commands and Layout sections of `AGENTS.md` current, from `commands:` in `.cruze/config.yaml` and the built modules; when `commands:` is empty, the Commands section stays as it was.
 9. **Get it onto main.** Follow the project's convention in `AGENTS.md`. When it has none, ask the user whether they want pull requests or direct merges, and add their answer under `## Conventions`, such as "Changes land through pull requests." Open the pull request, or merge. CI must pass before the merge; when the project has no CI runner, run its steps locally with the project's commands.
 
@@ -41,4 +41,4 @@ A fix from `triage` has no change folder, so `cruze land` doesn't run.
 
 ## Next step
 
-Once the work is on main, switch to an up-to-date main, run `cruze next` there, and name what it says. Before the merge, `cruze next` on the change's branch can name work that main doesn't hold yet. When a feature just finished and every roadmap item has landed, the next step is `roadmap`, to close the release.
+Once the work is on main, switch to an up-to-date main, run `cruze next` there, and name what it says. Start it in a new session, so its context starts empty. Before the merge, `cruze next` on the change's branch can name work that main doesn't hold yet. When a feature just finished and every roadmap item has landed, the next step is `roadmap`, to close the release.

package/skills/next/SKILL.md

@@ -11,7 +11,7 @@ Next reads the project's state and says what to do now. The CLI works it out fro
 
 1. **Ask the CLI.** Run `cruze next` and read its JSON: the step, what it works on, the reason, and any other work that could proceed.
 2. **Add the detail.** Run `cruze status` when the reason mentions approvals, and quote the documents and elements that changed.
-3. **Answer** in three lines or fewer: the step to run, with its target, why it is next, and what else is in flight on other branches. Don't start the step unless the user asks you to.
+3. **Answer** in three lines or fewer: the step to run, with its target, why it is next, and what else is in flight on other branches. Say that the step runs in a new session, so its context starts empty. Don't start the step unless the user asks you to.
 
 ## What the steps mean
 

package/skills/plan/SKILL.md

@@ -19,14 +19,14 @@ Plan turns one designed change into work an implementer can do without guessing:
    - `.agents/skills/cruze-behavioural-testing/SKILL.md`
    - `.agents/skills/cruze-hexagonal-design/SKILL.md`, and its language file when one exists for the project's language
    - `.agents/skills/cruze-formats/reference/work-items.md`
-6. **Read the design it builds.** Read the full body of every element in the scope, from the feature's delta or `docs/architecture.md`, and every scenario it delivers.
+6. **Read the design it builds.** Run `cruze show <ref>` and read its output: the full body of every element in the scope, every scenario it delivers, the settled decisions, the ledger and the references. Read an element it lists as cited only when a task will call it, from the place it names. Don't read `docs/architecture.md` or `feature.md` whole: two projects read a 40k-word architecture about 150 times each.
 7. **Check for overlap.** Run `cruze status --overlap --change <ref>`. For each change on another branch that touches the same elements, tell the user which elements are shared and which change should land first. Record the answer under `## Risks`.
 8. **Write the test plan.** Follow [test-plan.md](test-plan.md). Done when every delivered scenario has a `behaviour` row and every port a built adapter implements has a `contract` row.
 9. **Write the tasks.** Follow [tasks.md](tasks.md). Done when every scope ID is proved by a task and every task line matches the grammar.
 10. **Record decisions and risks.** Put task-level choices you made under `## Settled decisions`. Under `## Risks`, name the riskiest task and how its test catches the failure. Remove every template guide.
 11. **Validate.** Run `cruze validate`. Done when it reports no errors for the change.
 12. **Review the plan.** Commit the plan, then run the review in `.agents/skills/cruze-roles/SKILL.md` with the design reviewer and its plan rubric, `review=plan`, and `--item <ref>`.
-13. **Approve.** Run `cruze approve <ref> --by-agent` on this branch and quote its result. The plan carries no design of its own, so once its review has closed, with no blocker open and a disposition for every finding, you approve it for the user. The approval binds the change to the branch. When it refuses with `plan-review-open`, do what it names. A blocker still open after round 2 goes to the user, and once they decide it, they approve the plan themselves with `cruze approve <ref>`.
+13. **Approve.** For a feature's change, run `cruze approve <ref> --by-agent` on this branch and quote its result. The plan carries no design of its own, so once its review has closed, with no blocker open and a disposition for every finding, you approve it for the user. A standalone change, such as the walking skeleton or a prefactor, carries its own design, so show the user the plan and ask them to approve it with `cruze approve <ref>`. The approval binds the change to the branch. When it refuses with `plan-review-open`, do what it names. When it refuses with `size-unaccepted`, the plan has more tasks than `changes.max_tasks`: split the change through `rethink` at feature level, or, when the user accepts the size, list the change under `changes.exceptions` in `.cruze/config.yaml` with their reason and approve again. A blocker still open after round 2 goes to the user, and once they decide it, they approve the plan themselves with `cruze approve <ref>`.
 14. **Commit** with a message such as `docs: plan <change>`.
 
 ## When the plan needs design
@@ -49,4 +49,4 @@ The walking-skeleton change also makes CI and the project's tooling real. Its pl
 
 ## Next step
 
-Show the user the test plan table, the tasks in order and the risks, and say the plan is approved. They can object, and you amend the plan, run its review on the diff, and approve again. Otherwise the next step is `build`, on this branch.
+Show the user the test plan table, the tasks in order and the risks, and say the plan is approved, or, for a standalone change, ask them to approve it. They can object, and you amend the plan, run its review on the diff, and approve again. Otherwise the next step is `build`, on this branch, in a new session so its context starts empty.

package/skills/plan/tasks.md

@@ -9,8 +9,10 @@ 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".
+   - Put each test in the task that builds the behaviour it checks. When an earlier task's code would already pass a later task's test, such as a failure path the earlier task had to handle, move the test into the earlier task.
+   - 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, as the wrong behaviour rather than an edit to the code, such as "fails against a model that always shows the prompt". Build may use any break that compiles and turns the same assertion red.
    - 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.
+   - An accessor, variant or type arrives in the task whose code first handles, matches or constructs it, never in the task that only tests it. When a later task's `match` would pull in a variant, the variant belongs to that task. Two projects built 13 items in a task other than the planned one.
 3. **Write one line per task:**
 
    ```markdown
@@ -19,13 +21,15 @@ A task is one owner, the files it writes, and the IDs it proves. Build does them
    ```
 
    - 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.
+   - When a task adds a module, a file or a dependency, list the file that declares it, such as the crate root or `mod.rs`, the package manifest, or the Xcode project.
    - 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.
-5. **Size each task.** A task writes one owner, with its tests, in one sitting. When an owner would take several steps, such as a use case with many scenarios, split it into tasks that each prove a subset of the scenarios.
-   - Run `cruze check` on each existing file a task extends. When the task would take the file past `check.max_lines` or `check.max_types`, name the new file in the task, split along a responsibility the owner already has.
+4. **Find the owners.** For each rule, text, format or conversion a task's element applies, such as a message, a path format, a rounding or a name check, search the code and the other tasks for every place that applies it. Give it one owner: when an earlier task's owner already holds it, the later task's line names that file as a callee rather than building the rule again. Done when no rule is written in two places. Two projects wrote 20 rules twice and moved them at code review.
+5. **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.
+6. **Size each task.** A task writes one owner, with its tests, in one sitting. When an owner would take several steps, such as a use case with many scenarios, split it into tasks that each prove a subset of the scenarios.
+   - When a task would give an existing file a second responsibility, name the new file in the task, named for what it owns. Never plan a split by line or type count: a file that grows with its one responsibility stays whole, and when it passes a budget, build lists it under `check.exceptions` as the budget rule in `.agents/skills/cruze-hexagonal-design/SKILL.md` says.
    - The budgets apply to source files, not tests. Split a test file by the behaviour it covers, one use case or port per file, never to meet a budget. Tests that leave a source file go where the hexagonal-design language file you loaded says.
-6. **Check coverage.**
+7. **Check coverage.**
    - Every `Builds` ID is proved by a task, except a module, which is proved by any task that writes inside its `Path`.
    - Every delivered scenario is proved by at least one task.
    - Done when `cruze validate` reports no `unproved-scope`, `task-format` or `outside-module-map` problems. An `outside-module-map` warning means a task writes a file no module's `Path` covers: add the file to the owning module's `Path` through `rethink`, or move it.

package/skills/realign/SKILL.md

@@ -15,7 +15,7 @@ Each Cruze release can expect more of a project's code and documents than the la
    - `.agents/skills/cruze-hexagonal-design/SKILL.md`, and its language file when one exists for the project's language
    - `.agents/skills/cruze-behavioural-testing/SKILL.md`
    - `.agents/skills/cruze-formats/reference/architecture.md`
-4. **Audit.** Run the auditor role from `.agents/skills/cruze-roles/SKILL.md` on every note with an `Ask`. In a full audit, give it the standards instead, and run one auditor per module in the module map. Check its evidence against the files. Done when every note with an `Ask` has an answer with evidence, and every note with a `Detect` has its findings from the status report.
+4. **Audit.** Run the auditor role from `.agents/skills/cruze-roles/SKILL.md` on every note with an `Ask`. A note whose `Rule` is an item of the design reviewer's rubric is about designs, not code: run the design reviewer instead, on each feature in flight, with that item only, since those designs were reviewed before the item existed. In a full audit, give it the standards instead, and run one auditor per module in the module map. Check its evidence against the files. Done when every note with an `Ask` has an answer with evidence, and every note with a `Detect` has its findings from the status report.
 5. **Decide each finding** with the user, a group at a time, with your recommendation:
    - `fixed`: a prefactor change will fix it.
    - `waived`: the project keeps its own convention, with the reason. For a `check:` finding, list the file under `check.exceptions` with that reason, which keeps CI green. For the rest, the journal holds the waiver.
@@ -32,4 +32,4 @@ Done when `cruze realign status` reports the code meeting the installed version,
 
 ## Next step
 
-`plan` for the first prefactor change. When nothing needed fixing, `next`.
+`plan` for the first prefactor change. When nothing needed fixing, `next`. Start it in a new session, so its context starts empty.

package/skills/realign/notes/0.0.8.md

@@ -0,0 +1,97 @@
+# Realign notes: 0.0.8
+
+## Existing code
+
+### module-path-glob: A module's Path is a directory or a file, never a glob
+- Applies to: existing code
+- Rule: `.agents/skills/cruze-formats/reference/architecture.md`, "Element facts"
+- Detect: validate:module-path-glob
+- Migrate: replace each glob in a `MOD` element's `Path` with the directories it meant, each ending in `/`, or the files, through `rethink` at architecture level.
+
+### budget-not-a-shape: No code is bent to fit a file budget
+- Applies to: existing code
+- Rule: `.agents/skills/cruze-hexagonal-design/SKILL.md`, "Many small modules"
+- Ask: is any code shaped to stay under `check.max_lines` or `check.max_types`, such as a type alias, a string where an error type belongs, merged types, a function placed away from its owner, or Rust domain tests moved out of their file only for its length?
+- Migrate: write the code as it would be with no budget. Split a file that then passes its budget along a second responsibility, or list it under `check.exceptions` with the reason it has one. Rust domain tests may move back inline, since their `#[cfg(test)]` modules no longer count.
+
+### no-dependency-workarounds: No code works around a dependency or feature nobody asked for
+- Applies to: existing code
+- Rule: `.agents/skills/cruze-dependency-approval/SKILL.md`, "Weighing"
+- Ask: does any code hand-write, shell out for, or use a less idiomatic construct for something a dependency or a feature of an approved dependency does cleanly, where the design or a deviation gives avoiding the dependency as the reason?
+- Migrate: ask the user for the dependency as the dependency-approval skill says, then replace the workaround through `rethink`: at architecture level when the workaround is in an `XC` rule or an import allowlist, at feature level otherwise.
+
+### size-exceptions: An accepted size warning is recorded under changes.exceptions
+- Applies to: existing code
+- Rule: `.agents/skills/cruze-formats/reference/config.md`, "changes.exceptions"
+- Ask: does `cruze validate` report a `change-too-small`, `change-too-large`, `plan-too-large` or `feature-size` warning that a `D<n>` line records the user accepting? `cruze approve` now refuses the item until it is listed.
+- Migrate: list each such feature or change under `changes.exceptions` in `.cruze/config.yaml`, as its ref and the decision's reason.
+
+## New work only
+
+### fresh-session: Every step runs in a new session
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-next/SKILL.md`, "Steps", step 3
+
+### show-scope: Plan, build and the roles read the scope through cruze show
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-plan/SKILL.md`, "Steps", step 6
+
+### scoped-ledger: The settled ledger is the item's, and journal list leaves landed work out
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/SKILL.md`, "The settled ledger"
+
+### round-2-by-agent: Round 2 is checked by the agent
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/SKILL.md`, "Round 2"
+
+### verifier-front-doors: The verifier drives the scenarios that have a front door and never idles
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/verifier.md`, "Work", step 3
+
+### design-gives-every-value: The design gives every error, limit, timeout, transition and message owner
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/design-reviewer.md`, "Rubric", item 6
+
+### one-owner-per-rule: Plan gives each rule one owner, and each item to its first handler's task
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-plan/tasks.md`, steps 2 and 4
+
+### deviations-reviewed: The code reviewer reports a deviation that needed a rethink
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/code-reviewer.md`, "Rubric", item 11
+
+### depends-on-gate: Building waits for every change a change depends on to land
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-build/SKILL.md`, "Steps", step 1
+
+### build-checks-ci: Build runs the same check as verify and CI
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-build/SKILL.md`, "The task loop", step 4
+
+### check-in-flight-modules: cruze check knows the modules that work in progress adds
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-build/SKILL.md`, "The task loop", step 4
+
+### cites-dropped: Work doesn't cite a scenario its delta drops
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-formats/reference/specs.md`, "Spec delta"
+
+### planned-breaks: Plans name a break as the wrong behaviour, and put each test in the task that builds what it checks
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-plan/tasks.md`, step 2
+
+### declaring-files: A task lists the file that declares what it adds
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-plan/tasks.md`, step 3
+
+### named-dependencies: Every outside name the design uses comes from a dependency the using target declares
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-research/SKILL.md`, "Adopt or build", step 7
+
+### nits-are-counts: Review nits get no disposition
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/SKILL.md`, "Running a review"
+
+### illustrated-questions: Questions, review exceptions and the walkthrough show what each option looks like
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-grilling/illustrating.md`

package/skills/realign/notes/0.0.9.md

@@ -0,0 +1,59 @@
+# Realign notes: 0.0.9
+
+## Existing code
+
+### budget-backstop: File budgets are a backstop, and files split by responsibility, never by length
+- Applies to: existing code
+- Rule: `.agents/skills/cruze-hexagonal-design/SKILL.md`, "Many small modules"
+- Ask: does `.cruze/config.yaml` still set the old defaults, `check.max_lines: 250` and `check.max_types: 5`? Is any `check.exceptions` entry, or any split of one owner across files, there only to meet them?
+- Migrate: raise the budgets to `max_lines: 600` and `max_types: 12`, unless the user chose the old ones, and remove each exception whose file is now within budget. A split made only for length, whose files share one responsibility, merges back in a prefactor; waive it when the files read well apart.
+
+### flow-control-review: A design says how its work flows, waits and recovers
+- Applies to: existing code
+- Rule: `.agents/skills/cruze-roles/design-reviewer.md`, "Rubric", item 11
+- Ask: for each feature in flight, does its design leave out any check in rubric item 11 that a scenario or an `XC` rule depends on, such as what a sender does when a queue is full, or what happens when a reconnect fails?
+- Migrate: settle each gap through `rethink` at feature level before the feature's next change is planned. Code a landed change built goes to a prefactor.
+
+### references: External specifications the design must follow are listed under references
+- Applies to: existing code
+- Rule: `.agents/skills/cruze-formats/reference/config.md`, "references"
+- Ask: does the project rely on an external document it must comply with, such as a protocol specification in the repository, that `references:` in `.cruze/config.yaml` doesn't list?
+- Migrate: list each under `references:` with its path and what it governs, as the user confirms.
+
+## New work only
+
+### plan-splits-by-responsibility: Plan splits a file for a second responsibility, never for its length
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-plan/tasks.md`, step 6
+
+### name-clash-review: The design reviewer checks new names against the ones a caller already reaches
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/design-reviewer.md`, "Rubric", item 8
+
+### architecture-rethink-review: An architecture rethink that changes a contract gets a design review of the diff
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-rethink/levels.md`, "Architecture", step 2
+
+### missed-by-design-review: A gap the design review's rubric covers is missed by design-review
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-rethink/SKILL.md`, "Steps", step 7
+
+### sent-back-to: A sent-back verification says whether the change goes back to build or to rethink
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-verify/SKILL.md`, "Steps", step 10
+
+### standalone-plan-approval: The user approves the plan of a standalone change
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-plan/SKILL.md`, "Steps", step 13
+
+### deviation-read-back: Build reads a deviation back, and one that names a value the design didn't give is a rethink
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-build/SKILL.md`, "Deviations"
+
+### prefactor-verify: The verifier runs no suite again for a change that delivers no scenarios
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/verifier.md`, "Work", step 3
+
+### design-on-main: The approved design reaches main before plan branches from it
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-architect/SKILL.md`, "Next step"

package/skills/realign/notes.md

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

package/skills/research/SKILL.md

@@ -14,11 +14,12 @@ Run these steps for each component in a design that isn't domain logic. Domain l
 1. State the capability in one line, with the requirements that matter: platforms, performance, footprint, and license limits from the vision's constraints.
 2. Look in order: the language's standard library, the project's already-approved dependencies, then mature libraries in the ecosystem. Done when you have checked all three.
 3. For the two or three serious candidates, gather the evidence in [evaluation.md](evaluation.md).
-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.
+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. Weigh the candidates as `.agents/skills/cruze-dependency-approval/SKILL.md` says under Weighing, where avoiding a dependency is never a reason.
 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 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;
+   - each type, trait, macro or API the design names from a package: that the package exports it at that version, and every crate, package or target that must declare the package to use it, test support included;
    - 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.

package/skills/rethink/SKILL.md

@@ -32,7 +32,7 @@ Finding a design flaw mid-build is information, not failure. Rethink amends the
      --set agent="<the agent you run in>" [--item <ref>]
    ```
 
-   `found_by` is the step that found it. A defect also needs `missed_by`, the earliest step whose job was to catch it. Both take one of `envision`, `architect`, `research`, `design-review`, `walkthrough`, `plan`, `plan-review`, `build`, `code-review`, `verify`, `land`, `improve`, `validate`, `check` or `user`.
+   `found_by` is the step that found it. A defect also needs `missed_by`, the earliest step whose job was to catch it. Both take one of `envision`, `architect`, `research`, `design-review`, `walkthrough`, `plan`, `plan-review`, `build`, `code-review`, `verify`, `land`, `realign`, `improve`, `validate`, `check` or `user`. When a design review ran over the element and an item of its rubric in `.agents/skills/cruze-roles/design-reviewer.md` covers the gap, `missed_by` is `design-review`, not `architect`: a retro reads it to know which rubric to fix.
 
 Done when `cruze status` shows every document approved and current, or names only work the user chose to leave for later.
 
@@ -43,7 +43,7 @@ Done when `cruze status` shows every document approved and current, or names onl
 | 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 |
 | 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 | Walkthrough of the diff only, then `cruze approve architecture`, with `--replan` for built elements whose code must change |
+| 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 |
 | Vision | The release's scope was wrong, or a new goal appears | `docs/vision.md`, and `docs/roadmap.md` | Re-approve the vision and the roadmap. Decide what happens to features that served a dropped goal |
 
 ## After landing
@@ -56,4 +56,4 @@ Landed work is history, so rethink never edits an archived folder.
 
 ## Next step
 
-Run `cruze next`, and name what it says.
+Run `cruze next`, and name what it says. Start it in a new session, so its context starts empty.

package/skills/rethink/levels.md

@@ -18,8 +18,8 @@
 ## Architecture
 
 1. Edit `docs/architecture.md` directly. Keep every element's ID, and write complete bodies. Write an ADR with `cruze new adr` when the decision passes the ADR test, and link it under `## Decisions`.
-2. Run `cruze validate`, then run the walkthrough of the diff only, following `.agents/skills/cruze-architect/walkthrough.md`.
-3. List the elements you changed that are already `built`, whose code must now change. When the user approves, run `cruze approve architecture`, adding `--replan <ID>` for each of them. They go back to `planned` until a change rebuilds them.
+2. Run `cruze validate`. When the amendment adds, renames or changes an operation, a port, a use case's `Errors` or an `XC` rule, run the review in `.agents/skills/cruze-roles/SKILL.md` on the diff with the design reviewer, `review=design`: a realign amendment once named a method that clashed with one the type already had, found only at plan. Then run the walkthrough of the diff only, following `.agents/skills/cruze-architect/walkthrough.md`.
+3. List the elements you changed that are already `built`, whose code must now change. When the user approves, run `cruze approve architecture`, adding `--replan <ID>` for each of them. They go back to `planned` until a change rebuilds them, and only a land sets them back to `built`. A `- Status:` line belongs to the CLI: when an element was replanned by mistake, tell the user, and let the change rebuild or re-check it.
 4. Commit the amendment, and get it onto main on its own, as a pull request or a merge. Every branch and every later change must build on it. Then merge main into the branch you were working on.
 5. Hand each replanned element to a change that rebuilds it:
    - **The current change**, when the rebuild belongs to its work. Add the element to the feature's Changes row for that change and to the change's `Builds`, then re-plan and re-approve the change.

package/skills/roadmap/SKILL.md

@@ -49,3 +49,5 @@ Name the first item whose blockers have all landed:
 - A feature whose requirements are settled: `architect "<feature>"`.
 - A standalone change whose design exists: `plan`.
 - A tweak without a design yet: `architect "<tweak>"`.
+
+Start it in a new session, so its context starts empty.