work-kit-cli 0.2.7 → 0.3.0

package/cli/src/config/loopback-routes.ts

@@ -1,45 +1,45 @@
-import { PhaseName, Location } from "../state/schema.js";
+import { Location, StepOutcome } from "../state/schema.js";
 
 /**
- * Defines when a completed sub-stage should trigger a loop-back
+ * Defines when a completed step should trigger a loop-back
  * based on its outcome.
  */
 export interface LoopbackRoute {
   from: Location;
-  triggerOutcome: string;
+  triggerOutcome: StepOutcome;
   to: Location;
   reason: string;
 }
 
 export const LOOPBACK_ROUTES: LoopbackRoute[] = [
   {
-    from: { phase: "plan", subStage: "audit" },
+    from: { phase: "plan", step: "audit" },
     triggerOutcome: "revise",
-    to: { phase: "plan", subStage: "blueprint" },
+    to: { phase: "plan", step: "blueprint" },
     reason: "Audit found gaps — revising Blueprint",
   },
   {
-    from: { phase: "build", subStage: "refactor" },
+    from: { phase: "build", step: "refactor" },
     triggerOutcome: "broken",
-    to: { phase: "build", subStage: "core" },
+    to: { phase: "build", step: "core" },
     reason: "Refactor broke tests — re-running Core to fix",
   },
   {
-    from: { phase: "review", subStage: "handoff" },
+    from: { phase: "review", step: "handoff" },
     triggerOutcome: "changes_requested",
-    to: { phase: "build", subStage: "core" },
+    to: { phase: "build", step: "core" },
     reason: "Review requested changes — looping back to Build/Core",
   },
   {
-    from: { phase: "deploy", subStage: "merge" },
+    from: { phase: "deploy", step: "merge" },
     triggerOutcome: "fix_needed",
-    to: { phase: "build", subStage: "core" },
+    to: { phase: "build", step: "core" },
     reason: "Merge blocked — fix needed in Build/Core",
   },
   {
-    from: { phase: "deploy", subStage: "remediate" },
+    from: { phase: "deploy", step: "remediate" },
     triggerOutcome: "fix_and_redeploy",
-    to: { phase: "build", subStage: "core" },
+    to: { phase: "build", step: "core" },
     reason: "Deployment issue — fix and redeploy from Build/Core",
   },
 ];

package/cli/src/config/project-config.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, afterEach } from "node:test";
+import * as assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { randomUUID } from "node:crypto";
+import { loadProjectConfig } from "./project-config.js";
+import { resolveParallelGroups, DEFAULT_PARALLEL_GROUPS } from "../workflow/parallel.js";
+import { PROJECT_CONFIG_FILE } from "./constants.js";
+
+function makeTmpDir(): string {
+  const dir = path.join(os.tmpdir(), `wk-config-${randomUUID()}`);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+let tmpDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of tmpDirs) fs.rmSync(dir, { recursive: true, force: true });
+  tmpDirs = [];
+});
+
+describe("loadProjectConfig", () => {
+  it("returns empty config when file is missing", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    const config = loadProjectConfig(tmp);
+    assert.deepStrictEqual(config, {});
+  });
+
+  it("loads valid defaults", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    fs.writeFileSync(
+      path.join(tmp, PROJECT_CONFIG_FILE),
+      JSON.stringify({ defaults: { mode: "auto", classification: "feature", gated: true } }),
+    );
+    const config = loadProjectConfig(tmp);
+    assert.equal(config.defaults?.mode, "auto");
+    assert.equal(config.defaults?.classification, "feature");
+    assert.equal(config.defaults?.gated, true);
+  });
+
+  it("ignores invalid mode and classification", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    fs.writeFileSync(
+      path.join(tmp, PROJECT_CONFIG_FILE),
+      JSON.stringify({ defaults: { mode: "wat", classification: "nope" } }),
+    );
+    const config = loadProjectConfig(tmp);
+    assert.equal(config.defaults?.mode, undefined);
+    assert.equal(config.defaults?.classification, undefined);
+  });
+
+  it("loads parallel group overrides", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    fs.writeFileSync(
+      path.join(tmp, PROJECT_CONFIG_FILE),
+      JSON.stringify({
+        parallel: {
+          test: { parallel: ["verify"], thenSequential: "validate" },
+        },
+      }),
+    );
+    const config = loadProjectConfig(tmp);
+    assert.deepStrictEqual(config.parallel?.test, { parallel: ["verify"], thenSequential: "validate" });
+  });
+
+  it("filters invalid step names from parallel overrides", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    fs.writeFileSync(
+      path.join(tmp, PROJECT_CONFIG_FILE),
+      JSON.stringify({
+        parallel: { test: { parallel: ["verify", "made-up"] } },
+      }),
+    );
+    const config = loadProjectConfig(tmp);
+    assert.deepStrictEqual(config.parallel?.test?.parallel, ["verify"]);
+  });
+
+  it("validates workflow include/exclude refs", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    fs.writeFileSync(
+      path.join(tmp, PROJECT_CONFIG_FILE),
+      JSON.stringify({
+        workflow: { include: ["review/security", "bogus/step"], exclude: ["test/e2e"] },
+      }),
+    );
+    const config = loadProjectConfig(tmp);
+    assert.deepStrictEqual(config.workflow?.include, ["review/security"]);
+    assert.deepStrictEqual(config.workflow?.exclude, ["test/e2e"]);
+  });
+
+  it("survives invalid JSON", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    fs.writeFileSync(path.join(tmp, PROJECT_CONFIG_FILE), "not json");
+    const config = loadProjectConfig(tmp);
+    assert.deepStrictEqual(config, {});
+  });
+});
+
+describe("resolveParallelGroups", () => {
+  it("returns defaults with no project root", () => {
+    assert.deepStrictEqual(resolveParallelGroups(), DEFAULT_PARALLEL_GROUPS);
+  });
+
+  it("merges project overrides over defaults", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    fs.writeFileSync(
+      path.join(tmp, PROJECT_CONFIG_FILE),
+      JSON.stringify({
+        parallel: { test: { parallel: ["verify"], thenSequential: "validate" } },
+      }),
+    );
+    const groups = resolveParallelGroups(tmp);
+    assert.deepStrictEqual(groups.test, { parallel: ["verify"], thenSequential: "validate" });
+    // review (not overridden) keeps default
+    assert.deepStrictEqual(groups.review, DEFAULT_PARALLEL_GROUPS.review);
+  });
+});

package/cli/src/config/project-config.ts

@@ -0,0 +1,106 @@
+import * as path from "node:path";
+import {
+  PHASE_NAMES,
+  STEPS_BY_PHASE,
+  isClassification,
+  type PhaseName,
+  type Classification,
+} from "../state/schema.js";
+import { readJsonFile } from "../utils/json.js";
+import { PROJECT_CONFIG_FILE } from "./constants.js";
+
+/**
+ * Optional `.work-kit-config.json` lives at the main repo root.
+ *
+ * Example:
+ *   {
+ *     "defaults": { "mode": "auto", "classification": "feature", "gated": false },
+ *     "parallel": {
+ *       "review": { "parallel": ["self-review", "security"], "thenSequential": "handoff" }
+ *     },
+ *     "workflow": {
+ *       "include": ["review/security"],
+ *       "exclude": ["review/performance"]
+ *     }
+ *   }
+ */
+export interface ProjectParallelGroup {
+  parallel: string[];
+  thenSequential?: string;
+}
+
+export interface ProjectConfig {
+  defaults?: {
+    mode?: "full" | "auto";
+    classification?: Classification;
+    gated?: boolean;
+  };
+  /** Override or extend the per-phase parallel groups. */
+  parallel?: Partial<Record<PhaseName, ProjectParallelGroup>>;
+  /** Force-include or force-exclude specific steps (phase/step). */
+  workflow?: {
+    include?: string[];
+    exclude?: string[];
+  };
+}
+
+const EMPTY_CONFIG: ProjectConfig = {};
+
+/** Load and validate the project config. Returns empty config when missing/invalid. */
+export function loadProjectConfig(mainRepoRoot: string): ProjectConfig {
+  const parsed = readJsonFile<unknown>(path.join(mainRepoRoot, PROJECT_CONFIG_FILE));
+  if (!parsed) return EMPTY_CONFIG;
+  return validateConfig(parsed);
+}
+
+function validateConfig(raw: any): ProjectConfig {
+  const out: ProjectConfig = {};
+
+  if (raw && typeof raw === "object") {
+    if (raw.defaults && typeof raw.defaults === "object") {
+      const d = raw.defaults;
+      out.defaults = {};
+      if (d.mode === "full" || d.mode === "auto") out.defaults.mode = d.mode;
+      if (typeof d.classification === "string" && isClassification(d.classification)) {
+        out.defaults.classification = d.classification;
+      }
+      if (typeof d.gated === "boolean") out.defaults.gated = d.gated;
+    }
+
+    if (raw.parallel && typeof raw.parallel === "object") {
+      out.parallel = {};
+      for (const [phase, group] of Object.entries(raw.parallel)) {
+        if (!(PHASE_NAMES as readonly string[]).includes(phase)) continue;
+        const g = group as any;
+        if (!g || !Array.isArray(g.parallel)) continue;
+        const validSteps = STEPS_BY_PHASE[phase as PhaseName];
+        const parallel = g.parallel.filter((s: any) => typeof s === "string" && validSteps.includes(s));
+        if (parallel.length === 0) continue;
+        const entry: ProjectParallelGroup = { parallel };
+        if (typeof g.thenSequential === "string" && validSteps.includes(g.thenSequential)) {
+          entry.thenSequential = g.thenSequential;
+        }
+        out.parallel[phase as PhaseName] = entry;
+      }
+    }
+
+    if (raw.workflow && typeof raw.workflow === "object") {
+      out.workflow = {};
+      for (const key of ["include", "exclude"] as const) {
+        if (Array.isArray(raw.workflow[key])) {
+          out.workflow[key] = raw.workflow[key].filter((s: any) => isValidStepRef(s));
+        }
+      }
+    }
+  }
+
+  return out;
+}
+
+function isValidStepRef(ref: any): boolean {
+  if (typeof ref !== "string") return false;
+  const [phase, step] = ref.split("/");
+  if (!phase || !step) return false;
+  if (!(PHASE_NAMES as readonly string[]).includes(phase)) return false;
+  return STEPS_BY_PHASE[phase as PhaseName].includes(step);
+}

package/cli/src/config/{phases.ts → workflow.ts}

@@ -1,15 +1,17 @@
 import {
   PhaseName,
-  SUBSTAGES_BY_PHASE,
+  PHASE_NAMES,
+  STEPS_BY_PHASE,
   Classification,
   WorkflowStep,
 } from "../state/schema.js";
+import { SKILL_DIR_PREFIX } from "./constants.js";
 
-// ── Phase Order ──────────────────────────────────────────────────────
+// ── Phase Order ─────────────────────────────────────────────────────
 
-export const PHASE_ORDER: PhaseName[] = ["plan", "build", "test", "review", "deploy", "wrap-up"];
+export const PHASE_ORDER: PhaseName[] = [...PHASE_NAMES];
 
-// ── Prerequisites ────────────────────────────────────────────────────
+// ── Prerequisites ───────────────────────────────────────────────────
 
 export const PHASE_PREREQUISITES: Record<PhaseName, PhaseName | null> = {
   plan: null,
@@ -20,15 +22,15 @@ export const PHASE_PREREQUISITES: Record<PhaseName, PhaseName | null> = {
   "wrap-up": "review", // or deploy if deploy was included
 };
 
-// ── Skill File Paths ─────────────────────────────────────────────────
+// ── Skill File Paths ────────────────────────────────────────────────
 
-export function skillFilePath(phase: PhaseName, subStage?: string): string {
-  const dir = `wk-${phase}`;
-  if (!subStage) return `.claude/skills/${dir}/SKILL.md`;
-  return `.claude/skills/${dir}/stages/${subStage}.md`;
+export function skillFilePath(phase: PhaseName, step?: string): string {
+  const dir = `${SKILL_DIR_PREFIX}${phase}`;
+  if (!step) return `.claude/skills/${dir}/SKILL.md`;
+  return `.claude/skills/${dir}/steps/${step}.md`;
 }
 
-// ── Auto-kit Default Workflows ───────────────────────────────────────
+// ── Auto-kit Default Workflows ──────────────────────────────────────
 
 type InclusionRule = "YES" | "skip" | "if UI" | "if DB" | "optional";
 
@@ -42,7 +44,7 @@ const WORKFLOW_MATRIX: Record<Classification, Record<string, InclusionRule>> = {
     "review/self-review": "YES", "review/security": "skip", "review/performance": "skip",
     "review/compliance": "skip", "review/handoff": "YES",
     "deploy/merge": "YES", "deploy/monitor": "optional", "deploy/remediate": "optional",
-    "wrap-up/wrap-up": "YES",
+    "wrap-up/summary": "YES",
   },
   "small-change": {
     "plan/clarify": "YES", "plan/investigate": "skip", "plan/sketch": "skip", "plan/scope": "skip",
@@ -53,7 +55,7 @@ const WORKFLOW_MATRIX: Record<Classification, Record<string, InclusionRule>> = {
     "review/self-review": "YES", "review/security": "skip", "review/performance": "skip",
     "review/compliance": "skip", "review/handoff": "YES",
     "deploy/merge": "YES", "deploy/monitor": "optional", "deploy/remediate": "optional",
-    "wrap-up/wrap-up": "YES",
+    "wrap-up/summary": "YES",
   },
   refactor: {
     "plan/clarify": "YES", "plan/investigate": "YES", "plan/sketch": "skip", "plan/scope": "skip",
@@ -64,7 +66,7 @@ const WORKFLOW_MATRIX: Record<Classification, Record<string, InclusionRule>> = {
     "review/self-review": "YES", "review/security": "skip", "review/performance": "YES",
     "review/compliance": "skip", "review/handoff": "YES",
     "deploy/merge": "YES", "deploy/monitor": "optional", "deploy/remediate": "optional",
-    "wrap-up/wrap-up": "YES",
+    "wrap-up/summary": "YES",
   },
   feature: {
     "plan/clarify": "YES", "plan/investigate": "YES", "plan/sketch": "YES", "plan/scope": "YES",
@@ -75,7 +77,7 @@ const WORKFLOW_MATRIX: Record<Classification, Record<string, InclusionRule>> = {
     "review/self-review": "YES", "review/security": "YES", "review/performance": "skip",
     "review/compliance": "YES", "review/handoff": "YES",
     "deploy/merge": "YES", "deploy/monitor": "optional", "deploy/remediate": "optional",
-    "wrap-up/wrap-up": "YES",
+    "wrap-up/summary": "YES",
   },
   "large-feature": {
     "plan/clarify": "YES", "plan/investigate": "YES", "plan/sketch": "YES", "plan/scope": "YES",
@@ -86,20 +88,35 @@ const WORKFLOW_MATRIX: Record<Classification, Record<string, InclusionRule>> = {
     "review/self-review": "YES", "review/security": "YES", "review/performance": "YES",
     "review/compliance": "YES", "review/handoff": "YES",
     "deploy/merge": "YES", "deploy/monitor": "optional", "deploy/remediate": "optional",
-    "wrap-up/wrap-up": "YES",
+    "wrap-up/summary": "YES",
   },
 };
 
-export function buildDefaultWorkflow(classification: Classification): WorkflowStep[] {
+export function buildDefaultWorkflow(
+  classification: Classification,
+  overrides?: { include?: string[]; exclude?: string[] }
+): WorkflowStep[] {
   const matrix = WORKFLOW_MATRIX[classification];
   const steps: WorkflowStep[] = [];
 
+  const forceInclude = new Set(overrides?.include ?? []);
+  const forceExclude = new Set(overrides?.exclude ?? []);
+
   for (const [key, rule] of Object.entries(matrix)) {
-    const [phase, subStage] = key.split("/") as [PhaseName, string];
-    // "YES" always included, "skip" excluded, conditional ones included by default (user can remove)
-    const included = rule === "YES" || rule === "if UI" || rule === "if DB";
-    if (rule !== "skip") {
-      steps.push({ phase, subStage, included });
+    const [phase, step] = key.split("/") as [PhaseName, string];
+    let included = rule === "YES" || rule === "if UI" || rule === "if DB";
+    if (forceInclude.has(key)) included = true;
+    if (forceExclude.has(key)) included = false;
+    // "skip" excluded by default, but project config may force-include
+    if (rule === "skip" && !forceInclude.has(key)) continue;
+    steps.push({ phase, step, included });
+  }
+
+  // Add any force-included steps not in the matrix
+  for (const ref of forceInclude) {
+    const [phase, step] = ref.split("/") as [PhaseName, string];
+    if (!steps.some(s => s.phase === phase && s.step === step)) {
+      steps.push({ phase, step, included: true });
     }
   }
 
@@ -109,8 +126,8 @@ export function buildDefaultWorkflow(classification: Classification): WorkflowSt
 export function buildFullWorkflow(): WorkflowStep[] {
   const steps: WorkflowStep[] = [];
   for (const phase of PHASE_ORDER) {
-    for (const subStage of SUBSTAGES_BY_PHASE[phase]) {
-      steps.push({ phase, subStage, included: true });
+    for (const step of STEPS_BY_PHASE[phase]) {
+      steps.push({ phase, step, included: true });
     }
   }
   return steps;

package/cli/src/context/prompt-builder.ts

@@ -2,27 +2,28 @@ import { WorkKitState, PhaseName } from "../state/schema.js";
 import { getContextFor } from "../config/agent-map.js";
 import { extractSection, extractTopSection } from "./extractor.js";
 import { readStateMd } from "../state/store.js";
-import { skillFilePath } from "../config/phases.js";
+import { skillFilePath } from "../config/workflow.js";
 import { redactIgnoredBlocks } from "./redactor.js";
+import { CLI_BINARY } from "../config/constants.js";
 
 /**
- * Build a complete agent prompt for a given phase/sub-stage.
+ * Build a complete agent prompt for a given phase/step.
  * Accepts optional pre-read stateMd to avoid repeated file reads in parallel scenarios.
  */
 export function buildAgentPrompt(
   worktreeRoot: string,
   state: WorkKitState,
   phase: PhaseName,
-  subStage: string,
+  step: string,
   stateMd?: string | null
 ): string {
-  const ctx = getContextFor(phase, subStage);
+  const ctx = getContextFor(phase, step);
   const md = stateMd ?? readStateMd(worktreeRoot);
-  const skill = skillFilePath(phase, subStage);
+  const skill = skillFilePath(phase, step);
 
   const parts: string[] = [];
 
-  parts.push(`# Agent: ${phase}/${subStage}`);
+  parts.push(`# Agent: ${phase}/${step}`);
   parts.push(`**Worktree:** ${worktreeRoot}`);
   parts.push(`**Slug:** ${state.slug}`);
   parts.push(`**Branch:** ${state.branch}`);
@@ -59,12 +60,12 @@ export function buildAgentPrompt(
   }
 
   parts.push(`## Output`);
-  parts.push(`Write your outputs to \`.work-kit/state.md\` under a section for this sub-stage.`);
+  parts.push(`Write your outputs to \`.work-kit/state.md\` under a section for this step.`);
 
-  if (subStage === "wrap-up") {
+  if (step === "wrap-up") {
     parts.push(`Follow the wrap-up skill file instructions for archiving and cleanup.`);
   } else {
-    parts.push(`When done, report your outcome so the orchestrator can run: \`npx work-kit-cli complete ${phase}/${subStage} --outcome <outcome>\``);
+    parts.push(`When done, report your outcome so the orchestrator can run: \`${CLI_BINARY} complete ${phase}/${step} --outcome <outcome>\``);
   }
 
   return redactIgnoredBlocks(parts.join("\n"));

package/cli/src/index.ts

@@ -17,6 +17,9 @@ import { observeCommand } from "./commands/observe.js";
 import { uninstallCommand } from "./commands/uninstall.js";
 import { bootstrapCommand } from "./commands/bootstrap.js";
 import { cancelCommand } from "./commands/cancel.js";
+import { pauseCommand } from "./commands/pause.js";
+import { resumeCommand } from "./commands/resume.js";
+import { reportCommand } from "./commands/report.js";
 import { bold, green, yellow, red } from "./utils/colors.js";
 import type { Classification, PhaseName } from "./state/schema.js";
 
@@ -37,7 +40,7 @@ program
 program
   .command("init")
   .description("Create worktree and initialize state")
-  .requiredOption("--mode <mode>", "Workflow mode: full or auto")
+  .option("--mode <mode>", "Workflow mode: full or auto (default: from project config or 'full')")
   .requiredOption("--description <text>", "Description of the work")
   .option("--classification <type>", "Work classification (auto mode): bug-fix, small-change, refactor, feature, large-feature")
   .option("--gated", "Wait for user approval between phases (default: auto-proceed)")
@@ -45,10 +48,10 @@ program
   .action((opts) => {
     try {
       const result = initCommand({
-        mode: opts.mode as "full" | "auto",
+        mode: opts.mode as "full" | "auto" | undefined,
         description: opts.description,
         classification: opts.classification as Classification | undefined,
-        gated: opts.gated || false,
+        gated: opts.gated,
         worktreeRoot: opts.worktreeRoot,
       });
       console.log(JSON.stringify(result, null, 2));
@@ -78,7 +81,7 @@ program
 
 program
   .command("complete <target>")
-  .description("Mark a phase/sub-stage as complete (e.g., plan/clarify)")
+  .description("Mark a phase/step as complete (e.g., plan/clarify)")
   .option("--outcome <value>", "Outcome of the step (e.g., done, revise, broken, changes_requested)")
   .option("--worktree-root <path>", "Override worktree root")
   .action((target, opts) => {
@@ -144,8 +147,8 @@ program
 program
   .command("loopback")
   .description("Register a loop-back transition")
-  .requiredOption("--from <source>", "Source phase/sub-stage (e.g., review/handoff)")
-  .requiredOption("--to <target>", "Target phase/sub-stage (e.g., build/core)")
+  .requiredOption("--from <source>", "Source phase/step (e.g., review/handoff)")
+  .requiredOption("--to <target>", "Target phase/step (e.g., build/core)")
   .requiredOption("--reason <text>", "Reason for loop-back")
   .option("--worktree-root <path>", "Override worktree root")
   .action((opts) => {
@@ -260,9 +263,10 @@ program
   .command("bootstrap")
   .description("Detect work-kit state and output session orientation")
   .option("--json", "Output as JSON", true)
+  .option("--auto-resume", "If paused or stale, auto-flip to in-progress")
   .action((opts) => {
     try {
-      const result = bootstrapCommand();
+      const result = bootstrapCommand(undefined, { autoResume: opts.autoResume });
       console.log(JSON.stringify(result, null, 2));
     } catch (e: any) {
       console.error(JSON.stringify({ action: "error", message: e.message }));
@@ -270,6 +274,58 @@ program
     }
   });
 
+// ── pause ───────────────────────────────────────────────────────────
+
+program
+  .command("pause")
+  .description("Pause the active work-kit session")
+  .option("--reason <text>", "Optional reason for pausing")
+  .option("--worktree-root <path>", "Override worktree root")
+  .action((opts) => {
+    try {
+      const result = pauseCommand(opts.reason, opts.worktreeRoot);
+      console.log(JSON.stringify(result, null, 2));
+      process.exit(result.action === "error" ? 1 : 0);
+    } catch (e: any) {
+      console.error(JSON.stringify({ action: "error", message: e.message }));
+      process.exit(1);
+    }
+  });
+
+// ── resume ──────────────────────────────────────────────────────────
+
+program
+  .command("resume")
+  .description("Resume a paused work-kit session")
+  .option("--worktree-root <path>", "Override worktree root")
+  .action((opts) => {
+    try {
+      const result = resumeCommand(opts.worktreeRoot);
+      console.log(JSON.stringify(result, null, 2));
+      process.exit(result.action === "error" ? 1 : 0);
+    } catch (e: any) {
+      console.error(JSON.stringify({ action: "error", message: e.message }));
+      process.exit(1);
+    }
+  });
+
+// ── report ──────────────────────────────────────────────────────────
+
+program
+  .command("report")
+  .description("Show stats across completed work-kits")
+  .option("--json", "Output as JSON")
+  .option("--repo <path>", "Main repository root")
+  .option("--worktree-root <path>", "Override worktree root")
+  .action((opts) => {
+    try {
+      reportCommand({ json: opts.json, repo: opts.repo, worktreeRoot: opts.worktreeRoot });
+    } catch (e: any) {
+      console.error(JSON.stringify({ action: "error", message: e.message }));
+      process.exit(1);
+    }
+  });
+
 // ── cancel ──────────────────────────────────────────────────────────
 
 program