@printpractical/cruze 0.0.9 → 0.0.11

package/skills/build/SKILL.md

@@ -16,7 +16,7 @@ Build turns an approved plan into code, one task at a time. Each task starts wit
    - `.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-dependency-approval/SKILL.md`
-3. **Read the plan and the design.** Read the change's `change.md`. Run `cruze show <ref>` and read its output: the full body of every element the change builds, every scenario it delivers, and the settled decisions. Read an element it lists as cited only when the task calls it, from the place it names, never `feature.md` or `docs/architecture.md` whole. Read a reference it lists at the sections the change's elements cite. Read `commands:` in `.cruze/config.yaml`.
+3. **Read the plan and the design.** Read the change's `change.md`. Run `cruze show <ref>` and read its output: the full body of every element the change builds, every scenario it delivers, and the settled decisions. Read an element it lists as cited only when the task calls it, with `cruze show <ID>`, never `feature.md` or `docs/architecture.md` whole. Read a reference it lists at the sections the change's elements cite. Read `commands:` in `.cruze/config.yaml`.
 4. **Build each open task in order,** following the task loop below. Skip the tasks already ticked in `## Progress`.
 5. **Finish.** When every task is ticked:
    - Run the format, lint and build commands and the full suite, as `.agents/skills/cruze-formats/reference/config.md` defines it under `commands`.
@@ -36,7 +36,7 @@ For task `T<n>`:
 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.
 
-A task with no behaviour of its own, such as a package manifest or a plain data type, has no red step. Build it, check it, commit it and tick it, and the first task whose test uses it covers it.
+A task with no behaviour of its own, such as a package manifest or a plain data type, has no red step. Build it, check it, commit it and tick it, and the first task whose test uses it covers it. Neither has a prefactor's task: run the tests its plan names under `## Risks` before the first task, and after each task, and they pass unchanged.
 
 Done for a task when its tests pass, `cruze check --ci` passes for its files, the commit exists and the task is ticked.
 
@@ -49,12 +49,12 @@ The plan is design. Within a task you decide only what is local and reversible.
   - a new element, port operation or scenario;
   - a file outside the owner's module, other than the test support module;
   - a change to an approved scenario's behaviour, or to its test;
-  - a dependency, or a feature of an approved dependency, that the design doesn't name. Ask for it as `.agents/skills/cruze-dependency-approval/SKILL.md` says, and never write around it with hand-written code or a shell command;
-  - a limit, timeout, buffer size, message or error case the design doesn't give. Picking one in code hides a gap in the design: the user decides it, at feature level. Two projects settled 35 of them as deviations.
+  - a dependency, or a feature of an approved dependency, that the design doesn't name. Ask for it as `.agents/skills/cruze-dependency-approval/SKILL.md` says, and never write around it with hand-written code or a shell command.
 
   Explain what you found, with the evidence, and don't work around it. Completed tasks keep their commits.
-- **Read a deviation back before you record it.** One that says the design gives no value, text, error or outcome and names the one you chose, or that the code can't keep a promise a port or use case makes, is a rethink, not a deviation. In one change, two deviations worded that way came back as code-review blockers and sent it back at verify.
-- Never edit `feature.md`, `docs/architecture.md` or `docs/specs/` during build. Design changes go through `rethink`.
+- **Settle a detail with the user,** as "Detail" in `.agents/skills/cruze-rethink/levels.md` says, when the code needs a limit, timeout, buffer size, message or error case the design doesn't give. Never offer a deviation instead: two projects settled 35 details as deviations.
+- **Read a deviation back before you record it.** One naming a value, text, error or outcome the design doesn't give is a detail; one saying the code can't keep a promise a port or use case makes is a rethink.
+- Never edit `feature.md`, `docs/architecture.md` or `docs/specs/` during build. Design changes go through `rethink`, a detail included.
 
 ## Protecting the check
 

package/skills/envision/SKILL.md

@@ -10,7 +10,7 @@ Envision decides the what: the problem, who has it, and the behaviour that solve
 ## Steps
 
 1. **Pick the scope.** It is project scope when `docs/vision.md` doesn't exist yet, or when the user asks to rework the project's goals. It is feature scope when the user names a feature. When unsure, ask. Done when you can say which.
-2. **Gather the input.** Read what the user gave you: pasted drafts, files they point to, and notes in `.cruze/notes/`. Read whichever of `docs/vision.md`, `docs/glossary.md`, `docs/roadmap.md` and `docs/architecture.md` exist, and run `cruze status`.
+2. **Gather the input.** Read what the user gave you: pasted drafts, files they point to, and the notes `cruze show --notes` lists. Read whichever of `docs/vision.md`, `docs/glossary.md`, `docs/roadmap.md` and `docs/architecture.md` exist, and run `cruze status`.
 3. **Load the standards.** Read `.agents/skills/cruze-grilling/SKILL.md` and `.agents/skills/cruze-domain-language/SKILL.md`, and follow them for the rest of this step.
 4. **Follow the scope's procedure.** For project scope, follow [project.md](project.md). For feature scope, follow [feature.md](feature.md). Each one ends with the user's confirmation.
 5. **Check the documents.** Run `cruze validate`. Done when it reports no errors in the documents this step wrote. At feature scope, expect one `not-designed` warning for the feature, which `architect` clears.
@@ -20,7 +20,8 @@ Envision decides the what: the problem, who has it, and the behaviour that solve
 - Write in the user's terms and the glossary's words. Behaviour is described from outside the system: what a user does and what they observe.
 - Requirements and scenarios follow `.agents/skills/cruze-formats/reference/specs.md`. Every scenario uses concrete values: real names, real inputs, exact output. The scenarios become the tests, so their values are the expected results.
 - Keep implementation out: no modules, types, libraries or file formats unless the user names one as a constraint. When the user raises one, record it as a constraint or a settled decision and move on.
-- The vision stays within one page, excluding the feature map.
+- Problem through Constraints stay within one page. A principle or a capability that must stay possible takes as much as its intent needs: never shorten one to fit.
+- The product's long-term intent lives in the vision, in its Principles and Must stay possible tables, at either scope. Designs answer to it for the product's whole life, long after the conversation that settled it.
 - Only the CLI writes the feature map. Use `cruze features add`, `cruze features update` and `cruze features drop`.
 
 ## Next step

package/skills/envision/feature.md

@@ -7,13 +7,15 @@ The result is a feature folder whose `feature.md` holds the intent, the settled
    - When it isn't in the roadmap's phases, ask the user whether it belongs in this release. If it does, add it by following "Adding an item" in `.agents/skills/cruze-roadmap/SKILL.md`, and re-approve the roadmap. If it doesn't, put it on the future list with `cruze features add` and stop here.
    - When its `Blocked by` items haven't landed (see the roadmap's `## Status`), tell the user. Continue only if they want to design ahead, and record that as a settled decision.
 3. **Create the folder.** When the feature has no folder yet, run `cruze new feature <slug> --title "<title>" --roadmap <slug>`, using its roadmap slug. When a folder exists, edit its `feature.md`.
-4. **Read the behaviour it touches.** Read the specs in `docs/specs/` for every capability the feature changes, so you know each requirement and scenario it builds on.
+4. **Read the behaviour it touches.** Read the specs in `docs/specs/` for every capability the feature changes, so you know each requirement and scenario it builds on. Run `cruze show --notes <slug>`, and take up the notes about this feature and the parts of the user's input handed to it, open questions included, as "Taking up a hand-off later" in [intake.md](intake.md) describes.
 5. **List the open decisions:**
    - **Intent:** the problem and outcome in the user's words, who it is for, the constraints, and what is out of scope.
    - **Requirements:** each behaviour the feature adds, changes or removes, and the capability it belongs to. It goes in an existing capability when the behaviour fits one; otherwise it starts a new capability.
    - **Scenarios:** for each requirement, the main case, each edge and failure case a user will meet, and what they observe in each. Invent concrete edge cases to test the boundaries.
+   - **Later:** the vision's `PRINCIPLE` and `LATER` rows this feature touches, and the capabilities it may grow into, asked about as [possibilities.md](possibilities.md) describes. A feature that adds sign-in asks about single sign-on and multi-factor authentication, for example.
 6. **Grill in rounds** until every open decision is settled. Record decisions under `## Settled decisions` and terms in the glossary as they settle.
    - When a decision changes something the feature's summary on the feature map promises, such as a policy it names, correct the summary with `cruze features update <slug> --summary <text>`.
+   - When an answer names something the product may need later, or a decision departs from a principle, the vision changes, as "Long-term intent" in the grilling skill describes. A settled decision of this feature is archived when it lands, so it can't hold either.
 7. **Write the spec delta.** Use `ADDED` for new requirements, `MODIFIED` for a requirement whose text or scenarios change (writing its full new body with every scenario it keeps), `REMOVED` with a `Reason` and `Migration` for retired behaviour, and `ADDED CAPABILITY` for a new capability.
    - Name every ID with glossary terms. An ID is never reused.
    - Done when every requirement has a scenario for its main case and one for each failure a user can meet.

package/skills/envision/intake.md

@@ -0,0 +1,28 @@
+# Taking in the user's input
+
+The user may bring anything: a seed, a PRD, a TRD, a design write-up, an old project's notes, a pasted paragraph or a link. Everything in it is open for discussion, and every part of it reaches the step that takes it up. One project's 9,500-word seed held design that no step was told to read, and intent the vision had no room for.
+
+1. **Gather it.** Read every source the user names or pastes, and each note `cruze show --notes` lists with kind `input`. Run `cruze new note intake --title "Intake: <what the input is>" --kind intake --about project`. Under `## Sources`, cite each file in the repository by path, and copy in, verbatim, what would otherwise be lost: pasted text, and a document outside the repository, such as a link or a PDF.
+2. **Sort every part** by the step that takes it up. Name each part by its heading, or by a short quote where the input has none:
+   - `vision`: the problem, users, goals, non-goals, constraints, principles, and what must stay possible.
+   - `architect`: design choices, such as structure, protocols, technologies and data formats.
+   - `roadmap`: delivery order and phases.
+   - a feature's slug: one feature's behaviour, rules, limits and examples. Use the slug the feature map gives it.
+   - `user`: preferences about the process itself, which the user may add to `AGENTS.md`.
+
+   An open question goes to the step that settles it. Done when every part of every source has a place.
+3. **Read its stance.** Note how settled the input says each part is, from its own legend when it has one, or from its wording: "we decided" and "must" are firmer than "maybe", "TBD" or a question. Nothing is settled by being written down. The stance sets only your recommendation: keep what the input settled, with its reason; ask about what it proposed; research what it guesses; settle what it leaves open.
+4. **Write the hand-off** in the intake note, under `## Hand-off`, one row per part:
+
+   ```markdown
+   | Part | Source | Goes to | Status |
+   | --- | --- | --- | --- |
+   | Transport | `.cruze/notes/2026-10-12-seed.md`, "The protocol" | architect | open |
+   ```
+
+   A one-paragraph idea is all `vision`, so its hand-off is a row or two.
+5. **Take up the vision's parts now,** one section at a time. Each section is one question, keep or change, with the input's position as your recommendation. Set each row's status to `settled` or `dropped` as the user decides.
+
+## Taking up a hand-off later
+
+Architect, the roadmap and feature-scope envision take up their own rows. `cruze show --notes <step or feature slug>` lists them, and `cruze show <ref>` lists them for a feature or change. Read each part at its source, ask the user about it as in step 5, record what they keep where the step records decisions, and set the row's status. A row still `open` when the step ends goes to the user: keep it open for a later step, or drop it.

package/skills/envision/possibilities.md

@@ -0,0 +1,13 @@
+# Exploring what may come later
+
+The user knows where the product is heading better than any document does, but rarely says it unprompted. Ask, so designs leave room for it and never close it off.
+
+1. **Find the neighbours.** For each goal, user and capability in scope, name the capabilities that products in this domain commonly grow into, from what you know of the domain and its standards. Name them as the user would recognise them: single sign-on or multi-factor authentication next to sign-in, sync across devices next to local-only storage, teams and shared workspaces next to a single-user app, third-party plugins next to a fixed set of kinds, a second transport next to a local socket. Skip those the vision already records under `## Must stay possible` or `## Non-goals`.
+2. **Ask them as a round,** following `.agents/skills/cruze-grilling/SKILL.md`: whether the product may need each one, how likely, and why. Recommend an answer from what the user has said so far. Keep a round to 3 to 5, the likeliest first. "No" is a good answer too.
+3. **Record each answer:**
+   - **Likely or possible:** a `LATER-<name>` row under `## Must stay possible` in `docs/vision.md`, with the likelihood, why in the user's words, and what no design may close off. Say what must stay possible, never how to build it: the mechanism is decided when a feature builds it.
+   - **No, for a tempting neighbour of a goal:** a non-goal with the reason, so nobody proposes it again.
+   - **No, otherwise:** nothing.
+4. **Check the principles.** For each new `LATER` row, check every `PRINCIPLE` row against it. When one would stand in its way, such as "every record has exactly one owner" against shared workspaces, settle with the user which one gives, and amend the principle or the row.
+
+Done when every capability in scope has had its neighbours asked about once, and each answer is recorded. The vision changed, so the user approves it again with `cruze approve vision`.

package/skills/envision/project.md

@@ -3,18 +3,20 @@
 The result is an approved `docs/vision.md` and a `docs/glossary.md` holding the terms that settled. Formats: `.agents/skills/cruze-formats/reference/durable-docs.md`.
 
 1. **Create the documents.** Run `cruze new vision` and `cruze new glossary` for whichever doesn't exist yet. When the vision exists and you are reworking it, edit it in place. Bounded contexts don't exist yet, so group the glossary's terms under one `##` heading naming the product's domain, such as `## Console access`. `architect` regroups them by context.
-2. **Draft from the input.** Fill every section you can from what the user already gave you, and mark every guess as a question for step 3.
+2. **Take in the input** as [intake.md](intake.md) describes, then draft every section you can from the parts handed to `vision`, marking each as a question for step 3. Done when every part of the input has a hand-off row.
 3. **List the open decisions,** section by section:
    - **Problem:** the problem in the user's words, and who feels it.
    - **Users:** each kind of user and the situation they are in.
    - **Goals:** each goal as a `GOAL-<name>` row, with a measure that says how you would know it's met. A goal without a measure is still open.
    - **Non-goals:** what the product deliberately doesn't do, and why. Ask about the tempting neighbours of each goal.
    - **Constraints:** platforms, the implementation language, dependency policy, performance, security, privacy, licensing and legal limits.
+   - **Principles:** each rule every design must follow, as a `PRINCIPLE-<name>` row with why it holds. Ask about the rules behind the user's choices, such as what state and events are each for.
+   - **Must stay possible:** each capability the product may need after this release, as a `LATER-<name>` row, explored as [possibilities.md](possibilities.md) describes.
    - **Feature map:** the capabilities that deliver the goals, each a slug with a one-line summary and the goals it serves. They are what later `envision "<feature>"` runs pick up.
-4. **Grill in rounds** until every open decision is settled, following the grilling skill. As each domain term settles, add it to the glossary.
+4. **Grill in rounds** until every open decision is settled, following the grilling skill. As each domain term settles, add it to the glossary. Once the goals and feature map have settled, ask about what may come later, as [possibilities.md](possibilities.md) describes.
 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.
+7. **Confirm.** Walk the user through the vision in one short summary: the problem, the goals with their measures, the non-goals, the constraints, the principles, what must stay possible, and the feature map. Name what the hand-off gives each later step, and anything dropped, and why. Ask whether it matches their understanding, and apply any corrections.
 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`.

package/skills/explore/SKILL.md

@@ -10,7 +10,7 @@ Explore is the optional thinking partner that can come before any other Cruze st
 ## Steps
 
 1. **Frame the problem.** Ask what prompted the idea, who it affects, and what outcome would make it worthwhile. If the user starts from a solution, restate the problem underneath it and confirm it. Done when you can state the problem in one sentence the user agrees with.
-2. **Read what exists.** Read whichever of these exist: `docs/vision.md`, `docs/glossary.md`, `docs/architecture.md`, `docs/roadmap.md`, and the code the idea touches. Run `cruze status` to see work in flight. Use the glossary's words from here on, following `.agents/skills/cruze-domain-language/SKILL.md`.
+2. **Read what exists.** Read whichever of these exist: `docs/vision.md`, `docs/glossary.md`, `docs/architecture.md` as "Reading it" in `.agents/skills/cruze-formats/reference/architecture.md` says, `docs/roadmap.md`, and the code the idea touches. Run `cruze status` to see work in flight. Use the glossary's words from here on, following `.agents/skills/cruze-domain-language/SKILL.md`.
 3. **Separate facts from guesses.** List what is known evidence, what is a hypothesis, and what is a preference. Look up any fact you can rather than asking the user for it.
 4. **Diverge.** Lay out two to four genuinely different approaches, including leaving things as they are when that is credible. For each, give what it changes, what it leaves alone, its benefits, its costs and failure modes, the assumptions it rests on, and what evidence would tell it apart from the others. Show what each approach looks like, following `.agents/skills/cruze-grilling/illustrating.md`.
 5. **Converge.** Compare the strongest options against the user's outcome, the vision's goals and constraints, and the architecture. Challenge assumptions and accidental scope growth, following the challenge rules in `.agents/skills/cruze-grilling/SKILL.md`. Recommend one option only when its trade-offs are understood. Otherwise recommend the smallest step that would settle the question, such as a spike, a measurement or a research question.
@@ -20,7 +20,7 @@ Explore is the optional thinking partner that can come before any other Cruze st
 
 Only when the user says to capture:
 
-1. Run `cruze new note <slug> --title "<title>"` and write the note at the path it returns.
+1. Run `cruze new note <slug> --title "<title>" --kind explore --about <subjects>`, naming the feature slugs or contexts the idea concerns, or `project`, and write the note at the path it returns.
 2. Give the note these sections: `## Problem`, `## Options`, `## Recommendation` and `## Open questions`. Mark each statement as fact, hypothesis, preference or recommendation.
 3. Done when the note stands on its own for a reader who wasn't in the conversation.
 

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,7 +36,7 @@ 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, including every file the module owns outside its directory, such as a build script), `Layer` (`core`, `domain`, `application`, `adapter` or `composition`) | |
@@ -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/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/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,13 +19,13 @@ 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, the ledger and the references. Read an element it lists as cited only when a task will call it, from the place it names. Don't read `docs/architecture.md` or `feature.md` whole: two projects read a 40k-word architecture about 150 times each.
+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>`.
+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>`.
 
@@ -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:

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,11 +21,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. 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.
    - 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.

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`. A note whose `Rule` is an item of the design reviewer's rubric is about designs, not code: run the design reviewer instead, on each feature in flight, with that item only, since those designs were reviewed before the item existed. In a full audit, give it the standards instead, and run one auditor per module in the module map. Check its evidence against the files. Done when every note with an `Ask` has an answer with evidence, and every note with a `Detect` has its findings from the status report.
+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.