@printpractical/cruze 0.0.3 → 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.3 is the third preview. It sets projects up for agents other than Claude Code, and runs reviews in the agent's own helpers when no review agent is configured. 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.3/printpractical-cruze-0.0.3.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.3
+npm install -g --install-links github:PrintPractical/cruze#v0.0.4
 ```
 
 ### 2. Set up a repository
@@ -61,7 +61,7 @@ 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.3/printpractical-cruze-0.0.3.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, 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:
@@ -79,7 +79,7 @@ cruze init --package https://github.com/PrintPractical/cruze/releases/download/v
 
 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,7 +126,7 @@ 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 |

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 }),

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 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 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                         {
@@ -92,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/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);

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.3",
+  "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/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.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

@@ -6,6 +6,7 @@ Each release that changes what Cruze expects of a project ships a notes file, `n
 
 - [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/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 }),

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 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"], 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) {

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/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;
+}

package/src/app/use_cases/record_progress.ts

@@ -58,6 +58,23 @@ export async function addFutureFeature(deps: ProjectDeps, slug: string, 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: ProjectDeps, slug: string, summary: string): Promise<{ feature: string; list: "Future" | "Implemented" }> {
+  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: ProjectDeps, slug: string, reason: string): Promise<{ feature: string }> {
   const vision = await requireVision(deps);
   const { text, removed } = removeRow(vision, "Future", slug);

package/src/domain/status/work_status.ts

@@ -1,5 +1,4 @@
 import { evaluateApproval, type ApprovalStatus } from "../approvals/evaluate.ts";
-import { findIds } from "../ids.ts";
 import { PATHS } from "../project/layout.ts";
 import { readDelta } from "../project/deltas.ts";
 import { readScope } from "../project/plan_parts.ts";
@@ -89,13 +88,12 @@ export function buildGateReasons(view: ProjectView, branch: string | null): stri
   });
 }
 
-/** 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: ProjectView, change: WorkItem): Set<string> {
   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-")));
 }