@printpractical/cruze 0.0.13 → 0.0.14

package/skills/formats/templates/architecture.md

@@ -2,99 +2,43 @@
 
 ## Overview
 
-<One paragraph: what the system is and what kind (a library, a daemon or service, a mobile or desktop app, a CLI, or several deliverables), how it is used, and the architectural style.>
-
-### VIEW-context: System context
+<What the system is, in two sentences. Then the diagram: inbound adapters on the left, the application core in the middle, the ports and the adapters behind them on the right.>
 
 ```mermaid
 flowchart LR
-  user([<User>]) --> cli[<Inbound adapter>]
-  cli --> ctx[<Bounded context>]
-  ctx --> ext[(<External system>)]
 ```
 
-## Bounded contexts
+## Ports
 
-### CTX-<name>: <Context title>
-- Purpose: <what this context is responsible for>
-- Depends on: <CTX ID and what it uses, or "nothing">
+<One subsection per port: what the core needs from the outside world, or offers to it.>
 
-## Domain model
+### <Port name>
 
-### VIEW-domain-model: Domain model
+<What it is for, and who drives it. Then its operations as code, each with its errors.>
 
-```mermaid
-classDiagram
-  class <Entity>
+```text
 ```
 
-### ENT-<context>.<name>: <Entity title>
-- Kind: <aggregate | entity | value | service | policy | event>
-- Invariants:
-  - <a rule that always holds>
-- Relationships:
-  - <verb> <ENT ID> (<cardinality>)
-- Module: <MOD ID>
-- File: `<path>`
-
-## Use cases
-
-### UC-<context>.<name>: <Use case title>
-- Input: <what the caller provides>
-- Output: <what the caller gets>
-- Errors: <each failure the caller can see>
-- Uses: <PORT IDs>
-- Module: <MOD ID>
-- File: `<path>`
-
-## Ports
-
-### PORT-<context>.<name>: <Port title>
-- Direction: <driven | driving>
-- Operations:
-  - `<signature>`: <guarantee; failure cases; who owns cleanup>
-- Implemented by: <ADP IDs>
-- Module: <MOD ID>
-- File: `<path>`
-
 ## Adapters
 
-### ADP-<context>.<name>: <Adapter title>
-- Implements: <PORT ID>
-- Technology: <library, protocol or system>
-- Adopts: <library, and why adopt rather than build>
-- Module: <MOD ID>
-- File: `<path>`
-
-## Flows
-
-### FLOW-<context>.<name>: <Flow title>
-- Serves: <SCN IDs>
-- Elements: <IDs of every participant>
-
-```mermaid
-sequenceDiagram
-  participant A as <Element title>
-```
+| Adapter | Implements | Technology |
+| --- | --- | --- |
+| <name> | <port, or the inbound side it serves> | <library, protocol or device> |
 
-## Modules
+## Runtime
 
-### MOD-<context>.<name>: <Module title>
-- Path: `<directory or file>`
-- Layer: <core | domain | application | adapter | composition>
+<The threading or async model and how work is scheduled. Every limit and timeout with its number. What happens on overload, when a dependency fails, and at shutdown.>
 
-## Dependency rules
+## Technology
 
-### RULE-<name>: <Rule title>
-<One or two sentences stating what may depend on what.>
-- Enforced by: <config layer names>
+| Choice | For | Why |
+| --- | --- | --- |
+| <language, framework or significant dependency> | <what it does here> | <why it, in one line> |
 
-## Cross-cutting concerns
+## Layers
 
-### XC-<name>: <Concern title>
-<How the system handles it, and where.>
+<The layers, what each holds, and which may import which. The rules are in .cruze/config.yaml, where cruze check enforces them.>
 
 ## Decisions
 
-- ADR-<stem>: <one-line summary>
-- D1: <a project-level decision below the ADR bar> (<reason>)
+- <A choice that shapes the whole system, and why.>

package/skills/formats/templates/feature.md

@@ -1,49 +1,33 @@
----
-id: {{id}}
-title: {{title_quoted}}
-roadmap: <roadmap item slug>
----
+# {{title}}
 
-# Feature: {{title}}
+- Status: shaped
 
 ## Intent
 
-<The problem and outcome in the user's words. Who it is for. Constraints.>
+<What the user can do once this is built, and why, in two sentences.>
 
-Out of scope:
+## Behaviour
 
-- <what this feature deliberately leaves out>
+### SCN-{{slug}}.<name>: <Scenario title>
 
-## Settled decisions
+- Given <the starting state>
+- When <the one action>
+- Then <what the user sees>
 
-- D1: <decision> (<reason>)
+## Public API
 
-## Adopt or build
+<Every public type, function, command, endpoint or message this feature adds or changes, as real code in the project's language. Write "No change." when there is none.>
 
-| Component | Decision | Choice | Reason |
-| --- | --- | --- | --- |
+```text
+```
 
-## Spec delta
+## Stack sketch
 
-### ADDED REQ-<capability>.<name>: <Requirement title>
-<The requirement using SHALL or MUST.>
+<The main scenario crossing the stack, from the inbound adapter through the core to the ports and adapters, with what is new marked. Then each change this feature makes to docs/architecture.md, one line each.>
 
-#### SCN-<capability>.<name>: <Scenario title>
-- GIVEN <starting state>
-- WHEN <the one action>
-- THEN <observable outcome>
+```text
+```
 
-## Architecture delta
+## Decisions
 
-### ADDED <ID>: <Element title>
-- <the element's full body, as it will read in architecture.md>
-
-## Changes
-
-| Change | Delivers | Builds | Depends on |
-| --- | --- | --- | --- |
-| 01-<slug> | <SCN and REQ IDs> | <architecture IDs> | |
-
-<!-- cruze:managed -->
-## Progress
-<!-- /cruze:managed -->
+- <A choice the user would notice or might question, and why.>

package/skills/formats/templates/vision.md

@@ -8,42 +8,30 @@
 
 - <Who, and in what situation they use it.>
 
-## Goals
+## Terms
 
-| ID | Goal | Measure |
+| Term | Meaning | Avoid |
 | --- | --- | --- |
-| GOAL-<name> | <What the product achieves for its users.> | <How you would know it's met.> |
+| <term> | <What it means in this product.> | <Synonyms that would confuse.> |
 
-## Non-goals
-
-- <What the product deliberately doesn't do, and why.>
+## Release
 
-## Constraints
+<What a user can do when this release ships, in one sentence.>
 
-- <Platform, language, dependency, performance, security or legal limit.>
-
-## Principles
-
-| ID | Principle | Why |
+| Feature | Summary | Needs |
 | --- | --- | --- |
-| 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
+| <slug> | <What the user can do once it is built.> | <Slugs of the features it can't be built without, or blank.> |
 
-| 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.> |
+## Future features
 
-<!-- cruze:managed -->
-## Feature map
+| Feature | Summary | Must stay possible |
+| --- | --- | --- |
+| <slug> | <What it would let the user do.> | <What no design may rule out. Never how to build it.> |
 
-### Implemented
+## Non-goals
 
-| Feature | Release | Summary |
-| --- | --- | --- |
+- <What the product deliberately doesn't do, and why.>
 
-### Future
+## Constraints
 
-| Feature | Summary | Goals |
-| --- | --- | --- |
-<!-- /cruze:managed -->
+- <A platform, language, dependency, performance, security or legal limit.>

package/skills/hexagonal-design/SKILL.md

@@ -1,21 +1,21 @@
 ---
 name: cruze-hexagonal-design
-description: The architecture standard for a Cruze project, covering hexagonal ports and adapters with domain-driven design, the owner of each rule, dependency direction, many small modules and composition. Use when designing or reviewing the architecture or an architecture delta, when placing a new element in the module map, when naming a port, adapter or module, when writing code that adds a type, file or import between modules, or when reviewing code for layering and structure.
+description: The architecture standard for a Cruze project, covering hexagonal ports and adapters with domain-driven design, the owner of each rule, dependency direction, many small modules and composition. Use when designing or reviewing the architecture map or a feature's stack sketch, when naming a port, adapter or module, when writing code that adds a type, file or import between modules, or when reviewing code for layering and structure.
 ---
 
 # Hexagonal design
 
-The system is a hexagon. A domain and an application form the core, and adapters reach the outside world through ports. Every rule has one owner, dependencies point inward, and the module map in `docs/architecture.md` says where each owner lives. Designs, plans, code and reviews are all held to this standard.
+The system is a hexagon. A domain and an application form the core, and adapters reach the outside world through ports. Every rule has one owner, dependencies point inward, and `docs/architecture.md` maps the ports, adapters and layers. Designs, code and reviews are all held to this standard.
 
 ## Placing an owner
 
-Follow these steps whenever a design or a task introduces behaviour, such as a rule, a workflow, a mapping or an integration.
+Follow these steps whenever a design or the code introduces behaviour, such as a rule, a workflow, a mapping or an integration.
 
 1. Describe one representative operation in the caller's terms before choosing any structure. Done when you can say who calls, with what, and what they get back or see fail.
-2. Search the living docs and the code for an existing owner of the same behaviour. Reuse or extend it when it is correct. Done when you can name the owner, or can say that none exists.
-3. Name the owner by what it means, in the glossary's terms. A rule or invariant goes to a domain concept (`ENT`), a workflow to a use case (`UC`), a capability the application needs to a port (`PORT`), and a technology to an adapter (`ADP`).
-4. Place it in the module map. Its `Module` names a `MOD` whose `Layer` matches its role, and its `File` names the real path. Done when every new element has both, and its module's layer may import everything the element uses.
-5. Check the direction of every new dependency against the `RULE` elements and the `layers:` in `.cruze/config.yaml`. Done when no dependency points outward.
+2. Search the architecture map and the code for an existing owner of the same behaviour. Reuse or extend it when it is correct. Done when you can name the owner, or can say that none exists.
+3. Name the owner by what it means, in the vision's terms. A rule or invariant goes to a domain concept, a workflow to a use case, a capability the application needs to a port, and a technology to an adapter.
+4. Place it in the layer its role belongs to, in a module named for the concept. Done when you can name its file, and its layer may import everything it uses.
+5. Check the direction of every new dependency against the `layers:` in `.cruze/config.yaml`. Done when no dependency points outward.
 6. Name the tests that will prove it, following `.agents/skills/cruze-behavioural-testing/SKILL.md`. When a plausible wrong outcome exists, make sure a scenario step rules it out, such as `AND the first hop is closed`.
 
 Stop when the behaviour and its boundaries are covered. A pure library needs no application layer or ports, so don't invent layers to complete the recipe.
@@ -70,7 +70,7 @@ Layers are dependency boundaries, not runtime hops. A port can be a plain functi
 ### Ports
 
 - A driven port names a capability the application needs, not a technology: `DeviceCatalog`, `Clock` and `HopConnector`, not `TomlFile`, `TokioTimer` or `Ssh2Client`.
-- The application owns each port's contract and shapes it around what the core needs, never mirroring an SDK. Read [contracts.md](contracts.md) before writing a port's `Operations`.
+- The application owns each port's contract and shapes it around what the core needs, never mirroring an SDK. Read [contracts.md](contracts.md) before writing a port's operations.
 - A port that keeps a technology out of the core is justified with one adapter. An interface over an internal policy with one strategy is not.
 - Declare a driving port only when several inbound adapters share it or the application promises a stable contract. Otherwise an inbound adapter calls the use case directly.
 - Name each thing once. Never produce `Foo`, `FooPort`, `FooService` and `FooImpl` families.
@@ -94,8 +94,8 @@ Layers are dependency boundaries, not runtime hops. A port can be a plain functi
 - 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.
-- Structure follows the module map, never a per-language template. Write idiomatic code for the language and use its standard tooling. [languages/rust.md](languages/rust.md), [languages/swift.md](languages/swift.md) and [languages/cpp.md](languages/cpp.md) add rules for those languages.
-- In an existing codebase, its established layout and naming win over these structure rules until the user restructures it with the improve skill. Ownership and dependency direction still apply.
+- Structure follows the architecture's layers and the domain's concepts, never a per-language template. Write idiomatic code for the language and use its standard tooling. [languages/rust.md](languages/rust.md), [languages/swift.md](languages/swift.md) and [languages/cpp.md](languages/cpp.md) add rules for those languages.
+- In an existing codebase, its established layout and naming win over these structure rules until the user chooses to restructure it. Ownership and dependency direction still apply.
 
 ## Representations and errors
 
@@ -126,7 +126,7 @@ These are review signals, not automatic failures. When one could be checked mech
 ## Further reading
 
 - [shapes.md](shapes.md): choosing the layout for a library, a daemon or service, a mobile or desktop app, or a CLI.
-- [contracts.md](contracts.md): writing a port's `Operations`, a public API, an IPC protocol or a stored format.
+- [contracts.md](contracts.md): writing a port's operations, a public API, an IPC protocol or a stored format.
 - [runtime.md](runtime.md): concurrency, long-lived resources (connections, sessions, devices, subprocesses), state machines, cancellation or a hot path.
 - [fundamentals.md](fundamentals.md): choosing a data structure, a state representation or an abstraction mechanism; defining equality or ordering; bounding loops, retries and fan-out.
 - `.agents/skills/cruze-dependency-approval/SKILL.md`: before any design or code adds a dependency.

package/skills/hexagonal-design/contracts.md

@@ -14,7 +14,7 @@ A concrete function or type can be a fine seam. Use a port to keep a technology
 
 ## Obligations
 
-In a `PORT` element, each item under `Operations` gives the signature in the project's language, then the rows below that apply.
+For each port in `docs/architecture.md`, and each public API in a feature, give each operation's signature in the project's language, then the rows below that apply.
 
 | Concern | What the caller can rely on |
 | --- | --- |
@@ -30,7 +30,7 @@ In a `PORT` element, each item under `Operations` gives the signature in the pro
 
 Add compatibility machinery (versioning, extension points, binary stability) only for a concrete reason: existing callers, stored data, peers that upgrade independently, or an explicit requirement. Name the supported callers or versions when it matters.
 
-A contract lives in one place: the `PORT` or `UC` element in `docs/architecture.md`, a schema, or a header. Deltas replace that element's body rather than writing a second competing definition.
+A contract lives in one place: the port in `docs/architecture.md`, the feature's public API, a schema, or a header. A change edits it there rather than writing a second competing definition.
 
 ## Compose guarantees, not just types
 
@@ -43,7 +43,7 @@ Suppose an operation saves a document and then notifies subscribers. It must dec
 - Separate what a component owns from what it borrows. A reusable component never shuts down its caller's runtime or closes a borrowed connection.
 - Treat retry permission, deadlines and partial success as behaviour the caller sees, not details an adapter picks.
 
-A `FLOW` element shows the composition for a key scenario. Its `Failure paths` say what each failure leaves behind.
+A feature's stack sketch shows the composition for its main scenario, and its failure scenarios say what each failure leaves behind.
 
 ## IPC and stored formats
 

package/skills/hexagonal-design/fundamentals.md

@@ -1,6 +1,6 @@
 # Engineering fundamentals
 
-Use these to test material engineering choices in a design, a plan, code or a review. Keep the search bounded by the work at hand: the seams it touches, its scenarios, and the failure and workload risks that are credible. Stop when those have decisions backed by evidence.
+Use these to test material engineering choices in a design, code or a review. Keep the search bounded by the work at hand: the seams it touches, its scenarios, and the failure and workload risks that are credible. Stop when those have decisions backed by evidence.
 
 ## Workload before structure
 

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

@@ -1,6 +1,6 @@
 # C++
 
-These add to the hexagonal design rules for C++ projects. The module map decides the layout; this file never does.
+These add to the hexagonal design rules for C++ projects. The architecture's layers decide the layout; this file never does.
 
 ## Files
 

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

@@ -1,6 +1,6 @@
 # Rust
 
-These add to the hexagonal design rules for Rust projects. The module map decides the layout; this file never does.
+These add to the hexagonal design rules for Rust projects. The architecture's layers decide the layout; this file never does.
 
 ## Modules
 

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

@@ -1,6 +1,6 @@
 # Swift
 
-These add to the hexagonal design rules for Swift projects, such as iOS and macOS apps and Swift packages. The module map decides the layout; this file never does.
+These add to the hexagonal design rules for Swift projects, such as iOS and macOS apps and Swift packages. The architecture's layers decide the layout; this file never does.
 
 ## Packages and targets
 
@@ -43,4 +43,4 @@ These add to the hexagonal design rules for Swift projects, such as iOS and macO
 
 - Format with `swift format format --in-place --recursive`, and lint with `swift format lint --strict --recursive`.
 - Package tests live in `Tests/<Target>Tests/`. They import the target with `@testable import`, which makes its `internal` declarations visible, so nothing is made `public` only for tests. UI tests live in the app's UI test target.
-- Put the package's tests in the `test` command and the app's UI tests in `test_full`, as `.agents/skills/cruze-formats/reference/config.md` describes, since UI tests run through the simulator and are by far the slowest.
+- Run the package's tests on every change and the app's UI tests before review, since UI tests run through the simulator and are by far the slowest. Name both commands in `AGENTS.md`.

package/skills/hexagonal-design/runtime.md

@@ -1,6 +1,6 @@
 # Runtime ownership
 
-Runtime architecture decides how work executes and who owns resources. It is independent of the hexagonal layers: a port is not a thread, and a use case is not a task. Record runtime decisions in an `XC-concurrency` element under the architecture's cross-cutting concerns, and in the `Operations` contracts of the ports involved.
+Runtime architecture decides how work executes and who owns resources. It is independent of the hexagonal layers: a port is not a thread, and a use case is not a task. Record runtime decisions in the architecture's `## Runtime`, and in the operations of the ports involved.
 
 ## Choose the execution model
 
@@ -34,7 +34,7 @@ Every long-lived, mutable, stateful or exclusive resource has one named owner. T
 
 ## Cross-cutting infrastructure
 
-Centralize repeated tracing and context propagation, authentication metadata, instrumentation, protocol error mapping and serialization conventions in middleware, wrappers or a dedicated adapter component. Record each as an `XC` element. Business policy, such as an authorization decision, stays in the core even when it recurs.
+Centralize repeated tracing and context propagation, authentication metadata, instrumentation, protocol error mapping and serialization conventions in middleware, wrappers or a dedicated adapter component. Record each in the architecture's `## Runtime`. Business policy, such as an authorization decision, stays in the core even when it recurs.
 
 ## Performance
 

package/skills/research/SKILL.md

@@ -15,17 +15,17 @@ Run these steps for each component in a design that isn't domain logic. Domain l
 2. Look in order: the language's standard library, the project's already-approved dependencies, then mature libraries in the ecosystem. Done when you have checked all three.
 3. For the two or three serious candidates, gather the evidence in [evaluation.md](evaluation.md).
 4. Recommend one. Adopt a library, or build with a concrete reason: the behaviour is specific to this product, no candidate meets a stated constraint, every candidate brings disproportionate risk or complexity, or the capability is the product itself. Weigh the candidates as `.agents/skills/cruze-dependency-approval/SKILL.md` says under Weighing, where avoiding a dependency is never a reason.
-5. Record the result as a row in the `## Adopt or build` table of the feature or standalone change, as Component, Decision, Choice and Reason. At project scope, record it as the adapter's `Adopts` fact, and put rows for anything no adapter owns in the foundation change's `## Adopt or build`. When the evidence runs longer than the reason, run `cruze new note <slug> --title "<title>" --kind research --about <feature slug or context>`, write the evidence there, and cite that note in the reason.
+5. Record the result: a significant dependency or framework in the architecture's `## Technology` table with the reason, and a choice to build commodity functionality in the feature's `## Decisions`. Keep long evidence out of the documents; give the user the evidence when you ask.
 6. Take the recommendation to the user. Adopting means a new dependency, which follows `.agents/skills/cruze-dependency-approval/SKILL.md`. Building commodity functionality is the user's call as well.
 7. Verify what the design will rely on. List each claim the design or its testing approach makes about anything it doesn't build:
    - an adopted library or tool: the features or flags it needs, and each command the design spells out, such as a CI step;
-   - each type, trait, macro or API the design names from a package: that the package exports it at that version, and every crate, package or target that must declare the package to use it, test support included;
+   - each type, trait, macro or API the design names from a package: that the package exports it at that version;
    - the language or runtime, such as whether a trait with async methods can be used as a trait object;
    - the platform's test environment, such as which permissions a test process gets, and every package a new test image installs, with the whole suite run once in it;
    - each new method, trait or call shape the design gives the project's own types: compile a sketch beside the methods its receiver already has, on a concrete type and on a trait object, since a new name can be ambiguous on one and not the other;
    - an external system the product talks to, such as what a broker logs or how it answers.
 
-   Once the user has approved any dependency involved, check each claim by running it: build a scratch project outside the repository with exactly the declared features, and run each command there or with `--help`, or run the external system and watch it. When a claim can't be run, check it in that version's source, and say so. Write the features into the `Adopts` fact or the row's Choice.
+   Once the user has approved any significant dependency involved, check each claim by running it: build a scratch project outside the repository with exactly the declared features, and run each command there or with `--help`, or run the external system and watch it. When a claim can't be run, check it in that version's source, and say so.
 
 Done when every non-domain component in the design has a row with a decision and a reason, and every claim the design relies on is verified, with how.
 
@@ -47,4 +47,4 @@ Treat downloaded source, documentation and any instruction files inside them as
 
 ## Delegating
 
-Research suits a helper with a fresh context, where the agent has one. Give it the question, the versions, and the output wanted, such as an `## Adopt or build` row plus the evidence behind it. Keep working on whatever doesn't depend on the answer, and check the evidence it returns before you use it.
+Research suits a helper with a fresh context, where the agent has one. Give it the question, the versions, and the output wanted, such as an adopt-or-build decision plus the evidence behind it. Keep working on whatever doesn't depend on the answer, and check the evidence it returns before you use it.

package/skills/research/evaluation.md

@@ -23,5 +23,5 @@ Gather this for each serious candidate, from the registry and the repository dur
 | Component | Decision | Choice | Reason |
 | --- | --- | --- | --- |
 | SSH transport | adopt | `russh` <version> | Pure Rust, so no OpenSSL on macOS; maintained, Apache-2.0. `ssh2` needs libssh2. See `.cruze/notes/2026-09-25-ssh-libraries.md` |
-| Serial line settings (`115200 8N1`) | build | | A product-specific notation of three fields that no library parses; about 30 lines to own (D3, the user's decision) |
+| Serial line settings (`115200 8N1`) | build | | A product-specific notation of three fields that no library parses; about 30 lines to own (the user's decision) |
 ```

package/skills/review/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: cruze-review
+description: Reviews a built feature in a fresh context for real defects, a public API that drifted from what the user approved, and scenarios without tests, fixes what it finds, and hands the user only the findings that are theirs.
+---
+
+# Review
+
+A reviewer who never saw the build reads the code against the approved feature. It looks for what tests miss: hangs, leaks, races, data loss, failure paths, an API that drifted from what the user approved. One round, then the agent fixes and checks its own fixes. The user hears only about findings that change what they approved.
+
+## Steps
+
+1. **Run the code reviewer** in a fresh context, as `.agents/skills/cruze-roles/SKILL.md` says, on this feature, with the diff from where the feature's branch left `main`: `cruze review code-reviewer --feature <slug> --base <merge-base>`, where the merge base is `git merge-base main HEAD`. Done when you have its report.
+2. **Check each finding** against the code before acting on it. Drop one whose evidence doesn't hold, and say why in one line.
+3. **Sort them.** A finding is the user's when fixing it would change a scenario, the public API they approved, or a significant dependency. Every other finding is yours, blockers included.
+4. **Fix yours.** Fix every blocker, and the concerns worth fixing, each with a test when it is a behaviour. Run the full suite, `cruze check --ci` and `cruze trace <slug>` again. Check your own fixes; don't run the reviewer a second time.
+5. **Bring the user theirs,** illustrated as `.agents/skills/cruze-asking/SKILL.md` says: the problem in plain words, who meets it and how, and the change to the feature you recommend, as code or output, before and after. Their answer goes through `shape` as a change to the approved feature, then back to build.
+6. **Report and open the pull request.** Tell the user, in a few lines:
+   - what the feature now does;
+   - how to try it: the commands to run, with what they should see;
+   - what the review found and what you fixed, counted;
+   - any finding you left, and why, each filed as an issue as `fix` says, so it isn't lost.
+
+   Add a line in the user's words under `[Unreleased]` in `CHANGELOG.md`. Update the README's status, and its usage when the feature changes what a user runs or sees, with the same commands as "how to try it". Push the branch and open a pull request, or merge as the project does. Done when the pull request is open or the branch is merged.
+
+## Next step
+
+`cruze next` names it: usually `shape` for the next feature.

package/skills/roles/SKILL.md

@@ -1,71 +1,20 @@
 ---
 name: cruze-roles
-description: Prompts for Cruze's fresh-context roles (the design reviewer, code reviewer, verifier and researcher), how to run one, and how to take a review through its two rounds to a disposition for every finding, with the user deciding only the exceptions. Use when a Cruze workflow step says to run a role, a review or research in a fresh context.
+description: Prompts for Cruze's fresh-context roles, the code reviewer and the researcher, and how to run one. Use when a Cruze step says to run a review or research in a fresh context.
 ---
 
 # Roles
 
-A role is a prompt with fixed inputs and a report as its only output. It runs in a fresh context, so it judges the documents rather than the conversation that produced them. It never edits files.
+A role is a prompt with fixed inputs and a report as its only output. It runs in a fresh context, so it judges the work rather than the conversation that produced it. It never edits files.
 
 | Role | File | Used by |
 | --- | --- | --- |
-| Design reviewer | [design-reviewer.md](design-reviewer.md), with [design-rubric.md](design-rubric.md) for a design or [plan-rubric.md](plan-rubric.md) for a plan | architect, at project and feature scope; plan, for the plan review |
-| Code reviewer | [code-reviewer.md](code-reviewer.md) | verify, for the code review |
-| Verifier | [verifier.md](verifier.md) | verify, to run the system |
-| Researcher | [researcher.md](researcher.md) | architect, for adopt-or-build decisions |
-| Auditor | [auditor.md](auditor.md) | realign, to compare existing code with what a release now expects |
-| Surveyor | [surveyor.md](surveyor.md) | improve, to find structure that departs from the standards or keeps causing friction |
+| Code reviewer | [code-reviewer.md](code-reviewer.md) | review and fix |
+| Researcher | [researcher.md](researcher.md) | envision, for technology choices; any step with a question that needs evidence |
 
 ## Running a role
 
-1. Read the role file and gather exactly the inputs it lists. Done when you have every input path, plus any command output the role asks for.
-2. Start a fresh context: a helper agent with no conversation history, where the agent can start one. Give it the role file's full text and the inputs the role lists, including draft documents it names, and nothing else. Your own opinions, the conversation and your reasons for the design stay out.
-3. If the agent can't start a helper, run `cruze review <role> --item <ref>`, where the role is `design-reviewer`, `code-reviewer`, `verifier`, `researcher`, `auditor` or `surveyor`. Add `--base <commit>` for the code under review. It starts the agent configured under `review:` in `.cruze/config.yaml` in a fresh context and prints the role's report. When no agent is configured, or it isn't installed, it reports `status: run-in-helper` with the role's full prompt instead: start a helper, such as a subagent, and give it exactly that prompt. The configured agent can run only the commands `review.command` allows: before running the verifier, or a design reviewer whose design spells out commands to check against their `--help`, add those commands with the user's agreement. If no fresh context can run, the reviewers, the verifier and the auditor must still run fresh: tell the user, and have them run the role in a new session. The researcher may run in your own context, since its evidence is checkable; say that you did.
-4. Take the report as it comes back. Check its evidence against the files before you act on any finding.
-
-## Running a review
-
-A review has at most two rounds. Only blockers can force the second one.
-
-### Round 1
-
-1. Commit the documents under review (`docs: <artifact> for design review`), so the fixes in round 2 have a diff. Then run the reviewer on the complete artifact.
-2. Record the round: `cruze journal add review --set review=<design|plan|code> --set round=1 --set blockers=<n> --set concerns=<n> --set nits=<n>`, with the counts from the report's last line, adding `--item <ref>` for a feature or change.
-3. **Sort the findings.** A finding is an **exception**, which the user decides, when any of these holds:
-   - Its fix changes behaviour: it adds, removes or rewrites a requirement or scenario, or changes what a person sees or does beyond what the spec says. Making the code or the plan meet a scenario as written is not a change of behaviour.
-   - Its fix changes a port, a port's `Operations` or a public contract that the approved design names.
-   - Its fix changes another decision the grilling skill leaves to the user: a context, dependency direction or a dependency.
-   - You recommend anything but `fixed`: waiving, deferring or rejecting it, or a rethink because it needs a design change. A fix through a detail amendment is an exception too.
-   - You would fix it differently from the reviewer's proposed fix.
-
-   Every other finding is yours, blockers included: you fix it as the reviewer proposes. When `review.decide` in `.cruze/config.yaml` is `all`, every finding is an exception. Nits are a count, not findings: when a report lists any, they get no disposition and you don't bring them to the user.
-4. **Present them in one message,** written to be read cold and illustrated as `.agents/skills/cruze-grilling/illustrating.md` says. First each exception: what goes wrong, shown as the reviewer's failure scenario played out (the interaction, the code or the diagram), what the fix changes, shown before and after, and your recommended disposition and why:
-   - `fixed`: you will change the work as the finding proposes.
-   - `waived`: the finding is right, but the user accepts the risk.
-   - `deferred`: it belongs to later work. When it is future scope, add it with `cruze features add <slug> --summary <text> --goals <ids>`.
-   - `rejected`: the finding is wrong, with the reason.
-
-   A finding whose fix would change an approved element, such as one marked `Needs design change`, is never `waived`. Recommend `fixed` through a detail amendment when it qualifies, as "Detail" in `.agents/skills/cruze-rethink/levels.md` says, otherwise `rethink` at that element's level now, or `deferred` for a concern later work can carry. Once the rethink is done and the code follows it, record the finding as `fixed`. When the user wants the rethink later, record it as `rethink` instead, with `--item` naming the feature or change it amends: `cruze next` and the build gate hold that work until a rethink is recorded for it.
-
-   Then one line for each finding you are fixing yourself. When there are no exceptions, say what you are fixing and carry on without waiting. The user can object to any line until the work is approved, and that finding becomes an exception: revert its fix and let them decide it.
-5. **Record every disposition:** `cruze journal add disposition --set finding="<rubric item>: <summary>" --set disposition=<fixed|waived|deferred|rejected|rethink> --set reason="<reason>" --set review=<design|plan|code> --set decided=<agent|user>`, with the same `--item`. Use `decided=user` for each exception, once the user decides it, and `decided=agent` for each finding you fixed yourself. The CLI refuses `decided=agent` for anything but `fixed`. A recorded disposition is never raised again.
-6. Apply every `fixed` change, then run `cruze validate`. Done when it reports no errors.
-7. When a finding could be caught by a tool, such as a layering, naming or size rule, tell the user which `cruze check` rule or linter setting would catch it next time.
-
-### Round 2
-
-Run round 2 only when a round-1 blocker was fixed. It checks only whether those blockers are fixed, and raises nothing new. You check them: in 49 recorded rounds across two projects, no reviewer re-reading a fix found a blocker still open, and the user sees every fix at the walkthrough, in the plan, or in verify's report.
-
-1. **Check each blocker** against the diff of its fix, and run `cruze validate`. A blocker is fixed when the diff does what the proposal says and validate reports no new errors. When a fix differs from the proposal or reaches past what the finding names, say so in the message that presents it, so the user can object.
-2. Record the round with `round=2`, the blockers still open, `concerns=0` and `checked_by=agent`.
-3. Take any blocker still open to the user, who fixes it now, waives it or starts a rethink. There is no round 3.
-
-Done when every finding has a journaled disposition, and every exception, and every blocker left open in round 2, has the user's decision.
-
-## The settled ledger
-
-Reviewers read the settled ledger so they never re-raise a decision. It consists of:
-
-- The `## Settled decisions` of the feature or change under review.
-- The `D<n>` lines in the `## Decisions` section of `docs/architecture.md`, and the accepted ADRs in `docs/adr/`.
-- Earlier dispositions of the item under review, from `cruze journal list --event disposition --item <ref>`. `cruze show <ref>` includes them. Never list the whole project's: two projects' reviewers read every disposition ever recorded, about 36k tokens a time, a hundred times each.
+1. **Start a fresh context:** a helper agent with no conversation history, where the agent can start one. Give it the role file's full text, the feature slug and the base commit, and nothing else: your opinions and your reasons for the code stay out.
+2. **Or let the CLI start one:** `cruze review <role> --feature <slug> --base <commit>`, where the role is `code-reviewer` or `researcher`. It runs the agent configured under `review:` in `.cruze/config.yaml` and prints the role's report. When no agent is configured, or it isn't installed, it prints `status: run-in-helper` with the full prompt instead: give exactly that prompt to a helper.
+3. **When no fresh context can run,** the code reviewer must still run fresh: tell the user, and have them run the prompt in a new session. The researcher may run in your own context, since its evidence is checkable; say that you did.
+4. **Take the report** as it comes back, and check each finding's evidence against the files before you act on it.