@printpractical/cruze 0.0.2 → 0.0.4

package/README.md

@@ -10,7 +10,7 @@ It works with any agent that supports the [Agent Skills](https://agentskills.io)
 
 ## Status
 
-Version 0.0.2 is the second preview. It adds upgrading and `realign`, and the fixes from the first real project's retro. Early development. The CLI is complete for the V1 lifecycle. The document formats ship as the `cruze-formats` skill, the standards an agent designs and codes to ship as knowledge skills, and the whole workflow, from explore to land, ships as workflow skills. Claude Code is the agent tested so far.
+Version 0.0.4 is the fourth preview. It fixes what the first projects on 0.0.3 ran into: commands print one format on stdout and refuse options they don't take, overlap checks count only work in flight, and the feature map can be corrected when a feature's decisions change it. Early development. The CLI is complete for the V1 lifecycle. The document formats ship as the `cruze-formats` skill, the standards an agent designs and codes to ship as knowledge skills, and the whole workflow, from explore to land, ships as workflow skills. Claude Code is the agent tested so far.
 
 ## Why
 
@@ -35,7 +35,7 @@ The skills run `cruze` commands, so the agent needs `cruze` on its path. Install
 From a GitHub Release, without npm. Each release attaches the packed package:
 
 ```sh
-npm install -g https://github.com/PrintPractical/cruze/releases/download/v0.0.2/printpractical-cruze-0.0.2.tgz
+npm install -g https://github.com/PrintPractical/cruze/releases/download/v0.0.4/printpractical-cruze-0.0.4.tgz
 ```
 
 From npm, once a version is published there:
@@ -47,7 +47,7 @@ npm install -g @printpractical/cruze
 From the git repository, at a tag or `#main`. This needs git and access to the repository. npm 11 needs `--install-links` for a global git install, and the first `cruze` command builds the CLI, which takes a moment:
 
 ```sh
-npm install -g --install-links github:PrintPractical/cruze#v0.0.2
+npm install -g --install-links github:PrintPractical/cruze#v0.0.4
 ```
 
 ### 2. Set up a repository
@@ -61,25 +61,25 @@ cruze init
 When you didn't install from npm, tell `init` where Cruze came from, so the CI it writes runs the same source instead of the npm package:
 
 ```sh
-cruze init --package https://github.com/PrintPractical/cruze/releases/download/v0.0.2/printpractical-cruze-0.0.2.tgz
+cruze init --package https://github.com/PrintPractical/cruze/releases/download/v0.0.4/printpractical-cruze-0.0.4.tgz
 ```
 
-`init` asks for the project name, then creates:
+`init` asks for the project name, and which coding agent you use: `claude` for Claude Code, or `other` for any agent that reads `AGENTS.md` and `.agents/skills/`, such as Codex or OpenCode. It doesn't ask when you pass `--agent claude` or `--agent other`, or when the repository already has `CLAUDE.md` or `.claude/`. With `--yes`, or without a terminal, it sets up Claude Code. Then it creates:
 
 | Path | Purpose |
 | --- | --- |
 | `README.md` | Titled with the project name |
 | `CHANGELOG.md` | In [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format |
 | `AGENTS.md` | Agent instructions; Cruze keeps its managed sections current |
-| `CLAUDE.md` | One line that imports `AGENTS.md`, for Claude Code |
-| `.cruze/config.yaml` | Project configuration, including the Cruze version whose skills the project uses |
+| `CLAUDE.md` | For Claude Code only: a link to `AGENTS.md` |
+| `.cruze/config.yaml` | Project configuration, including the Cruze version whose skills the project uses, and for Claude Code the command `cruze review` runs |
 | `.github/workflows/ci.yml` | CI that runs `cruze validate`, `check` and `trace`; the walking-skeleton change adds the language's build and test steps |
 | `.gitattributes` | Merges Cruze's journals line by line, so parallel branches don't conflict on them |
-| `.agents/skills/cruze-*` | The Cruze skills, linked into `.claude/skills/` for Claude Code |
+| `.agents/skills/cruze-*` | The Cruze skills, also linked into `.claude/skills/` for Claude Code |
 
 Existing files are never overwritten, so it is safe to run in an existing repository.
 
-The CLI writes JSON to stdout when it isn't attached to a terminal, and a human summary to stderr. Pass `--json` to get JSON on a terminal too.
+The CLI writes its result to stdout: JSON when stdout isn't a terminal, and text on a terminal. Pass `--json` to get JSON on a terminal, or `--text` to get text through a pipe, as in `cruze journal list --text | grep review`. Errors and notes go to stderr.
 
 ## Upgrading
 
@@ -126,11 +126,11 @@ Skills call these at fixed points, and CI runs `check` and `trace` on every push
 | `cruze status --overlap` | Lists changes on other branches that touch the same elements as this branch's change |
 | `cruze new <kind>` | Creates a project document (`vision`, `glossary`, `architecture`, `roadmap`) or work (`feature`, `change`, `adr`, `note`) from its template, with a dated ID that is never reused |
 | `cruze task done <T#>` | Ticks a task with its commit; `cruze task reopen` unticks one a rethink changed, and `cruze task deviation` records a small departure from the plan |
-| `cruze features <add\|drop>` | Edits the future list of the feature map |
+| `cruze features <add\|update\|drop>` | Edits the feature map: adds or drops a future feature, or corrects a summary |
 | `cruze roadmap prune` | Clears landed items from the roadmap's status when a release closes |
 | `cruze trace` | Fails when a delivered scenario has no test carrying its ID; `--all` checks every built scenario |
 | `cruze check` | Enforces the layer rules and the file budgets; `--ci` also fails on budget warnings |
-| `cruze review <role>` | Runs a role (design reviewer, code reviewer, verifier, researcher or auditor) in a fresh agent context, through the command in `.cruze/config.yaml` |
+| `cruze review <role>` | Runs a role (design reviewer, code reviewer, verifier, researcher or auditor) in a fresh agent context, through the command in `.cruze/config.yaml`. When no command is set, or its program isn't installed, it prints the role's prompt for the agent to run in a helper of its own |
 | `cruze land` | Merges a verified change into the living docs, re-stamps the approvals the merge would make stale, fills the Commands and Layout sections of `AGENTS.md`, and archives finished work |
 | `cruze realign status` | Lists what the installed Cruze expects of existing code since its `standards:` version, with what the CLI rules find now; `--full` covers every release |
 | `cruze realign done` | Moves `standards:` up once every finding is fixed, waived or scheduled in a change named with `--change` |

package/dist/adapters/inbound/cli/argument_files.js

@@ -0,0 +1,29 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { UsageError } from "./cli_context.js";
+
+// 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        )                  {
+  try {
+    return await readFile(resolve(path), "utf8");
+  } catch (error) {
+    throw new UsageError(`cannot read ${path}: ${reason(error)}`);
+  }
+}
+
+export async function writeArgumentFile(path        , text        )                {
+  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         )         {
+  if (error instanceof Error && "code" in error && typeof error.code === "string") return error.code;
+  return error instanceof Error ? error.message : String(error);
+}

package/dist/adapters/inbound/cli/cli_context.js

@@ -29,6 +29,7 @@
                
                   
                 
+                
                  
                    
                    

package/dist/adapters/inbound/cli/command_options.js

@@ -0,0 +1,20 @@
+import { UsageError } from "./cli_context.js";
+                                             
+
+/** 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        , args          , command         , given          )       {
+  const sub = Array.isArray(command.options) ? undefined : args[0];
+  const taken = Array.isArray(command.options) ? command.options : sub === undefined ? undefined : (command.options                                     )[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/dist/adapters/inbound/cli/commands/journal.js

@@ -1,4 +1,5 @@
 import { exportFeedback, listEvents, recordEvent } from "../../../../app/use_cases/journal_events.js";
+import { writeArgumentFile } from "../argument_files.js";
 import { UsageError, requireArgs,                                                   } from "../cli_context.js";
 
 export async function runJournal(context            , args          , options         )                         {
@@ -14,7 +15,7 @@ export async function runJournal(context            , args          , options
     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            , args          , 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/dist/adapters/inbound/cli/commands/progress.js

@@ -1,4 +1,4 @@
-import { addFutureFeature, completeTask, dropFutureFeature, pruneRoadmap, recordDeviation, reopenTask } from "../../../../app/use_cases/record_progress.js";
+import { addFutureFeature, completeTask, dropFutureFeature, updateFeatureSummary, pruneRoadmap, recordDeviation, reopenTask } from "../../../../app/use_cases/record_progress.js";
 import { abandonWork } from "../../../../app/use_cases/abandon_work.js";
 import { UsageError, requireArgs, requireOption,                                                   } from "../cli_context.js";
 
@@ -23,17 +23,21 @@ export async function runTask(context            , args          , options
 }
 
 export async function runFeatures(context            , args          , options         )                         {
-  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            , args          )                         {

package/dist/adapters/inbound/cli/commands/review.js

@@ -1,12 +1,13 @@
 import { runReview } from "../../../../app/use_cases/run_review.js";
+import { readArgumentFile } from "../argument_files.js";
 import { UsageError, requireArgs,                                                   } from "../cli_context.js";
 
 export async function runReviewCommand(context            , args          , options         )                         {
   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            , args          , 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/dist/adapters/inbound/cli/commands/status.js

@@ -3,6 +3,9 @@ import { checkBuildGate, findOverlaps, showStatus, suggestNext } from "../../../
 import { UsageError,                                                   } from "../cli_context.js";
 
 export async function runStatus(context            , _args          , options         )                         {
+  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/dist/adapters/inbound/cli/commands.js

@@ -9,25 +9,36 @@ import { runAbandon, runFeatures, runRoadmap, runTask } from "./commands/progres
 import { runReviewCommand } from "./commands/review.js";
 import { runNext, runStatus } from "./commands/status.js";
 
-export const COMMANDS                                                      = {
-  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 const COMMANDS                          = {
+  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/dist/adapters/inbound/cli/parse_command.js

@@ -5,6 +5,8 @@ import { UsageError,              } from "./cli_context.js";
                                                                                       
                   
                    
+                                                                                                           
+                  
                 
                    
  
@@ -15,11 +17,13 @@ export function parseCommand(argv          )                {
     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          )                {
   } catch (error) {
     throw new UsageError(error instanceof Error ? error.message : String(error));
   }
-  const { values, positionals } = parsed;
+  const { values, positionals, tokens } = parsed;
   const optional =                   (key   , value                    )                             =>
     value === undefined ? {} : ({ [key]: value }                     );
   const 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          )                {
     ...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/dist/adapters/inbound/cli/run_cli.js

@@ -1,6 +1,7 @@
 import { versionNotice } from "../../../app/use_cases/record_version.js";
 import { CruzeError } from "../../../domain/cruze_error.js";
 import {                  UsageError } from "./cli_context.js";
+import { refuseUnknownOptions } from "./command_options.js";
 import { COMMANDS, USAGE } from "./commands.js";
 import { parseCommand } from "./parse_command.js";
 
@@ -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          , context            , terminal          )                  {
-  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                    ;
   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          , context            , terminal
     }
     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/dist/adapters/outbound/node_project_files.js

@@ -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 { CruzeError } from "../../domain/cruze_error.js";
 
 /** Project files on the local disk, confined to one root directory. */
 export class NodeProjectFiles                         {
@@ -78,7 +79,8 @@ export class NodeProjectFiles                         {
     this.assertInsideRoot(resolve(dirname(linkPath), target));
     await mkdir(dirname(linkPath), { recursive: true });
     await rm(linkPath, { recursive: true, force: true });
-    await symlink(target, linkPath, "dir");
+    // No link type: on Windows, Node picks a file or directory link from what the target is.
+    await symlink(target, linkPath);
   }
 
   /** Resolves a project-relative path, refusing anything outside the root. */
@@ -91,7 +93,7 @@ export class NodeProjectFiles                         {
           assertInsideRoot(absolute        )       {
     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/dist/adapters/outbound/process_agent_runner.js

@@ -11,15 +11,20 @@ export class ProcessAgentRunner                        {
 
   run(command          , prompt        )                    {
     const [program, ...args] = command;
-    if (program === undefined) return Promise.resolve({ exitCode: 127, output: "", error: "no command configured" });
+    if (program === undefined) return Promise.resolve({ kind: "missing" });
     return new Promise((resolve) => {
       const child = spawn(program, args, { cwd: this.cwd, stdio: ["pipe", "pipe", "pipe"] });
       let output = "";
       let error = "";
       child.stdout.on("data", (chunk        ) => (output += chunk.toString("utf8")));
       child.stderr.on("data", (chunk        ) => (error += chunk.toString("utf8")));
-      child.on("error", (failure) => resolve({ exitCode: 127, output, error: `${error}${failure.message}` }));
-      child.on("close", (code) => resolve({ exitCode: code ?? 1, output, error }));
+      // Spawning reports ENOENT when the program isn't on the PATH.
+      child.on("error", (failure                       ) =>
+        resolve(failure.code === "ENOENT" ? { kind: "missing" } : { kind: "finished", exitCode: 127, output, error: `${error}${failure.message}` }),
+      );
+      child.on("close", (code) => resolve({ kind: "finished", exitCode: code ?? 1, output, error }));
+      // A program that never started closes stdin; ignore the write error, since the spawn error reports it.
+      child.stdin.on("error", () => {});
       child.stdin.end(prompt);
     });
   }

package/dist/app/ports/agent_runner.js

@@ -1,11 +1,10 @@
 /** Starts a coding agent in a fresh context, non-interactively, and collects what it reports. */
                               
-                                                                            
+     
+                                                                                           
+                                                                          
+     
                                                             
  
 
-                           
-                   
-                 
-                
- 
+                                                                                                                   

package/dist/app/use_cases/init_project.js

@@ -1,5 +1,7 @@
+import { CruzeError } from "../../domain/cruze_error.js";
+import { agentSkillHome } from "../../domain/agent_skill_homes.js";
 import { parseProjectName } from "../../domain/project_name.js";
-import { INIT_SCAFFOLD, renderTemplate } from "../../domain/scaffold.js";
+import { CLAUDE_INSTRUCTIONS, INIT_AGENTS, INIT_SCAFFOLD,                 renderTemplate, reviewSettingTemplate } from "../../domain/scaffold.js";
                                                  
                                                               
                                                      
@@ -10,6 +12,7 @@ import { installSkills,                          } from "./install_skills.js";
                 
                                                                 
                       
+                                                                                                          
                    
      
                                                                                                 
@@ -20,6 +23,7 @@ import { installSkills,                          } from "./install_skills.js";
 
                                     
                   
+                   
                     
                                                             
                     
@@ -36,11 +40,13 @@ export async function initProject(
 )                             {
   const { files, bundle, prompter } = deps;
   const project = parseProjectName(request.name ?? (await prompter.ask("Project name", request.defaultName)));
+  const agent = await chooseAgent(files, prompter, request.agents);
   const values = {
     project_name: project,
     project_name_quoted: JSON.stringify(project),
     cruze_version: bundle.version,
     cruze_package: request.package ?? `@printpractical/cruze@${bundle.version}`,
+    review_setting: (await bundle.template(reviewSettingTemplate(agent))).trimEnd(),
   };
 
   const created           = [];
@@ -53,7 +59,29 @@ export async function initProject(
     await files.writeText(entry.path, renderTemplate(await bundle.template(entry.template), values));
     created.push(entry.path);
   }
+  if (agent === "claude") {
+    if (await files.exists(CLAUDE_INSTRUCTIONS.path)) skipped.push(CLAUDE_INSTRUCTIONS.path);
+    else {
+      await files.link(CLAUDE_INSTRUCTIONS.path, CLAUDE_INSTRUCTIONS.target);
+      created.push(CLAUDE_INSTRUCTIONS.path);
+    }
+  }
 
-  const skills = await installSkills({ files, bundle }, { agents: request.agents });
-  return { project, created, skipped, skills };
+  const linkFor = new Set(request.agents.filter((a) => a !== "other"));
+  if (agent === "claude") linkFor.add("claude");
+  const skills = await installSkills({ files, bundle }, { agents: [...linkFor] });
+  return { project, agent, created, skipped, skills };
+}
+
+/** The agent named with `--agent`, or shown by the project's files, or else the answer to asking. */
+async function chooseAgent(files              , prompter          , requested          )                     {
+  if (requested.includes("claude")) return "claude";
+  if (requested.includes("other")) return "other";
+  for (const marker of agentSkillHome("claude")?.markers ?? []) {
+    if (await files.exists(marker)) return "claude";
+  }
+  const answer = (await prompter.ask(`Coding agent (${INIT_AGENTS.join(" or ")})`, "claude")).trim().toLowerCase();
+  const agent = INIT_AGENTS.find((a) => a === answer);
+  if (agent === undefined) throw new CruzeError("unknown-agent", `Unknown agent: ${answer}. Answer ${INIT_AGENTS.join(" or ")}, or pass --agent.`);
+  return agent;
 }

package/dist/app/use_cases/journal_events.js

@@ -1,5 +1,5 @@
 import { CruzeError } from "../../domain/cruze_error.js";
-import { recordedEventProblems, recordedFields,                   } from "../../domain/journal.js";
+import { journalPath, parseJournal, recordedEventProblems, recordedFields,                   } from "../../domain/journal.js";
 import { resolveArtifact } from "../../domain/project/artifact_ref.js";
 import { appendJournal, loadView,                  } from "../project_context.js";
 
@@ -18,9 +18,17 @@ export async function recordEvent(deps             , event        , fields
   return appendJournal(deps, folder, event, { ...recorded, cruze: deps.bundle.version });
 }
 
-export async function listEvents(deps             , event         )                          {
-  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             , event         , item         )                          {
+  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);
 }
 
                                  

package/dist/app/use_cases/project_status.js

@@ -1,6 +1,7 @@
 import { CruzeError } from "../../domain/cruze_error.js";
 import { readProgress } from "../../domain/project/progress.js";
 import { buildProjectView } from "../../domain/project/project_view.js";
+import { findWorkItem,               } from "../../domain/project/work_items.js";
 import { nextSteps,                 } from "../../domain/status/next_step.js";
 import { activeChange, buildGateReasons, projectStatus, touchedIds,                    } from "../../domain/status/work_status.js";
 import { appendJournal, loadView,                  } from "../project_context.js";
@@ -59,10 +60,11 @@ export async function findOverlaps(deps             , ref         )
   const overlaps            = [];
   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             , ref         )
   }
   return { change: change.ref, overlaps };
 }
+
+function landed(item          )          {
+  return item.archived || readProgress(item.doc).landed !== undefined;
+}

package/dist/app/use_cases/record_progress.js

@@ -58,6 +58,23 @@ export async function addFutureFeature(deps             , slug        , summary
   return { feature: slug };
 }
 
+/**
+ * Replaces a feature's summary on the feature map, in the future list or the implemented list,
+ * when a decision changed what the feature delivers. Its goals or release stay as they are.
+ */
+export async function updateFeatureSummary(deps             , slug        , summary        )                                                               {
+  if (summary.trim() === "") throw new CruzeError("missing-summary", "a feature needs a summary");
+  const vision = await requireVision(deps);
+  const future = readRows(vision, "Future").find((row) => row[0] === slug);
+  const implemented = readRows(vision, "Implemented").find((row) => row[0] === slug);
+  if (future === undefined && implemented === undefined) throw new CruzeError("not-found", `${slug} is not on the feature map`);
+  const list = future !== undefined ? "Future" : "Implemented";
+  const cells = future !== undefined ? [slug, summary.trim(), future[2] ?? ""] : [slug, implemented?.[1] ?? "", summary.trim()];
+  await deps.files.writeText(PATHS.vision, upsertRow(vision, list, cells));
+  await appendJournal(deps, ".cruze", "feature-map", { action: "update", feature: slug, summary: summary.trim() });
+  return { feature: slug, list };
+}
+
 export async function dropFutureFeature(deps             , slug        , reason        )                               {
   const vision = await requireVision(deps);
   const { text, removed } = removeRow(vision, "Future", slug);