@printpractical/cruze 0.0.1

package/skills/triage/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: cruze-triage
+description: Handles a bug report by reproducing it, finding its root cause against the living docs, and fixing a code defect with a failing test first, or sending a spec gap to architect and a design flaw to rethink.
+---
+
+# Triage
+
+Triage starts from a symptom and ends with a fix, or with the right step to fix it. A bug has three possible causes, and each goes somewhere different. When the code doesn't do what the specs say, triage fixes it. When the specs never covered the case, it goes to `architect` as a tweak. When the design can't deliver the specs, it goes to `rethink`.
+
+## Steps
+
+1. **Capture the symptom.** Get the exact steps, what happened (output, error, exit code), what the user expected, and the environment. Done when you can write the steps as commands.
+2. **Reproduce it.** Run the steps against the real system. Done when you can make it fail on demand and have quoted the output. When you can't reproduce it, ask the user for what differs in their environment, and stop until you can.
+3. **Place it in the living docs.** Find the requirement and scenarios in `docs/specs/` that cover this behaviour, and the flow in `docs/architecture.md` that runs it. Then classify it:
+   - **Code defect:** a scenario says what should happen, and the code does something else.
+   - **Spec gap:** no scenario covers this case.
+   - **Design flaw:** the design as written can't deliver what the scenario says.
+4. **Confirm the diagnosis.** Tell the user the classification, the scenario or its absence, and your evidence. They confirm it before anything changes. For a spec gap, stop and hand off to `architect "<tweak>"`. For a design flaw, stop and hand off to `rethink`.
+5. **Find the root cause.** Trace the failing path through the code until you can name the line that is wrong and why. The cause is the first wrong decision, not the place the error surfaces.
+6. **Write the failing test first.** On a branch such as `fix/<slug>`, add a test at the seam of the violated scenario, following `.agents/skills/cruze-behavioural-testing/SKILL.md`. It carries the scenario's ID and reproduces the bug. Run it, and see it fail for this bug's reason.
+7. **Fix it.** Make the smallest change in the module that owns the wrong decision, following `.agents/skills/cruze-hexagonal-design/SKILL.md`. Run `cruze check` on the files you changed, then the full test suite. Done when the new test passes and nothing else broke.
+8. **Commit** with a message such as `fix(<scope>): <what the user saw> (SCN-<id>)`.
+9. **Record it** with `cruze journal add bug --set summary="<what the user saw>" --set cause="<the root cause>" --set scenario=<SCN id> --set escaped="<the step that should have caught it>"`. `escaped` names the Cruze step that let the bug through, such as `verify`, or `none` when no step could have.
+
+## Rules
+
+- A missing test is part of the cause. When the violated scenario had a test that passed anyway, say why it missed the bug, and strengthen it in the same fix.
+- Fix the cause only. Clean-ups you notice nearby go to the user as suggestions.
+- Never change a scenario to match the code. That is a spec change, and it goes through `architect`.
+
+## Next step
+
+- Code defect fixed: `land`, which lands bug fixes too.
+- Spec gap: `architect "<tweak>"`.
+- Design flaw: `rethink`.

package/skills/verify/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: cruze-verify
+description: Verifies a built change before it lands, with the mechanical checks, a fresh-context verifier that runs the real system, a two-lane code review and a manual test script, ending with your decision to accept it or send it back.
+---
+
+# Verify
+
+Verify answers one question: does this change work when someone uses it? Green tests are evidence, not proof. A verifier in a fresh context runs the real system through each scenario, reviewers check the code against the spec and the architecture, and the user gets a script to try it themselves. The user decides whether it lands.
+
+## Steps
+
+1. **Check it is ready.** Run `cruze next`. It must name `verify` for this change, on this branch. Find the base commit the change branched from with `git merge-base main HEAD`.
+2. **Run the mechanical checks.** Run the project's format, lint, build and test commands from `commands:` in `.cruze/config.yaml`, then `cruze validate`, `cruze check --ci` and `cruze trace --change <ref>`. Quote each result. When one fails, fix the code in a commit and run them again. When a fix needs design, stop and offer `rethink`.
+3. **Check the dependencies.** Follow "Checking" in `.agents/skills/cruze-dependency-approval/SKILL.md` against the base commit. An unrecorded dependency is a blocker.
+4. **Run the verifier.** Run the verifier role from `.agents/skills/cruze-roles/SKILL.md` for the change. It must be able to build and run the system. When it runs through `cruze review`, check that `review.command` in `.cruze/config.yaml` allows the project's build and run commands, and add them with the user's agreement. Done when you have its report, with a result for every delivered scenario.
+5. **Review the code.** Run the review in the roles skill with the code reviewer, `review=code`, `--item <ref>` and the base commit. Fix each finding the user marks `fixed` in a commit, then check the fixes in round 2.
+6. **Write the manual test script** as `manual-test.md` in the change folder, following [manual-test.md](manual-test.md). Commit it.
+7. **Report.** Show the user four things:
+   - The mechanical checks, one line each.
+   - The verifier's result for every scenario.
+   - The review's outcome, with each finding's disposition.
+   - The path to `manual-test.md`, with a recommendation to run it before accepting.
+8. **Ask for the decision:** "Do you accept this change, or send it back?"
+9. **Record it** with `cruze journal add verification --set result=accepted --set summary="<one line>" --item <ref>`, or `result=sent-back`. On sent-back, say what goes back:
+   - A defect in code a task already built: `cruze task reopen T<n> "<reason>"`, then `build`.
+   - A design that can't deliver the scenario: `rethink`.
+
+Done when the decision is recorded.
+
+## Rules
+
+- A scenario the verifier couldn't run isn't passed. Mark it clearly in the report and in `manual-test.md`.
+- Findings from the review are dispositions in the journal, never edits to `change.md`.
+- Fixes made during verify are code commits that stay within the tasks' files. When a fix needs a new file or owner, it is a deviation or a rethink, exactly as in build.
+
+## Next step
+
+- Accepted: `land`.
+- Sent back: `build` for reopened tasks, or `rethink` for design.

package/skills/verify/manual-test.md

@@ -0,0 +1,23 @@
+# The manual test script
+
+`manual-test.md` in the change folder is what a person runs to see the change work with their own eyes. Write it for someone who knows the product but not the code.
+
+```markdown
+# Manual test: <change title>
+
+Setup, once:
+1. <build or install command, from the project's commands>
+2. <any configuration file to create, with its full content>
+
+## SCN-<id>: <scenario title>
+1. <exact command or action>
+2. <next action>
+Expected: <what they see, quoted from the scenario's THEN>
+Verifier: pass | fail | could not run (<what it needs>)
+```
+
+- One section per scenario the change delivers, in the order of the spec delta.
+- Every step is a command they can paste or an action they can take, with real values.
+- Expected results are quoted from the scenario.
+- Scenarios the verifier couldn't run come first, since they carry the most risk. Say what each needs, such as a serial device or a jump host.
+- Finish with how to clean up anything the setup created.

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

@@ -0,0 +1,75 @@
+import type { ProjectDeps } from "../../../app/project_context.ts";
+import type { AgentRunner } from "../../../app/ports/agent_runner.ts";
+import type { Prompter } from "../../../app/ports/prompter.ts";
+
+/** Everything a command handler needs, assembled by the composition root. */
+export interface CliContext extends ProjectDeps {
+  /** Asks a person; used only when the terminal is interactive and --yes is absent. */
+  interactivePrompter: Prompter;
+  /** Accepts every default. */
+  unattendedPrompter: Prompter;
+  interactive: boolean;
+  /** Starts an agent in a fresh context for `cruze review`. */
+  runner: AgentRunner;
+  /** Name of the working directory, the default project name. */
+  directoryName: string;
+}
+
+/** What a command produces: a JSON result for agents, a summary for people, and whether it passed. */
+export interface CommandResult {
+  json: unknown;
+  human: string;
+  /** Exit code 1 without an error: a check ran and found problems. */
+  failed?: boolean;
+}
+
+/** Parsed options, shared by every command; each handler reads the ones it accepts. */
+export interface Options {
+  name?: string;
+  yes: boolean;
+  agent: string[];
+  json: boolean;
+  title?: string;
+  feature?: string;
+  roadmap?: string;
+  change?: string;
+  commit?: string;
+  summary?: string;
+  goals?: string;
+  reason?: string;
+  set: string[];
+  item?: string;
+  event?: string;
+  out?: string;
+  redact: boolean;
+  all: boolean;
+  file: string[];
+  ci: boolean;
+  gate?: string;
+  override?: string;
+  overlap: boolean;
+  replan: string[];
+  rebase: string[];
+  round?: string;
+  package?: string;
+  base?: string;
+  blockers?: string;
+}
+
+export type Handler = (context: CliContext, args: string[], options: Options) => Promise<CommandResult>;
+
+export class UsageError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "UsageError";
+  }
+}
+
+export function requireArgs(args: string[], names: string[]): void {
+  if (args.length < names.length) throw new UsageError(`missing ${names.slice(args.length).map((n) => `<${n}>`).join(" ")}`);
+}
+
+export function requireOption<T>(value: T | undefined, flag: string): T {
+  if (value === undefined) throw new UsageError(`${flag} is required`);
+  return value;
+}

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

@@ -0,0 +1,30 @@
+import { checkCode, traceTests } from "../../../../app/use_cases/check_code.ts";
+import { landChange } from "../../../../app/use_cases/land_change.ts";
+import type { CliContext, CommandResult, Options } from "../cli_context.ts";
+
+export async function runCheck(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
+  const files = [...options.file, ...args];
+  const report = await checkCode(context, { ci: options.ci, ...(files.length === 0 ? {} : { files }) });
+  const lines = report.findings.map((f) => `${f.severity} ${f.path}${f.line === undefined ? "" : `:${f.line}`} ${f.message} [${f.rule}]`);
+  lines.push(`Checked ${report.checked} file(s): ${report.passed ? "passed" : "failed"}.`);
+  return { json: report, human: lines.join("\n"), failed: !report.passed };
+}
+
+export async function runTrace(context: CliContext, _args: string[], options: Options): Promise<CommandResult> {
+  const report = await traceTests(context, { all: options.all, ...(options.change === undefined ? {} : { change: options.change }) });
+  const lines = report.missing.map((id) => `missing test for ${id}`);
+  lines.push(...report.unknown.map((u) => `${u.path}:${u.line} cites ${u.id}, which no spec or delta defines`));
+  lines.push(`Traced ${report.scenarios.length} scenario(s) for ${report.scope}: ${report.passed ? "passed" : "failed"}.`);
+  return { json: report, human: lines.join("\n"), failed: !report.passed };
+}
+
+export async function runLand(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
+  const report = await landChange(context, args[0], options.override === undefined ? {} : { override: options.override });
+  const lines = [`Landed ${report.change}.`];
+  if (report.merged.length > 0) lines.push(`Merged into the living docs: ${report.merged.join(", ")}`);
+  if (report.built.length > 0) lines.push(`Now built: ${report.built.join(", ")}`);
+  if (report.removed.length > 0) lines.push(`Removed: ${report.removed.join(", ")}`);
+  if (report.restamped.length > 0) lines.push(`Re-stamped approvals: ${report.restamped.join(", ")}`);
+  if (report.archivedTo !== undefined) lines.push(`Finished; archived to ${report.archivedTo}.`);
+  return { json: report, human: lines.join("\n") };
+}

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

@@ -0,0 +1,52 @@
+import { approveArtifact } from "../../../../app/use_cases/approve_artifact.ts";
+import { PROJECT_DOC_KINDS, createNote, createProjectDoc, type ProjectDocKind } from "../../../../app/use_cases/new_project_doc.ts";
+import { createWorkItem, type NewKind } from "../../../../app/use_cases/new_work_item.ts";
+import { validate } from "../../../../app/use_cases/validate_project.ts";
+import type { Problem } from "../../../../domain/validation/problem.ts";
+import { UsageError, requireArgs, requireOption, type CliContext, type CommandResult, type Options } from "../cli_context.ts";
+
+export async function runValidate(context: CliContext): Promise<CommandResult> {
+  const report = await validate(context);
+  const summary = report.problems.length === 0 ? "No problems." : `${report.errors} error(s), ${report.warnings} warning(s).`;
+  return { json: report, human: [...report.problems.map(formatProblem), summary].join("\n"), failed: !report.valid };
+}
+
+export async function runApprove(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
+  requireArgs(args, ["document"]);
+  const report = await approveArtifact(context, args[0] ?? "", { replan: options.replan, rebase: options.rebase });
+  const lines = [`Approved ${report.artifact} (${report.hash.slice(0, 19)}), pinned to ${report.upstream.length} upstream element(s).`];
+  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(", ")}.`);
+  if (report.rebased.length > 0) lines.push(`Accepted the current living text of: ${report.rebased.join(", ")}.`);
+  return { json: report, human: lines.join("\n") };
+}
+
+export async function runNew(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
+  requireArgs(args, ["kind"]);
+  if (PROJECT_DOC_KINDS.includes(args[0] as ProjectDocKind)) {
+    const report = await createProjectDoc(context, args[0] as ProjectDocKind);
+    return { json: report, human: `Created ${report.path}` };
+  }
+  requireArgs(args, ["kind", "slug"]);
+  if (args[0] === "note") {
+    const report = await createNote(context, args[1] ?? "", requireOption(options.title, "--title"));
+    return { json: report, human: `Created ${report.path}` };
+  }
+  const kind = args[0] as NewKind;
+  if (!["feature", "change", "adr"].includes(kind)) {
+    throw new UsageError(`cruze new takes ${PROJECT_DOC_KINDS.join(", ")}, feature, change, adr or note, not "${args[0]}"`);
+  }
+  const report = await createWorkItem(context, {
+    kind,
+    slug: args[1] ?? "",
+    title: requireOption(options.title, "--title"),
+    ...(options.feature === undefined ? {} : { feature: options.feature }),
+    ...(options.roadmap === undefined ? {} : { roadmap: options.roadmap }),
+  });
+  return { json: report, human: `Created ${report.kind} ${report.ref} at ${report.path}` };
+}
+
+export function formatProblem(problem: Problem): string {
+  return `${problem.severity === "error" ? "error" : "warning"} ${problem.path}${problem.line === undefined ? "" : `:${problem.line}`} ${problem.message} [${problem.rule}]`;
+}

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

@@ -0,0 +1,23 @@
+import { initProject } from "../../../../app/use_cases/init_project.ts";
+import type { CliContext, CommandResult, Options } from "../cli_context.ts";
+import { describeSkillInstall } from "./install.ts";
+
+export async function runInit(context: CliContext, _args: string[], options: Options): Promise<CommandResult> {
+  const prompter = options.yes || !context.interactive ? context.unattendedPrompter : context.interactivePrompter;
+  const report = await initProject(
+    { files: context.files, bundle: context.bundle, prompter },
+    {
+      defaultName: context.directoryName,
+      agents: options.agent,
+      ...(options.name === undefined ? {} : { name: options.name }),
+      ...(options.package === undefined ? {} : { package: options.package }),
+    },
+  );
+
+  const lines = [`Initialized ${report.project} with Cruze ${report.skills.version}.`];
+  if (report.created.length > 0) lines.push(`Created: ${report.created.join(", ")}`);
+  if (report.skipped.length > 0) lines.push(`Left untouched (already present): ${report.skipped.join(", ")}`);
+  lines.push(...describeSkillInstall(report.skills));
+  lines.push("Next: open your coding agent in this repository and ask it what Cruze can do.");
+  return { json: report, human: lines.join("\n") };
+}

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

@@ -0,0 +1,15 @@
+import { installSkills, type InstallSkillsReport } from "../../../../app/use_cases/install_skills.ts";
+import type { CliContext, CommandResult, Options } from "../cli_context.ts";
+
+export async function runInstall(context: CliContext, _args: string[], options: Options): Promise<CommandResult> {
+  const report = await installSkills({ files: context.files, bundle: context.bundle }, { agents: options.agent });
+  return { json: report, human: describeSkillInstall(report).join("\n") };
+}
+
+export function describeSkillInstall(report: InstallSkillsReport): string[] {
+  const count = report.installed.length;
+  const lines = [`Installed ${count} Cruze skill${count === 1 ? "" : "s"} into .agents/skills/: ${report.installed.join(", ")}`];
+  if (report.removed.length > 0) lines.push(`Removed skills no longer shipped: ${report.removed.join(", ")}`);
+  for (const link of report.linked) lines.push(`Linked them for ${link.agent} in ${link.dir}/`);
+  return lines;
+}

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

@@ -0,0 +1,31 @@
+import { exportFeedback, listEvents, recordEvent } from "../../../../app/use_cases/journal_events.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> {
+  requireArgs(args, ["add|list"]);
+  if (args[0] === "add") {
+    requireArgs(args, ["add", "event"]);
+    const fields = Object.fromEntries(options.set.map((pair) => {
+      const at = pair.indexOf("=");
+      if (at < 1) throw new UsageError(`--set takes key=value, not "${pair}"`);
+      return [pair.slice(0, at), pair.slice(at + 1)];
+    }));
+    const entry = await recordEvent(context, args[1] ?? "", fields, options.item);
+    return { json: entry, human: `Recorded ${entry.event}.` };
+  }
+  if (args[0] === "list") {
+    const entries = await listEvents(context, options.event);
+    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]}"`);
+}
+
+export async function runFeedback(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
+  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`);
+    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

@@ -0,0 +1,51 @@
+import { addFutureFeature, completeTask, dropFutureFeature, 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";
+
+export async function runTask(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
+  requireArgs(args, ["done|deviation|reopen", "task"]);
+  const change = options.change === undefined ? {} : { change: options.change };
+  if (args[0] === "done") {
+    const report = await completeTask(context, args[1] ?? "", { ...change, ...(options.commit === undefined ? {} : { commit: options.commit }) });
+    return { json: report, human: `${report.task} done in ${report.change} (${report.done}/${report.total}).` };
+  }
+  if (args[0] === "deviation") {
+    requireArgs(args, ["deviation", "task", "text"]);
+    const report = await recordDeviation(context, args[1] ?? "", args.slice(2).join(" "), change);
+    return { json: report, human: `Recorded a deviation on ${report.task} in ${report.change}.` };
+  }
+  if (args[0] === "reopen") {
+    requireArgs(args, ["reopen", "task", "reason"]);
+    const report = await reopenTask(context, args[1] ?? "", args.slice(2).join(" "), change);
+    return { json: report, human: `Reopened ${report.task} in ${report.change}.` };
+  }
+  throw new UsageError(`cruze task takes done, deviation or reopen, not "${args[0]}"`);
+}
+
+export async function runFeatures(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
+  requireArgs(args, ["add|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] === "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]}"`);
+}
+
+export async function runRoadmap(context: CliContext, args: string[]): Promise<CommandResult> {
+  requireArgs(args, ["prune"]);
+  if (args[0] !== "prune") throw new UsageError(`cruze roadmap takes prune, not "${args[0]}"`);
+  const report = await pruneRoadmap(context);
+  return { json: report, human: report.removed.length === 0 ? "No landed items to clear." : `Cleared ${report.removed.join(", ")} from the roadmap status.` };
+}
+
+export async function runAbandon(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
+  requireArgs(args, ["ref"]);
+  const report = await abandonWork(context, args[0] ?? "", requireOption(options.reason, "--reason"));
+  const back = report.futureList === undefined ? "" : ` ${report.futureList} is back on the future list.`;
+  return { json: report, human: `Abandoned ${report.ref}; archived to ${report.archivedTo}.${back}` };
+}

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

@@ -0,0 +1,18 @@
+import { runReview } from "../../../../app/use_cases/run_review.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}`);
+  const report = await runReview(context, {
+    role: args[0] ?? "",
+    ...(options.item === undefined ? {} : { item: options.item }),
+    ...(round === undefined ? {} : { round }),
+    ...(blockers === undefined ? {} : { blockers }),
+    ...(options.base === undefined ? {} : { base: options.base }),
+  });
+  return { json: report, human: report.report };
+}

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

@@ -0,0 +1,45 @@
+import { checkBuildGate, findOverlaps, showStatus, suggestNext } from "../../../../app/use_cases/project_status.ts";
+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.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);
+    const human = report.passed
+      ? report.overridden ? `Build gate overridden and journaled:\n  ${report.reasons.join("\n  ")}` : "Build gate passed."
+      : `Build gate blocked:\n  ${report.reasons.join("\n  ")}`;
+    return { json: report, human, failed: !report.passed };
+  }
+  if (options.overlap) {
+    const report = await findOverlaps(context, options.change);
+    const human = report.overlaps.length === 0
+      ? `No other branch touches what ${report.change} touches.`
+      : report.overlaps.map((o) => `${o.branch}: ${o.item} also touches ${o.shared.join(", ")}`).join("\n");
+    return { json: report, human };
+  }
+  const report = await showStatus(context);
+  const lines = [`Branch: ${report.branch ?? "(none)"}${report.active === undefined ? "" : `, building ${report.active}`}`];
+  for (const doc of report.documents) lines.push(describe(doc.artifact, doc));
+  for (const feature of report.features) {
+    lines.push(describe(`feature ${feature.ref}`, feature.approval));
+    for (const change of feature.changes) {
+      const name = change.ref.split("/")[1] ?? change.ref;
+      lines.push(change.landed !== undefined ? `  ${name}: landed ${change.landed}` : `  ${describe(name, change.approval)}, tasks ${change.tasksDone}/${change.tasksTotal}`);
+    }
+  }
+  for (const change of report.standalone) lines.push(`${describe(`change ${change.ref}`, change.approval)}, tasks ${change.tasksDone}/${change.tasksTotal}`);
+  return { json: report, human: lines.join("\n") };
+}
+
+function describe(label: string, status: ApprovalStatus): string {
+  const detail = status.changed.length > 0 ? ` (${status.changed.join(", ")})` : status.unjournaled === true ? " (no journal entry)" : "";
+  return `${label}: ${status.state}${detail}`;
+}
+
+export async function runNext(context: CliContext): Promise<CommandResult> {
+  const report = await suggestNext(context);
+  const describe = (s: { step: string; target?: string; reason: string }): string => `${s.step}${s.target === undefined ? "" : ` ${s.target}`}: ${s.reason}`;
+  const lines = [`Next: ${describe(report.next)}`, ...report.also.map((s) => `Also: ${describe(s)}`)];
+  return { json: report, human: lines.join("\n") };
+}

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

@@ -0,0 +1,36 @@
+import type { Handler } from "./cli_context.ts";
+import { runCheck, runLand, runTrace } from "./commands/code.ts";
+import { runApprove, runNew, runValidate } from "./commands/documents.ts";
+import { runInit } from "./commands/init.ts";
+import { runInstall } from "./commands/install.ts";
+import { runFeedback, runJournal } from "./commands/journal.ts";
+import { runAbandon, runFeatures, runRoadmap, runTask } from "./commands/progress.ts";
+import { runReviewCommand } from "./commands/review.ts";
+import { runNext, runStatus } from "./commands/status.ts";
+
+export const COMMANDS: Record<string, { handler: Handler; usage: string }> = {
+  init: { handler: runInit, usage: "init [--name <name>] [--yes] [--agent <agent>] [--package <npm spec>]   set up this repository and install the skills" },
+  install: { handler: runInstall, usage: "install [--agent <agent>]                         install or update the Cruze skills" },
+  validate: { handler: runValidate, usage: "validate                                          check every document against the formats" },
+  status: { handler: runStatus, usage: "status [--gate build [--override <reason>]] [--overlap [--change <ref>]]" },
+  next: { handler: runNext, usage: "next                                              the step to run next on this branch, and why" },
+  approve: { handler: runApprove, usage: "approve <vision|architecture|roadmap|ref|path> [--replan <ID>...] [--rebase <ID>...]   record your approval of a document" },
+  new: { handler: runNew, usage: "new <vision|glossary|architecture|roadmap> | new <feature|change|adr|note> <slug> --title <title> [--feature <ref>] [--roadmap <slug>]" },
+  task: { handler: runTask, usage: "task <done|deviation|reopen> <T#> [text] [--change <ref>] [--commit <sha>]" },
+  features: { handler: runFeatures, usage: "features <add|drop> <slug> [--summary <text> --goals <ids>] [--reason <text>]" },
+  roadmap: { handler: runRoadmap, usage: "roadmap prune                                     clear landed items from the roadmap status when a release closes" },
+  journal: { handler: runJournal, usage: "journal <add <event> --set key=value... [--item <ref>]|list [--event <event>]>" },
+  review: { handler: runReviewCommand, usage: "review <role> [--item <ref>] [--round 1|2 --blockers <file>] [--base <commit>]   run a role in a fresh agent context" },
+  feedback: { handler: runFeedback, usage: "feedback export [--out <file>] [--no-redact]" },
+  trace: { handler: runTrace, usage: "trace [--all] [--change <ref>]                    link scenarios to the tests that prove them" },
+  check: { handler: runCheck, usage: "check [<file>...] [--ci]                          enforce layer rules and file budgets" },
+  abandon: { handler: runAbandon, usage: "abandon <ref> --reason <text>                     archive a feature or standalone change that stops for good" },
+  land: { handler: runLand, usage: "land [<ref>] [--override <reason>]                merge a verified change into the living docs" },
+};
+
+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.`;

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

@@ -0,0 +1,90 @@
+import { parseArgs } from "node:util";
+import { UsageError, type Options } from "./cli_context.ts";
+
+export interface ParsedCommand {
+  /** The command and, for grouped commands, its subcommand, such as `new feature`. */
+  words: string[];
+  options: Options;
+  help: boolean;
+  version: boolean;
+}
+
+export function parseCommand(argv: string[]): ParsedCommand {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        name: { type: "string" },
+        yes: { type: "boolean", short: "y", default: false },
+        agent: { type: "string", multiple: true, default: [] },
+        json: { type: "boolean", default: false },
+        version: { type: "boolean", short: "v", default: false },
+        help: { type: "boolean", short: "h", default: false },
+        title: { type: "string" },
+        feature: { type: "string" },
+        roadmap: { type: "string" },
+        change: { type: "string" },
+        commit: { type: "string" },
+        summary: { type: "string" },
+        goals: { type: "string" },
+        reason: { type: "string" },
+        set: { type: "string", multiple: true, default: [] },
+        item: { type: "string" },
+        event: { type: "string" },
+        out: { type: "string" },
+        "no-redact": { type: "boolean", default: false },
+        all: { type: "boolean", default: false },
+        file: { type: "string", multiple: true, default: [] },
+        ci: { type: "boolean", default: false },
+        gate: { type: "string" },
+        override: { type: "string" },
+        overlap: { type: "boolean", default: false },
+        round: { type: "string" },
+        package: { type: "string" },
+        replan: { type: "string", multiple: true, default: [] },
+        rebase: { type: "string", multiple: true, default: [] },
+        base: { type: "string" },
+        blockers: { type: "string" },
+      },
+    });
+  } catch (error) {
+    throw new UsageError(error instanceof Error ? error.message : String(error));
+  }
+  const { values, positionals } = 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,
+    set: values.set,
+    redact: !values["no-redact"],
+    all: values.all,
+    file: values.file,
+    ci: values.ci,
+    overlap: values.overlap,
+    replan: values.replan,
+    rebase: values.rebase,
+    ...optional("name", values.name),
+    ...optional("title", values.title),
+    ...optional("feature", values.feature),
+    ...optional("roadmap", values.roadmap),
+    ...optional("change", values.change),
+    ...optional("commit", values.commit),
+    ...optional("summary", values.summary),
+    ...optional("goals", values.goals),
+    ...optional("reason", values.reason),
+    ...optional("item", values.item),
+    ...optional("event", values.event),
+    ...optional("out", values.out),
+    ...optional("gate", values.gate),
+    ...optional("override", values.override),
+    ...optional("round", values.round),
+    ...optional("package", values.package),
+    ...optional("base", values.base),
+    ...optional("blockers", values.blockers),
+  };
+  return { words: positionals, options, help: values.help, version: values.version };
+}

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

@@ -0,0 +1,50 @@
+import { CruzeError } from "../../../domain/cruze_error.ts";
+import { type CliContext, UsageError } from "./cli_context.ts";
+import { COMMANDS, USAGE } from "./commands.ts";
+import { parseCommand } from "./parse_command.ts";
+
+export interface Terminal {
+  stdout(text: string): void;
+  stderr(text: string): void;
+  /** True when stdout is a terminal, so a person rather than an agent is reading it. */
+  stdoutIsTerminal: boolean;
+}
+
+/**
+ * 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.
+ */
+export async function runCli(argv: string[], context: CliContext, terminal: Terminal): Promise<number> {
+  let json = !terminal.stdoutIsTerminal || argv.includes("--json");
+  try {
+    const parsed = parseCommand(argv);
+    json ||= parsed.options.json;
+    if (parsed.version) {
+      terminal.stdout(context.bundle.version);
+      return 0;
+    }
+    const [name, ...args] = parsed.words;
+    if (parsed.help || name === undefined || name === "help") {
+      terminal.stderr(USAGE);
+      return 0;
+    }
+    const command = COMMANDS[name];
+    if (command === undefined) throw new UsageError(`Unknown command: ${name}`);
+    const result = await command.handler(context, args, parsed.options);
+    terminal.stderr(result.human);
+    if (json) terminal.stdout(JSON.stringify(result.json, null, 2));
+    return result.failed === true ? 1 : 0;
+  } catch (error) {
+    if (error instanceof UsageError) {
+      terminal.stderr(`${error.message}\n\n${USAGE}`);
+      if (json) terminal.stdout(JSON.stringify({ error: { code: "usage", message: error.message } }));
+      return 2;
+    }
+    if (error instanceof CruzeError) {
+      terminal.stderr(`cruze: ${error.message}`);
+      if (json) terminal.stdout(JSON.stringify({ error: { code: error.code, message: error.message } }));
+      return 1;
+    }
+    throw error;
+  }
+}