@printpractical/cruze 0.0.8 → 0.0.10

package/skills/formats/SKILL.md

@@ -21,7 +21,7 @@ Every Cruze document is Markdown that people read and the `cruze` CLI parses. Wr
 | `.cruze/features/<id>/changes/<NN-slug>/change.md` | One change of a feature: scope, test plan, tasks | plan |
 | `.cruze/changes/<id>/change.md` | A standalone change, carrying its own deltas | architect (tweak scope) |
 | `.cruze/config.yaml` | Project configuration | `cruze init`, architect |
-| `.cruze/notes/<date>-<slug>.md` | A captured explore note, or research evidence behind an adopt-or-build decision, free-form | explore, research |
+| `.cruze/notes/<date>-<slug>.md` | The user's input, envision's intake and its hand-off, an explore note, or research evidence. Free-form under a title and `- Kind:` (`input`, `intake`, `explore` or `research`) and `- About:` lines, which say the work it informs: `project`, feature slugs, or contexts | the user, envision, explore, research |
 
 Only the CLI writes `approvals.json`, `journal.jsonl` and anything under `.cruze/archive/`.
 
@@ -37,6 +37,8 @@ An ID names one element for its whole life. Other documents cite it, tests carry
 | Kind | Element | Lives in | Scope |
 | --- | --- | --- | --- |
 | `GOAL` | A goal of the product | vision | none |
+| `PRINCIPLE` | A rule every design follows | vision | none |
+| `LATER` | A capability that must stay possible after this release | vision | none |
 | `CTX` | Bounded context | architecture | none |
 | `ENT` | Domain concept: aggregate, entity, value object, domain service, policy or domain event | architecture | context |
 | `UC` | Use case (the application's driving API) | architecture | context |
@@ -54,11 +56,20 @@ An ID names one element for its whole life. Other documents cite it, tests carry
 ## Elements
 
 - A **heading element** is a heading whose text is exactly `<ID>: <Title>`. It extends to the next heading of the same or a higher level.
-- A **row element** is a table row whose first cell is exactly an ID. Only goals use rows.
+- A **row element** is a table row whose first cell is exactly an ID. Only the vision's goals, principles and must-stay-possible capabilities use rows.
 - Element facts are list items of the form `- Key: value`, directly in the element's body. Sub-items hold lists of values.
 - An element cites another by writing its ID anywhere in its body. Every ID a document mentions counts as cited.
 - A cited ID must exist, either in the living docs or in a delta of the same feature or change. Design at project scope cites only what it defines; the feature that adds scenarios links them to flows and use cases through `MODIFIED` operations.
 
+## Decisions
+
+A settled decision is a bullet `D<n>: <decision> (<reason>)` in the architecture's `## Decisions`, a feature or a change. Each document numbers its own from D1, and a feature or change is archived when it finishes, so a number means something only inside the document that records it.
+
+- Cite a decision by number only inside that document. The architecture cites its own. A feature cites its own, and a change cites its own and its feature's.
+- A delta's elements merge into the living docs, so they cite only a project decision that the work's own `## Settled decisions` doesn't also number. Write what any other decision settled into the element, or record it as an ADR and cite the ADR.
+- Code comments cite no decision by number. Say what was decided, or cite the element or ADR that holds it.
+- `cruze validate` and `cruze check` report a citation that breaks these rules as `decision-citation`, and `cruze approve` refuses a feature or standalone change whose delta has one (`decision-cited`).
+
 ## Managed content
 
 The CLI owns some content so that routine bookkeeping never changes a design:

package/skills/formats/reference/architecture.md

@@ -4,6 +4,10 @@
 
 Template: [../templates/architecture.md](../templates/architecture.md).
 
+## Reading it
+
+Read the prose sections whole: the Overview, Bounded contexts, Dependency rules, Cross-cutting concerns and Decisions. Reach elements through the CLI. `cruze show --index` lists every element of the architecture and specs on one line, with its status, its module and the work in flight that changes it, and `cruze show --index <context>` lists one context or capability with its scenarios. `cruze show <ID>...` prints the chosen elements' bodies, with each in-flight delta's version beside the living one. The index also gives the architecture's size: under 6,000 words, read it whole instead. One project's architecture held 52k words, and an architect run read all of it to find the few elements it would extend.
+
 ## Sections
 
 The document has these `##` sections, in this order. Each holds elements of one kind as `###` heading elements, plus any `VIEW` diagrams that summarize them. A section with no elements yet keeps its heading and a one-line note.
@@ -32,10 +36,10 @@ Facts are `- Key: value` items. Keys marked required must be present; the others
 | `CTX` | `Purpose` | `Depends on` (context IDs, with what is used) |
 | `ENT` | `Kind` (`aggregate`, `entity`, `value`, `service`, `policy` or `event`), `Module`, `File` | `Invariants`, `Relationships`, `States` (for state machines) |
 | `UC` | `Input`, `Output`, `Errors`, `Uses`, `Module`, `File` | `Serves` (REQ IDs) |
-| `PORT` | `Direction` (`driven` or `driving`), `Operations`, `Module`, `File` | `Implemented by`, `Future` |
+| `PORT` | `Direction` (`driven` or `driving`), `Operations`, `Module`, `File` | `Implemented by` |
 | `ADP` | `Implements` (a driven port) or `Drives` (use cases), `Technology`, `Module`, `File` | `Adopts` (library and adopt-or-build reason), `Format` (the stored or wire format it owns, or where its schema lives) |
 | `FLOW` | `Elements`, a Mermaid `sequenceDiagram` | `Serves` (SCN IDs, once they exist), `Failure paths` |
-| `MOD` | `Path` (a directory ending in `/`, or one file; list several in backticks, never a glob), `Layer` (`core`, `domain`, `application`, `adapter` or `composition`) | |
+| `MOD` | `Path` (a directory ending in `/`, or one file; list several in backticks, never a glob, including every file the module owns outside its directory, such as a build script), `Layer` (`core`, `domain`, `application`, `adapter` or `composition`) | |
 | `RULE` | one or two sentences of rule | `Enforced by` (config layer names) |
 | `XC` | prose | |
 
@@ -45,7 +49,7 @@ Rules for facts:
 - `File` names the real source path, one per element, with sub-items when an element spans files. Every element with code has one: an element without a file cannot be built, checked or reviewed.
 - `Operations` lists each operation as a sub-item with its signature in the project's language, then its contract: what it guarantees, its failure cases and who owns cleanup.
 - `Relationships` sub-items read `<verb> <ID> (<cardinality>)`, for example `- has one ENT-inventory.console-path (1)`.
-- `Future` records a seam kept open for a later release and the element it will need, so later features extend the design rather than rework it.
+- `Future`, on any element, records a seam kept open for later and what it will need, so later features extend the design rather than rework it. It names the need it serves: the vision's `LATER` capability, by ID, so a change to that capability makes the design stale, or the feature on the map or the roadmap, by slug. `cruze validate` warns `future-unanchored` when it names neither.
 - Add another fact when it helps a reader, such as `Failure attribution` on an adapter. The CLI checks the listed facts and ignores the others.
 - An element that grows over several features, such as the CLI adapter gaining a command per feature, gets a `MODIFIED` operation in each feature that extends it. Its status goes back to `planned` when that feature's first change lands, and to `built` when the change that builds the new text lands.
 - The CLI adds `- Status: planned` to a new element and flips it to `built` when a landed change builds it. Leave it out of what you write.
@@ -73,7 +77,7 @@ A feature, or a standalone change, proposes architecture edits in its `## Archit
 - Reason: telnet support was dropped from the release scope
 ```
 
-- `ADDED` introduces an ID that doesn't exist yet. `MODIFIED` replaces an existing element's whole body. `REMOVED` retires an ID and needs a `Reason`.
+- `ADDED` introduces an ID that doesn't exist yet. `MODIFIED` replaces an existing element's whole body. `REMOVED` retires an ID and needs a `Reason`. Once it merges, no living doc may cite the ID, so modify each element that cites it to describe it in words.
 - The element kind decides its section. `land` appends an added element to the end of its section.
 - A delta never touches `Status`. A change's `Builds` scope decides what becomes built.
 - A delta with no operations says `None.` under its heading.

package/skills/formats/reference/config.md

@@ -13,8 +13,8 @@ source: ["src/**/*.rs"]
 tests: ["src/**/*.rs", "tests/**/*.rs"]
 
 check:
-  max_lines: 250
-  max_types: 5
+  max_lines: 600
+  max_types: 12
   exceptions:
     - path: src/cli/args.rs
       reason: the clap derive struct lists every flag in one place
@@ -37,6 +37,10 @@ changes:
     - item: 2026-09-25-open-console/02-ssh-hops
       reason: every scenario runs through one reconcile, which can't be split without building it twice
 
+references:
+  - path: third_party/rfc4254.txt
+    use: the SSH connection protocol every hop speaks; channels and their failures must follow it
+
 layers:
   - name: inventory-domain
     paths: ["src/inventory/domain/**"]
@@ -55,9 +59,10 @@ layers:
 | `tracker` | Where work items live. `markdown` is the only value in V1. |
 | `source` | Globs of the source files `cruze check` inspects. |
 | `tests` | Globs of the files `cruze trace` searches for scenario IDs. |
-| `check.max_lines` | Line budget per source file. Test files outside `source` have no budget, and a Rust file's `#[cfg(test)]` modules don't count. |
-| `check.max_types` | Budget of top-level types per source file. |
+| `check.max_lines` | Line budget per source file, a backstop against a file that has outgrown one responsibility. `cruze init` sets `600`. Test files outside `source` have no budget, and a Rust file's `#[cfg(test)]` modules don't count. |
+| `check.max_types` | Budget of top-level types per source file. `cruze init` sets `12`. |
 | `check.exceptions` | Files allowed past a budget, or Rust test files allowed under `src/` (`test-placement`), each with a `path` and a `reason`. `realign` adds entries whose reason ends `scheduled in <ref>`, and landing that change removes them. |
+| `references` | External documents the design must comply with, such as a protocol specification or a standard, each with its `path` in the repository and its `use`: what it governs. Optional. `cruze show` lists them, and architect, plan, build and the reviewers read the parts their scope relies on and cite them, such as `RFC 4254 §5.2`, in the design. |
 | `layers` | Each layer has a `name`, the `paths` it covers, and `may_import`, the layers it may depend on. |
 | `commands` | The project's commands by name, such as `test` or `run`. The walking-skeleton change fills them in, and `cruze land` copies them into the Commands section of `AGENTS.md`. When the suite has a slow tier, such as UI, device or end-to-end tests, `test` runs only the fast tier and `test_full` runs everything. The full suite is `test_full` when it is set, and `test` otherwise. |
 | `review.command` | The program and arguments `cruze review` runs to start an agent in a fresh context, with the prompt on standard input. Optional. `cruze init` sets it for Claude Code to run in print mode, allowed to read the project and run `git diff`, `git log`, `git show` and `cruze`. The verifier runs the system, so add the project's build and run commands. When it is unset, or its program isn't installed, `cruze review` hands the role's prompt back to the calling agent to run in a helper. |

package/skills/formats/reference/durable-docs.md

@@ -4,7 +4,7 @@ Templates: [../templates/vision.md](../templates/vision.md), [../templates/gloss
 
 ## docs/vision.md
 
-What the product is for. At most one page, excluding the feature map.
+What the product is for, and the intent every design answers to, for the product's whole life. Problem through Constraints fit on one page. The Principles and Must stay possible tables don't count against it: each row holds as much as its intent needs, and `Leave room for` keeps every need, one clause each, so no step has to guess what was meant.
 
 | Section | Holds |
 | --- | --- |
@@ -13,8 +13,11 @@ What the product is for. At most one page, excluding the feature map.
 | `## Goals` | Table of ID, Goal and Measure. Each goal is a row element with a `GOAL-<name>` ID, and its measure says how you would know it's met |
 | `## Non-goals` | What the product deliberately doesn't do, one bullet each with the reason |
 | `## Constraints` | Platforms, languages, dependencies, performance, security and legal limits, one bullet each |
+| `## Principles` | Table of ID, Principle and Why. Each is a row element with a `PRINCIPLE-<name>` ID: a rule every design follows, such as "state is the truth; events are hints". A design that departs from one amends it here first |
+| `## Must stay possible` | Table of ID, Capability, Likelihood, Why and Leave room for. Each is a row element with a `LATER-<name>` ID: a capability the product may need after this release. Likelihood is `likely` or `possible`. Leave room for says what no design may close off, never how to build it. A design that keeps a seam open for one cites it in a `Future` fact |
 | `## Feature map` | Managed. `### Implemented` is a table of Feature, Release and Summary. `### Future` is a table of Feature, Summary and Goals |
 
+- Principles and capabilities that must stay possible live here, not in a feature's settled decisions, which are archived when the feature lands. A project with none writes `None.` under the heading.
 - Feature-map entries are named by slug, such as `jump-hosts`. A future entry gets a folder ID only when its feature starts.
 - Only the CLI writes the feature map. `cruze features add` puts an entry on the future list, `cruze features update` corrects an entry's summary on either list, `cruze features drop` removes one from the future list, and `land` moves a finished feature to implemented, tagged with the release in progress.
 

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

@@ -48,7 +48,7 @@ These rules close the gap between a design and what gets built. `cruze validate`
 - The first change of a feature to land merges the feature's whole delta, so the living docs never cite something a later change hasn't merged yet. What this change delivers or builds becomes `built`. Everything else arrives as `planned`, including a `MODIFIED` element whose new text isn't built yet. Each later change flips what it builds to `built`.
 - A `REMOVED` operation applies when the change whose scope lists it under `Removes` lands.
 - Under a `MODIFIED` requirement, a scenario must be in some change's scope when it is new or its text changed. An unchanged scenario the requirement keeps needs no change.
-- If someone else edits an element after this feature merged it, the next land refuses with a conflict instead of overwriting their edit. Resolve it with `rethink`.
+- If someone else edits an element after this feature merged it, their edit stands: while the feature's delta entry for that element is unchanged, later lands keep the living text, and approving the feature needs no rebase. When the feature's delta changes that element again, `cruze approve` refuses with `rebase-required` and `cruze land` with a conflict, rather than overwrite the edit. Resolve it with `rethink`.
 - The `Changes` table and each change's `Scope` agree. `plan` copies the row into the change and refines it; a disagreement is a validation error.
 
 ## Test plan

package/skills/formats/templates/vision.md

@@ -22,6 +22,18 @@
 
 - <Platform, language, dependency, performance, security or legal limit.>
 
+## Principles
+
+| ID | Principle | Why |
+| --- | --- | --- |
+| PRINCIPLE-<name> | <A rule every design follows, such as "state is the truth; events are hints".> | <Why it holds, in the user's words.> |
+
+## Must stay possible
+
+| ID | Capability | Likelihood | Why | Leave room for |
+| --- | --- | --- | --- | --- |
+| LATER-<name> | <A capability the product may need after this release.> | <likely or possible> | <Why the user may want it.> | <What no design may close off. Never how to build it.> |
+
 <!-- cruze:managed -->
 ## Feature map
 

package/skills/grilling/SKILL.md

@@ -71,8 +71,18 @@ When the user steers toward something that breaks a principle, an accepted ADR o
 
 Be direct and precise, peer to peer. Challenge only with a specific reason, and never agree without thinking.
 
+## Long-term intent
+
+The vision's `## Principles` and `## Must stay possible` hold what the product answers to beyond the work in hand. A step's own decisions are archived with its work, so long-term intent recorded there is lost. One project's "eventually" answers all went into feature decisions, and were archived with them.
+
+- **The user names something the product may need later,** in an answer or an aside, with words such as "eventually", "in the future" or "one day": propose a `LATER` row for it, with its likelihood, why, and what no design may close off. Ask it in the round.
+- **A decision touches a capability area:** once per area, ask about what it may grow into, as `.agents/skills/cruze-envision/possibilities.md` describes, unless the vision already records it.
+- **A decision departs from a `PRINCIPLE`:** name the principle, and ask whether it changes for the whole project. When it does, amend its row, with the new reason, before you record the decision. When it doesn't, the decision changes. Never record a decision that contradicts a principle the vision still states.
+- **Record it in the vision.** Edit `docs/vision.md` as the answers settle, show the user the rows that changed, and once they confirm, they approve it with `cruze approve vision`. A design that cites a row goes stale when it changes, and its next step re-checks it.
+
 ## Recording
 
 - Record each decision as soon as it settles, not at the end.
+- Principles and capabilities that must stay possible go in the vision, as "Long-term intent" says, whatever step you are in.
 - The workflow step names the document. Features and changes keep decisions in `## Settled decisions` as `D<n>: <decision> (<reason>)`. At project scope, the vision keeps goals, non-goals and constraints in their own sections, and other project decisions go in the architecture's `## Decisions` as `D<n>` lines. A decision that passes the ADR test becomes an ADR.
 - Put a term in the glossary the moment it settles, following `.agents/skills/cruze-domain-language/SKILL.md`.

package/skills/hexagonal-design/SKILL.md

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

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

@@ -25,12 +25,13 @@ These add to the hexagonal design rules for Rust projects. The module map decide
 - 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.
+- No `unwrap`, `expect` or `panic!` for conditions that can happen in production, including those a caller, the clock or a concurrent call can reach, such as an overflow from a huge timeout or a call racing `shutdown`. For each `expect`, be able to name what rules its case out. Tests may use them.
 
 ## Async and concurrency
 
 - Use Tokio when the project needs async. Keep the domain synchronous.
 - Call async functions directly. Spawn a task only when it owns a resource, runs concurrently, handles events or isolates failure, and give every long-lived task an explicit shutdown.
+- Run a test of a race on `#[tokio::test(flavor = "multi_thread")]` with the racing work spawned, since the default runtime runs one task at a time.
 - Prefer ownership and borrowing over shared synchronization. Use a channel when one task owning the state makes things simpler, and a `Mutex` when shared state is simpler. Don't build an actor only to avoid a lock.
 
 ## Dependencies and tooling

package/skills/hexagonal-design/runtime.md

@@ -29,6 +29,7 @@ Every long-lived, mutable, stateful or exclusive resource has one named owner. T
 - Technical retry and backoff live in an outbound adapter. Whether an operation is safe to repeat, and the use case's deadline, are part of the core contract.
 - Never retry non-idempotent work blindly, and never stack retries at several layers.
 - Stopping a wait, dropping a future, requesting cancellation, ending a task and cancelling remotely are different events. Say which one an operation promises, what effects may remain, and how completion is observed.
+- In a use case that writes to storage, update the in-memory state right after the durable step and before any later await, so a cancelled call leaves the old state or the new one whole.
 - When a caller needs a guaranteed or fallible finish, give it an explicit `close` or `shutdown` operation. Destruction alone can't report failure.
 
 ## Cross-cutting infrastructure

package/skills/land/SKILL.md

@@ -15,7 +15,7 @@ Land makes finished work part of the living model. `cruze land` merges the chang
    - When an `approvals.json` conflicts, take main's version of it. Then run `cruze status`, and re-approve what it shows stale, as step 3 describes.
    - Resolve code conflicts as usual, then run the full suite. When main came in without code conflicts, leave the full suite to CI.
 3. **Run `cruze status`.** When the change or its feature shows `upstream changed`, another branch landed changes to elements it cites. Then:
-   - Show the user the diff of each changed element, and check that the change's code and tests still hold against it.
+   - Run `cruze diff <ref>` for each, show the user the diff of each changed element, and check that the change's code and tests still hold against it.
    - When they still hold, re-approve the stale documents: the feature first, then the change. The change's verification carries over when its own design didn't change.
    - 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.
@@ -24,7 +24,11 @@ Land makes finished work part of the living model. `cruze land` merges the chang
    - A `merge-invalid` means the merged docs, or the feature and changes being landed, wouldn't validate, such as a decision citing an ID the change removes. Nothing was written. Stop and run `rethink`.
 5. **Update the changelog.** Under `## [Unreleased]` in `CHANGELOG.md`, add one line per user-visible behaviour the change delivers, in the user's words, under `### Added`, `### Changed` or `### Removed`. Name the behaviour, not the code, including any rule a user can now run into that no scenario covers yet.
 6. **Update the README** when the change altered how someone installs, runs or uses the product. Run every command you add, to check it works.
-7. **Check the pitfalls.** Run `cruze journal list --event disposition --all --text | grep -i "<rubric item>"` for each rubric item this change's findings named, and `cruze journal list --event rethink --all` and `cruze journal list --event bug --all`; `--all` includes landed work, which the default leaves out. When findings under the same rubric item with the same root cause, or two defects with the same cause, have now happened twice, add one line under `## Known pitfalls` in `AGENTS.md` saying what to do instead. Keep `AGENTS.md` under one page. When the pitfalls outgrow it, propose to the user a `cruze check` rule or a knowledge-skill change for the oldest ones.
+7. **Check the pitfalls.** Run `cruze journal list --event disposition --all --text | grep -i "<rubric item>"` for each rubric item this change's findings named, and `cruze journal list --event rethink --all` and `cruze journal list --event bug --all`; `--all` includes landed work, which the default leaves out. When findings under the same rubric item with the same root cause, or two defects with the same cause, have now happened twice, sort the lesson by what it is about:
+   - **This product:** its domain, its code's own conventions, or a tool or service only it uses, such as "an `ApiError` prints `<Code>: <message>`". Add one line under `## Known pitfalls` in `AGENTS.md` saying what to do instead.
+   - **Cruze's workflow, or practice that holds in any project:** how a delta, plan, task, test plan or review is written, or a rule of the language or its tooling, such as "a task lists the file that declares each new file". Record it with `cruze journal add lesson --set summary="<what happened twice>" --set instead="<what to do instead>" --set step=<the step that should have prevented it>`, and leave `AGENTS.md` alone: every session reads it, and `cruze feedback export` takes the lesson to Cruze, where the step itself gets fixed.
+
+   Keep `AGENTS.md` under one page. When the pitfalls outgrow it, propose to the user a `cruze check` rule or a knowledge-skill change for the oldest ones.
 8. **Commit** the land with a message such as `docs: land <change>`. `cruze land` keeps the Commands and Layout sections of `AGENTS.md` current, from `commands:` in `.cruze/config.yaml` and the built modules; when `commands:` is empty, the Commands section stays as it was.
 9. **Get it onto main.** Follow the project's convention in `AGENTS.md`. When it has none, ask the user whether they want pull requests or direct merges, and add their answer under `## Conventions`, such as "Changes land through pull requests." Open the pull request, or merge. CI must pass before the merge; when the project has no CI runner, run its steps locally with the project's commands.
 

package/skills/plan/SKILL.md

@@ -19,14 +19,14 @@ Plan turns one designed change into work an implementer can do without guessing:
    - `.agents/skills/cruze-behavioural-testing/SKILL.md`
    - `.agents/skills/cruze-hexagonal-design/SKILL.md`, and its language file when one exists for the project's language
    - `.agents/skills/cruze-formats/reference/work-items.md`
-6. **Read the design it builds.** Run `cruze show <ref>` and read its output: the full body of every element in the scope, every scenario it delivers, the settled decisions and the ledger. Read an element it lists as cited only when a task will call it, from the place it names. Don't read `docs/architecture.md` or `feature.md` whole: two projects read a 40k-word architecture about 150 times each.
+6. **Read the design it builds.** Run `cruze show <ref>` and read its output: the full body of every element in the scope, every scenario it delivers, the settled decisions, the ledger and the references. Read an element it lists as cited only when a task will call it, with `cruze show <ID>`. Don't read `docs/architecture.md` or `feature.md` whole: two projects read a 40k-word architecture about 150 times each.
 7. **Check for overlap.** Run `cruze status --overlap --change <ref>`. For each change on another branch that touches the same elements, tell the user which elements are shared and which change should land first. Record the answer under `## Risks`.
 8. **Write the test plan.** Follow [test-plan.md](test-plan.md). Done when every delivered scenario has a `behaviour` row and every port a built adapter implements has a `contract` row.
 9. **Write the tasks.** Follow [tasks.md](tasks.md). Done when every scope ID is proved by a task and every task line matches the grammar.
-10. **Record decisions and risks.** Put task-level choices you made under `## Settled decisions`. Under `## Risks`, name the riskiest task and how its test catches the failure. Remove every template guide.
+10. **Record decisions and risks.** Put task-level choices you made under `## Settled decisions`. Under `## Risks`, name the riskiest task and how its test catches the failure. Open each check you name and confirm it reaches the failure: the test asserts the value at risk rather than one a clamp or default hides, the lint is enabled, and the command prints what you say it shows. When no check does, name a review of the diff. Remove every template guide.
 11. **Validate.** Run `cruze validate`. Done when it reports no errors for the change.
-12. **Review the plan.** Commit the plan, then run the review in `.agents/skills/cruze-roles/SKILL.md` with the design reviewer and its plan rubric, `review=plan`, and `--item <ref>`.
-13. **Approve.** Run `cruze approve <ref> --by-agent` on this branch and quote its result. The plan carries no design of its own, so once its review has closed, with no blocker open and a disposition for every finding, you approve it for the user. The approval binds the change to the branch. When it refuses with `plan-review-open`, do what it names. When it refuses with `size-unaccepted`, the plan has more tasks than `changes.max_tasks`: split the change through `rethink` at feature level, or, when the user accepts the size, list the change under `changes.exceptions` in `.cruze/config.yaml` with their reason and approve again. A blocker still open after round 2 goes to the user, and once they decide it, they approve the plan themselves with `cruze approve <ref>`.
+12. **Review the plan.** Commit the plan, then run the review in `.agents/skills/cruze-roles/SKILL.md` with the design reviewer and its plan rubric, `.agents/skills/cruze-roles/plan-rubric.md`, `review=plan`, and `--item <ref>`.
+13. **Approve.** For a feature's change, run `cruze approve <ref> --by-agent` on this branch and quote its result. The plan carries no design of its own, so once its review has closed, with no blocker open and a disposition for every finding, you approve it for the user. A standalone change, such as the walking skeleton or a prefactor, carries its own design, so show the user the plan and ask them to approve it with `cruze approve <ref>`. The approval binds the change to the branch. When it refuses with `plan-review-open`, do what it names. When it refuses with `size-unaccepted`, the plan has more tasks than `changes.max_tasks`: split the change through `rethink` at feature level, or, when the user accepts the size, list the change under `changes.exceptions` in `.cruze/config.yaml` with their reason and approve again. A blocker still open after round 2 goes to the user, and once they decide it, they approve the plan themselves with `cruze approve <ref>`.
 14. **Commit** with a message such as `docs: plan <change>`.
 
 ## When the plan needs design
@@ -40,6 +40,16 @@ Stop planning when you find you need any of these:
 
 Say what is missing and why, then send the change to `rethink` at feature level. For a standalone change, that means its own deltas. Never add design to `change.md`.
 
+## A prefactor
+
+A prefactor changes structure, not behaviour, so it delivers no scenarios and its tasks have no red step. The tests that already reach what it rebuilds are its safety net. Its plan differs in three places:
+
+- **Test plan:** no `behaviour` row. Keep the `contract` row of each port a rebuilt adapter implements, naming its existing test file.
+- **Risks:** list the existing test files that reach each element it rebuilds, and the command that runs them. They pass before the first task and after every task, and no task edits them. When nothing reaches an element, the first task pins its current behaviour with a test that passes from the start.
+- **Tasks:** each task moves one owner and leaves those tests green. Each item keeps the visibility it had, widened only as far as its new callers need: one prefactor's only review finding was visibility left wider than it had to be.
+
+The plan review checks these with the plan rubric's Prefactor item.
+
 ## The walking skeleton
 
 The walking-skeleton change also makes CI and the project's tooling real. Its plan adds:
@@ -49,4 +59,4 @@ The walking-skeleton change also makes CI and the project's tooling real. Its pl
 
 ## Next step
 
-Show the user the test plan table, the tasks in order and the risks, and say the plan is approved. They can object, and you amend the plan, run its review on the diff, and approve again. Otherwise the next step is `build`, on this branch, in a new session so its context starts empty.
+Show the user the test plan table, the tasks in order and the risks, and say the plan is approved, or, for a standalone change, ask them to approve it. They can object, and you amend the plan, run its review on the diff, and approve again. Otherwise the next step is `build`, on this branch, in a new session so its context starts empty.

package/skills/plan/tasks.md

@@ -11,7 +11,7 @@ A task is one owner, the files it writes, and the IDs it proves. Build does them
    - Each task's test can fail first and then pass, using only what earlier tasks built.
    - Put each test in the task that builds the behaviour it checks. When an earlier task's code would already pass a later task's test, such as a failure path the earlier task had to handle, move the test into the earlier task.
    - A test that expects a default or empty result, such as no prompt, an empty list, `nil` or `0`, passes against a stub that returns it. Name in the task the break it is first seen failing against, as the wrong behaviour rather than an edit to the code, such as "fails against a model that always shows the prompt". Build may use any break that compiles and turns the same assertion red.
-   - When the project's lint rejects unused code, such as `cargo clippy -- -D warnings`, put each new item in the task of its first user, or in a task whose own test uses it. Each task then commits green on its own.
+   - When the project's lint rejects unused code, such as `cargo clippy -- -D warnings`, put each new item, private and crate-visible ones included, in the task of its first production caller. A test doesn't count as a caller: built earlier, the item fails the lint, and built later, its caller's task can't compile. Each task then commits green on its own.
    - An accessor, variant or type arrives in the task whose code first handles, matches or constructs it, never in the task that only tests it. When a later task's `match` would pull in a variant, the variant belongs to that task. Two projects built 13 items in a task other than the planned one.
 3. **Write one line per task:**
 
@@ -21,13 +21,13 @@ A task is one owner, the files it writes, and the IDs it proves. Build does them
    ```
 
    - Owner and paths in backticks. Every path is a file the architecture assigns to that owner, or a test or support file. List the test support files the task extends, such as a shared harness or fixture, so its tests reuse them.
-   - When a task adds a module, a file or a dependency, list the file that declares it, such as the crate root or `mod.rs`, the package manifest, or the Xcode project.
+   - When a task adds a module, a file or a dependency, list the file that declares it, such as the crate root or `mod.rs`, the package manifest, or the Xcode project. A task that adds a dependency or a feature of one also lists the lockfile, and names the `## Adopt or build` row that approves it.
    - A task proves the elements it builds, and each scenario whose test goes green in it.
    - A task that only sets up tooling proves the flow or scenario its checks run.
 4. **Find the owners.** For each rule, text, format or conversion a task's element applies, such as a message, a path format, a rounding or a name check, search the code and the other tasks for every place that applies it. Give it one owner: when an earlier task's owner already holds it, the later task's line names that file as a callee rather than building the rule again. Done when no rule is written in two places. Two projects wrote 20 rules twice and moved them at code review.
-5. **Find the callers.** For each signature, default or setting a task changes, search the code for every use of it, including tests that start the real binary or read the setting. Add each file that must change to the task. Done when no task will need a file it doesn't list.
+5. **Find the callers.** For each signature, default or setting a task changes, search the code for every use of it, including tests that start the real binary or read the setting. A new field breaks every literal of its type that names all the fields, so search for `<Type> {` too. Add each file that must change to the task. Done when no task will need a file it doesn't list.
 6. **Size each task.** A task writes one owner, with its tests, in one sitting. When an owner would take several steps, such as a use case with many scenarios, split it into tasks that each prove a subset of the scenarios.
-   - Run `cruze check` on each existing file a task extends. When the task would take the file past `check.max_lines` or `check.max_types`, name the new file in the task, split along a responsibility the owner already has. When the owner has one responsibility, plan a `check.exceptions` entry with that reason instead of a split, following the budget rule in `.agents/skills/cruze-hexagonal-design/SKILL.md`.
+   - When a task would give an existing file a second responsibility, name the new file in the task, named for what it owns. Never plan a split by line or type count: a file that grows with its one responsibility stays whole, and when it passes a budget, build lists it under `check.exceptions` as the budget rule in `.agents/skills/cruze-hexagonal-design/SKILL.md` says.
    - The budgets apply to source files, not tests. Split a test file by the behaviour it covers, one use case or port per file, never to meet a budget. Tests that leave a source file go where the hexagonal-design language file you loaded says.
 7. **Check coverage.**
    - Every `Builds` ID is proved by a task, except a module, which is proved by any task that writes inside its `Path`.

package/skills/realign/SKILL.md

@@ -15,17 +15,19 @@ Each Cruze release can expect more of a project's code and documents than the la
    - `.agents/skills/cruze-hexagonal-design/SKILL.md`, and its language file when one exists for the project's language
    - `.agents/skills/cruze-behavioural-testing/SKILL.md`
    - `.agents/skills/cruze-formats/reference/architecture.md`
-4. **Audit.** Run the auditor role from `.agents/skills/cruze-roles/SKILL.md` on every note with an `Ask`. In a full audit, give it the standards instead, and run one auditor per module in the module map. Check its evidence against the files. Done when every note with an `Ask` has an answer with evidence, and every note with a `Detect` has its findings from the status report.
+4. **Audit.** Run the auditor role from `.agents/skills/cruze-roles/SKILL.md` on every note with an `Ask`. A note whose `Rule` is an item of `.agents/skills/cruze-roles/design-rubric.md` is about designs, not code: run the design reviewer instead, on each feature in flight, with that item only, since those designs were reviewed before the item existed. In a full audit, give it the standards instead, and run one auditor per module in the module map. Check its evidence against the files. Done when every note with an `Ask` has an answer with evidence, and every note with a `Detect` has its findings from the status report.
 5. **Decide each finding** with the user, a group at a time, with your recommendation:
    - `fixed`: a prefactor change will fix it.
    - `waived`: the project keeps its own convention, with the reason. For a `check:` finding, list the file under `check.exceptions` with that reason, which keeps CI green. For the rest, the journal holds the waiver.
    - `deferred`: it waits for later work, recorded with `cruze features add` or on the roadmap.
+   - `rethink`: a design reviewer's finding on a feature in flight, which a feature-level rethink of its design fixes. A prefactor can't fix a design, so never record one of these as `fixed`.
 
-   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.
+   Record each with `cruze journal add disposition --set review=realign --set finding="<note id>: <path or summary>" --set disposition=<fixed|waived|deferred|rethink> --set reason="<reason>"`, adding `--item <feature>` for a `rethink`. Until a rethink is recorded for that feature, `cruze next` names it, `cruze status` counts its findings, and the build gate holds its changes. One project recorded seven such findings as `fixed`, and nothing showed them. 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.
+   - Put each on the roadmap, following `.agents/skills/cruze-roadmap/SKILL.md`, which says where a prefactor goes. Run `cruze status --overlap --change <ref>`, and ask the user the order for each item it overlaps, with your recommendation.
+   - Run `cruze next`. When it names a feature in flight because an amendment moved an element it cites, settle it now, with `cruze diff <feature>`: re-stamp it, or rebase its delta as `.agents/skills/cruze-rethink/levels.md` describes. Leave no feature stale for the next session to find.
 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.

package/skills/realign/notes/0.0.10.md

@@ -0,0 +1,131 @@
+# Realign notes: 0.0.10
+
+## Existing code
+
+### decision-citations-docs: Living docs and deltas cite a decision by number only where it is recorded
+- Applies to: existing code
+- Rule: `.agents/skills/cruze-formats/SKILL.md`, "Decisions"
+- Detect: validate:decision-citation
+- Migrate: in a prefactor, rewrite each citation the rule reports in `docs/`: write what the decision settled into the element or sentence, reading it from the archived feature's `## Settled decisions` under `.cruze/archive/`, or cite the ADR that records it. A feature in flight fixes its own delta through `rethink` before its next approval, since `cruze approve` refuses a delta that cites one.
+
+### decision-citations-code: Code comments cite no decision by number
+- Applies to: existing code
+- Rule: `.agents/skills/cruze-formats/SKILL.md`, "Decisions"
+- Detect: check:decision-citation
+- Migrate: in a prefactor, replace each citation `cruze check` reports with what was decided, in a few words, or with the element or ADR ID that holds it. Delete one that adds nothing to what the code already says.
+
+### pitfalls-to-cruze: Known pitfalls hold only lessons about the project
+- Applies to: existing code
+- Rule: `.agents/skills/cruze-land/SKILL.md`, "Landing a change", step 7
+- Ask: which lines under `## Known pitfalls` in `AGENTS.md` are about how Cruze's deltas, plans, tasks, test plans or reviews are written, or about practice that holds in any project in the language, rather than this product's domain or code?
+- Migrate: record each such line with `cruze journal add lesson --set summary=<text> --set instead=<text> --set step=<step>`, so `cruze feedback export` carries it to Cruze, then remove it from `AGENTS.md`.
+
+### vision-intent: The vision holds the principles every design follows and what must stay possible
+- Applies to: existing code
+- Rule: `.agents/skills/cruze-formats/reference/durable-docs.md`, "docs/vision.md"
+- Ask: does `docs/vision.md` lack `## Principles` or `## Must stay possible`, while the notes in `.cruze/notes/`, the ADRs, the architecture's `## Decisions` or the settled decisions of features, archived ones included, state a rule every design follows, or a capability the user expects later, such as one introduced with "eventually"?
+- Migrate: run envision at project scope to rework the vision. Add the two sections from those sources, with the user, ask about what may come later as `.agents/skills/cruze-envision/possibilities.md` describes, and approve the vision again. A principle the design already departs from is settled with the user: amend the principle, or rethink the design.
+
+### intent-review: A design follows the vision's principles and leaves room for what must stay possible
+- Applies to: existing code
+- Rule: `.agents/skills/cruze-roles/design-rubric.md`, "Design rubric", item 12
+- Ask: for each feature in flight, does its design depart from a `PRINCIPLE` the vision states, or close off a `LATER` capability it touches?
+- Migrate: settle each through `rethink` at feature level before the feature's next change is planned, or amend the vision's row when the user decides the principle or capability changes.
+
+### future-unanchored: A Future fact names the need it keeps room for
+- Applies to: existing code
+- Rule: `.agents/skills/cruze-formats/reference/architecture.md`, "Rules for facts"
+- Detect: validate:future-unanchored
+- Migrate: for each `Future` fact `cruze validate` reports, cite the vision's `LATER` capability or the feature on the map or roadmap it serves, adding the capability to the vision with the user when it isn't there yet. A seam nobody needs goes, through `rethink` at architecture level.
+
+### notes-say-what-they-are: Every note says its kind and what it is about
+- Applies to: existing code
+- Rule: `.agents/skills/cruze-formats/SKILL.md`, "Where documents live"
+- Ask: which notes in `.cruze/notes/` have no `- Kind:` and `- About:` lines under their title, and which of them hold the user's input, such as a seed, a PRD or a design write-up, whose parts no step has taken up?
+- Migrate: add `- Kind:` and `- About:` to each, as `cruze show --notes` lists them. For a note of the user's input, run the intake in `.agents/skills/cruze-envision/intake.md` on it, so its parts are handed to the steps that take them up.
+
+## New work only
+
+### plan-task-files: Items wait for a production caller, and tasks list lockfiles and every literal a new field breaks
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-plan/tasks.md`, steps 2, 3 and 5
+
+### plan-risks-reach: A check named under Risks is confirmed to reach the failure
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-plan/SKILL.md`, "Steps", step 10
+
+### design-review-ports-and-quotes: The design reviewer checks each use case against every refusal it can meet, and quoted output against the code
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/design-rubric.md`, "Design rubric", item 8
+
+### architect-retired-rules: A delta rewords every statement of a rule it retires, and modifies a port it gives a new use
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-architect/feature.md`, step 4
+
+### fakes-partial-failure: Fakes stall and fail partway, and end the way the real adapter does
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-behavioural-testing/fakes.md`, "Writing a fake"
+
+### tests-races-and-callers: Race tests are seen failing, and a test is never a reason for production code
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-behavioural-testing/SKILL.md`, "Writing tests for a task" and "Expected values"
+
+### cancel-safe-writes: Memory follows storage before the next await
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-hexagonal-design/runtime.md`, "Failures, retries and cancellation"
+
+### rust-reachable-panics: No expect on a case a caller, the clock or a race can reach
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-hexagonal-design/languages/rust.md`, "Errors"
+
+### research-own-call-shapes: New call shapes and test images are verified by running them
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-research/SKILL.md`, "Adopt or build", step 7
+
+### rethink-dispositions: A finding a later rethink fixes is recorded as rethink, and holds its work
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-realign/SKILL.md`, "Steps", step 5
+
+### prefactor-order: A prefactor goes before the items it overlaps, unless one is building
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roadmap/SKILL.md`, "Adding an item"
+
+### prefactor-plans: A prefactor's plan names its safety net and keeps visibility as it was
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-plan/SKILL.md`, "A prefactor"
+
+### merged-deltas: An element a feature merged keeps its living text, and needs no rebase
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-rethink/levels.md`, "A conflict with living text"
+
+### envision-possibilities: Envision asks about the capabilities the product may grow into
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-envision/possibilities.md`, "Exploring what may come later"
+
+### grilling-long-term-intent: Long-term intent goes to the vision, from any step
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-grilling/SKILL.md`, "Long-term intent"
+
+### envision-confirms-agreed: A proposal the user never decided is asked, not carried as settled
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-envision/project.md`, step 2
+
+### reviewer-rubrics: A review reads only the rubric for what it reviews
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/design-reviewer.md`, "Rubric"
+
+### element-lookup: Steps read a large architecture's elements through the index
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-formats/reference/architecture.md`, "Reading it"
+
+### intake-handoff: Envision takes in any input and hands each part to the step that takes it up
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-envision/intake.md`, "Taking in the user's input"
+
+### every-later-row: Every design is checked against every capability that must stay possible
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/design-rubric.md`, "Design rubric", item 12
+
+### vision-intent-length: A principle or capability keeps every need it names
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-formats/reference/durable-docs.md`, "docs/vision.md"

package/skills/realign/notes/0.0.2.md

@@ -42,7 +42,7 @@
 
 ### 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"
+- Rule: `.agents/skills/cruze-roles/design-rubric.md`, "Design rubric"
 
 ### verified-claims: Research runs every claim the design relies on
 - Applies to: new work only

package/skills/realign/notes/0.0.6.md

@@ -33,7 +33,7 @@
 
 ### cross-section-consistency: The design reviewer checks cross-cutting rules, interleavings and stale prose
 - Applies to: new work only
-- Rule: `.agents/skills/cruze-roles/design-reviewer.md`, "Rubric", item 8
+- Rule: `.agents/skills/cruze-roles/design-rubric.md`, "Design rubric", item 8
 
 ### one-message-walkthrough: The design walkthrough is one overview, then the documents in full
 - Applies to: new work only

package/skills/realign/notes/0.0.8.md

@@ -18,7 +18,7 @@
 - Applies to: existing code
 - Rule: `.agents/skills/cruze-dependency-approval/SKILL.md`, "Weighing"
 - Ask: does any code hand-write, shell out for, or use a less idiomatic construct for something a dependency or a feature of an approved dependency does cleanly, where the design or a deviation gives avoiding the dependency as the reason?
-- Migrate: ask the user for the dependency as the dependency-approval skill says, then replace the workaround through `rethink` at feature level.
+- Migrate: ask the user for the dependency as the dependency-approval skill says, then replace the workaround through `rethink`: at architecture level when the workaround is in an `XC` rule or an import allowlist, at feature level otherwise.
 
 ### size-exceptions: An accepted size warning is recorded under changes.exceptions
 - Applies to: existing code
@@ -50,7 +50,7 @@
 
 ### design-gives-every-value: The design gives every error, limit, timeout, transition and message owner
 - Applies to: new work only
-- Rule: `.agents/skills/cruze-roles/design-reviewer.md`, "Rubric", item 6
+- Rule: `.agents/skills/cruze-roles/design-rubric.md`, "Design rubric", item 6
 
 ### one-owner-per-rule: Plan gives each rule one owner, and each item to its first handler's task
 - Applies to: new work only