@printpractical/cruze 0.0.13 → 0.0.14

package/skills/roles/code-reviewer.md

@@ -1,38 +1,29 @@
 # 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`.
 
+You may run the project's tests.
+
 ## 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.
 
 ## Findings
 
@@ -42,17 +33,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/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}`;
 }

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

@@ -1,14 +1,9 @@
 import type { Handler } from "./cli_context.ts";
-import { runCheck, runLand, runTrace } from "./commands/code.ts";
-import { runDiff } from "./commands/diff.ts";
+import { runCheck, runTrace } from "./commands/code.ts";
 import { runApprove, runNew, runValidate } from "./commands/documents.ts";
 import { runInit } from "./commands/init.ts";
 import { runInstall } from "./commands/install.ts";
-import { runRealign } from "./commands/realign.ts";
-import { runFeedback, runJournal } from "./commands/journal.ts";
-import { runAbandon, runFeatures, runRoadmap, runTask } from "./commands/progress.ts";
 import { runReviewCommand } from "./commands/review.ts";
-import { runShow } from "./commands/show.ts";
 import { runNext, runStatus } from "./commands/status.ts";
 
 /** A command, and the options it takes: one list, or one per subcommand for a command that has them. */
@@ -20,37 +15,15 @@ export interface Command {
 
 export const COMMANDS: Record<string, Command> = {
   init: { handler: runInit, options: ["name", "yes", "agent", "package"], usage: "init [--name <name>] [--yes] [--agent claude|other] [--package <npm spec>]   set up this repository and install the skills" },
-  install: { handler: runInstall, options: ["agent"], usage: "install [--agent <agent>]                         install or update the Cruze skills" },
-  validate: { handler: runValidate, options: [], usage: "validate                                          check every document against the formats" },
-  status: { handler: runStatus, options: ["gate", "override", "overlap", "change"], usage: "status [--gate build [--override <reason>]] [--overlap [--change <ref>]]" },
-  next: { handler: runNext, options: [], usage: "next                                              the step to run next on this branch, and why" },
-  diff: { handler: runDiff, options: [], usage: "diff <ref>                                        what changed upstream of a document since its approval, and whether its delta needs a rebase" },
-  show: {
-    handler: runShow,
-    options: ["index", "notes"],
-    usage: "show <ref> | show <ID>... | show --index [<context>] | show --notes [<target>]   a change's design, chosen elements, one line per element, or the notes and hand-offs for a target",
-  },
-  approve: {
-    handler: runApprove,
-    options: ["replan", "rebase", "by-agent", "restamp-unchanged"],
-    usage: "approve <vision|architecture|roadmap|ref|path> [--replan <ID>...] [--rebase <ID>...] [--by-agent|--restamp-unchanged]   record an approval of a document",
-  },
-  new: {
-    handler: runNew,
-    options: { vision: [], glossary: [], architecture: [], roadmap: [], feature: ["title", "roadmap"], change: ["title", "feature", "roadmap"], adr: ["title"], note: ["title", "kind", "about"] },
-    usage: "new <vision|glossary|architecture|roadmap> | new <feature|change|adr> <slug> --title <title> [--feature <ref>] [--roadmap <slug>] | new note <slug> --title <title> --kind <input|intake|explore|research> --about <subjects>",
-  },
-  task: { handler: runTask, options: { done: ["change", "commit"], deviation: ["change"], reopen: ["change"] }, usage: "task <done|deviation|reopen> <T#> [text] [--change <ref>] [--commit <sha>]" },
-  features: { handler: runFeatures, options: { add: ["summary", "goals"], update: ["summary"], drop: ["reason"] }, usage: "features <add|update|drop> <slug> [--summary <text>] [--goals <ids>] [--reason <text>]" },
-  roadmap: { handler: runRoadmap, options: { prune: [] }, usage: "roadmap prune                                     clear landed items from the roadmap status when a release closes" },
-  journal: { handler: runJournal, options: { add: ["set", "item"], list: ["event", "item", "all"] }, usage: "journal <add <event> --set key=value... [--item <ref>]|list [--event <event>] [--item <ref>] [--all]>" },
-  review: { handler: runReviewCommand, options: ["item", "round", "blockers", "base"], usage: "review <role> [--item <ref>] [--round 1|2 --blockers <file>] [--base <commit>]   run a role in a fresh agent context" },
-  feedback: { handler: runFeedback, options: { export: ["out", "no-redact"] }, usage: "feedback export [--out <file>] [--no-redact]" },
-  trace: { handler: runTrace, options: ["all", "change"], usage: "trace [--all] [--change <ref>]                    link scenarios to the tests that prove them" },
-  check: { handler: runCheck, options: ["file", "ci"], usage: "check [<file>...] [--ci]                          enforce layer rules and file budgets" },
-  abandon: { handler: runAbandon, options: ["reason"], usage: "abandon <ref> --reason <text>                     archive a feature or standalone change that stops for good" },
-  land: { handler: runLand, options: ["override"], usage: "land [<ref>] [--override <reason>]                merge a verified change into the living docs" },
-  realign: { handler: runRealign, options: { status: ["full"], done: ["change"] }, usage: "realign <status [--full]|done [--change <ref>]>    what the installed Cruze expects of existing code, and recording that the code meets it" },
+  install: { handler: runInstall, options: ["agent"], usage: "install [--agent <agent>]                 install or update the Cruze skills" },
+  new: { handler: runNew, options: { vision: [], architecture: [], feature: ["title"] }, usage: "new vision | new architecture | new feature <slug> [--title <title>]   start a document from its template" },
+  validate: { handler: runValidate, options: [], usage: "validate                                  check every document against the formats" },
+  approve: { handler: runApprove, options: [], usage: "approve <vision|architecture|feature slug>   record that the user approved a document as it reads now" },
+  status: { handler: runStatus, options: [], usage: "status                                    each document's approval, each feature's progress, and the next step" },
+  next: { handler: runNext, options: [], usage: "next                                      the step to run next, and why" },
+  trace: { handler: runTrace, options: [], usage: "trace [<feature slug>]                    link scenarios to the tests that carry their IDs" },
+  check: { handler: runCheck, options: ["ci"], usage: "check [<file>...] [--ci]                  enforce layer rules and file budgets" },
+  review: { handler: runReviewCommand, options: ["feature", "base"], usage: "review <code-reviewer|researcher> [--feature <slug>] [--base <commit>]   run a role in a fresh agent context" },
 };
 
 export const USAGE = `Usage: cruze <command> [options]

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

@@ -28,36 +28,9 @@ export function parseCommand(argv: string[]): ParsedCommand {
         help: { type: "boolean", short: "h", default: false },
         title: { type: "string" },
         feature: { type: "string" },
-        roadmap: { type: "string" },
-        change: { type: "string" },
-        commit: { type: "string" },
-        summary: { type: "string" },
-        goals: { type: "string" },
-        reason: { type: "string" },
-        set: { type: "string", multiple: true, default: [] },
-        item: { type: "string" },
-        event: { type: "string" },
-        out: { type: "string" },
-        "no-redact": { type: "boolean", default: false },
-        all: { type: "boolean", default: false },
-        file: { type: "string", multiple: true, default: [] },
         ci: { type: "boolean", default: false },
-        gate: { type: "string" },
-        override: { type: "string" },
-        overlap: { type: "boolean", default: false },
-        full: { type: "boolean", default: false },
-        round: { type: "string" },
         package: { type: "string" },
-        replan: { type: "string", multiple: true, default: [] },
-        rebase: { type: "string", multiple: true, default: [] },
         base: { type: "string" },
-        blockers: { type: "string" },
-        "by-agent": { type: "boolean", default: false },
-        "restamp-unchanged": { type: "boolean", default: false },
-        index: { type: "boolean", default: false },
-        notes: { type: "boolean", default: false },
-        kind: { type: "string" },
-        about: { type: "string" },
       },
     });
   } catch (error) {
@@ -71,39 +44,12 @@ export function parseCommand(argv: string[]): ParsedCommand {
     agent: values.agent,
     json: values.json,
     text: values.text,
-    set: values.set,
-    redact: !values["no-redact"],
-    all: values.all,
-    file: values.file,
     ci: values.ci,
-    overlap: values.overlap,
-    full: values.full,
-    replan: values.replan,
-    rebase: values.rebase,
-    byAgent: values["by-agent"],
-    restampUnchanged: values["restamp-unchanged"],
-    index: values.index,
-    notes: values.notes,
     ...optional("name", values.name),
     ...optional("title", values.title),
     ...optional("feature", values.feature),
-    ...optional("roadmap", values.roadmap),
-    ...optional("change", values.change),
-    ...optional("commit", values.commit),
-    ...optional("summary", values.summary),
-    ...optional("goals", values.goals),
-    ...optional("reason", values.reason),
-    ...optional("item", values.item),
-    ...optional("event", values.event),
-    ...optional("out", values.out),
-    ...optional("gate", values.gate),
-    ...optional("override", values.override),
-    ...optional("round", values.round),
     ...optional("package", values.package),
     ...optional("base", values.base),
-    ...optional("blockers", values.blockers),
-    ...optional("kind", values.kind),
-    ...optional("about", values.about),
   };
   const given = [...new Set(tokens.flatMap((token) => (token.kind === "option" ? [token.name] : [])))];
   return { words: positionals, options, given, help: values.help, version: values.version };