@printpractical/cruze 0.0.3 → 0.0.5

package/skills/roles/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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. 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 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.
 ---
 
 # Roles
@@ -30,16 +30,26 @@ A review has at most two rounds. Only blockers can force the second one.
 
 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. Present every finding to the user with your recommended disposition and why:
-   - `fixed`: you will change the design as the finding proposes.
+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.
+   - 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.
+4. **Present them in one message.** First each exception, with 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 `deferred` or `waived`. Recommend `rethink` at that element's level now. Once the rethink is done and the code follows it, record the finding as `fixed`.
-4. The user decides each one. Record each decision: `cruze journal add disposition --set finding="<rubric item>: <summary>" --set disposition=<fixed|waived|deferred|rejected> --set reason="<reason>" --set review=<design|plan|code>`, with the same `--item`. A recorded disposition is never raised again.
-5. Apply every `fixed` change, then run `cruze validate`. Done when it reports no errors.
-6. 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.
+
+   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> --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
 
@@ -49,7 +59,7 @@ Run round 2 only when a round-1 blocker was fixed.
 2. Record the round with `round=2`.
 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 no blocker is open without the user's decision.
+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
 

package/skills/roles/code-reviewer.md

@@ -46,7 +46,7 @@ Each finding has this shape:
 ```
 
 - 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 finding that needs a design change is a blocker. Everything else is a **concern**.
-- List every blocker. List at most 5 concerns, the most important first. Count the rest as nits without listing them.
+- 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 without listing them. 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>`.
 - In round 2, report only whether each round-1 blocker is fixed, as `fixed` or `open` with the reason. Raise nothing new.

package/skills/roles/design-reviewer.md

@@ -29,7 +29,7 @@ Review against these items and nothing else. Each finding names one.
    - each use case's `Output` and `Errors` against the `FLOW`s that serve it and the `XC` rules that apply to it;
    - each adapter's duties against the port it implements and the `XC` rules it follows;
    - each guarantee, such as "always fits" or "never returns", against the limits and failures that bound it.
-9. **Slicing.** Each change is a vertical slice that delivers scenarios end to end and can land on its own. The order respects `Depends on`, and the first change is the thinnest useful tracer bullet. A change `Builds` an element only when its delivered scenarios prove the whole body; an element whose duties arrive in several changes is split into elements that each arrive whole. `Depends on` names every earlier change that builds something this change's scenarios need. At project scope, the roadmap starts with the walking skeleton, and every goal in the release is covered.
+9. **Slicing.** Each change is a vertical slice that delivers scenarios end to end and can land on its own. The order respects `Depends on`, and the first change proves the design end to end. Each change carries enough work to be worth its own plan review, code review and verify: changes that build one or two elements each on the same adapters or screens, in a chain, are one change split too fine. A change that one verifier run can't hold is split too coarse. A change `Builds` an element only when its delivered scenarios prove the whole body; an element whose duties arrive in several changes is split into elements that each arrive whole. `Depends on` names every earlier change that builds something this change's scenarios need. At project scope, the roadmap starts with the walking skeleton, and every goal in the release is covered.
 10. **Ambiguity.** Name each point where a fresh implementer could reasonably build something different from what the user expects.
 
 ## Plan rubric
@@ -56,7 +56,7 @@ Each finding has this shape:
 ```
 
 - A **blocker** means building from the design as written would produce wrong behaviour, a layering violation or an untestable scenario. Two elements that contradict each other are always a blocker, because an implementer has to pick one. Everything else is a **concern**.
-- List every blocker. List at most 5 concerns, the most important first. Count the rest as nits without listing them.
+- List every blocker. List at most 5 concerns, or for a plan one per 5 tasks when that is more, the most important first. Count the rest as nits without listing them. Report only what would go wrong: no concerns is a valid report, and a small artifact 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>`.
 - In round 2, report only whether each round-1 blocker is fixed, as `fixed` or `open` with the reason. Raise nothing new.

package/skills/verify/SKILL.md

@@ -13,7 +13,7 @@ Verify answers one question: does this change work when someone uses it? Green t
 2. **Run the mechanical checks.** Run the project's format, lint, build and test commands from `commands:` in `.cruze/config.yaml`, then `cruze validate`, `cruze check --ci` and `cruze trace --change <ref>`. Quote each result. When one fails, fix the code in a commit and run them again. When a fix needs design, stop and offer `rethink`.
 3. **Check the dependencies.** Follow "Checking" in `.agents/skills/cruze-dependency-approval/SKILL.md` against the base commit. An unrecorded dependency is a blocker.
 4. **Run the verifier.** Run the verifier role from `.agents/skills/cruze-roles/SKILL.md` for the change. It must be able to build and run the system. When it runs through `cruze review`, check that `review.command` in `.cruze/config.yaml` allows the project's build and run commands, and add them with the user's agreement. Done when you have its report, with a result for every delivered scenario.
-5. **Review the code.** Run the review in the roles skill with the code reviewer, `review=code`, `--item <ref>` and the base commit. Fix each finding the user marks `fixed` in a commit, then check the fixes in round 2.
+5. **Review the code.** Run the review in the roles skill with the code reviewer, `review=code`, `--item <ref>` and the base commit. Fix each finding whose disposition is `fixed` in a commit, then check the fixes in round 2.
 6. **Write the manual test script** as `manual-test.md` in the change folder, following [manual-test.md](manual-test.md). Commit it.
 7. **Report.** Show the user four things:
    - The mechanical checks, one line each.

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

@@ -0,0 +1,29 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { UsageError } from "./cli_context.ts";
+
+// Files a person or agent names on the command line, such as a scratch file of review blockers or
+// the path for an exported bundle. They may be anywhere, unlike project files, and relative paths
+// resolve against the working directory.
+
+export async function readArgumentFile(path: string): Promise<string> {
+  try {
+    return await readFile(resolve(path), "utf8");
+  } catch (error) {
+    throw new UsageError(`cannot read ${path}: ${reason(error)}`);
+  }
+}
+
+export async function writeArgumentFile(path: string, text: string): Promise<void> {
+  try {
+    await mkdir(dirname(resolve(path)), { recursive: true });
+    await writeFile(resolve(path), text, "utf8");
+  } catch (error) {
+    throw new UsageError(`cannot write ${path}: ${reason(error)}`);
+  }
+}
+
+function reason(error: unknown): string {
+  if (error instanceof Error && "code" in error && typeof error.code === "string") return error.code;
+  return error instanceof Error ? error.message : String(error);
+}

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

@@ -29,6 +29,7 @@ export interface Options {
   yes: boolean;
   agent: string[];
   json: boolean;
+  text: boolean;
   title?: string;
   feature?: string;
   roadmap?: string;
@@ -51,6 +52,8 @@ export interface Options {
   full: boolean;
   replan: string[];
   rebase: string[];
+  byAgent: boolean;
+  restampUnchanged: boolean;
   round?: string;
   package?: string;
   base?: string;

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

@@ -0,0 +1,20 @@
+import { UsageError } from "./cli_context.ts";
+import type { Command } from "./commands.ts";
+
+/** Options every command takes. */
+const GLOBAL_OPTIONS = ["json", "text", "help", "version"];
+
+/**
+ * Refuses an option the command doesn't take, rather than ignoring it, so a caller never gets
+ * wider output than it asked for. An unknown subcommand is left to the handler to report.
+ */
+export function refuseUnknownOptions(name: string, args: string[], command: Command, given: string[]): void {
+  const sub = Array.isArray(command.options) ? undefined : args[0];
+  const taken = Array.isArray(command.options) ? command.options : sub === undefined ? undefined : (command.options as Record<string, readonly string[]>)[sub];
+  if (taken === undefined) return;
+  const refused = given.filter((option) => !GLOBAL_OPTIONS.includes(option) && !taken.includes(option));
+  if (refused.length === 0) return;
+  const which = sub === undefined ? `cruze ${name}` : `cruze ${name} ${sub}`;
+  const takes = taken.length === 0 ? "it takes no options" : `it takes ${taken.map((o) => `--${o}`).join(", ")}`;
+  throw new UsageError(`${which} doesn't take ${refused.map((o) => `--${o}`).join(", ")}; ${takes}`);
+}

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

@@ -13,8 +13,12 @@ export async function runValidate(context: CliContext): Promise<CommandResult> {
 
 export async function runApprove(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
   requireArgs(args, ["document"]);
-  const report = await approveArtifact(context, args[0] ?? "", { replan: options.replan, rebase: options.rebase });
+  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(", ")}.`);

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

@@ -1,4 +1,5 @@
 import { exportFeedback, listEvents, recordEvent } from "../../../../app/use_cases/journal_events.ts";
+import { writeArgumentFile } from "../argument_files.ts";
 import { UsageError, requireArgs, type CliContext, type CommandResult, type Options } from "../cli_context.ts";
 
 export async function runJournal(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
@@ -14,7 +15,7 @@ export async function runJournal(context: CliContext, args: string[], options: O
     return { json: entry, human: `Recorded ${entry.event}.` };
   }
   if (args[0] === "list") {
-    const entries = await listEvents(context, options.event);
+    const entries = await listEvents(context, options.event, options.item);
     return { json: entries, human: entries.map((e) => `${e.at} ${e.event} ${JSON.stringify({ ...e, at: undefined, event: undefined, by: undefined })}`).join("\n") || "No entries." };
   }
   throw new UsageError(`cruze journal takes add or list, not "${args[0]}"`);
@@ -24,7 +25,7 @@ export async function runFeedback(context: CliContext, args: string[], options:
   if (args[0] !== "export") throw new UsageError("usage: cruze feedback export [--out <file>] [--no-redact]");
   const bundle = await exportFeedback(context, options.redact);
   if (options.out !== undefined) {
-    await context.files.writeText(options.out, `${JSON.stringify(bundle, null, 2)}\n`);
+    await writeArgumentFile(options.out, `${JSON.stringify(bundle, null, 2)}\n`);
     return { json: { out: options.out, entries: bundle.entries.length }, human: `Wrote ${bundle.entries.length} entries to ${options.out}.` };
   }
   return { json: bundle, human: `${bundle.entries.length} journal entries${bundle.redacted ? ", redacted" : ""}.` };

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

@@ -1,4 +1,4 @@
-import { addFutureFeature, completeTask, dropFutureFeature, pruneRoadmap, recordDeviation, reopenTask } from "../../../../app/use_cases/record_progress.ts";
+import { addFutureFeature, completeTask, dropFutureFeature, updateFeatureSummary, pruneRoadmap, recordDeviation, reopenTask } from "../../../../app/use_cases/record_progress.ts";
 import { abandonWork } from "../../../../app/use_cases/abandon_work.ts";
 import { UsageError, requireArgs, requireOption, type CliContext, type CommandResult, type Options } from "../cli_context.ts";
 
@@ -23,17 +23,21 @@ export async function runTask(context: CliContext, args: string[], options: Opti
 }
 
 export async function runFeatures(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
-  requireArgs(args, ["add|drop", "slug"]);
+  requireArgs(args, ["add|update|drop", "slug"]);
   if (args[0] === "add") {
     const goals = (options.goals ?? "").split(",").map((g) => g.trim()).filter((g) => g !== "");
     const report = await addFutureFeature(context, args[1] ?? "", requireOption(options.summary, "--summary"), goals);
     return { json: report, human: `Added ${report.feature} to the future list.` };
   }
+  if (args[0] === "update") {
+    const report = await updateFeatureSummary(context, args[1] ?? "", requireOption(options.summary, "--summary"));
+    return { json: report, human: `Updated the summary of ${report.feature} on the ${report.list === "Future" ? "future" : "implemented"} list.` };
+  }
   if (args[0] === "drop") {
     const report = await dropFutureFeature(context, args[1] ?? "", requireOption(options.reason, "--reason"));
     return { json: report, human: `Dropped ${report.feature} from the future list.` };
   }
-  throw new UsageError(`cruze features takes add or drop, not "${args[0]}"`);
+  throw new UsageError(`cruze features takes add, update or drop, not "${args[0]}"`);
 }
 
 export async function runRoadmap(context: CliContext, args: string[]): Promise<CommandResult> {

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

@@ -1,12 +1,13 @@
 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";
 
 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");
-  const blockers = options.blockers === undefined ? undefined : await context.files.readText(options.blockers);
-  if (options.blockers !== undefined && blockers === undefined) throw new UsageError(`cannot read ${options.blockers}`);
+  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 }),

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

@@ -3,6 +3,9 @@ import type { ApprovalStatus } from "../../../../domain/approvals/evaluate.ts";
 import { UsageError, type CliContext, type CommandResult, type Options } 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);
@@ -32,8 +35,11 @@ export async function runStatus(context: CliContext, _args: string[], options: O
   return { json: report, human: lines.join("\n") };
 }
 
+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 detail = status.changed.length > 0 ? ` (${status.changed.join(", ")})` : status.unjournaled === true ? " (no journal entry)" : "";
+  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}`;
 }
 

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

@@ -9,25 +9,40 @@ import { runAbandon, runFeatures, runRoadmap, runTask } from "./commands/progres
 import { runReviewCommand } from "./commands/review.ts";
 import { runNext, runStatus } from "./commands/status.ts";
 
-export const COMMANDS: Record<string, { handler: Handler; usage: string }> = {
-  init: { handler: runInit, usage: "init [--name <name>] [--yes] [--agent claude|other] [--package <npm spec>]   set up this repository and install the skills" },
-  install: { handler: runInstall, usage: "install [--agent <agent>]                         install or update the Cruze skills" },
-  validate: { handler: runValidate, usage: "validate                                          check every document against the formats" },
-  status: { handler: runStatus, usage: "status [--gate build [--override <reason>]] [--overlap [--change <ref>]]" },
-  next: { handler: runNext, usage: "next                                              the step to run next on this branch, and why" },
-  approve: { handler: runApprove, usage: "approve <vision|architecture|roadmap|ref|path> [--replan <ID>...] [--rebase <ID>...]   record your approval of a document" },
-  new: { handler: runNew, usage: "new <vision|glossary|architecture|roadmap> | new <feature|change|adr|note> <slug> --title <title> [--feature <ref>] [--roadmap <slug>]" },
-  task: { handler: runTask, usage: "task <done|deviation|reopen> <T#> [text] [--change <ref>] [--commit <sha>]" },
-  features: { handler: runFeatures, usage: "features <add|drop> <slug> [--summary <text> --goals <ids>] [--reason <text>]" },
-  roadmap: { handler: runRoadmap, usage: "roadmap prune                                     clear landed items from the roadmap status when a release closes" },
-  journal: { handler: runJournal, usage: "journal <add <event> --set key=value... [--item <ref>]|list [--event <event>]>" },
-  review: { handler: runReviewCommand, usage: "review <role> [--item <ref>] [--round 1|2 --blockers <file>] [--base <commit>]   run a role in a fresh agent context" },
-  feedback: { handler: runFeedback, usage: "feedback export [--out <file>] [--no-redact]" },
-  trace: { handler: runTrace, usage: "trace [--all] [--change <ref>]                    link scenarios to the tests that prove them" },
-  check: { handler: runCheck, usage: "check [<file>...] [--ci]                          enforce layer rules and file budgets" },
-  abandon: { handler: runAbandon, usage: "abandon <ref> --reason <text>                     archive a feature or standalone change that stops for good" },
-  land: { handler: runLand, usage: "land [<ref>] [--override <reason>]                merge a verified change into the living docs" },
-  realign: { handler: runRealign, usage: "realign <status [--full]|done [--change <ref>]>    what the installed Cruze expects of existing code, and recording that the code meets it" },
+/** A command, and the options it takes: one list, or one per subcommand for a command that has them. */
+export interface Command {
+  handler: Handler;
+  usage: string;
+  options: readonly string[] | Readonly<Record<string, readonly string[]>>;
+}
+
+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" },
+  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"] },
+    usage: "new <vision|glossary|architecture|roadmap> | new <feature|change|adr|note> <slug> --title <title> [--feature <ref>] [--roadmap <slug>]",
+  },
+  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"] }, usage: "journal <add <event> --set key=value... [--item <ref>]|list [--event <event>] [--item <ref>]>" },
+  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" },
 };
 
 export const USAGE = `Usage: cruze <command> [options]
@@ -35,4 +50,5 @@ export const USAGE = `Usage: cruze <command> [options]
 Commands:
 ${Object.values(COMMANDS).map((c) => `  ${c.usage}`).join("\n")}
 
-Every command prints JSON on stdout when it isn't a terminal, or with --json.`;
+Every command prints its result on stdout: JSON when stdout isn't a terminal or with --json,
+and text on a terminal or with --text. Errors and notes go to stderr.`;

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

@@ -5,6 +5,8 @@ export interface ParsedCommand {
   /** The command and, for grouped commands, its subcommand, such as `new feature`. */
   words: string[];
   options: Options;
+  /** The options given on the command line, by long name, so a command can refuse ones it doesn't take. */
+  given: string[];
   help: boolean;
   version: boolean;
 }
@@ -15,11 +17,13 @@ export function parseCommand(argv: string[]): ParsedCommand {
     parsed = parseArgs({
       args: argv,
       allowPositionals: true,
+      tokens: true,
       options: {
         name: { type: "string" },
         yes: { type: "boolean", short: "y", default: false },
         agent: { type: "string", multiple: true, default: [] },
         json: { type: "boolean", default: false },
+        text: { type: "boolean", default: false },
         version: { type: "boolean", short: "v", default: false },
         help: { type: "boolean", short: "h", default: false },
         title: { type: "string" },
@@ -48,18 +52,21 @@ export function parseCommand(argv: string[]): ParsedCommand {
         rebase: { type: "string", multiple: true, default: [] },
         base: { type: "string" },
         blockers: { type: "string" },
+        "by-agent": { type: "boolean", default: false },
+        "restamp-unchanged": { type: "boolean", default: false },
       },
     });
   } catch (error) {
     throw new UsageError(error instanceof Error ? error.message : String(error));
   }
-  const { values, positionals } = parsed;
+  const { values, positionals, tokens } = parsed;
   const optional = <K extends string>(key: K, value: string | undefined): Partial<Record<K, string>> =>
     value === undefined ? {} : ({ [key]: value } as Record<K, string>);
   const options: Options = {
     yes: values.yes,
     agent: values.agent,
     json: values.json,
+    text: values.text,
     set: values.set,
     redact: !values["no-redact"],
     all: values.all,
@@ -69,6 +76,8 @@ export function parseCommand(argv: string[]): ParsedCommand {
     full: values.full,
     replan: values.replan,
     rebase: values.rebase,
+    byAgent: values["by-agent"],
+    restampUnchanged: values["restamp-unchanged"],
     ...optional("name", values.name),
     ...optional("title", values.title),
     ...optional("feature", values.feature),
@@ -88,5 +97,6 @@ export function parseCommand(argv: string[]): ParsedCommand {
     ...optional("base", values.base),
     ...optional("blockers", values.blockers),
   };
-  return { words: positionals, options, help: values.help, version: values.version };
+  const given = [...new Set(tokens.flatMap((token) => (token.kind === "option" ? [token.name] : [])))];
+  return { words: positionals, options, given, help: values.help, version: values.version };
 }

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

@@ -1,6 +1,7 @@
 import { versionNotice } from "../../../app/use_cases/record_version.ts";
 import { CruzeError } from "../../../domain/cruze_error.ts";
 import { type CliContext, UsageError } from "./cli_context.ts";
+import { refuseUnknownOptions } from "./command_options.ts";
 import { COMMANDS, USAGE } from "./commands.ts";
 import { parseCommand } from "./parse_command.ts";
 
@@ -16,15 +17,17 @@ const NO_VERSION_NOTICE = new Set(["init", "install", "validate"]);
 
 /**
  * Runs one CLI invocation and returns the exit code: 0 on success, 1 when a check fails or
- * an expected error occurs, 2 for usage errors. Agents get JSON on stdout; people get a summary on stderr.
- * When the project's skills don't match this CLI, a note on stderr says so, even when the command fails.
+ * an expected error occurs, 2 for usage errors. The result goes to stdout in one format: JSON for an agent,
+ * when stdout isn't a terminal or with --json, and text for a person, on a terminal or with --text.
+ * stderr carries errors, and a note when the project's skills don't match this CLI, even when the command fails.
  */
 export async function runCli(argv: string[], context: CliContext, terminal: Terminal): Promise<number> {
-  let json = !terminal.stdoutIsTerminal || argv.includes("--json");
+  // Read from argv too, so a usage error is reported in the format asked for.
+  const json = argv.includes("--json") || (!terminal.stdoutIsTerminal && !argv.includes("--text"));
   let notice: string | undefined;
   try {
     const parsed = parseCommand(argv);
-    json ||= parsed.options.json;
+    if (parsed.options.json && parsed.options.text) throw new UsageError("--json and --text are alternatives");
     if (parsed.version) {
       terminal.stdout(context.bundle.version);
       return 0;
@@ -36,10 +39,11 @@ export async function runCli(argv: string[], context: CliContext, terminal: Term
     }
     const command = COMMANDS[name];
     if (command === undefined) throw new UsageError(`Unknown command: ${name}`);
+    refuseUnknownOptions(name, args, command, parsed.given);
     if (!NO_VERSION_NOTICE.has(name)) notice = await versionNotice(context.files, context.bundle.version);
     const result = await command.handler(context, args, parsed.options);
-    terminal.stderr(result.human);
     if (json) terminal.stdout(JSON.stringify(result.json, null, 2));
+    else if (result.human !== "") terminal.stdout(result.human);
     return result.failed === true ? 1 : 0;
   } catch (error) {
     if (error instanceof UsageError) {

package/src/adapters/outbound/node_project_files.ts

@@ -1,6 +1,7 @@
 import { appendFile, lstat, mkdir, readFile, readdir, rename, rm, symlink, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import type { ProjectFiles } from "../../app/ports/project_files.ts";
+import { CruzeError } from "../../domain/cruze_error.ts";
 
 /** Project files on the local disk, confined to one root directory. */
 export class NodeProjectFiles implements ProjectFiles {
@@ -92,7 +93,7 @@ export class NodeProjectFiles implements ProjectFiles {
   private assertInsideRoot(absolute: string): void {
     const fromRoot = relative(this.root, absolute);
     if (fromRoot.startsWith("..") || isAbsolute(fromRoot)) {
-      throw new Error(`Path escapes the project root: ${absolute}`);
+      throw new CruzeError("outside-project", `${absolute} is outside the project at ${this.root}`);
     }
   }
 }

package/src/app/use_cases/approve_artifact.ts

@@ -1,3 +1,4 @@
+import { requirePlanReviewClosed, requireUnchangedSinceApproval, type AgentBasis } from "../../domain/approvals/agent_approval.ts";
 import { evaluateApproval } from "../../domain/approvals/evaluate.ts";
 import { fingerprint, isApprovable } from "../../domain/approvals/fingerprint.ts";
 import { latestApproval, serializeApprovals, withApproval, type ApprovalRecord } from "../../domain/approvals/records.ts";
@@ -29,6 +30,10 @@ export interface ApproveReport {
   replanned: string[];
   /** Elements whose current living text this feature accepted after a land conflict. */
   rebased: string[];
+  /** Why the agent gave this approval for the user, when it did. */
+  basis?: AgentBasis;
+  /** For a re-stamp: the upstream IDs or documents that had changed. */
+  restamped?: string[];
 }
 
 export interface ApproveOptions {
@@ -36,6 +41,8 @@ export interface ApproveOptions {
   replan?: string[];
   /** Elements this work's delta changes whose living text changed since its last approval; the approval accepts the current text. */
   rebase?: string[];
+  /** Approve for the user: a change whose plan review closed, or work a rethink left unchanged. */
+  agent?: AgentBasis;
 }
 
 /**
@@ -53,6 +60,9 @@ export async function approveArtifact(deps: ProjectDeps, ref: string, options: A
   if (item !== undefined && item.kind !== "feature" && !isPlanned(item.doc)) {
     throw new CruzeError("not-planned", `${path} has no test plan or tasks yet; plan it before approving`);
   }
+  const before = evaluateApproval(view, path);
+  if (options.agent === "plan-review") requirePlanReviewClosed(view.journal, item ?? notWork(path));
+  if (options.agent === "rethink") requireUnchangedSinceApproval(view.journal, item, path, before);
 
   const edits = new Map<string, string>();
   let text = view.snapshot.get(path) ?? "";
@@ -103,12 +113,23 @@ export async function approveArtifact(deps: ProjectDeps, ref: string, options: A
     upstream,
     approvedAt: deps.clock.now().toISOString(),
     by: (await deps.repository.userName()) ?? "unknown",
+    ...(options.agent === undefined ? {} : { basis: options.agent }),
   });
   for (const [changed, content] of edits) await deps.files.writeText(changed, content);
   await deps.files.writeText(approvalsPath(folder), serializeApprovals(approvals));
-  await appendJournal(deps, folder, "approve", { artifact: path, hash, ...(replanned.length > 0 ? { replanned } : {}), ...(rebased.length > 0 ? { rebased } : {}) });
+  const restamped = options.agent === "rethink" ? before.changed : undefined;
+  await appendJournal(deps, folder, "approve", {
+    artifact: path,
+    hash,
+    ...(replanned.length > 0 ? { replanned } : {}),
+    ...(rebased.length > 0 ? { rebased } : {}),
+    ...(options.agent === undefined ? {} : { basis: options.agent }),
+    ...(restamped === undefined ? {} : { restamped }),
+  });
   const report: ApproveReport = { artifact: path, hash, upstream: Object.keys(upstream), stamped, replanned, rebased };
   if (bound !== undefined) report.bound = bound;
+  if (options.agent !== undefined) report.basis = options.agent;
+  if (restamped !== undefined) report.restamped = restamped;
   return report;
 }
 
@@ -133,6 +154,10 @@ function requireRebased(view: ProjectView, deltaIds: Set<string>, previous: Appr
   }
 }
 
+function notWork(path: string): never {
+  throw new CruzeError("needs-user", `${path} is a project document, so the user approves it`);
+}
+
 /** A change needs its feature approved; a feature or standalone change needs the architecture approved. */
 function requireUpstreamApproved(view: ProjectView, path: string): void {
   const item = view.items.find((i) => i.path === path);

package/src/app/use_cases/journal_events.ts

@@ -1,5 +1,5 @@
 import { CruzeError } from "../../domain/cruze_error.ts";
-import { recordedEventProblems, recordedFields, type JournalEntry } from "../../domain/journal.ts";
+import { journalPath, parseJournal, recordedEventProblems, recordedFields, type JournalEntry } from "../../domain/journal.ts";
 import { resolveArtifact } from "../../domain/project/artifact_ref.ts";
 import { appendJournal, loadView, type ProjectDeps } from "../project_context.ts";
 
@@ -18,9 +18,17 @@ export async function recordEvent(deps: ProjectDeps, event: string, fields: Reco
   return appendJournal(deps, folder, event, { ...recorded, cruze: deps.bundle.version });
 }
 
-export async function listEvents(deps: ProjectDeps, event?: string): Promise<JournalEntry[]> {
-  const { journal } = await loadView(deps.files);
-  return event === undefined ? journal : journal.filter((entry) => entry.event === event);
+/** The journal, or one feature's or change's part of it: its own journal, and a feature's changes' too. */
+export async function listEvents(deps: ProjectDeps, event?: string, item?: string): Promise<JournalEntry[]> {
+  const view = await loadView(deps.files);
+  let entries = view.journal;
+  if (item !== undefined) {
+    const resolved = resolveArtifact(view, item).item;
+    if (resolved === undefined) throw new CruzeError("not-found", `"${item}" is not a feature or change`);
+    const parts = [resolved, ...view.items.filter((i) => resolved.kind === "feature" && i.featureRef === resolved.ref)];
+    entries = parts.flatMap((part) => parseJournal(view.snapshot.get(journalPath(part.folder))).entries).sort((a, b) => a.at.localeCompare(b.at));
+  }
+  return event === undefined ? entries : entries.filter((entry) => entry.event === event);
 }
 
 export interface FeedbackExport {

package/src/app/use_cases/project_status.ts

@@ -1,6 +1,7 @@
 import { CruzeError } from "../../domain/cruze_error.ts";
 import { readProgress } from "../../domain/project/progress.ts";
 import { buildProjectView } from "../../domain/project/project_view.ts";
+import { findWorkItem, type WorkItem } from "../../domain/project/work_items.ts";
 import { nextSteps, type NextReport } from "../../domain/status/next_step.ts";
 import { activeChange, buildGateReasons, projectStatus, touchedIds, type ProjectStatus } from "../../domain/status/work_status.ts";
 import { appendJournal, loadView, type ProjectDeps } from "../project_context.ts";
@@ -59,10 +60,11 @@ export async function findOverlaps(deps: ProjectDeps, ref?: string): Promise<{ c
   const overlaps: Overlap[] = [];
   for (const other of await deps.repository.otherBranches()) {
     const theirs = buildProjectView(new Map([...view.snapshot].filter(([p]) => p.startsWith("docs/")).concat([...(await deps.repository.filesOnBranch(other, ".cruze"))])));
-    // Work in flight on a branch is the change bound to it.
+    // Work in flight on a branch is the change bound to it that hasn't landed, there or here.
     const boundThere = theirs.items.filter((i) => {
       const bound = readProgress(i.doc).branch;
-      return !i.archived && i.ref !== change.ref && bound !== undefined && (other === bound || other.endsWith(`/${bound}`));
+      const here = findWorkItem(view.items, i.ref);
+      return !landed(i) && (here === undefined || !landed(here)) && i.ref !== change.ref && bound !== undefined && (other === bound || other.endsWith(`/${bound}`));
     });
     for (const item of boundThere) {
       const shared = [...touchedIds(theirs, item)].filter((id) => mine.has(id));
@@ -71,3 +73,7 @@ export async function findOverlaps(deps: ProjectDeps, ref?: string): Promise<{ c
   }
   return { change: change.ref, overlaps };
 }
+
+function landed(item: WorkItem): boolean {
+  return item.archived || readProgress(item.doc).landed !== undefined;
+}