@printpractical/cruze 0.0.13 → 0.0.15

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. Correct the documents where they no longer match the code, and show the user each change to an approved one with your report, for them to approve. 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.

package/skills/roles/code-reviewer.md

@@ -1,38 +1,30 @@
 # Code reviewer
 
-You review the code a change adds, before it lands. You work in two lanes. The spec lane asks whether the code does what the change promised, and nothing else. The architecture lane asks whether it sits where the design put it and is built the way the project's standards require. You report findings, and you edit nothing.
+You review the code of one feature before it lands, in a fresh context. You ask two things: does the code do what the user approved, and will it hold up when it runs. You report findings, and you edit nothing.
 
 ## Inputs
 
-- The change's `change.md`, and the output of `cruze show <ref>`: the elements it builds, the scenarios it delivers, the settled decisions and the ledger. Read an element it lists as cited only when the diff calls it, with `cruze show <ID>`.
-- The diff under review, from `git diff <base>` for the base commit you are given. When the base is where an earlier verify stopped, review older code only where the diff changes what it does.
-- The ADRs in `docs/adr/`, and the specs in `docs/specs/` for the capabilities the change touches.
-- The references `cruze show` lists, at the sections the change's elements cite.
-- The settled ledger, as `.agents/skills/cruze-roles/SKILL.md` defines it, with the output of `cruze journal list --event disposition --item <ref>`.
-- The deviations the change recorded, from `cruze journal list --event deviation --item <ref>`.
-- The output of `cruze check` and `cruze trace --change <ref>`.
+- The feature file in `docs/features/`: its scenarios, public API, stack sketch and decisions. This is what the user approved.
+- The diff under review, from `git diff <base>` for the base commit you are given.
+- `docs/architecture.md`, at the ports, runtime and layers the diff touches.
+- The output of `cruze check` and `cruze trace <slug>`.
 - The standards: `.agents/skills/cruze-hexagonal-design/SKILL.md`, its language file for the project's language when one exists, `.agents/skills/cruze-behavioural-testing/SKILL.md` and `.agents/skills/cruze-dependency-approval/SKILL.md`.
 
+Run the project's tests and lints, one plain command at a time, with no pipes, `&&`, `;` or redirects: an agent's allowed commands match only a plain command. When a command is refused, say so in your report.
+
 ## Rubric
 
 Review against these items and nothing else. Each finding names one.
 
-### Spec lane
-
-1. **Scenarios.** Every scenario the change delivers is implemented, and has a test that carries its ID, drives the seam the test plan names, and takes its expected values from the scenario.
-2. **Failures.** Each failure scenario produces the error it specifies and leaves the state it specifies. Wire formats, codes and behaviour that a reference governs follow the section the design cites.
-3. **Scope.** The code adds no behaviour the change's scope doesn't deliver, and no public item, variant or operation that only a later change uses. Unrequested or early code is a finding, even when it looks useful or the next change needs it.
-4. **Protected tests.** No behaviour, contract or smoke test for an approved scenario, port or flow was weakened, skipped or deleted without a delta that changes its subject.
-
-### Architecture lane
-
-5. **Placement.** Every file the diff adds or changes is where the architecture puts its owner, and matches the task's file targets or a recorded deviation.
-6. **Direction.** Dependencies point inward. No technology type crosses a port. Inbound adapters hold no domain rules or workflow.
-7. **Size.** No file holds two responsibilities, and none passes its budget without a recorded exception. No file was split by length alone, leaving one responsibility across files, and no code is bent to fit a budget, such as a type alias, a string where an error type belongs, types merged or a function placed away from its owner to stay under a limit.
-8. **Idiom.** The code is idiomatic for the language, uses its standard tooling, and follows the language file's rules, including where tests live. Tests reuse the fixtures and harnesses in the test support module rather than redefining them. Each `expect`, `unwrap` or panic in the diff has a reason its case can't happen; one a caller, the clock or a concurrent call can reach is a finding.
-9. **Libraries.** Nothing hand-writes what a mature library does without a recorded `build` decision, and every new dependency has a recorded approval. No code works around a dependency or a feature: hand-written code, a shell command or a less idiomatic construct chosen because the clean one needs a dependency is a finding.
-10. **Contracts.** Each adapter honours its port's `Operations`, and each fake passes the same contract tests as the real adapter.
-11. **Deviations.** Each deviation the change recorded is a choice build may make on its own: a private helper or a new file inside the owner's module, a `check.exceptions` entry, a fixture in the test support module, or two tasks swapped. A deviation that added an element, port operation or scenario, wrote a file outside the owner's module, changed an approved scenario's behaviour or its test, worked around a dependency or a feature, or settled a limit, timeout, message or error case the design doesn't give, needed a design amendment: a blocker, with `Needs design change` naming the element.
+1. **Scenarios.** Every scenario is implemented and has a test that carries its ID, drives a public seam, and takes its expected values from the scenario. Each failure scenario produces the message and leaves the state it specifies.
+2. **Public API.** What the code exposes matches the feature's public API section: names, types, errors, commands and output. Anything public it doesn't list is a finding.
+3. **Runtime.** Follow each request, message and event from its source to its consumer through every task, channel and queue. Look for what tests rarely reach: a hang, a spin, a leak of a task, handle or memory, a race, unbounded growth, a full queue holding up unrelated work, a lost result across a reconnect, shutdown that waits forever or drops work it promised to finish.
+4. **Failures.** Each external call's failure is handled as the feature and the architecture say: disks, networks, peers and user mistakes. Nothing is silently swallowed.
+5. **Ports and adapters.** Dependencies point inward and match the layers. No technology type crosses a port. Inbound adapters hold no domain rules. Each fake passes the same contract tests as its real adapter.
+6. **Tests.** No test was weakened, skipped or deleted. Tests drive behaviour through public interfaces rather than restating what a fake was told.
+7. **Idiom.** The code is idiomatic for the language and follows its language file. Each `expect`, `unwrap` or panic has a reason its case can't happen.
+8. **Libraries.** Nothing hand-writes what a mature library does, and every significant dependency is in the architecture or approved.
+9. **Documents.** The feature's public API and stack sketch, and `docs/architecture.md` where the diff touches it, match the code: a port, operation, type, flag or claim the documents state that the code doesn't bear out, or the reverse.
 
 ## Findings
 
@@ -42,17 +34,15 @@ Each finding has this shape:
 ### <n>. <rubric item>: <one-line summary>
 - Severity: blocker | concern
 - Evidence: <path:line, quoting the code>
-- Failure scenario: <what goes wrong, concretely, when this runs>
+- Failure scenario: <who meets it, how, and what goes wrong>
 - Proposed fix: <the specific change>
-- Needs design change: <the approved element whose text the fix must change, such as a port's `Operations`, or `no`>
+- Changes what the user approved: <the scenario or public API the fix changes, or no>
 ```
 
-- A **blocker** means a scenario fails or is untested, a protected test was weakened, a layering rule is broken, an unapproved dependency was added, or an adapter can't honour its port's `Operations`. A failure is also a blocker when a user or client the design serves reaches it in ordinary use, their mistakes and failing disks, networks and peers included, and it loses or corrupts data, crashes, hangs, spins, or holds up someone else's work.
-- Everything else is a **concern**, even when its fix needs a design change, such as a failure only hand-made input reaches that harms only its sender: in one change, such cases were the only blockers of two verifies in a row. Say who reaches the failure, and how.
-- List every blocker. List at most 5 concerns, or one per 5 tasks of the change when that is more, the most important first. Count the rest as nits: give only their number, never their text. Report only what would go wrong: no concerns is a valid report, and a small change usually has few.
-- Drop any finding that contradicts the settled ledger. The only exception is a blocker with new evidence, which you mark `New evidence:` and explain.
-- When a finding could be caught mechanically, add `Check: <the cruze check rule or linter setting that would catch it>`.
+- A **blocker** is a scenario that fails or has no test, a public API that differs from the approved one, a broken layer rule, or a failure that someone using the product in an ordinary way reaches and that loses or corrupts data, crashes, hangs, spins, or holds up other work.
+- Everything else is a **concern**. Say who reaches it and how. A failure that only deliberately malformed input reaches, and that harms only its sender, is a concern.
+- List every blocker, and at most 5 concerns, the most important first. Count the rest as nits by number only. No findings is a valid report.
 
 ## Report
 
-Report the spec lane, then the architecture lane. End with one line: `Blockers: <n>. Concerns: <n>. Nits: <n>.` When a lane has no findings, give the evidence for its most important item.
+List the findings, then end with one line: `Blockers: <n>. Concerns: <n>. Nits: <n>.`

package/skills/roles/researcher.md

@@ -1,10 +1,10 @@
 # Researcher
 
-You find out whether mature libraries already provide the components a design needs, and you answer technical questions from primary sources. You report what you found, and you edit nothing in the project.
+You find out whether mature libraries already provide the components the architecture needs, and you answer technical questions from primary sources. You report what you found, and you edit nothing in the project.
 
 ## Inputs
 
-- The components to research. For each: the capability in one line, the requirements that matter, and the module that would own it.
+- The components to research. For each: the capability in one line, and the requirements that matter.
 - Or a question, with the version it applies to.
 - The constraints section of `docs/vision.md`.
 - The project's dependency manifests and lockfiles, if they exist.
@@ -25,7 +25,7 @@ For components, report one block each:
 | <component> | adopt or build | <package and version, when adopting> | <the deciding reason> |
 
 Evidence: <the evaluation table for the serious candidates, with sources and the date checked>
-New dependency: yes or no
+New dependency: no, yes, or significant with the reason
 Claims to verify: <each feature, flag or command the design would rely on, with where the source shows it>
 ```
 

package/skills/shape/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: cruze-shape
+description: Shapes one feature with the user before it is built, writing its behaviour as scenarios, its public API as code and a sketch of how it crosses the stack, and ends with the user's approval.
+---
+
+# Shape
+
+Shape is where the user decides what a feature does and what it looks like from outside, before any code exists. It produces one document, `docs/features/<slug>.md`, and one approval. Everything the user would otherwise discover at the end, such as an internal type they wouldn't have chosen or a thread they didn't expect, is shown here instead.
+
+Read `.agents/skills/cruze-asking/SKILL.md` and `.agents/skills/cruze-formats/SKILL.md`, and `.agents/skills/cruze-hexagonal-design/SKILL.md` with its language file.
+
+## Steps
+
+1. **Find the feature.** Run `cruze next`, or take the slug the user names. Read its row in the vision's Release table, `docs/architecture.md`, and the feature files of what it needs. Work on a branch named for the feature. Done when you know what the feature is for and what it builds on.
+2. **Start the document** with `cruze new feature <slug> --title "<title>"`, unless it exists.
+3. **Write the behaviour.** For the feature's intent, write the scenarios: the main case first, then each edge and each failure a user can meet, with concrete values. Each one is a Given, a When and a Then, in the user's words, with the exact message or output they see. Invent the edge cases a user would hit: empty input, a duplicate, the thing not there, the network gone, the limit reached.
+4. **Write the public API** as real code in the project's language: every public type, function, command, endpoint, message or file format this feature adds or changes, with its errors. For a command-line tool, the commands and their exact output. Write "No change." when the feature has none.
+5. **Sketch the stack.** A plain-text diagram of the main scenario crossing the stack: the inbound adapter, the use case, the domain, each port and the adapter behind it, marking what is new. Below it, one line per change to `docs/architecture.md`, such as a new port or a new runtime task, and make those changes there. Name any value the system's own components pass each other untyped or encoded, such as a JSON value, and any new thread, task or queue.
+6. **Check it yourself** against [self-check.md](self-check.md), and fix what it finds. Done when every item passes.
+7. **Ask what only the user can answer,** in at most one round, as the asking skill says. Write the answers in.
+8. **Show it.** In one message:
+   - what the feature does, in two sentences;
+   - each scenario in one line, as the user would see it;
+   - the public API as code;
+   - the stack sketch;
+   - the decisions you took, one line each.
+
+   End with: "Do you approve this feature, or what should change?" Apply changes, and say what moved. Done when the user approves.
+9. **Approve and commit.** Run `cruze approve <slug>`, then commit the feature file and any architecture change with a message such as `docs: shape <slug>`.
+
+## Changing an approved feature
+
+Shape also runs when build finds that a scenario or the public API must change. Edit the document, show the user exactly what changed, with the before and after as code or output, and approve again. `cruze status` shows the feature as edited until then.
+
+## Next step
+
+`build`, for the approved feature.

package/skills/shape/self-check.md

@@ -0,0 +1,12 @@
+# Self-check before showing a feature
+
+Read the feature as an implementer who never saw the conversation. Each "no" is a gap build would fill with a guess; fix it in the document.
+
+1. **Every failure has a scenario.** For each external call the feature makes, and each input a user gives, the scenarios say what the user sees when it fails: the message, the exit code or the screen, and what state is left behind.
+2. **Every number is written down.** Each timeout, limit, buffer size, retry count and poll interval the feature depends on has a value, in the scenario or the architecture's runtime.
+3. **Every queue says what happens when it is full.** For each channel, buffer or queue the feature adds: what a sender does when it is full, and which other work waits meanwhile. One slow peer holds up only its own work unless a decision says otherwise.
+4. **Shutdown and recovery are covered.** What happens to work in flight when the process stops, a connection drops, or a dependency comes back.
+5. **The public API is complete.** Every error a caller can meet is named in the code sketch. Nothing public exists only for a later feature.
+6. **The ports stay ports.** No technology type, such as a database row, an HTTP request or a JSON value, crosses into the domain or the use cases.
+7. **Nothing is built ahead of need.** Every type, field and operation in the sketch is used by one of this feature's scenarios. A future feature leaves room; it adds nothing now.
+8. **Each scenario can be tested** through a public interface, with the values it states.

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

@@ -34,36 +34,9 @@ export interface Options {
   text: boolean;
   title?: string;
   feature?: string;
-  roadmap?: string;
-  change?: string;
-  commit?: string;
-  summary?: string;
-  goals?: string;
-  reason?: string;
-  set: string[];
-  item?: string;
-  event?: string;
-  out?: string;
-  redact: boolean;
-  all: boolean;
-  file: string[];
   ci: boolean;
-  gate?: string;
-  override?: string;
-  overlap: boolean;
-  full: boolean;
-  replan: string[];
-  rebase: string[];
-  byAgent: boolean;
-  restampUnchanged: boolean;
-  index: boolean;
-  notes: boolean;
-  kind?: string;
-  about?: string;
-  round?: string;
   package?: string;
   base?: string;
-  blockers?: string;
 }
 
 export type Handler = (context: CliContext, args: string[], options: Options) => Promise<CommandResult>;

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

@@ -1,32 +1,19 @@
 import { posix } from "node:path";
 import { checkCode, traceTests } from "../../../../app/use_cases/check_code.ts";
-import { landChange } from "../../../../app/use_cases/land_change.ts";
 import type { CliContext, CommandResult, Options } from "../cli_context.ts";
 
 export async function runCheck(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
-  const files = [...options.file, ...args].map((file) => posix.normalize(posix.join(context.workingDirectory, file)));
+  const files = args.map((file) => posix.normalize(posix.join(context.workingDirectory, file)));
   const report = await checkCode(context, { ci: options.ci, ...(files.length === 0 ? {} : { files }) });
-  const lines = report.findings.map((f) => `${f.severity} ${f.path}${f.line === undefined ? "" : `:${f.line}`} ${f.message} [${f.rule}]${f.pending === true ? " (pending realign)" : ""}`);
+  const lines = report.findings.map((f) => `${f.severity} ${f.path}${f.line === undefined ? "" : `:${f.line}`} ${f.message} [${f.rule}]`);
   lines.push(`Checked ${report.checked} file(s): ${report.passed ? "passed" : "failed"}.`);
   return { json: report, human: lines.join("\n"), failed: !report.passed };
 }
 
-export async function runTrace(context: CliContext, _args: string[], options: Options): Promise<CommandResult> {
-  const report = await traceTests(context, { all: options.all, ...(options.change === undefined ? {} : { change: options.change }) });
+export async function runTrace(context: CliContext, args: string[]): Promise<CommandResult> {
+  const report = await traceTests(context, args[0]);
   const lines = report.missing.map((id) => `missing test for ${id}`);
-  lines.push(...report.unknown.map((u) => `${u.path}:${u.line} cites ${u.id}, which no spec or delta defines`));
+  lines.push(...report.unknown.map((u) => `${u.path}:${u.line} cites ${u.id}, which no feature defines`));
   lines.push(`Traced ${report.scenarios.length} scenario(s) for ${report.scope}: ${report.passed ? "passed" : "failed"}.`);
   return { json: report, human: lines.join("\n"), failed: !report.passed };
 }
-
-export async function runLand(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
-  const report = await landChange(context, args[0], options.override === undefined ? {} : { override: options.override });
-  const lines = [`Landed ${report.change}.`];
-  if (report.merged.length > 0) lines.push(`Merged into the living docs: ${report.merged.join(", ")}`);
-  if (report.built.length > 0) lines.push(`Now built: ${report.built.join(", ")}`);
-  if (report.removed.length > 0) lines.push(`Removed: ${report.removed.join(", ")}`);
-  if (report.restamped.length > 0) lines.push(`Re-stamped approvals: ${report.restamped.join(", ")}`);
-  if (report.unexcepted.length > 0) lines.push(`CI checks these again, now that the change realign scheduled them in has landed: ${report.unexcepted.join(", ")}`);
-  if (report.archivedTo !== undefined) lines.push(`Finished; archived to ${report.archivedTo}.`);
-  return { json: report, human: lines.join("\n") };
-}

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

@@ -1,9 +1,8 @@
-import { approveArtifact } from "../../../../app/use_cases/approve_artifact.ts";
-import { PROJECT_DOC_KINDS, createNote, createProjectDoc, type ProjectDocKind } from "../../../../app/use_cases/new_project_doc.ts";
-import { createWorkItem, type NewKind } from "../../../../app/use_cases/new_work_item.ts";
+import { approveDocument } from "../../../../app/use_cases/approve_document.ts";
+import { DOCUMENT_KINDS, createDocument, type DocumentKind } from "../../../../app/use_cases/new_document.ts";
 import { validate } from "../../../../app/use_cases/validate_project.ts";
 import type { Problem } from "../../../../domain/validation/problem.ts";
-import { UsageError, requireArgs, requireOption, type CliContext, type CommandResult, type Options } from "../cli_context.ts";
+import { UsageError, requireArgs, type CliContext, type CommandResult, type Options } from "../cli_context.ts";
 
 export async function runValidate(context: CliContext): Promise<CommandResult> {
   const report = await validate(context);
@@ -11,44 +10,19 @@ export async function runValidate(context: CliContext): Promise<CommandResult> {
   return { json: report, human: [...report.problems.map(formatProblem), summary].join("\n"), failed: !report.valid };
 }
 
-export async function runApprove(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
+export async function runApprove(context: CliContext, args: string[]): Promise<CommandResult> {
   requireArgs(args, ["document"]);
-  if (options.byAgent && options.restampUnchanged) throw new UsageError("--by-agent and --restamp-unchanged are alternatives");
-  const agent = options.byAgent ? "plan-review" : options.restampUnchanged ? "rethink" : undefined;
-  const report = await approveArtifact(context, args[0] ?? "", { replan: options.replan, rebase: options.rebase, ...(agent === undefined ? {} : { agent }) });
-  const lines = [`Approved ${report.artifact} (${report.hash.slice(0, 19)}), pinned to ${report.upstream.length} upstream element(s).`];
-  if (report.basis === "plan-review") lines.push("Approved for the user: its plan review closed with no blocker open.");
-  if (report.restamped !== undefined) lines.push(`Re-stamped for the user: its own design is unchanged, and only ${report.restamped.join(", ")} changed.`);
-  if (report.stamped.length > 0) lines.push(`Marked ${report.stamped.length} element(s) planned.`);
-  if (report.bound !== undefined) lines.push(`Bound the change to branch ${report.bound}.`);
-  if (report.replanned.length > 0) lines.push(`Set back to planned: ${report.replanned.join(", ")}.`);
-  if (report.rebased.length > 0) lines.push(`Accepted the current living text of: ${report.rebased.join(", ")}.`);
-  return { json: report, human: lines.join("\n") };
+  const record = await approveDocument(context, args[0] ?? "");
+  return { json: record, human: `Approved ${record.path} (${record.hash.slice(0, 19)}).` };
 }
 
 export async function runNew(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
   requireArgs(args, ["kind"]);
-  if (PROJECT_DOC_KINDS.includes(args[0] as ProjectDocKind)) {
-    const report = await createProjectDoc(context, args[0] as ProjectDocKind);
-    return { json: report, human: `Created ${report.path}` };
-  }
-  requireArgs(args, ["kind", "slug"]);
-  if (args[0] === "note") {
-    const report = await createNote(context, args[1] ?? "", requireOption(options.title, "--title"), requireOption(options.kind, "--kind"), requireOption(options.about, "--about"));
-    return { json: report, human: `Created ${report.path}` };
-  }
-  const kind = args[0] as NewKind;
-  if (!["feature", "change", "adr"].includes(kind)) {
-    throw new UsageError(`cruze new takes ${PROJECT_DOC_KINDS.join(", ")}, feature, change, adr or note, not "${args[0]}"`);
-  }
-  const report = await createWorkItem(context, {
-    kind,
-    slug: args[1] ?? "",
-    title: requireOption(options.title, "--title"),
-    ...(options.feature === undefined ? {} : { feature: options.feature }),
-    ...(options.roadmap === undefined ? {} : { roadmap: options.roadmap }),
-  });
-  return { json: report, human: `Created ${report.kind} ${report.ref} at ${report.path}` };
+  const kind = args[0] as DocumentKind;
+  if (!DOCUMENT_KINDS.includes(kind)) throw new UsageError(`cruze new takes ${DOCUMENT_KINDS.join(", ")}, not "${args[0]}"`);
+  if (kind === "feature") requireArgs(args, ["kind", "slug"]);
+  const report = await createDocument(context, kind, args[1], options.title);
+  return { json: report, human: `Created ${report.path}` };
 }
 
 export function formatProblem(problem: Problem): string {

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

@@ -18,6 +18,6 @@ export async function runInit(context: CliContext, _args: string[], options: Opt
   if (report.created.length > 0) lines.push(`Created: ${report.created.join(", ")}`);
   if (report.skipped.length > 0) lines.push(`Left untouched (already present): ${report.skipped.join(", ")}`);
   lines.push(...describeSkillInstall(report.skills));
-  lines.push("Next: open your coding agent in this repository and ask it what Cruze can do.");
+  lines.push("Next: open your coding agent in this repository and ask it to envision the project, with whatever you have: a sentence, a design document, notes.");
   return { json: report, human: lines.join("\n") };
 }

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

@@ -15,5 +15,6 @@ export function describeSkillInstall(report: InstallSkillsReport): string[] {
   if (from !== to) lines.push(`Recorded Cruze ${to} in .cruze/config.yaml${from === undefined ? "" : `, up from ${from}`}`);
   if (ci.repinned.length > 0) lines.push(`CI runs ${ci.repinned.join(", ")}`);
   for (const spec of ci.unrecognised) lines.push(`CI runs ${spec}, which Cruze can't move to ${to}; update .github/workflows/ci.yml yourself`);
+  for (const note of report.notes) lines.push(`Note: ${note}`);
   return lines;
 }

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

@@ -1,18 +1,11 @@
 import { runReview } from "../../../../app/use_cases/run_review.ts";
-import { readArgumentFile } from "../argument_files.ts";
-import { UsageError, requireArgs, type CliContext, type CommandResult, type Options } from "../cli_context.ts";
+import { requireArgs, type CliContext, type CommandResult, type Options } from "../cli_context.ts";
 
 export async function runReviewCommand(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
   requireArgs(args, ["role"]);
-  const round = options.round === undefined ? undefined : Number(options.round);
-  if (round !== undefined && round !== 1 && round !== 2) throw new UsageError("--round is 1 or 2");
-  if (options.blockers !== undefined && round !== 2) throw new UsageError("--blockers goes with --round 2");
-  const blockers = options.blockers === undefined ? undefined : await readArgumentFile(options.blockers);
   const report = await runReview(context, {
     role: args[0] ?? "",
-    ...(options.item === undefined ? {} : { item: options.item }),
-    ...(round === undefined ? {} : { round }),
-    ...(blockers === undefined ? {} : { blockers }),
+    ...(options.feature === undefined ? {} : { item: options.feature }),
     ...(options.base === undefined ? {} : { base: options.base }),
   });
   return { json: report, human: report.status === "reported" ? report.report : `${report.instruction}\n\n${report.prompt}` };

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

@@ -1,71 +1,24 @@
-import { checkBuildGate, findOverlaps, showStatus, suggestNext } from "../../../../app/use_cases/project_status.ts";
-import type { ApprovalStatus } from "../../../../domain/approvals/evaluate.ts";
-import { UsageError, type CliContext, type CommandResult, type Options } from "../cli_context.ts";
+import { showStatus, suggestNext } from "../../../../app/use_cases/project_status.ts";
+import type { NextStep } from "../../../../domain/next_step.ts";
+import type { CliContext, CommandResult } from "../cli_context.ts";
 
-export async function runStatus(context: CliContext, _args: string[], options: Options): Promise<CommandResult> {
-  if (options.override !== undefined && options.gate === undefined) throw new UsageError("--override goes with --gate build");
-  if (options.change !== undefined && !options.overlap) throw new UsageError("--change goes with --overlap");
-  if (options.gate !== undefined && options.overlap) throw new UsageError("--gate and --overlap are alternatives");
-  if (options.gate !== undefined) {
-    if (options.gate !== "build") throw new UsageError(`unknown gate "${options.gate}"; the only gate is build`);
-    const report = await checkBuildGate(context, options.override);
-    const human = report.passed
-      ? report.overridden ? `Build gate overridden and journaled:\n  ${report.reasons.join("\n  ")}` : "Build gate passed."
-      : `Build gate blocked:\n  ${report.reasons.join("\n  ")}`;
-    return { json: report, human, failed: !report.passed };
-  }
-  if (options.overlap) {
-    const report = await findOverlaps(context, options.change);
-    const human = report.overlaps.length === 0
-      ? `No other branch touches what ${report.change} touches.`
-      : report.overlaps.map((o) => `${o.branch}: ${o.item} also touches ${o.shared.join(", ")}`).join("\n");
-    return { json: report, human };
-  }
+export async function runStatus(context: CliContext): Promise<CommandResult> {
   const report = await showStatus(context);
-  const lines = [`Branch: ${report.branch ?? "(none)"}${report.active === undefined ? "" : `, building ${report.active}`}`];
-  for (const doc of report.documents) lines.push(describe(doc.artifact, doc));
-  for (const feature of report.features) {
-    lines.push(`${describe(`feature ${feature.ref}`, feature.approval)}${pendingNote(feature.rethinkPending)}`);
-    for (const change of feature.changes) {
-      const name = change.ref.split("/")[1] ?? change.ref;
-      lines.push(change.landed !== undefined ? `  ${name}: landed ${change.landed}` : `  ${describe(name, change.approval)}, tasks ${change.tasksDone}/${change.tasksTotal}${pendingNote(change.rethinkPending)}`);
-    }
+  const lines = report.documents.map((d) => `${d.path}: ${d.state}`);
+  for (const f of report.features) {
+    const needs = f.needs.length === 0 ? "" : `, needs ${f.needs.join(", ")}`;
+    const approval = f.approval === "missing" ? "" : `, ${f.approval}`;
+    lines.push(`${f.slug}: ${f.status}${approval}${f.scenarios === 0 ? "" : `, ${f.scenarios} scenario(s)`}${needs}${f.inRelease ? "" : " (not in the release)"}`);
   }
-  for (const change of report.standalone) lines.push(`${describe(`change ${change.ref}`, change.approval)}, tasks ${change.tasksDone}/${change.tasksTotal}${pendingNote(change.rethinkPending)}`);
-  const json = {
-    ...report,
-    documents: report.documents.map(compact),
-    features: report.features.map((f) => ({ ...f, approval: compact(f.approval), changes: f.changes.map((c) => ({ ...c, approval: compact(c.approval) })) })),
-    standalone: report.standalone.map((c) => ({ ...c, approval: compact(c.approval) })),
-  };
-  return { json, human: lines.join("\n") };
-}
-
-/** The state without the record's hashes: an agent reads status often, and the hashes were a third of each read. */
-function compact(status: ApprovalStatus): Omit<ApprovalStatus, "record"> & { approvedAt?: string; by?: string; basis?: string } {
-  const { record, ...rest } = status;
-  if (record === undefined) return rest;
-  return { ...rest, approvedAt: record.approvedAt, by: record.by, ...(record.basis === undefined ? {} : { basis: record.basis }) };
-}
-
-function pendingNote(findings: string[] | undefined): string {
-  return findings === undefined ? "" : `, ${findings.length} finding(s) waiting on a rethink`;
+  lines.push(`Next: ${describe(report.next)}`);
+  return { json: report, human: lines.join("\n") };
 }
 
-/** Every step starts a new session: one session that ran plan, build, verify and land reached 745k tokens of context. */
-const FRESH_SESSION = "Run it in a new session, so its context starts empty.";
-
-const BASIS: Record<string, string> = { "plan-review": " (by the agent, after its plan review)", rethink: " (re-stamped by the agent after a rethink)" };
-
-function describe(label: string, status: ApprovalStatus): string {
-  const byAgent = status.state === "approved" ? BASIS[status.record?.basis ?? ""] ?? "" : "";
-  const detail = status.changed.length > 0 ? ` (${status.changed.join(", ")})` : status.unjournaled === true ? " (no journal entry)" : byAgent;
-  return `${label}: ${status.state}${detail}`;
+export async function runNext(context: CliContext): Promise<CommandResult> {
+  const next = await suggestNext(context);
+  return { json: next, human: `Next: ${describe(next)}` };
 }
 
-export async function runNext(context: CliContext): Promise<CommandResult> {
-  const report = await suggestNext(context);
-  const describe = (s: { step: string; target?: string; reason: string }): string => `${s.step}${s.target === undefined ? "" : ` ${s.target}`}: ${s.reason}`;
-  const lines = [`Next: ${describe(report.next)}`, ...report.also.map((s) => `Also: ${describe(s)}`), FRESH_SESSION];
-  return { json: { ...report, session: FRESH_SESSION }, human: lines.join("\n") };
+function describe(step: NextStep): string {
+  return `${step.step}${step.target === undefined ? "" : ` ${step.target}`}: ${step.reason}`;
 }