@printpractical/cruze 0.0.1 → 0.0.2

package/skills/architect/feature.md

@@ -15,7 +15,7 @@ The result is a `feature.md` with a complete architecture delta and an ordered l
    - `MODIFIED` for an existing element, with its full new body. Copy the current body from `docs/architecture.md` and edit it, so nothing is lost by accident.
    - `REMOVED` with a `Reason`, for an element the feature retires.
 5. **Link behaviour to design.** Each use case that runs a requirement lists it under `Serves`. Add or modify a `FLOW` for each key scenario, with `Serves` naming its scenarios and the failure paths they need.
-6. **Research and decide.** For each new component that isn't domain logic, run the researcher role and record a row in `## Adopt or build`. Take every new dependency to the user.
+6. **Research and decide.** For each new component that isn't domain logic, run the researcher role and record a row in `## Adopt or build`. Take every new dependency to the user. Then verify every claim the design relies on, following step 7 of adopt or build in `.agents/skills/cruze-research/SKILL.md`. Done when no claim in the design is unverified.
 7. **Keep later seams open.** When the feature map shows a later feature that will extend this area, record the seam in a `Future` fact, and don't build it.
 8. Done when `cruze validate` reports no errors in the delta itself, and every cited ID exists in the living docs or this delta.
 
@@ -23,7 +23,9 @@ The result is a `feature.md` with a complete architecture delta and an ordered l
 
 9. **Slice vertically.** Each change delivers one or more scenarios end to end, through every layer they need, and can land on its own. The first change is the thinnest slice that proves the design, a tracer bullet. Later changes widen it.
 10. **Fill the Changes table.** Give each row a number and a slug, such as `01-local-serial`. List the scenario and requirement IDs it `Delivers`, the architecture IDs it `Builds`, any IDs it `Removes`, and the changes it `Depends on`.
+    - A change builds an element only when its scenarios prove the whole element. Each delta element is built by exactly one change, so when an element's duties arrive in different changes, split it into elements that each arrive whole, such as frame limits split out of a concurrency rule.
+    - `Depends on` names every earlier change that builds something this change's scenarios need.
 11. **Cover everything exactly once.** Every delta ID appears in exactly one change. A module the delta adds, or one still `planned` in the living docs, is built by the first change that writes a file in it. A module already `built` isn't listed. Done when `cruze validate` reports no errors for the feature, and no `not-designed` warning.
-12. **Size each change.** A change that would need more than about 12 tasks, or touches more than one context's domain, splits in two.
+12. **Size each change, and the feature.** A change that would need more than about 12 tasks, or touches more than one context's domain, splits in two. A feature of more than 6 changes is more than one design review can hold: split it into features that each serve part of its goals, and run `cruze features add` for the later ones. `cruze validate` warns `feature-size` until it is split.
 
 Then continue with the review and walkthrough steps of the skill. When the user approves, run `cruze approve <feature>` and quote its result. The command takes the feature's full ID, such as `2026-09-25-open-console`, or its slug when no other active item shares it.

package/skills/behavioural-testing/SKILL.md

@@ -36,6 +36,12 @@ A behaviour test drives a use case, not a single domain type, so it keeps passin
 - Time, randomness and the environment are ports too. Inject a clock instead of reading the system time.
 - A fake earns trust from the contract tests it shares with the real adapter. Read [fakes.md](fakes.md) before writing one.
 
+## Test support
+
+- Share fixtures and harnesses the way you share fakes. Keep one builder or constant for each domain value tests keep needing, such as a valid configuration or an ID from a string, and one harness per seam, such as an in-process service or the real binary started on a temporary directory. They live in the test support module the language file names.
+- Before writing a helper in a test file, look in the test support module. Use or extend what is there, and never redefine it.
+- Split a test file by the behaviour it covers, one use case, port or flow per file. File budgets apply to source, not to tests, so never split a test file to meet one.
+
 ## Expected values
 
 - Take expected values from an independent source: the scenario's worked example, a spec, or a known-good literal. Never compute the expected value the way the code does.

package/skills/build/SKILL.md

@@ -30,7 +30,7 @@ For task `T<n>`:
 
 1. **Read it.** Note its owner, its files, the IDs it proves, and the test plan rows for those IDs.
 2. **Red.** Write the tests for the IDs it proves, at the seams the test plan names, carrying the IDs. Run them, and see them fail for the reason you expect.
-3. **Green.** Write the least code that makes them pass, in the task's files. Code that belongs to another task waits for that task.
+3. **Green.** Write the least code that makes them pass, in the task's files. Code that belongs to another task, or another change, waits for it, even when the next change will need it.
 4. **Check.** Run `cruze check <the task's files>`, the formatter and the linter, and fix what they report. Run the tests the task touched, and the rest of the suite when they are quick.
 5. **Commit** with a Conventional Commit message naming the task, such as `feat(access): console session state machine (T2)`.
 6. **Tick it.** Run `cruze task done T<n>`, which records the commit. Its progress edit rides along in the next commit.

package/skills/envision/project.md

@@ -15,6 +15,8 @@ The result is an approved `docs/vision.md` and a `docs/glossary.md` holding the
 5. **Write the vision.** Fill each section, and remove every template guide.
 6. **Fill the feature map.** For each capability, run `cruze features add <slug> --summary "<summary>" --goals <GOAL IDs>`. Put command syntax in backticks, such as `` `consolectl console <device>` ``, so it isn't read as a template guide. Running `add` again for the same slug replaces its entry in place. Done when every goal is served by at least one feature on the map.
 7. **Confirm.** Walk the user through the vision in one short summary: the problem, the goals with their measures, the non-goals, the constraints, and the feature map. Ask whether it matches their understanding, and apply any corrections.
-8. **Approve.** When the user approves, run `cruze approve vision` and quote its result. Commit, with a message such as `docs: envision the project`.
+8. **Approve.** When the user approves, run `cruze approve vision` and quote its result.
+9. **Introduce the project in the README.** Under the title of `README.md`, write one paragraph drawn from the vision's Problem, Users and Goals: what the product is, who it is for, and why it exists, ending with a link to `docs/vision.md`. Keep anything already there that is still true. Done when `cruze validate` reports no `readme-overview` warning.
+10. **Commit,** with a message such as `docs: envision the project`.
 
-Done when `cruze status` shows `docs/vision.md` approved and the glossary holds every domain term the vision uses.
+Done when `cruze status` shows `docs/vision.md` approved, the README says what the project is, and the glossary holds every domain term the vision uses.

package/skills/formats/reference/config.md

@@ -4,6 +4,8 @@
 
 ```yaml
 version: 1
+cruze: "0.0.2"
+standards: "0.0.2"
 project: "Console Access"
 tracker: markdown
 
@@ -38,13 +40,15 @@ layers:
 | Key | Meaning |
 | --- | --- |
 | `version` | Format version. Always `1` for now. |
+| `cruze` | The Cruze version whose skills the project installed. `cruze install` writes it; don't edit it, except to go back to an older version on purpose. |
+| `standards` | The Cruze version whose expectations the code meets. `cruze realign done` moves it up. A rule a later release added reports but fails no CI until then. Without it, a project meets `0.0.1`. |
 | `project` | The project name, quoted. |
 | `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. |
+| `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.exceptions` | Files allowed past a budget, each with a `path` and a `reason`. |
+| `check.exceptions` | Files allowed past a budget, or Rust test files allowed under `src/` (`test-placement`), each with a `path` and a `reason`. `realign` adds entries whose reason ends `scheduled in <ref>`, and landing that change removes them. |
 | `layers` | Each layer has a `name`, the `paths` it covers, and `may_import`, the layers it may depend on. |
 | `commands` | The project's commands by name, such as `test` or `run`. The walking-skeleton change fills them in, and `cruze land` copies them into the Commands section of `AGENTS.md`. |
 | `review.command` | The program and arguments `cruze review` runs to start an agent in a fresh context, with the prompt on standard input. The default runs Claude Code 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. |

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 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.
 
 `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/hexagonal-design/SKILL.md

@@ -94,7 +94,12 @@ Layers are dependency boundaries, not runtime hops. A port can be a plain functi
 ## Representations and errors
 
 - Keep transport, application, domain and persistence representations separate when their meaning differs. Map them explicitly at the boundary, with one owner per mapping. Don't copy a type only to have one per layer.
-- Domain errors describe domain failures, application errors describe use-case failures, and adapter errors describe infrastructure failures. Translate at each boundary and never expose an SDK's error type through a port. Expected failures are values the caller handles, not crashes.
+- Expected failures are values the caller handles, not crashes. An error type exists where a caller handles its cases differently, and nowhere else.
+  - Domain errors describe domain failures and live with the concept that raises them.
+  - A use case returns the domain error unchanged when nothing else can fail. When it adds failures of its own, such as a port's, its error wraps the domain error in one case and never copies its variants.
+  - Adapter errors describe infrastructure failures. The adapter translates them at the port, so an SDK's error type never crosses it.
+  - Similar failures share one type, with what differs as a field: one `too large` failure naming what was too large, not one type per operation.
+  - A function returns only the failures its callers can meet. When every caller has already ruled a case out, narrow the return type rather than handling the case as unreachable.
 
 ## Warning signs
 
@@ -107,6 +112,7 @@ Reconsider ownership when a design or a diff shows any of these:
 - Application code constructs an adapter.
 - Logic that already exists is implemented again, or a change keeps a private copy of shared behaviour.
 - An interface mirrors its only implementation, or a chain of components only forwards calls.
+- An error type copies another's cases, or two error types differ only in their names.
 - Commodity infrastructure is being hand-written although a mature library does it. Follow `.agents/skills/cruze-research/SKILL.md`.
 
 These are review signals, not automatic failures. When one could be checked mechanically, propose a `cruze check` rule or a linter setting instead of repeating the finding.

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

@@ -21,7 +21,9 @@ These add to the hexagonal design rules for Rust projects. The module map decide
 
 ## Errors
 
-- Define structured error enums with `thiserror` for the domain, each use case and each adapter, and convert between them at the boundaries.
+- Define error enums with `thiserror` where the hexagonal-design error rules call for a type, not one per layer by default. A use case whose only failure is a domain error returns that error. One that adds failures wraps it in a single `#[from]` variant.
+- Put what differs between similar failures in fields, such as `TooLarge { subject: Subject, size: usize, limit: usize }`, rather than `BatchTooLarge`, `MutationTooLarge` and `SetTooLarge`.
+- A match arm that can only be `unreachable!`, or an `expect` on an error the caller has ruled out, means the callee returns too wide a type: narrow it.
 - `anyhow` belongs only in the composition root and binaries, where no caller inspects the error. Never return it from a port or a domain function.
 - No `unwrap`, `expect` or `panic!` for conditions that can happen in production. Tests may use them.
 
@@ -37,4 +39,7 @@ These add to the hexagonal design rules for Rust projects. The module map decide
 - Add dependencies with `cargo add`, so the version comes from the registry.
 - 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 `tests/` and reach the code through the library's public API. They share fakes through `tests/support/mod.rs`, which each test file declares with `mod support;`. Domain tests sit in a `#[cfg(test)] mod tests` beside the code and need no fakes.
+- 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.
+- 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/land/SKILL.md

@@ -20,7 +20,7 @@ Land makes finished work part of the living model. `cruze land` merges the chang
    - When they don't hold, stop and offer `rethink`.
 4. **Run `cruze land`** and quote its report: what it merged, what is now built, and whether the work finished and was archived.
    - A `merge-conflict` means someone changed an element this feature merged earlier. Stop and run `rethink`, which reconciles it.
-   - A `merge-invalid` means the merged docs wouldn't validate. Nothing was written. Stop and run `rethink`.
+   - 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.

package/skills/next/SKILL.md

@@ -25,6 +25,7 @@ Next reads the project's state and says what to do now. The CLI works it out fro
 | `verify` | `verify`, on this branch |
 | `land` | `land`, on this branch |
 | `rethink` | `rethink`: something approved changed, and the work citing it must be reviewed |
+| `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`.

package/skills/plan/tasks.md

@@ -9,6 +9,7 @@ A task is one owner, the files it writes, and the IDs it proves. Build does them
    - The composition root comes last.
    - Put fakes just before the first task whose test needs them.
    - Each task's test can fail first and then pass, using only what earlier tasks built.
+   - When the project's lint rejects unused code, such as `cargo clippy -- -D warnings`, put each new item in the task of its first user, or in a task whose own test uses it. Each task then commits green on its own.
 3. **Write one line per task:**
 
    ```markdown
@@ -19,8 +20,11 @@ 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.
    - 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. **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.
-5. **Check coverage.**
+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.
+   - 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.**
    - 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` or `task-format` problems.
+   - 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/plan/test-plan.md

@@ -9,6 +9,6 @@ The test plan decides, before any code, which test proves each scenario and at w
 2. **One `contract` row per port that a built adapter implements.** The seam names the fake and each real adapter, and what stands in for the outside world: a temporary directory, a pseudo-terminal, a local test server.
 3. **A `domain` row only for real logic.** Add one for a state machine, a calculation, or an invariant with many edge cases, when reaching every case through use cases would take many tests.
 4. **A `smoke` row for each flow the change completes,** when that flow is one of the system's top 1 to 3. It runs the real inbound adapter wired by the real composition root.
-5. **Test file paths follow the language's conventions.** Put behaviour, contract and smoke tests where the language keeps tests that use the public API, such as `tests/` in Rust. Put domain tests where it keeps unit tests.
+5. **Test file paths follow the language's conventions.** Put behaviour, contract and smoke tests where the language keeps tests that use the public API, such as `tests/` in Rust. Put domain tests where it keeps unit tests. When the language file says where tests go once they outgrow their source file, follow it. Add each test to the file for its seam in the test support module the language file names, rather than a new file per task.
 
 Done when every delivered scenario has a `behaviour` row, every port a built adapter implements has a `contract` row, and every test file path is a real path the project's test runner will find.

package/skills/realign/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: cruze-realign
+description: Brings an existing codebase up to what the installed Cruze expects, by auditing it against each release's realign notes, deciding every finding with you, and scheduling the fixes as prefactor changes.
+---
+
+# Realign
+
+Each Cruze release can expect more of a project's code and documents than the last, such as where tests live or how error types are shaped. `cruze install` updates the skills; realign brings the existing work up to them. The code's version is `standards:` in `.cruze/config.yaml`, and the installed one is `cruze:`. Rules newer than `standards:` report but fail no CI until realign moves it.
+
+## Steps
+
+1. **Find the gap.** Run `cruze realign status` and quote its first line: the version the code meets and the one installed. Add `--full` when the user asks for a full audit, or the project adopted Cruze partway and has never been realigned; it takes every release's notes. On `install-first`, the skills are older than the CLI: run `cruze install` first. Read [notes.md](notes.md) for what a note holds. Done when you can name every note in the report.
+2. **See what is in flight.** Run `cruze status`. Realign doesn't wait for active features and changes; it schedules around them in step 6.
+3. **Load the standards.** Read these, and each skill file a note's `Rule` names:
+   - `.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.
+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.
+   - `deferred`: it waits for later work, recorded with `cruze features add` or on the roadmap.
+
+   Record each with `cruze journal add disposition --set review=realign --set finding="<note id>: <path or summary>" --set disposition=<fixed|waived|deferred> --set reason="<reason>"`. For a finding from a `Detect` rule, write the finding as exactly `<note id>: <path>`, so `cruze realign status` knows it next time. A recorded waiver is never raised again.
+6. **Schedule the fixes.** Group the `fixed` findings into prefactor changes, each small enough to plan (about 12 tasks), one module or concern per change.
+   - When a fix changes what `docs/architecture.md` says, such as an error element, a use case's `Errors` or a port's `Operations`, run `rethink` at architecture level first. It replans the built elements the prefactor rebuilds.
+   - Create each prefactor as "A prefactor" in `.agents/skills/cruze-architect/tweak.md` describes. The behaviour tests are its safety net: wire formats, messages and exit codes stay as they are unless the user decides otherwise.
+   - 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.
+7. **Record it.** Run `cruze realign done`, adding `--change <ref>` for the prefactor that fixes the `Detect` findings still open. It moves `standards:` up, and lists those files under `check.exceptions` until that change lands, when `cruze land` removes them. Quote its result, and commit with a message such as `chore: realign to Cruze <version>`.
+
+Done when `cruze realign status` reports the code meeting the installed version, and every finding has a journaled disposition.
+
+## Next step
+
+`plan` for the first prefactor change. When nothing needed fixing, `next`.

package/skills/realign/notes/0.0.2.md

@@ -0,0 +1,69 @@
+# Realign notes: 0.0.2
+
+## Existing code
+
+### test-placement: Rust tests that outgrow their file live in tests/
+- Applies to: existing code
+- Rule: `.agents/skills/cruze-hexagonal-design/languages/rust.md`, "Dependencies and tooling"
+- Detect: check:test-placement
+- Migrate: move `src/<module>/tests.rs` and `src/<module>/tests/*.rs` to the crate's `tests/<module>.rs`, or `tests/<module>/main.rs` with one file per topic, driving the public API. A test whose private seam is the contract, such as a filesystem trait a crash test injects, stays, listed under `check.exceptions` with that reason.
+
+### readme-overview: The README says what the project is
+- Applies to: existing code
+- Rule: `.agents/skills/cruze-envision/project.md`, step 9
+- Detect: validate:readme-overview
+- Migrate: write one paragraph under the README's title from the vision's Problem, Users and Goals, ending with a link to `docs/vision.md`.
+
+### feature-size: A feature has at most 6 changes
+- Applies to: existing code
+- Rule: `.agents/skills/cruze-architect/feature.md`, step 12
+- Detect: validate:feature-size
+- Migrate: only for features still in progress. Keep the changes that have landed or started, and move the rest into a new feature with `cruze features add`, through `rethink` at feature level.
+
+### module-paths: Every file a task writes is inside a module's Path
+- Applies to: existing code
+- Rule: `.agents/skills/cruze-plan/tasks.md`, step 6
+- Detect: validate:outside-module-map
+- Migrate: only for changes still being planned or built. Add the file to its owner's `Path` through `rethink` at architecture level, or move the file.
+
+### error-types: Error types exist only where callers handle their cases differently
+- Applies to: existing code
+- Rule: `.agents/skills/cruze-hexagonal-design/SKILL.md`, "Representations and errors"
+- Ask: Does any error type copy another's variants, differ from another only in its name, or carry a case that every caller rules out, such as with `unreachable!` or `expect`? Does a use case define its own error when it only passes a domain error through?
+- Migrate: return or wrap the domain error in one case, merge similar failures into one type with the difference as a field, and narrow return types. Keep wire codes, messages and exit statuses unchanged. When `docs/architecture.md` names the error types, rethink at architecture level before the prefactor.
+
+### shared-test-support: Tests share fixtures and harnesses
+- Applies to: existing code
+- Rule: `.agents/skills/cruze-behavioural-testing/SKILL.md`, "Test support"
+- Ask: Do test files define helpers, fixtures or harnesses that another test file or the test support module already has, or share code across crates with `#[path]` includes?
+- Migrate: move each shared helper into the test support module, and in a Rust workspace into one dev-only test-support crate. Replace the copies with uses of it.
+
+## New work only
+
+### design-review-rubric: Contradictions are blockers, and slices build whole elements
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/design-reviewer.md`, "Rubric"
+
+### verified-claims: Research runs every claim the design relies on
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-research/SKILL.md`, "Adopt or build", step 7
+
+### design-change-findings: A finding that needs a design change goes to rethink
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/SKILL.md`, "Round 1", step 3
+
+### scope-now: Code for a later change waits for that change
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/code-reviewer.md`, rubric item 3
+
+### plan-foresight: Plans find callers, respect budgets and lints, and split tests by behaviour
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-plan/tasks.md`
+
+### rethink-attribution: Rethinks name the step that found and missed them
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-rethink/SKILL.md`, step 7
+
+### recorded-version: Install records the Cruze version and keeps CI on it
+- Applies to: new work only
+- Rule: `cruze install`, which writes `cruze:` in `.cruze/config.yaml` and moves the CI pin

package/skills/realign/notes.md

@@ -0,0 +1,29 @@
+# Realign notes
+
+Each release that changes what Cruze expects of a project ships a notes file, `notes/<version>.md`. `cruze realign status` reads the notes between the project's `standards:` and the installed version.
+
+## Releases
+
+- [0.0.2](notes/0.0.2.md)
+
+## Format
+
+A note is a `###` heading with an ID and a title, then facts:
+
+```markdown
+### test-placement: Rust tests live in tests/
+- Applies to: existing code
+- Rule: `.agents/skills/cruze-hexagonal-design/languages/rust.md`, "Dependencies and tooling"
+- Detect: check:test-placement
+- Migrate: move `src/<module>/tests.rs` to `tests/<module>.rs`
+```
+
+| Fact | Holds |
+| --- | --- |
+| `Applies to` | `existing code`, when work that met the last release must change; `new work only`, when only future work follows it |
+| `Rule` | The skill file and heading that state the rule |
+| `Detect` | The CLI rule that finds it, as `check:<rule>` or `validate:<rule>` |
+| `Ask` | The question the auditor answers when no CLI rule can |
+| `Migrate` | How existing work changes to meet it |
+
+A note for existing code has `Migrate`, and `Detect` or `Ask`.

package/skills/research/SKILL.md

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

package/skills/rethink/SKILL.md

@@ -24,10 +24,12 @@ Finding a design flaw mid-build is information, not failure. Rethink amends the
    ```sh
    cruze journal add rethink --set level=<task|change|feature|architecture|vision> --set kind=<defect|discovery> \
      --set summary="<what changed>" --set wrong="<document and element, and what was wrong>" \
-     --set caught_by="<for a defect, the step that should have caught it; for a discovery, the step that found it>" \
+     --set found_by=<step> [--set missed_by=<step>] \
      --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`.
+
 Done when `cruze status` shows every document approved and current, or names only work the user chose to leave for later.
 
 ## Levels

package/skills/rethink/levels.md

@@ -30,7 +30,7 @@
 
 ## Vision
 
-1. Edit `docs/vision.md` with the user: goals, non-goals or constraints. The feature map changes only through `cruze features add` and `cruze features drop`.
+1. Edit `docs/vision.md` with the user: goals, non-goals or constraints. The feature map changes only through `cruze features add` and `cruze features drop`. When the problem, users or goals changed, update the overview under the title of `README.md` to match.
 2. Update `docs/roadmap.md` to match, following `.agents/skills/cruze-roadmap/SKILL.md`.
 3. For each feature in progress that served a dropped goal, the user decides: keep it, or stop it with `cruze abandon <ref> --reason "<why>"`. Abandoning archives the folder and puts the feature back on the future list; changes that already landed stay.
 4. Re-approve with `cruze approve vision`, then `cruze approve roadmap`.

package/skills/roles/SKILL.md

@@ -13,12 +13,13 @@ A role is a prompt with fixed inputs and a report as its only output. It runs in
 | Code reviewer | [code-reviewer.md](code-reviewer.md) | verify, for the code review |
 | 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 |
 
 ## 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` or `researcher`. 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. If that can't run either, the reviewers and the verifier 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` 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. If that can't run either, 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
@@ -28,12 +29,14 @@ A review has at most two rounds. Only blockers can force the second one.
 ### Round 1
 
 1. Commit the documents under review (`docs: <artifact> for design review`), so the fixes in round 2 have a diff. Then run the reviewer on the complete artifact.
-2. Record the round: `cruze journal add review --set review=<design|plan|code> --set round=1 --set blockers=<n> --set concerns=<n>`, adding `--item <ref>` for a feature or change.
+2. Record the round: `cruze journal add review --set review=<design|plan|code> --set round=1 --set blockers=<n> --set concerns=<n> --set nits=<n>`, with the counts from the report's last line, adding `--item <ref>` for a feature or change.
 3. Present every finding to the user with your recommended disposition and why:
    - `fixed`: you will change the design as the finding proposes.
    - `waived`: the finding is right, but the user accepts the risk.
    - `deferred`: it belongs to later work. When it is future scope, add it with `cruze features add <slug> --summary <text> --goals <ids>`.
    - `rejected`: the finding is wrong, with the reason.
+
+   A finding whose fix would change an approved element, such as one marked `Needs design change`, is never `deferred` or `waived`. Recommend `rethink` at that element's level now. Once the rethink is done and the code follows it, record the finding as `fixed`.
 4. The user decides each one. Record each decision: `cruze journal add disposition --set finding="<rubric item>: <summary>" --set disposition=<fixed|waived|deferred|rejected> --set reason="<reason>" --set review=<design|plan|code>`, with the same `--item`. A recorded disposition is never raised again.
 5. Apply every `fixed` change, then run `cruze validate`. Done when it reports no errors.
 6. When a finding could be caught by a tool, such as a layering, naming or size rule, tell the user which `cruze check` rule or linter setting would catch it next time.

package/skills/roles/auditor.md

@@ -0,0 +1,35 @@
+# Auditor
+
+You compare a project's existing code and documents with what the installed Cruze now expects, and report every place they differ. You report findings, and you edit nothing.
+
+## Inputs
+
+- The notes to audit, from `cruze realign status`: each note's ID, `Rule`, `Ask` and `Migrate`.
+- In a full audit, the standards instead of notes: `.agents/skills/cruze-hexagonal-design/SKILL.md` and its language file, `.agents/skills/cruze-behavioural-testing/SKILL.md`, and `.agents/skills/cruze-formats/reference/architecture.md`. You audit one module, named with its `Path`.
+- `docs/architecture.md`, for the module map and the elements the code implements.
+- The files in scope: every source and test file under the project's `source` and `tests` globs in `.cruze/config.yaml`, or under the module's `Path`.
+- The settled ledger, as `.agents/skills/cruze-roles/SKILL.md` defines it, and the earlier realign dispositions from `cruze journal list --event disposition`. Never raise a finding they waived.
+
+## Work
+
+1. For each note, answer its `Ask` for every file in scope, not a sample. Work module by module.
+2. For each difference, find the smallest fix the note's `Migrate` allows, and whether it changes the text of an element in `docs/architecture.md`.
+3. Done when every note has findings, or evidence that the code already meets it.
+
+## Findings
+
+Group findings by note, in this shape:
+
+```markdown
+### <n>. <note ID>: <one-line summary>
+- Evidence: <path:line, quoting the code>
+- Standard: <the rule text it departs from>
+- Fix: <the specific change>
+- Design change: <the element in docs/architecture.md whose text must change, or `no`>
+```
+
+List every finding. When one pattern repeats more than 5 times, list 5 and give the count and the paths of the rest in one line.
+
+## Report
+
+End with one line: `Findings: <n> across <m> notes.` For each note with no findings, give the evidence that the code meets it.

package/skills/roles/code-reviewer.md

@@ -20,7 +20,7 @@ Review against these items and nothing else. Each finding names one.
 
 1. **Scenarios.** Every scenario the change delivers is implemented, and has a test that carries its ID, drives the seam the test plan names, and takes its expected values from the scenario.
 2. **Failures.** Each failure scenario produces the error it specifies and leaves the state it specifies.
-3. **Scope.** The code adds no behaviour the change's scope doesn't deliver. Unrequested behaviour is a finding, even when it looks useful.
+3. **Scope.** The code adds no behaviour the change's scope doesn't deliver, and no public item, variant or operation that only a later change uses. Unrequested or early code is a finding, even when it looks useful or the next change needs it.
 4. **Protected tests.** No behaviour, contract or smoke test for an approved scenario, port or flow was weakened, skipped or deleted without a delta that changes its subject.
 
 ### Architecture lane
@@ -28,7 +28,7 @@ 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.
-8. **Idiom.** The code is idiomatic for the language, uses its standard tooling, and follows the language file's rules.
+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.
 10. **Contracts.** Each adapter honours its port's `Operations`, and each fake passes the same contract tests as the real adapter.
 
@@ -42,9 +42,10 @@ Each finding has this shape:
 - Evidence: <path:line, quoting the code>
 - Failure scenario: <what goes wrong, concretely, when this runs>
 - Proposed fix: <the specific change>
+- Needs design change: <the approved element whose text the fix must change, such as a port's `Operations`, or `no`>
 ```
 
-- A **blocker** means a scenario fails or is untested, a protected test was weakened, a layering rule is broken, or an unapproved dependency was added. Everything else is a **concern**.
+- A **blocker** means a scenario fails or is untested, a protected test was weakened, a layering rule is broken, an unapproved dependency was added, or an adapter can't honour its port's `Operations`. A finding that needs a design change is a blocker. Everything else is a **concern**.
 - List every blocker. List at most 5 concerns, the most important first. Count the rest as nits without listing them.
 - Drop any finding that contradicts the settled ledger. The only exception is a blocker with new evidence, which you mark `New evidence:` and explain.
 - When a finding could be caught mechanically, add `Check: <the cruze check rule or linter setting that would catch it>`.

package/skills/roles/design-reviewer.md

@@ -20,13 +20,16 @@ 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.
+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.
 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.
+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.
 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` and the accepted ADRs, or changes them explicitly through a `MODIFIED` operation or a new ADR.
-9. **Slicing.** Each change is a vertical slice that delivers scenarios end to end and can land on its own. The order respects `Depends on`, and the first change is the thinnest useful tracer bullet. At project scope, the roadmap starts with the walking skeleton, and every goal in the release is covered.
+8. **Consistency.** The design agrees with `docs/architecture.md`, the accepted ADRs and what earlier changes landed, or changes them explicitly through a `MODIFIED` operation or a new ADR. Its own elements agree with each other. Check every pair, not a sample:
+   - each use case's `Output` and `Errors` against the `FLOW`s that serve it and the `XC` rules that apply to it;
+   - each adapter's duties against the port it implements and the `XC` rules it follows;
+   - each guarantee, such as "always fits" or "never returns", against the limits and failures that bound it.
+9. **Slicing.** Each change is a vertical slice that delivers scenarios end to end and can land on its own. The order respects `Depends on`, and the first change is the thinnest useful tracer bullet. A change `Builds` an element only when its delivered scenarios prove the whole body; an element whose duties arrive in several changes is split into elements that each arrive whole. `Depends on` names every earlier change that builds something this change's scenarios need. At project scope, the roadmap starts with the walking skeleton, and every goal in the release is covered.
 10. **Ambiguity.** Name each point where a fresh implementer could reasonably build something different from what the user expects.
 
 ## Plan rubric
@@ -34,7 +37,7 @@ 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.
+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.
 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.
@@ -52,7 +55,7 @@ Each finding has this shape:
 - Proposed fix: <the specific edit>
 ```
 
-- A **blocker** means building from the design as written would produce wrong behaviour, a layering violation or an untestable scenario. Everything else is a **concern**.
+- A **blocker** means building from the design as written would produce wrong behaviour, a layering violation or an untestable scenario. Two elements that contradict each other are always a blocker, because an implementer has to pick one. Everything else is a **concern**.
 - List every blocker. List at most 5 concerns, the most important first. Count the rest as nits without listing them.
 - Drop any finding that contradicts the settled ledger. The only exception is a blocker with new evidence, which you mark `New evidence:` and explain.
 - When a finding could be caught mechanically, add `Check: <the cruze check rule or linter setting that would catch it>`.

package/skills/roles/researcher.md

@@ -26,6 +26,7 @@ For components, report one block each:
 
 Evidence: <the evaluation table for the serious candidates, with sources and the date checked>
 New dependency: yes or no
+Claims to verify: <each feature, flag or command the design would rely on, with where the source shows it>
 ```
 
 For a question, report the answer, its evidence (version or commit, and file and line or URL) and what you couldn't verify.

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

@@ -48,6 +48,7 @@ export interface Options {
   gate?: string;
   override?: string;
   overlap: boolean;
+  full: boolean;
   replan: string[];
   rebase: string[];
   round?: string;

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

@@ -5,7 +5,7 @@ import type { CliContext, CommandResult, Options } from "../cli_context.ts";
 export async function runCheck(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
   const files = [...options.file, ...args];
   const report = await checkCode(context, { ci: options.ci, ...(files.length === 0 ? {} : { files }) });
-  const lines = report.findings.map((f) => `${f.severity} ${f.path}${f.line === undefined ? "" : `:${f.line}`} ${f.message} [${f.rule}]`);
+  const lines = report.findings.map((f) => `${f.severity} ${f.path}${f.line === undefined ? "" : `:${f.line}`} ${f.message} [${f.rule}]${f.pending === true ? " (pending realign)" : ""}`);
   lines.push(`Checked ${report.checked} file(s): ${report.passed ? "passed" : "failed"}.`);
   return { json: report, human: lines.join("\n"), failed: !report.passed };
 }
@@ -25,6 +25,7 @@ export async function runLand(context: CliContext, args: string[], options: Opti
   if (report.built.length > 0) lines.push(`Now built: ${report.built.join(", ")}`);
   if (report.removed.length > 0) lines.push(`Removed: ${report.removed.join(", ")}`);
   if (report.restamped.length > 0) lines.push(`Re-stamped approvals: ${report.restamped.join(", ")}`);
+  if (report.unexcepted.length > 0) lines.push(`CI checks these again, now that the change realign scheduled them in has landed: ${report.unexcepted.join(", ")}`);
   if (report.archivedTo !== undefined) lines.push(`Finished; archived to ${report.archivedTo}.`);
   return { json: report, human: lines.join("\n") };
 }

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

@@ -11,5 +11,9 @@ export function describeSkillInstall(report: InstallSkillsReport): string[] {
   const lines = [`Installed ${count} Cruze skill${count === 1 ? "" : "s"} into .agents/skills/: ${report.installed.join(", ")}`];
   if (report.removed.length > 0) lines.push(`Removed skills no longer shipped: ${report.removed.join(", ")}`);
   for (const link of report.linked) lines.push(`Linked them for ${link.agent} in ${link.dir}/`);
+  const { from, to, ci } = report.recorded;
+  if (from !== to) lines.push(`Recorded Cruze ${to} in .cruze/config.yaml${from === undefined ? "" : `, up from ${from}`}`);
+  if (ci.repinned.length > 0) lines.push(`CI runs ${ci.repinned.join(", ")}`);
+  for (const spec of ci.unrecognised) lines.push(`CI runs ${spec}, which Cruze can't move to ${to}; update .github/workflows/ci.yml yourself`);
   return lines;
 }