@printpractical/cruze 0.0.3 → 0.0.5

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.5 is the fifth preview. It cuts the ceremony per change: reviews bring you only the findings that are yours to decide, plans are approved once their review closes, a rethink re-stamps the work it didn't change, and changes are sized to be worth their review and verify. 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
 
@@ -22,7 +22,7 @@ Spec-driven workflows tend to fail in the same few ways:
 - Everything is "fully specified", yet the result fails when a person actually uses it.
 - Review loops keep finding new things to change and never converge.
 
-Cruze answers each of these with a specific mechanism. A living `docs/architecture.md` is read at every step and updated by every change. Approvals are bound to document content, so stepping back is just editing. Every task names the file it touches, and `cruze check` enforces layer rules. Scenarios are traced to behavioural tests, and the system is actually run. Reviews use a closed rubric with a hard limit of two rounds.
+Cruze answers each of these with a specific mechanism. A living `docs/architecture.md` is read at every step and updated by every change. Approvals are bound to document content, so stepping back is just editing. Every task names the file it touches, and `cruze check` enforces layer rules. Scenarios are traced to behavioural tests, and the system is actually run. Reviews use a closed rubric with a hard limit of two rounds, and bring you only the findings that are yours to decide: changes to behaviour or to the designed contracts.
 
 ## Quick start
 
@@ -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.5/printpractical-cruze-0.0.5.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.5
 ```
 
 ### 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.5/printpractical-cruze-0.0.5.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
 
@@ -118,15 +118,15 @@ Skills call these at fixed points, and CI runs `check` and `trace` on every push
 
 | Command | What it does |
 | --- | --- |
-| `cruze validate` | Checks every document against the formats: IDs, elements, deltas, scope rules, task lines, test plans, roadmap and config |
-| `cruze approve <doc>` | Records an approval as a fingerprint: the document's design hash plus the hash of every upstream element it cites. `--replan` sets built elements a rethink changed back to planned; `--rebase` accepts living text a feature must now build on |
+| `cruze validate` | Checks every document against the formats: IDs, elements, deltas, scope rules, task lines, test plans, roadmap and config, and warns when a change falls outside the size band in `changes:` |
+| `cruze approve <doc>` | Records an approval as a fingerprint: the document's design hash plus the hash of every upstream element it cites. `--replan` sets built elements a rethink changed back to planned; `--rebase` accepts living text a feature must now build on. `--by-agent` approves a change for you once its plan review has closed, and `--restamp-unchanged` re-stamps work a rethink didn't change; both record that the agent gave the approval |
 | `cruze next` | Names the step to run next on this branch, and why, from computed status |
 | `cruze status` | Computes each document's state (approved, edited, upstream changed or unapproved) from content, never from stored state |
 | `cruze status --gate build` | Passes only when this branch's change, its feature and the architecture are approved and current |
 | `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 |
@@ -149,7 +149,7 @@ Stepping back is editing: change an upstream document and every approval that ci
 | `cruze-envision` | The what: the project's vision, goals and feature map, or one feature's intent and requirements with scenarios |
 | `cruze-architect` | The how: the architecture, a feature's architecture delta and its changes, or a tweak; ends with a design review and a walkthrough for your approval |
 | `cruze-roadmap` | Orders the release into phases with blocking edges and goal coverage, and closes a release |
-| `cruze-plan` | Turns a change into a test plan and ordered tasks with file targets, reviewed in a fresh context |
+| `cruze-plan` | Turns a change into a test plan and ordered tasks with file targets, reviewed in a fresh context and approved once the review closes |
 | `cruze-build` | Builds the change task by task, each test-first, checked and committed, and stops to rethink when the design is wrong |
 | `cruze-verify` | Runs the checks, a fresh-context verifier that uses the real system, a two-lane code review and a manual test script, then asks you to accept |
 | `cruze-land` | Merges the change into the living docs and updates the changelog, README and `AGENTS.md`; also lands bug fixes |

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 @@
                
                   
                 
+                
                  
                    
                    
@@ -51,6 +52,8 @@
                 
                    
                    
+                   
+                            
                  
                    
                 

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/documents.js

@@ -13,8 +13,12 @@ export async function runValidate(context            )                         {
 
 export async function runApprove(context            , args          , options         )                         {
   requireArgs(args, ["document"]);
-  const report = await approveArtifact(context, args[0] ?? "", { replan: options.replan, rebase: options.rebase });
+  if (options.byAgent && options.restampUnchanged) throw new UsageError("--by-agent and --restamp-unchanged are alternatives");
+  const agent = options.byAgent ? "plan-review" : options.restampUnchanged ? "rethink" : undefined;
+  const report = await approveArtifact(context, args[0] ?? "", { replan: options.replan, rebase: options.rebase, ...(agent === undefined ? {} : { agent }) });
   const lines = [`Approved ${report.artifact} (${report.hash.slice(0, 19)}), pinned to ${report.upstream.length} upstream element(s).`];
+  if (report.basis === "plan-review") lines.push("Approved for the user: its plan review closed with no blocker open.");
+  if (report.restamped !== undefined) lines.push(`Re-stamped for the user: its own design is unchanged, and only ${report.restamped.join(", ")} changed.`);
   if (report.stamped.length > 0) lines.push(`Marked ${report.stamped.length} element(s) planned.`);
   if (report.bound !== undefined) lines.push(`Bound the change to branch ${report.bound}.`);
   if (report.replanned.length > 0) lines.push(`Set back to planned: ${report.replanned.join(", ")}.`);

package/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);
@@ -32,8 +35,11 @@ export async function runStatus(context            , _args          , options
   return { json: report, human: lines.join("\n") };
 }
 
+const BASIS                         = { "plan-review": " (by the agent, after its plan review)", rethink: " (re-stamped by the agent after a rethink)" };
+
 function describe(label        , status                )         {
-  const detail = status.changed.length > 0 ? ` (${status.changed.join(", ")})` : status.unjournaled === true ? " (no journal entry)" : "";
+  const byAgent = status.state === "approved" ? BASIS[status.record?.basis ?? ""] ?? "" : "";
+  const detail = status.changed.length > 0 ? ` (${status.changed.join(", ")})` : status.unjournaled === true ? " (no journal entry)" : byAgent;
   return `${label}: ${status.state}${detail}`;
 }
 

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

@@ -9,25 +9,40 @@ 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", "by-agent", "restamp-unchanged"],
+    usage: "approve <vision|architecture|roadmap|ref|path> [--replan <ID>...] [--rebase <ID>...] [--by-agent|--restamp-unchanged]   record an approval of a document",
+  },
+  new: {
+    handler: runNew,
+    options: { vision: [], glossary: [], architecture: [], roadmap: [], feature: ["title", "roadmap"], change: ["title", "feature", "roadmap"], adr: ["title"], note: ["title"] },
+    usage: "new <vision|glossary|architecture|roadmap> | new <feature|change|adr|note> <slug> --title <title> [--feature <ref>] [--roadmap <slug>]",
+  },
+  task: { handler: runTask, options: { done: ["change", "commit"], deviation: ["change"], reopen: ["change"] }, usage: "task <done|deviation|reopen> <T#> [text] [--change <ref>] [--commit <sha>]" },
+  features: { handler: runFeatures, options: { add: ["summary", "goals"], update: ["summary"], drop: ["reason"] }, usage: "features <add|update|drop> <slug> [--summary <text>] [--goals <ids>] [--reason <text>]" },
+  roadmap: { handler: runRoadmap, options: { prune: [] }, usage: "roadmap prune                                     clear landed items from the roadmap status when a release closes" },
+  journal: { handler: runJournal, options: { add: ["set", "item"], list: ["event", "item"] }, usage: "journal <add <event> --set key=value... [--item <ref>]|list [--event <event>] [--item <ref>]>" },
+  review: { handler: runReviewCommand, options: ["item", "round", "blockers", "base"], usage: "review <role> [--item <ref>] [--round 1|2 --blockers <file>] [--base <commit>]   run a role in a fresh agent context" },
+  feedback: { handler: runFeedback, options: { export: ["out", "no-redact"] }, usage: "feedback export [--out <file>] [--no-redact]" },
+  trace: { handler: runTrace, options: ["all", "change"], usage: "trace [--all] [--change <ref>]                    link scenarios to the tests that prove them" },
+  check: { handler: runCheck, options: ["file", "ci"], usage: "check [<file>...] [--ci]                          enforce layer rules and file budgets" },
+  abandon: { handler: runAbandon, options: ["reason"], usage: "abandon <ref> --reason <text>                     archive a feature or standalone change that stops for good" },
+  land: { handler: runLand, options: ["override"], usage: "land [<ref>] [--override <reason>]                merge a verified change into the living docs" },
+  realign: { handler: runRealign, options: { status: ["full"], done: ["change"] }, usage: "realign <status [--full]|done [--change <ref>]>    what the installed Cruze expects of existing code, and recording that the code meets it" },
 };
 
 export const USAGE = `Usage: cruze <command> [options]
@@ -35,4 +50,5 @@ export const USAGE = `Usage: cruze <command> [options]
 Commands:
 ${Object.values(COMMANDS).map((c) => `  ${c.usage}`).join("\n")}
 
-Every command prints JSON on stdout when it isn't a terminal, or with --json.`;
+Every command prints its result on stdout: JSON when stdout isn't a terminal or with --json,
+and text on a terminal or with --text. Errors and notes go to stderr.`;

package/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" },
@@ -48,18 +52,21 @@ export function parseCommand(argv          )                {
         rebase: { type: "string", multiple: true, default: [] },
         base: { type: "string" },
         blockers: { type: "string" },
+        "by-agent": { type: "boolean", default: false },
+        "restamp-unchanged": { type: "boolean", default: false },
       },
     });
   } catch (error) {
     throw new UsageError(error instanceof Error ? error.message : String(error));
   }
-  const { values, positionals } = parsed;
+  const { values, positionals, tokens } = parsed;
   const optional =                   (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,
@@ -69,6 +76,8 @@ export function parseCommand(argv          )                {
     full: values.full,
     replan: values.replan,
     rebase: values.rebase,
+    byAgent: values["by-agent"],
+    restampUnchanged: values["restamp-unchanged"],
     ...optional("name", values.name),
     ...optional("title", values.title),
     ...optional("feature", values.feature),
@@ -88,5 +97,6 @@ export function parseCommand(argv          )                {
     ...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/approve_artifact.js

@@ -1,3 +1,4 @@
+import { requirePlanReviewClosed, requireUnchangedSinceApproval,                 } from "../../domain/approvals/agent_approval.js";
 import { evaluateApproval } from "../../domain/approvals/evaluate.js";
 import { fingerprint, isApprovable } from "../../domain/approvals/fingerprint.js";
 import { latestApproval, serializeApprovals, withApproval,                     } from "../../domain/approvals/records.js";
@@ -29,6 +30,10 @@ import { appendJournal, loadView, withFiles,                  } from "../project
                       
                                                                                         
                     
+                                                                    
+                     
+                                                                        
+                       
  
 
                                  
@@ -36,6 +41,8 @@ import { appendJournal, loadView, withFiles,                  } from "../project
                     
                                                                                                                                      
                     
+                                                                                                   
+                     
  
 
 /**
@@ -53,6 +60,9 @@ export async function approveArtifact(deps             , ref        , options
   if (item !== undefined && item.kind !== "feature" && !isPlanned(item.doc)) {
     throw new CruzeError("not-planned", `${path} has no test plan or tasks yet; plan it before approving`);
   }
+  const before = evaluateApproval(view, path);
+  if (options.agent === "plan-review") requirePlanReviewClosed(view.journal, item ?? notWork(path));
+  if (options.agent === "rethink") requireUnchangedSinceApproval(view.journal, item, path, before);
 
   const edits = new Map                ();
   let text = view.snapshot.get(path) ?? "";
@@ -103,12 +113,23 @@ export async function approveArtifact(deps             , ref        , options
     upstream,
     approvedAt: deps.clock.now().toISOString(),
     by: (await deps.repository.userName()) ?? "unknown",
+    ...(options.agent === undefined ? {} : { basis: options.agent }),
   });
   for (const [changed, content] of edits) await deps.files.writeText(changed, content);
   await deps.files.writeText(approvalsPath(folder), serializeApprovals(approvals));
-  await appendJournal(deps, folder, "approve", { artifact: path, hash, ...(replanned.length > 0 ? { replanned } : {}), ...(rebased.length > 0 ? { rebased } : {}) });
+  const restamped = options.agent === "rethink" ? before.changed : undefined;
+  await appendJournal(deps, folder, "approve", {
+    artifact: path,
+    hash,
+    ...(replanned.length > 0 ? { replanned } : {}),
+    ...(rebased.length > 0 ? { rebased } : {}),
+    ...(options.agent === undefined ? {} : { basis: options.agent }),
+    ...(restamped === undefined ? {} : { restamped }),
+  });
   const report                = { artifact: path, hash, upstream: Object.keys(upstream), stamped, replanned, rebased };
   if (bound !== undefined) report.bound = bound;
+  if (options.agent !== undefined) report.basis = options.agent;
+  if (restamped !== undefined) report.restamped = restamped;
   return report;
 }
 
@@ -133,6 +154,10 @@ function requireRebased(view             , deltaIds             , previous
   }
 }
 
+function notWork(path        )        {
+  throw new CruzeError("needs-user", `${path} is a project document, so the user approves it`);
+}
+
 /** A change needs its feature approved; a feature or standalone change needs the architecture approved. */
 function requireUpstreamApproved(view             , path        )       {
   const item = view.items.find((i) => i.path === path);

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