@printpractical/cruze 0.0.1 → 0.0.3

package/dist/domain/validation/work_item_rules.js

@@ -56,6 +56,9 @@ function itemProblems(view             , item          )            {
 }
 
 /** A feature's Changes table covers its deltas, and each change folder agrees with its row. */
+/** More changes than this, and one design review can't hold the whole feature: contradictions slip through to plan. */
+const MAX_CHANGES = 6;
+
 function featureScopeProblems(view             , feature          , delta       )            {
   const rows = readChangesTable(feature.doc);
   if (rows.length === 0) return [warning(feature.path, undefined, "not-designed", "the feature has no changes yet; architect designs and splits it")];
@@ -64,6 +67,10 @@ function featureScopeProblems(view             , feature          , delta
     [...readProgress(feature.doc).changes].filter(([, state]) => state === "landed").map(([change]) => change),
   );
   const names = rows.map((row) => row.change);
+  const extra = rows[MAX_CHANGES];
+  if (extra !== undefined) {
+    problems.push(warning(feature.path, extra.line, "feature-size", `the feature has ${rows.length} changes, over ${MAX_CHANGES}; split it into features a single design review can hold`));
+  }
   for (const row of rows) {
     if (!/^\d\d-[a-z0-9]+(?:-[a-z0-9]+)*$/.test(row.change)) problems.push(error(feature.path, row.line, "change-name", `change "${row.change}" must be named NN-slug`));
     if (names.indexOf(row.change) !== names.lastIndexOf(row.change)) problems.push(error(feature.path, row.line, "change-name", `change ${row.change} is listed twice`));

package/dist/domain/versions/ci_pin.js

@@ -0,0 +1,40 @@
+/** The Cruze package CI runs through `npx --package=<spec>`, kept at the version the project installed. */
+
+                        
+               
+                                                                              
+                     
+                                                                                                   
+                         
+ 
+
+const FORMS                                                          = [
+  // The npm package: @printpractical/cruze@0.0.1
+  (spec, version) => (/^@printpractical\/cruze@[^/\s]+$/.test(spec) ? `@printpractical/cruze@${version}` : null),
+  // The release tarball: .../releases/download/v0.0.1/printpractical-cruze-0.0.1.tgz
+  (spec, version) => {
+    const m = /^(.*\/releases\/download\/)v[^/]+\/printpractical-cruze-[^/]+\.tgz$/.exec(spec);
+    return m === null ? null : `${m[1]}v${version}/printpractical-cruze-${version}.tgz`;
+  },
+  // The git repository at a release tag: github:PrintPractical/cruze#v0.0.1
+  (spec, version) => {
+    const m = /^(.*cruze(?:\.git)?)#v\d[^\s]*$/.exec(spec);
+    return m === null ? null : `${m[1]}#v${version}`;
+  },
+];
+
+/** Moves every `--package=<spec>` that runs Cruze in a CI workflow to the version. */
+export function repinCruze(ciText        , version        )        {
+  const repinned           = [];
+  const unrecognised           = [];
+  const text = ciText.replace(/--package=(\S+)(?=\s+cruze\b)/g, (whole, spec        ) => {
+    const moved = FORMS.map((form) => form(spec, version)).find((result) => result !== null);
+    if (moved === undefined || moved === null) {
+      if (!unrecognised.includes(spec)) unrecognised.push(spec);
+      return whole;
+    }
+    if (!repinned.includes(moved)) repinned.push(moved);
+    return `--package=${moved}`;
+  });
+  return { text, repinned, unrecognised };
+}

package/dist/domain/versions/cruze_version.js

@@ -0,0 +1,51 @@
+/** Which Cruze a project runs: recorded in `.cruze/config.yaml` by `cruze install`, compared with the CLI. */
+
+/** Orders two versions such as `0.0.1` and `0.1.0` by their numeric parts; a pre-release tag is ignored. */
+export function compareVersions(a        , b        )         {
+  const parts = (v        )           => (v.split("-")[0] ?? "").split(".").map((p) => Number.parseInt(p, 10) || 0);
+  const [x, y] = [parts(a), parts(b)];
+  for (let i = 0; i < Math.max(x.length, y.length); i++) {
+    const diff = (x[i] ?? 0) - (y[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+                         
+                                           
+                                                               
+                                                             
+
+/** How the project's recorded Cruze differs from the CLI running now, or undefined when they match. */
+export function versionSkew(cli        , recorded                    )                          {
+  if (recorded === undefined) {
+    return { kind: "unrecorded", message: `the project doesn't record which Cruze its skills came from; run \`cruze install\` to install the skills of this CLI (${cli}) and record it` };
+  }
+  const order = compareVersions(recorded, cli);
+  if (order < 0) {
+    return { kind: "skills-older", recorded, message: `the project's skills are from Cruze ${recorded}, older than this CLI (${cli}); run \`cruze install\` to update them and the CI pin` };
+  }
+  if (order > 0) {
+    return { kind: "cli-older", recorded, message: `the project uses Cruze ${recorded}, newer than this CLI (${cli}); upgrade the CLI as the README's "Upgrading" section says` };
+  }
+  return undefined;
+}
+
+/**
+ * The config text with `cruze:` set to the version. The line is replaced in place, or added
+ * after `version:`, so the file's comments and layout survive.
+ */
+export function withRecordedVersion(configText        , version        )         {
+  return withVersionLine(configText, "cruze", version);
+}
+
+/** The config text with a top-level version key, such as `cruze:` or `standards:`, set in place. */
+export function withVersionLine(configText        , key                       , version        )         {
+  const line = `${key}: ${JSON.stringify(version)}`;
+  const existing = new RegExp(`^${key}:.*$`, "m");
+  if (existing.test(configText)) return configText.replace(existing, line);
+  const anchor = key === "standards" ? /^cruze:.*$/m.exec(configText) ?? /^version:.*$/m.exec(configText) : /^version:.*$/m.exec(configText);
+  if (anchor === null) return `${line}\n${configText}`;
+  const end = anchor.index + anchor[0].length;
+  return `${configText.slice(0, end)}\n${line}${configText.slice(end)}`;
+}

package/dist/domain/versions/realign_notes.js

@@ -0,0 +1,72 @@
+import { compareVersions } from "./cruze_version.js";
+
+/**
+ * A realign note: one change in what Cruze expects of a project, shipped in
+ * `skills/realign/notes/<version>.md` so `realign` can bring existing code up to it.
+ */
+                              
+             
+                
+                  
+                                                                                      
+                                
+                                                                    
+               
+                                                                      
+                  
+                                                              
+               
+                   
+ 
+
+                              
+                       
+                     
+ 
+
+const APPLIES                                           = { "existing code": "existing", "new work only": "new" };
+
+/** Parses one version's notes file. Each note is a `### <id>: <title>` heading with facts under it. */
+export function parseRealignNotes(version        , text        )              {
+  const notes                = [];
+  const problems           = [];
+  const sections = text.split(/^### /m).slice(1);
+  for (const section of sections) {
+    const [heading = "", ...body] = section.split("\n");
+    const match = /^([a-z0-9]+(?:-[a-z0-9]+)*): (.+)$/.exec(heading.trim());
+    if (match === null) {
+      problems.push(`${version}: "### ${heading.trim()}" must read "### <id>: <title>"`);
+      continue;
+    }
+    const [, id = "", title = ""] = match;
+    const fact = (key        )                     => body.map((line) => new RegExp(`^- ${key}: (.+)$`).exec(line)?.[1]?.trim()).find((v) => v !== undefined);
+    const applies = APPLIES[fact("Applies to") ?? ""];
+    const rule = fact("Rule");
+    const detect = fact("Detect")?.replace(/`/g, "");
+    const ask = fact("Ask");
+    const migrate = fact("Migrate");
+    if (applies === undefined) problems.push(`${version} ${id}: "- Applies to:" must be "existing code" or "new work only"`);
+    if (rule === undefined) problems.push(`${version} ${id}: needs "- Rule:"`);
+    if (detect !== undefined && !/^(check|validate):[a-z-]+$/.test(detect)) problems.push(`${version} ${id}: "- Detect:" names a rule as check:<rule> or validate:<rule>`);
+    if (applies === "existing" && detect === undefined && ask === undefined) problems.push(`${version} ${id}: a note for existing code needs "- Detect:" or "- Ask:"`);
+    if (applies === "existing" && migrate === undefined) problems.push(`${version} ${id}: a note for existing code needs "- Migrate:"`);
+    notes.push({
+      id,
+      title,
+      version,
+      appliesTo: applies ?? "new",
+      rule: rule ?? "",
+      ...(detect === undefined ? {} : { detect }),
+      ...(ask === undefined ? {} : { ask }),
+      ...(migrate === undefined ? {} : { migrate }),
+    });
+  }
+  const ids = notes.map((n) => n.id);
+  ids.filter((id, i) => ids.indexOf(id) !== i).forEach((id) => problems.push(`${version}: note ${id} appears twice`));
+  return { notes, problems };
+}
+
+/** Notes after the version the code meets, up to and including the version installed. */
+export function notesBetween(notes               , standards        , target        )                {
+  return notes.filter((n) => compareVersions(n.version, standards) > 0 && compareVersions(n.version, target) <= 0);
+}

package/dist/domain/versions/rule_versions.js

@@ -0,0 +1,22 @@
+import { compareVersions } from "./cruze_version.js";
+
+/** The first release of Cruze. A project that records no `standards:` meets its expectations. */
+export const FIRST_RELEASE = "0.0.1";
+
+/**
+ * The release that introduced each rule reporting on existing code, keyed as `<command>:<rule>`.
+ * A rule newer than the project's `standards:` still reports, but can't fail CI until the project realigns.
+ * Every entry needs a realign note in `skills/realign/notes/<version>.md`; the bundle lint checks it.
+ */
+export const RULE_SINCE                         = {
+  "check:test-placement": "0.0.2",
+  "validate:outside-module-map": "0.0.2",
+  "validate:readme-overview": "0.0.2",
+  "validate:feature-size": "0.0.2",
+};
+
+/** Whether a rule arrived after the version the project's code meets, so it waits for `realign`. */
+export function isPending(command                      , rule        , standards        )          {
+  const since = RULE_SINCE[`${command}:${rule}`];
+  return since !== undefined && compareVersions(since, standards) > 0;
+}

package/dist/domain/versions/scheduled_exceptions.js

@@ -0,0 +1,41 @@
+import { parseDocument,               } from "yaml";
+
+/**
+ * `check.exceptions` entries that `realign` adds for findings a prefactor change will fix,
+ * and that landing that change removes. Edited through the YAML document, so comments survive.
+ */
+
+                            
+               
+               
+ 
+
+const scheduledReason = (version        , note        , ref        )         => `realign ${version} (${note}): scheduled in ${ref}`;
+
+/** The config text with an exception for each finding, naming the change that will fix it. */
+export function withScheduledExceptions(configText        , version        , ref        , findings             )         {
+  if (findings.length === 0) return configText;
+  const doc = parseDocument(configText);
+  const listed = new Set(((doc.getIn(["check", "exceptions"])                                                      )?.toJSON() ?? []).map((e) => e.path));
+  for (const finding of findings.filter((f, i) => !listed.has(f.path) && findings.findIndex((o) => o.path === f.path) === i)) {
+    doc.addIn(["check", "exceptions"], doc.createNode({ path: finding.path, reason: scheduledReason(version, finding.note, ref) }));
+  }
+  return render(doc);
+}
+
+/** The config text without the exceptions scheduled in a change, once it lands; unchanged when it had none. */
+export function withoutScheduledExceptions(configText        , ref        )                                      {
+  const doc = parseDocument(configText);
+  const exceptions = doc.getIn(["check", "exceptions"])                                                                                  ;
+  if (exceptions === undefined || !Array.isArray(exceptions.items)) return { text: configText, removed: [] };
+  const suffix = `: scheduled in ${ref}`;
+  const removed = exceptions.items.map((item) => item.toJSON()).filter((e) => e.reason?.endsWith(suffix)).map((e) => e.path ?? "");
+  if (removed.length === 0) return { text: configText, removed: [] };
+  exceptions.items = exceptions.items.filter((item) => !(item.toJSON().reason ?? "").endsWith(suffix));
+  return { text: render(doc), removed };
+}
+
+/** Renders without wrapping long lines or padding flow lists, so an edit changes only what it touches. */
+function render(doc          )         {
+  return doc.toString({ lineWidth: 0, flowCollectionPadding: false });
+}

package/package.json

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

package/skills/architect/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,16 +40,18 @@ 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. |
+| `review.command` | The program and arguments `cruze review` runs to start an agent in a fresh context, with the prompt on standard input. Optional. `cruze init` sets it for Claude Code to run in print mode, allowed to read the project and run `git diff`, `git log`, `git show` and `cruze`. The verifier runs the system, so add the project's build and run commands. When it is unset, or its program isn't installed, `cruze review` hands the role's prompt back to the calling agent to run in a helper. |
 
 Rules for layers:
 

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/0.0.3.md

@@ -0,0 +1,11 @@
+# Realign notes: 0.0.3
+
+## New work only
+
+### review-helper-fallback: A review runs in a helper when no review agent is configured or installed
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/SKILL.md`, "Running a role", step 3
+
+### optional-review-command: review.command is optional, and set only for Claude Code
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-formats/reference/config.md`, "Configuration format"