@printpractical/cruze 0.0.2 → 0.0.4

package/dist/app/use_cases/run_review.js

@@ -18,16 +18,19 @@ export const ROLES = ["design-reviewer", "code-reviewer", "verifier", "researche
                 
  
 
-                               
-             
-                
-                    
-                 
- 
+/**
+ * The role's report, or, when the configured agent isn't installed, the prompt for the calling
+ * agent to run in a helper of its own.
+ */
+                                                                                
+                                          
+                                                                    
+  
 
 /**
  * Runs a Cruze role in a fresh agent context: the role's prompt, what it reviews, and nothing
- * from the conversation that produced the work. Returns the role's report as written.
+ * from the conversation that produced the work. Returns the role's report as written, or the
+ * prompt to run in a helper when the configured agent isn't installed.
  */
 export async function runReview(deps                                       , request               )                        {
   if (!(ROLES                     ).includes(request.role)) throw new CruzeError("unknown-role", `the roles are ${ROLES.join(", ")}`);
@@ -55,12 +58,23 @@ export async function runReview(deps                                       , req
     context.map((line) => `- ${line}`).join("\n"),
   ].join("\n\n");
 
-  const command = view.config?.config?.review.command ?? [];
+  const subject = { role, ...(request.item === undefined ? {} : { item: request.item }) };
+  const command = view.config?.config?.review.command;
+  if (command === undefined) return { ...subject, status: "run-in-helper", instruction: helperInstruction(undefined), prompt };
   const run = await deps.runner.run(command, prompt);
+  if (run.kind === "missing") return { ...subject, command, status: "run-in-helper", instruction: helperInstruction(command[0]), prompt };
   if (run.exitCode !== 0) throw new CruzeError("review-failed", `${command.join(" ")} exited with ${run.exitCode}: ${run.error.trim() || run.output.trim()}`);
-  const report               = { role, command, report: run.output.trim() };
-  if (request.item !== undefined) report.item = request.item;
-  return report;
+  return { ...subject, command, status: "reported", report: run.output.trim() };
+}
+
+/** Why cruze review can't start the fresh context itself, and how the calling agent does instead. */
+function helperInstruction(program                    )         {
+  return [
+    program === undefined ? "No review agent is configured under review.command." : `${program} is not installed, so cruze review can't start a fresh context.`,
+    "Start a helper agent with no conversation history, give it this prompt and nothing else, and take its report as the role's report.",
+    "If you can't start a helper, tell the user, and have them run the prompt in a new session.",
+    "To have cruze review start an agent itself, set review.command in .cruze/config.yaml.",
+  ].join(" ");
 }
 
 async function bundledRole(deps             , role      )                  {

package/dist/domain/config.js

@@ -19,12 +19,12 @@ import { parse as parseYaml } from "yaml";
                   
                                                                                 
                                    
-                                                                                              
-                                
+     
+                                                                                          
+                                                                                  
+     
+                                 
  
-
-/** Claude Code in print mode, allowed to read the project, its history and run `cruze`, but not to edit. */
-export const DEFAULT_REVIEW_COMMAND = ["claude", "-p", "--allowedTools", "Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(git show:*) Bash(cruze:*)"];
 
                         
                
@@ -95,8 +95,8 @@ export function parseConfig(text        )               {
     }
   }
   const review = asRecord(root["review"]) ?? {};
-  const reviewCommand = review["command"] === undefined ? DEFAULT_REVIEW_COMMAND : stringList(review["command"], "review.command", problems);
-  if (reviewCommand.length === 0) problems.push("review.command needs at least the program to run");
+  const reviewCommand = review["command"] === undefined ? undefined : stringList(review["command"], "review.command", problems);
+  if (reviewCommand?.length === 0) problems.push("review.command needs at least the program to run");
 
   const config              = {
     version: 1,
@@ -109,7 +109,7 @@ export function parseConfig(text        )               {
     check: { maxLines: maxLines ?? 250, maxTypes: maxTypes ?? 5, exceptions },
     layers,
     commands,
-    review: { command: reviewCommand.length === 0 ? DEFAULT_REVIEW_COMMAND : reviewCommand },
+    review: reviewCommand === undefined || reviewCommand.length === 0 ? {} : { command: reviewCommand },
   };
   return { config, problems };
 }

package/dist/domain/scaffold.js

@@ -11,12 +11,26 @@ export const INIT_SCAFFOLD                           = [
   { path: "README.md", template: "init/README.md" },
   { path: "CHANGELOG.md", template: "init/CHANGELOG.md" },
   { path: "AGENTS.md", template: "init/AGENTS.md" },
-  { path: "CLAUDE.md", template: "init/CLAUDE.md" },
   { path: ".cruze/config.yaml", template: "init/config.yaml" },
   { path: ".github/workflows/ci.yml", template: "init/ci.yml" },
   { path: ".gitattributes", template: "init/gitattributes" },
 ];
 
+/**
+ * The agents `cruze init` sets a project up for: Claude Code, which gets `CLAUDE.md`, linked skills
+ * and a review command, or any other agent, which reads `AGENTS.md` and `.agents/skills/`.
+ */
+export const INIT_AGENTS = ["claude", "other"]         ;
+                                                     
+
+/** Claude Code reads `CLAUDE.md`, so init links it to `AGENTS.md` rather than keeping a second copy. */
+export const CLAUDE_INSTRUCTIONS = { path: "CLAUDE.md", target: "AGENTS.md" };
+
+/** The template for the config's `review:` setting, which only Claude Code gets filled in. */
+export function reviewSettingTemplate(agent           )         {
+  return `init/review/${agent}.yaml`;
+}
+
 /** Replaces every `{{key}}` with its value; an unknown key is a template bug. */
 export function renderTemplate(template        , values                        )         {
   return template.replace(/\{\{([a-z_]+)\}\}/g, (placeholder, key        ) => {

package/dist/domain/status/work_status.js

@@ -1,5 +1,4 @@
 import { evaluateApproval,                     } from "../approvals/evaluate.js";
-import { findIds } from "../ids.js";
 import { PATHS } from "../project/layout.js";
 import { readDelta } from "../project/deltas.js";
 import { readScope } from "../project/plan_parts.js";
@@ -89,13 +88,12 @@ export function buildGateReasons(view             , branch               )
   });
 }
 
-/** The elements a change touches: its scope plus every ID its documents cite. */
+/** The elements a change touches: its scope and its delta, not the elements it only cites, such as a test seam. */
 export function touchedIds(view             , change          )              {
   const feature = featureOf(view.items, change);
   const scope = readScope(change.doc);
   const ids = new Set([...(scope?.delivers ?? []), ...(scope?.builds ?? []), ...(scope?.removes ?? [])]);
   const deltaDoc = feature?.doc ?? change.doc;
   for (const id of readDelta(deltaDoc).ids) ids.add(id);
-  for (const id of findIds(change.doc.lines.join("\n"))) ids.add(id);
   return new Set([...ids].filter((id) => !id.startsWith("RULE-")));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@printpractical/cruze",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Spec-driven development for coding agents: one living model of the system, small deltas, convergent review.",
   "license": "Apache-2.0",
   "author": "Chris Buchter",

package/skills/about/SKILL.md

@@ -9,7 +9,7 @@ Cruze is a spec-driven development framework. It keeps one living model of the s
 
 This installation is an early preview. It has:
 
-- The `cruze` CLI: `cruze init` sets up a repository, `cruze install` updates the skills after an upgrade, and `cruze help` lists the commands that validate, approve, check, trace and land work.
+- The `cruze` CLI: `cruze init` sets up a repository, `cruze install` updates the skills after an upgrade, and `cruze help` lists the commands that validate, approve, check, trace and land work. Each prints its result on stdout, as JSON when stdout isn't a terminal, or as text with `--text`. A command refuses an option it doesn't take, so check `cruze help` when one is refused.
 - `cruze-formats`, the format of every Cruze document.
 - Knowledge skills holding the standards to design and code to: `cruze-hexagonal-design`, `cruze-behavioural-testing`, `cruze-grilling`, `cruze-domain-language`, `cruze-dependency-approval` and `cruze-research`.
 - The workflow: `explore` (optional), `envision` for the what, `architect` for the how, `roadmap` for the order of work, then `plan`, `build`, `verify` and `land` for each change. `triage` handles bugs, `rethink` steps back from anywhere, and `next` says what to do now.

package/skills/envision/SKILL.md

@@ -21,7 +21,7 @@ Envision decides the what: the problem, who has it, and the behaviour that solve
 - Requirements and scenarios follow `.agents/skills/cruze-formats/reference/specs.md`. Every scenario uses concrete values: real names, real inputs, exact output. The scenarios become the tests, so their values are the expected results.
 - Keep implementation out: no modules, types, libraries or file formats unless the user names one as a constraint. When the user raises one, record it as a constraint or a settled decision and move on.
 - The vision stays within one page, excluding the feature map.
-- Only the CLI writes the feature map. Use `cruze features add` and `cruze features drop`.
+- Only the CLI writes the feature map. Use `cruze features add`, `cruze features update` and `cruze features drop`.
 
 ## Next step
 

package/skills/envision/feature.md

@@ -13,6 +13,7 @@ The result is a feature folder whose `feature.md` holds the intent, the settled
    - **Requirements:** each behaviour the feature adds, changes or removes, and the capability it belongs to. It goes in an existing capability when the behaviour fits one; otherwise it starts a new capability.
    - **Scenarios:** for each requirement, the main case, each edge and failure case a user will meet, and what they observe in each. Invent concrete edge cases to test the boundaries.
 6. **Grill in rounds** until every open decision is settled. Record decisions under `## Settled decisions` and terms in the glossary as they settle.
+   - When a decision changes something the feature's summary on the feature map promises, such as a policy it names, correct the summary with `cruze features update <slug> --summary <text>`.
 7. **Write the spec delta.** Use `ADDED` for new requirements, `MODIFIED` for a requirement whose text or scenarios change (writing its full new body with every scenario it keeps), `REMOVED` with a `Reason` and `Migration` for retired behaviour, and `ADDED CAPABILITY` for a new capability.
    - Name every ID with glossary terms. An ID is never reused.
    - Done when every requirement has a scenario for its main case and one for each failure a user can meet.

package/skills/formats/reference/config.md

@@ -51,7 +51,7 @@ layers:
 | `check.exceptions` | Files allowed past a budget, or Rust test files allowed under `src/` (`test-placement`), each with a `path` and a `reason`. `realign` adds entries whose reason ends `scheduled in <ref>`, and landing that change removes them. |
 | `layers` | Each layer has a `name`, the `paths` it covers, and `may_import`, the layers it may depend on. |
 | `commands` | The project's commands by name, such as `test` or `run`. The walking-skeleton change fills them in, and `cruze land` copies them into the Commands section of `AGENTS.md`. |
-| `review.command` | The program and arguments `cruze review` runs to start an agent in a fresh context, with the prompt on standard input. The default runs Claude Code in print mode, allowed to read the project and run `git diff`, `git log`, `git show` and `cruze`. The verifier runs the system, so add the project's build and run commands. |
+| `review.command` | The program and arguments `cruze review` runs to start an agent in a fresh context, with the prompt on standard input. Optional. `cruze init` sets it for Claude Code to run in print mode, allowed to read the project and run `git diff`, `git log`, `git show` and `cruze`. The verifier runs the system, so add the project's build and run commands. When it is unset, or its program isn't installed, `cruze review` hands the role's prompt back to the calling agent to run in a helper. |
 
 Rules for layers:
 

package/skills/formats/reference/durable-docs.md

@@ -16,7 +16,7 @@ What the product is for. At most one page, excluding the feature map.
 | `## Feature map` | Managed. `### Implemented` is a table of Feature, Release and Summary. `### Future` is a table of Feature, Summary and Goals |
 
 - Feature-map entries are named by slug, such as `jump-hosts`. A future entry gets a folder ID only when its feature starts.
-- Only the CLI writes the feature map. `cruze features add` puts an entry on the future list, `cruze features drop` removes one, and `land` moves a finished feature to implemented, tagged with the release in progress.
+- Only the CLI writes the feature map. `cruze features add` puts an entry on the future list, `cruze features update` corrects an entry's summary on either list, `cruze features drop` removes one from the future list, and `land` moves a finished feature to implemented, tagged with the release in progress.
 
 ## docs/glossary.md
 

package/skills/land/SKILL.md

@@ -20,6 +20,7 @@ Land makes finished work part of the living model. `cruze land` merges the chang
    - When they don't hold, stop and offer `rethink`.
 4. **Run `cruze land`** and quote its report: what it merged, what is now built, and whether the work finished and was archived.
    - A `merge-conflict` means someone changed an element this feature merged earlier. Stop and run `rethink`, which reconciles it.
+   - When the work finished, read the feature's row under `### Implemented` in `docs/vision.md` against its settled decisions and spec delta. When the summary no longer describes what landed, correct it with `cruze features update <slug> --summary <text>`.
    - A `merge-invalid` means the merged docs, or the feature and changes being landed, wouldn't validate, such as a decision citing an ID the change removes. Nothing was written. Stop and run `rethink`.
 5. **Update the changelog.** Under `## [Unreleased]` in `CHANGELOG.md`, add one line per user-visible behaviour the change delivers, in the user's words, under `### Added`, `### Changed` or `### Removed`. Name the behaviour, not the code, including any rule a user can now run into that no scenario covers yet.
 6. **Update the README** when the change altered how someone installs, runs or uses the product. Run every command you add, to check it works.

package/skills/realign/notes/0.0.3.md

@@ -0,0 +1,11 @@
+# Realign notes: 0.0.3
+
+## New work only
+
+### review-helper-fallback: A review runs in a helper when no review agent is configured or installed
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/SKILL.md`, "Running a role", step 3
+
+### optional-review-command: review.command is optional, and set only for Claude Code
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-formats/reference/config.md`, "Configuration format"

package/skills/realign/notes/0.0.4.md

@@ -0,0 +1,27 @@
+# Realign notes: 0.0.4
+
+## New work only
+
+### argument-files-anywhere: Files named on the command line may be outside the project
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/SKILL.md`, "Running a role"
+
+### cli-output-format: The CLI prints one format on stdout, JSON for agents and text with --text
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-about/SKILL.md`
+
+### overlap-scope: Overlap counts only in-flight changes, and only the elements their scope and delta name
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-plan/SKILL.md`, "Steps", step 7
+
+### refused-options: The CLI refuses an option its command doesn't take
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-about/SKILL.md`
+
+### feature-map-summary: A feature's summary on the feature map follows its decisions
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-land/SKILL.md`, "Landing a change", step 4
+
+### journal-list-item: Journal list narrows to one feature or change with --item
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-about/SKILL.md`

package/skills/realign/notes.md

@@ -5,6 +5,8 @@ Each release that changes what Cruze expects of a project ships a notes file, `n
 ## Releases
 
 - [0.0.2](notes/0.0.2.md)
+- [0.0.3](notes/0.0.3.md)
+- [0.0.4](notes/0.0.4.md)
 
 ## Format
 

package/skills/rethink/levels.md

@@ -30,7 +30,7 @@
 
 ## Vision
 
-1. Edit `docs/vision.md` with the user: goals, non-goals or constraints. The feature map changes only through `cruze features add` and `cruze features drop`. When the problem, users or goals changed, update the overview under the title of `README.md` to match.
+1. Edit `docs/vision.md` with the user: goals, non-goals or constraints. The feature map changes only through `cruze features add`, `cruze features update` and `cruze features drop`. When the problem, users or goals changed, update the overview under the title of `README.md` to match.
 2. Update `docs/roadmap.md` to match, following `.agents/skills/cruze-roadmap/SKILL.md`.
 3. For each feature in progress that served a dropped goal, the user decides: keep it, or stop it with `cruze abandon <ref> --reason "<why>"`. Abandoning archives the folder and puts the feature back on the future list; changes that already landed stay.
 4. Re-approve with `cruze approve vision`, then `cruze approve roadmap`.

package/skills/roles/SKILL.md

@@ -19,7 +19,7 @@ A role is a prompt with fixed inputs and a report as its only output. It runs in
 
 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` or `auditor`. 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. If that can't run either, 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.
+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` or `auditor`. 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. 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

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;

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/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 }),
@@ -14,5 +15,5 @@ export async function runReviewCommand(context: CliContext, args: string[], opti
     ...(blockers === undefined ? {} : { blockers }),
     ...(options.base === undefined ? {} : { base: options.base }),
   });
-  return { json: report, human: report.report };
+  return { json: report, human: report.status === "reported" ? report.report : `${report.instruction}\n\n${report.prompt}` };
 }

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);

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

@@ -9,25 +9,36 @@ 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 <agent>] [--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"], usage: "approve <vision|architecture|roadmap|ref|path> [--replan <ID>...] [--rebase <ID>...]   record your 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 +46,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" },
@@ -53,13 +57,14 @@ export function parseCommand(argv: string[]): ParsedCommand {
   } 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,
@@ -88,5 +93,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) {