@printpractical/cruze 0.0.6 → 0.0.8

package/skills/hexagonal-design/shapes.md

@@ -0,0 +1,49 @@
+# Shapes by kind of system
+
+Start from the layout that is normal for the kind of system and its language, then place each owner in it. The hexagonal rules decide what depends on what. They don't decide the folders: a reader who knows the ecosystem should find the code where they expect it.
+
+Name the kind in the architecture's Overview. A system can be more than one kind, such as a daemon that ships a client library and a CLI. Each is then its own deliverable, with its own entry point, and in a language with packages, its own package.
+
+## Library
+
+A crate, package or SDK that other code calls.
+
+- The public API is the inbound adapter. Callers drive the use cases through it, so keep it small and treat it as a contract: read [contracts.md](contracts.md).
+- A pure library, with no I/O, has a core only: no ports and no application layer.
+- A client library that talks to a server keeps the transport and the wire format behind driven ports, so its tests run against a fake server. Group its modules by what callers do with it, such as `connection`, `consumer` and `provider`, with the wire format and the transport as adapters.
+
+## Daemon or service
+
+A process that runs until it is stopped, serving requests or reconciling state.
+
+- `main` is the composition root and stays thin: configuration, construction, signals and shutdown.
+- One inbound adapter per interface it offers, such as HTTP, IPC, a message consumer or a signal handler. Each decodes, calls one use case and encodes.
+- One outbound adapter per technology it uses, such as storage, the OS, a subprocess or another service.
+- Each context's core is one module, by concept. Long-lived tasks and their shutdown follow [runtime.md](runtime.md).
+
+## Mobile or desktop app
+
+An app with screens, on a platform that hosts it.
+
+- Group modules by feature, such as `Offices` or `Dashboard`, each with its core and its screens.
+- A screen's view and its model form the inbound adapter: the model maps what the person does to use cases, and use-case results to what the view shows. Neither holds a domain rule.
+- Platform frameworks, such as location, notifications, maps and storage, are outbound adapters behind ports named for the capability, such as `ZoneMonitor` rather than `CoreLocationClient`.
+- The app's entry point is the composition root.
+- Most tests drive the core and the screen models with fakes. UI tests prove only what needs the screen itself, one or two per flow, because they are the slowest tests the project has.
+
+## CLI tool
+
+A program a person or a script runs and that exits.
+
+- The commands are the inbound adapter, one module per command or command group. Argument parsing and output formatting stay there, and each command calls one use case.
+- The filesystem, the network, the terminal and the clock are outbound adapters behind ports, like any other technology, so tests run the commands against fakes.
+
+## Splitting further
+
+Split a deliverable into more packages, crates or targets only for a concrete need, and record it as a `D<n>` decision:
+
+- a second deliverable that shares the code, such as a client library, a CLI or an app extension;
+- a dependency boundary the build should enforce, such as keeping a platform framework out of the core's tests;
+- build time, when one package has grown too slow to build and test alone.
+
+A package per layer, or per layer per context, is rarely normal in any ecosystem. Each boundary costs a public API between the layers and slows the build, and `cruze check` enforces the layer rules inside a package where it reads the language's imports.

package/skills/improve/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: cruze-improve
+description: Improves the structure of existing code to meet Cruze's current standards, by surveying it for structure that departs from them or keeps causing friction, letting you pick any or all of the candidates, designing the target through an architecture rethink, and scheduling the moves as prefactor changes.
+---
+
+# Improve
+
+Improve restructures code that already works, so it meets the standards Cruze holds new work to, such as a layout that is normal for the kind of system, or so it stops causing the same friction. It is design work with one approval gate, and it never changes behaviour: the behaviour tests are the safety net, and they pass unchanged at every step.
+
+Realign is different. It applies what each release's notes expect of existing code, and moves `standards:`. Improve runs whenever the user asks, whatever the version, and can take on structure that realign leaves alone, such as a layout the notes mark as new work only.
+
+## Steps
+
+1. **Check what it builds on.** Run `cruze status`. `docs/architecture.md` must be approved and current; when it isn't, stop and name `rethink`. Note the features and changes in flight, which step 8 schedules around. When the user names an area, such as a context or a module, keep to it.
+2. **Check the safety net.** Run `cruze trace --all`, and the full suite as `.agents/skills/cruze-formats/reference/config.md` defines it under `commands`. Done when both pass, and you have listed each module whose scenarios have no test. Moving such a module first needs tests that record what it does today.
+3. **Load the standards.** Read these, and follow them for the rest of this skill:
+   - `.agents/skills/cruze-hexagonal-design/SKILL.md`, `.agents/skills/cruze-hexagonal-design/shapes.md`, and the language file when one exists for the project's language
+   - `.agents/skills/cruze-behavioural-testing/SKILL.md`
+   - `.agents/skills/cruze-formats/reference/architecture.md`
+   - `.agents/skills/cruze-grilling/SKILL.md`
+4. **Survey.** Run the surveyor role from `.agents/skills/cruze-roles/SKILL.md` once for the system's layout, then once for each module in the module map, or in the user's area, giving it the module's `Path`. Run them in parallel where the agent can. Check each candidate's evidence against the files and the journal before you use it. Done when the layout and every module in scope have a report.
+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, 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 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.
+   - Order them so each lands on its own and the code builds after every one: first the tests that record behaviour a module lacks, then one context or feature at a time.
+   - Put each on the roadmap, following `.agents/skills/cruze-roadmap/SKILL.md`. Run `cruze status --overlap --change <ref>`, and block it on every in-flight item it overlaps.
+   - Commit, with a message such as `docs: plan the <area> restructure`.
+
+Done when every candidate has a journaled disposition, the target architecture is approved, and every move is a prefactor change on the roadmap.
+
+## Rules
+
+- **Behaviour stays.** Wire formats, stored formats, messages, exit codes, and every approved scenario and its test stay as they are, unless the user decided otherwise in step 5.
+- **Small files stay.** Many small modules are the standard, so a candidate never merges files only to make a module deeper. Merging is a candidate when two modules own one responsibility, or one only forwards calls to another.
+- **Ports and adapters stay.** A restructure moves where the core, the ports and the adapters live, never whether a technology sits behind a port.
+- **The existing layout wins** until the user picks a candidate that changes it. Improve never restructures code the user didn't pick.
+
+## Next step
+
+`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
 
@@ -28,4 +28,4 @@ Next reads the project's state and says what to do now. The CLI works it out fro
 | `realign` | `realign`: the installed Cruze expects more of existing code than it meets |
 | `switch-branch` | Switch to the named branch, where that change is built |
 
-When the user asks about something `cruze next` didn't name, such as a bug or an idea, point them to `triage` or `explore`.
+When the user asks about something `cruze next` didn't name, point them to `triage` for a bug, `explore` for an idea, or `improve` for existing code whose structure they want to change.

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 and the ledger. 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.** 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. 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. 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.
+   - 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. When the owner has one responsibility, plan a `check.exceptions` entry with that reason instead of a split, following the budget rule in `.agents/skills/cruze-hexagonal-design/SKILL.md`.
    - 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

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

@@ -0,0 +1,11 @@
+# Realign notes: 0.0.7
+
+## New work only
+
+### improve-skill: Existing code can be restructured to today's standards with the improve skill
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-improve/SKILL.md`
+
+### layout-by-kind: The layout is the one normal for the kind of system and its language, with the fewest layers that keep the rules
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-hexagonal-design/SKILL.md`, "Layers"

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 feature level.
+
+### 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.md

@@ -9,6 +9,8 @@ Each release that changes what Cruze expects of a project ships a notes file, `n
 - [0.0.4](notes/0.0.4.md)
 - [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)
 
 ## 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`, `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`, `improve`, `validate`, `check` or `user`.
 
 Done when `cruze status` shows every document approved and current, or names only work the user chose to leave for later.
 
@@ -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/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.

package/skills/roles/SKILL.md

@@ -14,12 +14,13 @@ A role is a prompt with fixed inputs and a report as its only output. It runs in
 | Verifier | [verifier.md](verifier.md) | verify, to run the system |
 | Researcher | [researcher.md](researcher.md) | architect, for adopt-or-build decisions |
 | Auditor | [auditor.md](auditor.md) | realign, to compare existing code with what a release now expects |
+| Surveyor | [surveyor.md](surveyor.md) | improve, to find structure that departs from the standards or keeps causing friction |
 
 ## Running a role
 
 1. Read the role file and gather exactly the inputs it lists. Done when you have every input path, plus any command output the role asks for.
 2. Start a fresh context: a helper agent with no conversation history, where the agent can start one. Give it the role file's full text and the inputs the role lists, including draft documents it names, and nothing else. Your own opinions, the conversation and your reasons for the design stay out.
-3. If the agent can't start a helper, run `cruze review <role> --item <ref>`, where the role is `design-reviewer`, `code-reviewer`, `verifier`, `researcher` or `auditor`. Add `--base <commit>` for the code under review. It starts the agent configured under `review:` in `.cruze/config.yaml` in a fresh context and prints the role's report. When no agent is configured, or it isn't installed, it reports `status: run-in-helper` with the role's full prompt instead: start a helper, such as a subagent, and give it exactly that prompt. If no fresh context can run, the reviewers, the verifier and the auditor must still run fresh: tell the user, and have them run the role in a new session. The researcher may run in your own context, since its evidence is checkable; say that you did.
+3. If the agent can't start a helper, run `cruze review <role> --item <ref>`, where the role is `design-reviewer`, `code-reviewer`, `verifier`, `researcher`, `auditor` or `surveyor`. Add `--base <commit>` for the code under review. It starts the agent configured under `review:` in `.cruze/config.yaml` in a fresh context and prints the role's report. When no agent is configured, or it isn't installed, it reports `status: run-in-helper` with the role's full prompt instead: start a helper, such as a subagent, and give it exactly that prompt. If no fresh context can run, the reviewers, the verifier and the auditor must still run fresh: tell the user, and have them run the role in a new session. The researcher may run in your own context, since its evidence is checkable; say that you did.
 4. Take the report as it comes back. Check its evidence against the files before you act on any finding.
 
 ## Running a review
@@ -37,8 +38,8 @@ A review has at most two rounds. Only blockers can force the second one.
    - You recommend anything but `fixed`: waiving, deferring or rejecting it, or a rethink because it needs a design change.
    - You would fix it differently from the reviewer's proposed fix.
 
-   Every other finding is yours, blockers included: you fix it as the reviewer proposes. When `review.decide` in `.cruze/config.yaml` is `all`, every finding is an exception.
-4. **Present them in one message.** First each exception, with your recommended disposition and why:
+   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.
+4. **Present them in one message,** written to be read cold and illustrated as `.agents/skills/cruze-grilling/illustrating.md` says. First each exception: what goes wrong, shown as the reviewer's failure scenario played out (the interaction, the code or the diagram), what the fix changes, shown before and after, and your recommended disposition and why:
    - `fixed`: you will change the work as the finding proposes.
    - `waived`: the finding is right, but the user accepts the risk.
    - `deferred`: it belongs to later work. When it is future scope, add it with `cruze features add <slug> --summary <text> --goals <ids>`.
@@ -53,13 +54,11 @@ A review has at most two rounds. Only blockers can force the second one.
 
 ### Round 2
 
-Run round 2 only when a round-1 blocker was fixed. It checks only whether those blockers are fixed, and raises nothing new.
+Run round 2 only when a round-1 blocker was fixed. It checks only whether those blockers are fixed, and raises nothing new. You check them: in 49 recorded rounds across two projects, no reviewer re-reading a fix found a blocker still open, and the user sees every fix at the walkthrough, in the plan, or in verify's report.
 
-1. **Choose who checks.** When every blocker was fixed exactly as the reviewer proposed, check the fixes yourself: a fresh reviewer re-reading a fix it proposed finds nothing new. When any blocker was fixed differently from the proposal, or its fix reaches past what the finding names, run the reviewer.
-2. **Check them yourself:** read each blocker's finding against the diff of its fix, and run `cruze validate`. A blocker is fixed when the diff does what the proposal says and validate reports no new errors.
-3. **Or run the reviewer** again with its usual inputs, plus the round-1 blockers and the diff of their fixes. It may be the round-1 reviewer resumed, since that context never saw the conversation that produced the work (with `cruze review`: `--round 2 --blockers <file> --base <round-1 commit>`).
-4. Record the round with `round=2`, the blockers still open, `concerns=0`, and `checked_by=agent` or `checked_by=reviewer`.
-5. Take any blocker still open to the user, who fixes it now, waives it or starts a rethink. There is no round 3.
+1. **Check each blocker** against the diff of its fix, and run `cruze validate`. A blocker is fixed when the diff does what the proposal says and validate reports no new errors. When a fix differs from the proposal or reaches past what the finding names, say so in the message that presents it, so the user can object.
+2. Record the round with `round=2`, the blockers still open, `concerns=0` and `checked_by=agent`.
+3. Take any blocker still open to the user, who fixes it now, waives it or starts a rethink. There is no round 3.
 
 Done when every finding has a journaled disposition, and every exception, and every blocker left open in round 2, has the user's decision.
 
@@ -69,4 +68,4 @@ Reviewers read the settled ledger so they never re-raise a decision. It consists
 
 - The `## Settled decisions` of the feature or change under review.
 - The `D<n>` lines in the `## Decisions` section of `docs/architecture.md`, and the accepted ADRs in `docs/adr/`.
-- Earlier dispositions, from `cruze journal list --event disposition`.
+- Earlier dispositions of the item under review, from `cruze journal list --event disposition --item <ref>`. `cruze show <ref>` includes them. Never list the whole project's: two projects' reviewers read every disposition ever recorded, about 36k tokens a time, a hundred times each.

package/skills/roles/code-reviewer.md

@@ -4,13 +4,13 @@ You review the code a change adds, before it lands. You work in two lanes. The s
 
 ## Inputs
 
-- The change's `change.md`, and its `feature.md` when it belongs to a feature.
+- 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.
 - The diff under review, from `git diff <base>` for the base commit you are given.
-- `docs/architecture.md`, the ADRs in `docs/adr/`, and the specs in `docs/specs/` for the capabilities the change touches.
-- The settled ledger, as `.agents/skills/cruze-roles/SKILL.md` defines it, with the output of `cruze journal list --event disposition`.
+- The ADRs in `docs/adr/`, and the specs in `docs/specs/` for the capabilities the change touches.
+- The settled ledger, as `.agents/skills/cruze-roles/SKILL.md` defines it, with the output of `cruze journal list --event disposition --item <ref>`.
+- The deviations the change recorded, from `cruze journal list --event deviation --item <ref>`.
 - The output of `cruze check` and `cruze trace --change <ref>`.
 - The standards: `.agents/skills/cruze-hexagonal-design/SKILL.md`, its language file for the project's language when one exists, `.agents/skills/cruze-behavioural-testing/SKILL.md` and `.agents/skills/cruze-dependency-approval/SKILL.md`.
-- In round 2 only: the round-1 blockers and the diff of their fixes.
 
 ## Rubric
 
@@ -27,10 +27,11 @@ Review against these items and nothing else. Each finding names one.
 
 5. **Placement.** Every file the diff adds or changes is where the architecture puts its owner, and matches the task's file targets or a recorded deviation.
 6. **Direction.** Dependencies point inward. No technology type crosses a port. Inbound adapters hold no domain rules or workflow.
-7. **Size.** No file holds two responsibilities or passes its budget without a recorded exception.
+7. **Size.** No file holds two responsibilities or passes its budget without a recorded exception. No code is bent to fit a budget, such as a type alias, a string where an error type belongs, types merged or a function placed away from its owner to stay under a limit.
 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.
-9. **Libraries.** Nothing hand-writes what a mature library does without a recorded `build` decision, and every new dependency has a recorded approval.
+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.
 
 ## Findings
 
@@ -46,10 +47,9 @@ Each finding has this shape:
 ```
 
 - A **blocker** means a scenario fails or is untested, a protected test was weakened, a layering rule is broken, an unapproved dependency was added, or an adapter can't honour its port's `Operations`. A finding that needs a design change is a blocker. Everything else is a **concern**.
-- List every blocker. List at most 5 concerns, or one per 5 tasks of the change when that is more, the most important first. Count the rest as nits without listing them. Report only what would go wrong: no concerns is a valid report, and a small change usually has few.
+- 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>`.
-- In round 2, report only whether each round-1 blocker is fixed, as `fixed` or `open` with the reason. Raise nothing new.
 
 ## Report
 

package/skills/roles/design-reviewer.md

@@ -5,14 +5,13 @@ You review a design, or a change's plan, before any code exists. You find the pl
 ## Inputs
 
 - The artifact under review:
-  - Feature scope: the feature's `feature.md`.
+  - Feature scope: the feature's `feature.md`, and the output of `cruze show <ref>` for the elements its delta cites, each with where it sits, and the settled ledger.
   - Project scope: `docs/architecture.md`, `.cruze/config.yaml` and `docs/roadmap.md`, plus the walking-skeleton change once it exists.
-  - A plan: the change's `change.md`, its `feature.md` when it has one, and the output of `cruze status --overlap --change <ref>`.
-- The living docs it builds on: `docs/vision.md`, `docs/glossary.md`, `docs/architecture.md`, the ADRs in `docs/adr/`, and the specs in `docs/specs/` that the artifact cites.
-- The settled ledger, as `.agents/skills/cruze-roles/SKILL.md` defines it, with the output of `cruze journal list --event disposition`.
+  - A plan: the change's `change.md`, the output of `cruze show <ref>`, and the output of `cruze status --overlap --change <ref>`.
+- The living docs it builds on: `docs/vision.md`, `docs/glossary.md`, the ADRs in `docs/adr/`, the specs in `docs/specs/` that the artifact cites, and, from `docs/architecture.md`, its Overview, Dependency rules, Cross-cutting concerns and Decisions sections plus each element `cruze show` lists as cited. Read the whole architecture only at project scope.
+- The settled ledger, as `.agents/skills/cruze-roles/SKILL.md` defines it, with the output of `cruze journal list --event disposition --item <ref>`.
 - The output of `cruze validate`.
 - The standards: `.agents/skills/cruze-hexagonal-design/SKILL.md` and `.agents/skills/cruze-formats/SKILL.md`.
-- In round 2 only: the round-1 blockers and the diff of their fixes.
 
 ## Rubric
 
@@ -20,10 +19,10 @@ Review against these items and nothing else. Each finding names one.
 
 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. Every element, fact and value serves a requirement in scope or a `Future` fact the feature map calls for. Anything reserved for a need nobody stated is a finding.
+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 calls for. Anything reserved for a need nobody stated is a finding.
 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 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.
+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.
 7. **Flows.** The key scenarios have a `FLOW` whose participants are all in its `Elements`, including the failure paths the scenarios need.
 8. **Consistency.** The design agrees with `docs/architecture.md`, the accepted ADRs and what earlier changes landed, or changes them explicitly through a `MODIFIED` operation or a new ADR. Its own elements agree with each other. Check every pair, not a sample:
    - each use case's `Output` and `Errors` against the `FLOW`s that serve it and the `XC` rules that apply to it;
@@ -40,8 +39,8 @@ Review against these items and nothing else. Each finding names one.
 When the artifact is a change's plan, review against these items instead.
 
 1. **Test plan.** Every delivered scenario has a `behaviour` row at a real seam, with its test file. Every port that a built adapter implements has a `contract` row. Seams need fakes of driven ports only, never mocks of internal code.
-2. **Tasks.** Every task names one owner and file paths the architecture assigns to that owner. Every scope ID is proved by a task. Each task is small enough to build red to green and commit on its own. A task that changes a signature, default or setting lists every file whose callers it breaks, including tests that start the real binary.
-3. **Order.** Tasks run from the inside out, domain before ports, use cases and adapters, so each task's test can fail first and then pass. The last tasks wire the composition root.
+2. **Tasks.** Every task names one owner and file paths the architecture assigns to that owner. Every scope ID is proved by a task. Each task is small enough to build red to green and commit on its own. A task that changes a signature, default or setting lists every file whose callers it breaks, including tests that start the real binary. A task that adds a module, file or dependency lists the file that declares it, such as a crate root, a `mod.rs`, a package manifest or an Xcode project. A rule, text, format or conversion that several elements apply has one owning file, and each later task that applies it names that file as a callee rather than restating it. 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.
+3. **Order.** Tasks run from the inside out, domain before ports, use cases and adapters, so each task's test can fail first and then pass. A test sits in the task that builds the behaviour it checks: a test that an earlier task's code already passes is in the wrong task. A break the plan names is a behaviour the task's code could get wrong, not an edit that may not compile. The last tasks wire the composition root.
 4. **No design.** Nothing in the plan changes the architecture or the specs. A plan that needs a new element, operation or scenario goes back to `architect` or `rethink`.
 5. **Risks and overlap.** The riskiest task is named, with how it is checked. Overlap with work on other branches is resolved or accepted.
 6. **Ambiguity.** Name each task a fresh implementer could reasonably build differently from what the plan means.
@@ -59,10 +58,9 @@ Each finding has this shape:
 ```
 
 - A **blocker** means building from the design as written would produce wrong behaviour, a layering violation or an untestable scenario. Two elements that contradict each other are always a blocker, because an implementer has to pick one. Everything else is a **concern**.
-- List every blocker. List at most 5 concerns, or for a plan one per 5 tasks when that is more, the most important first. Count the rest as nits without listing them. Report only what would go wrong: no concerns is a valid report, and a small artifact usually has few.
+- List every blocker. List at most 5 concerns, or one per 5 scenarios in a feature's spec delta, or for a plan one per 5 tasks, 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 artifact usually has few.
 - Drop any finding that contradicts the settled ledger. The only exception is a blocker with new evidence, which you mark `New evidence:` and explain.
 - When a finding could be caught mechanically, add `Check: <the cruze check rule or linter setting that would catch it>`.
-- In round 2, report only whether each round-1 blocker is fixed, as `fixed` or `open` with the reason. Raise nothing new.
 
 ## Report
 

package/skills/roles/surveyor.md

@@ -0,0 +1,40 @@
+# Surveyor
+
+You survey existing code for structure that departs from Cruze's current standards, or that keeps causing friction, and say what it should become. You report candidates, and you edit nothing.
+
+## Inputs
+
+- What to survey: the system's layout, or one module, named with its `Path`.
+- The standards: `.agents/skills/cruze-hexagonal-design/SKILL.md`, `.agents/skills/cruze-hexagonal-design/shapes.md`, the language file for the project's language when one exists, and `.agents/skills/cruze-behavioural-testing/SKILL.md`.
+- `docs/architecture.md`, for the module map and the elements the code implements, and `.cruze/config.yaml`.
+- The files in scope: for the layout, the build manifests, such as `Cargo.toml` or `Package.swift`, and each module's `Path`; for a module, every source and test file under its `Path`.
+- The journal, landed work included: the output of `cruze journal list --event deviation --all`, `cruze journal list --event rethink --all` and `cruze journal list --event disposition --all`.
+- The settled ledger, as `.agents/skills/cruze-roles/SKILL.md` defines it, and the earlier `improve` and `realign` dispositions. Never raise a candidate they waived.
+
+## Work
+
+1. **The layout.** Name the kind of system, and compare the module map and the packages, crates or targets with the layout `shapes.md` and the language file describe. For each boundary between packages or targets, count what it costs: the declarations made public to cross it, and the bridges, re-exports and duplicated types that exist only because of it.
+2. **The module's code.** Read every file in scope, not a sample. Check it against the standards: who owns each rule, dependency direction, ports and adapters, errors, and the warning signs in the hexagonal-design skill.
+3. **The journal.** Find the deviations, rethinks and review findings that name a file in scope, and group them by cause. A cause that recurs is friction.
+4. **The history.** Run `git log --format=%h --name-only -n 300 -- <Path>`. Name the files outside the module that change in the same commits as its files in more than half of those commits; a boundary there is often in the wrong place. Name the files that change most.
+5. **One operation.** Pick one representative operation the module serves, and list the files a reader opens to follow it from the inbound adapter to the outbound one. Note modules that only forward calls, and pairs of modules that own one responsibility between them.
+6. **Shape each candidate.** Give the smallest target that meets the standard or removes the friction, and say whether it changes the text of an element in `docs/architecture.md`. A target keeps behaviour, keeps small files, and keeps every technology behind a port.
+
+Done when every file in scope was read, and every candidate has evidence.
+
+## Report
+
+One block per candidate:
+
+```markdown
+### <n>. <one-line summary>
+- Kind: standard | friction
+- Evidence: <path:line quoting the code, journal entries with their timestamps, or commit counts>
+- Cost: <the rule text it departs from, or what the friction cost, such as five deviations>
+- Target: <the specific shape it should take>
+- Size: <prefactor changes, and tasks in each>
+- Risk: <what could break, and which tests cover it>
+- Design change: <the elements in docs/architecture.md whose text must change, or `no`>
+```
+
+Report every candidate that has evidence, and none that doesn't. End with one line: `Candidates: <n>. Standard: <n>. Friction: <n>.`