forge-workflow 0.0.10 → 0.1.0-beta.3

package/lib/commands/migrate.js

@@ -0,0 +1,362 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const {
+  buildMigrationDryRunReport,
+  renderMigrationDryRunReport,
+} = require('../migrate-dry-run');
+const {
+  loadBeadsSnapshotFromDirectory,
+  importBeadsSnapshot,
+} = require('../adapters/beads-kernel-compat');
+const { buildMigratedKernelIssueDeps } = require('../kernel/cli-broker-factory');
+
+function hasArg(args, name) {
+  return Array.isArray(args) && args.includes(name);
+}
+
+/**
+ * Parse `forge migrate` options from positional args (with a parsed flags object
+ * as a fallback). Supported: --from <source>, --source <dir>, --dry-run, --json.
+ * Unknown tokens are ignored so the legacy v2→v3 PoC flags pass through untouched.
+ */
+function parseMigrateOptions(args = [], flags = {}) {
+  const options = {
+    from: flags.from,
+    source: flags.source,
+    dryRun: Boolean(flags.dryRun || flags['dry-run']),
+    json: Boolean(flags.json),
+    errors: [],
+  };
+
+  const takeValue = (arg, prefix, current, index) => {
+    if (arg.startsWith(`${prefix}=`)) {
+      const value = arg.slice(prefix.length + 1);
+      if (!value) options.errors.push(`${prefix} requires a value`);
+      return { value: value || current, next: index };
+    }
+    const candidate = args[index + 1];
+    if (candidate && !candidate.startsWith('--')) {
+      return { value: candidate, next: index + 1 };
+    }
+    options.errors.push(`${prefix} requires a value`);
+    return { value: current, next: index };
+  };
+
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    if (arg === '--dry-run') options.dryRun = true;
+    else if (arg === '--json') options.json = true;
+    else if (arg === '--from' || arg.startsWith('--from=')) {
+      const parsed = takeValue(arg, '--from', options.from, i);
+      options.from = parsed.value;
+      i = parsed.next;
+    } else if (arg === '--source' || arg.startsWith('--source=')) {
+      const parsed = takeValue(arg, '--source', options.source, i);
+      options.source = parsed.value;
+      i = parsed.next;
+    }
+    i += 1;
+  }
+
+  return options;
+}
+
+function directoryHasJsonl(dir, fsImpl) {
+  try {
+    return fsImpl.readdirSync(dir).some(entry => entry.endsWith('.jsonl'));
+  } catch (_err) {
+    /* intentional: unreadable directory has no usable jsonl */ // NOSONAR S2486
+    return false;
+  }
+}
+
+/**
+ * Export a Dolt-only Beads store to JSONL in a temp dir via `bd export --all`,
+ * then return that dir for the loader. Defensive: a missing `bd` on PATH yields a
+ * clear, actionable error instead of a stack trace.
+ *
+ * NOTE (flagged ambiguity): the exact on-disk shape `bd export --all` emits is not
+ * pinned in this repo. We capture stdout into `<temp>/issues.jsonl`, which the
+ * loader reads. Operators with a different layout should prefer `--source <dir>`.
+ */
+function exportDoltStoreToJsonl(beadsDir, projectRoot, deps) {
+  const exec = deps.execFileSync || execFileSync;
+  const fsImpl = deps.fs || fs;
+  const tempDir = fsImpl.mkdtempSync(path.join(os.tmpdir(), 'forge-migrate-bd-'));
+  try {
+    const stdout = exec('bd', ['export', '--all'], {
+      cwd: projectRoot || process.cwd(),
+      encoding: 'utf8',
+    });
+    fsImpl.writeFileSync(path.join(tempDir, 'issues.jsonl'), stdout || '');
+    return { dir: tempDir, kind: 'dolt-export', temp: tempDir };
+  } catch (err) {
+    fsImpl.rmSync(tempDir, { recursive: true, force: true });
+    const message = err && err.message ? err.message : String(err);
+    if (/ENOENT|not found|not recognized|no such file/i.test(message)) {
+      return {
+        error:
+          "Beads CLI 'bd' is not on PATH — cannot export the Dolt store at " +
+          `${beadsDir}. Install bd, or pass --source <dir> with exported *.jsonl files.`,
+      };
+    }
+    return { error: `bd export --all failed: ${message}` };
+  }
+}
+
+/**
+ * Resolve the directory holding Beads JSONL the loader will read.
+ *   1. --source wins (used as given).
+ *   2. else auto-detect a `.beads/` dir containing *.jsonl.
+ *   3. else a Dolt-only `.beads/` (no jsonl) → `bd export --all` into a temp dir.
+ *   4. else nothing found.
+ */
+function resolveBeadsSource(options, projectRoot, deps) {
+  const fsImpl = deps.fs || fs;
+  const root = projectRoot || process.cwd();
+
+  if (options.source) {
+    const dir = path.resolve(root, options.source);
+    if (!fsImpl.existsSync(dir)) {
+      return { error: `No beads data found at --source ${dir} (directory does not exist)` };
+    }
+    return { dir, kind: 'source' };
+  }
+
+  const beadsDir = path.join(root, '.beads');
+  if (fsImpl.existsSync(beadsDir)) {
+    if (directoryHasJsonl(beadsDir, fsImpl)) {
+      return { dir: beadsDir, kind: 'jsonl-autodetect' };
+    }
+    return exportDoltStoreToJsonl(beadsDir, root, deps);
+  }
+
+  return {
+    error:
+      'No beads data found. Looked for a .beads/ directory with *.jsonl under ' +
+      `${root}. Pass --source <dir> to point at an exported Beads store.`,
+  };
+}
+
+function cleanupResolved(resolved, deps) {
+  if (resolved && resolved.temp) {
+    const fsImpl = deps.fs || fs;
+    fsImpl.rmSync(resolved.temp, { recursive: true, force: true });
+  }
+}
+
+function summarizeGaps(gaps) {
+  const items = Array.isArray(gaps) ? gaps : [];
+  return {
+    count: items.length,
+    items: items.map(gap => ({ field: gap.field, reason: gap.reason })),
+  };
+}
+
+function renderHuman(payload) {
+  if (payload.error) {
+    return `forge migrate failed: ${payload.error}`;
+  }
+
+  const gaps = payload.gaps || { count: 0, items: [] };
+  const gapBrief = gaps.count > 0
+    ? ` (${gaps.items.map(item => item.field).join(', ')})`
+    : '';
+
+  if (payload.dryRun) {
+    return [
+      `Dry run — would import beads → kernel from ${payload.source}:`,
+      `  issues: ${payload.planned.issues}, comments: ${payload.planned.comments}, ` +
+        `dependencies: ${payload.planned.dependencies}, events: ${payload.planned.events ?? 0}`,
+      `  gaps: ${gaps.count}${gapBrief}`,
+      '  (nothing written to the kernel)',
+    ].join('\n');
+  }
+
+  const imported = payload.imported;
+  const importedEvents = imported.events || { inserted: 0, skipped: 0 };
+  return [
+    `Migrated beads → kernel from ${payload.source}:`,
+    `  issues: ${imported.issues.inserted} imported, ${imported.issues.skipped} skipped`,
+    `  comments: ${imported.comments.inserted} imported, ${imported.comments.skipped || 0} skipped`,
+    `  dependencies: ${imported.dependencies.inserted} imported, ` +
+      `${imported.dependencies.skipped} skipped`,
+    `  events: ${importedEvents.inserted} imported, ${importedEvents.skipped || 0} skipped`,
+    `  gaps: ${gaps.count}${gapBrief}`,
+  ].join('\n');
+}
+
+function finalize(options, payload, exitCode) {
+  const output = options.json ? JSON.stringify(payload, null, 2) : renderHuman(payload);
+  const result = { ...payload, output, json: Boolean(options.json) };
+  if (payload.success === false && Number.isInteger(exitCode)) {
+    result.exitCode = exitCode;
+  }
+  return result;
+}
+
+/**
+ * Beads → Forge Kernel transport. Reuses the faithful-import spine end-to-end:
+ * loadBeadsSnapshotFromDirectory → importBeadsSnapshot → broker.importIssues.
+ */
+async function runBeadsMigration(options, projectRoot, opts) {
+  const now = opts._now || new Date().toISOString();
+  const deps = { execFileSync: opts._execFileSync, fs: opts._fs };
+
+  const resolved = resolveBeadsSource(options, projectRoot, deps);
+  if (resolved.error) {
+    return finalize(options, { success: false, from: 'beads', error: resolved.error }, 1);
+  }
+
+  let snapshot;
+  try {
+    snapshot = loadBeadsSnapshotFromDirectory(resolved.dir);
+  } catch (err) {
+    cleanupResolved(resolved, deps);
+    return finalize(
+      options,
+      { success: false, from: 'beads', source: resolved.dir, error: `Failed to read beads data: ${err.message}` },
+      1,
+    );
+  }
+
+  if (snapshot.issues.length === 0 && snapshot.comments.length === 0 && snapshot.dependencies.length === 0) {
+    cleanupResolved(resolved, deps);
+    return finalize(
+      options,
+      { success: false, from: 'beads', source: resolved.dir, error: `No beads data found in ${resolved.dir}` },
+      1,
+    );
+  }
+
+  let kernel;
+  let report;
+  try {
+    ({ kernel, report } = importBeadsSnapshot(snapshot, { importedAt: now }));
+  } catch (err) {
+    cleanupResolved(resolved, deps);
+    return finalize(
+      options,
+      { success: false, from: 'beads', source: resolved.dir, error: `Failed to map beads data: ${err.message}` },
+      1,
+    );
+  }
+  const gaps = summarizeGaps(report?.gaps);
+  const planned = {
+    issues: kernel.issues.length,
+    comments: kernel.comments.length,
+    dependencies: kernel.dependencies.length,
+    events: Array.isArray(kernel.activityEvents) ? kernel.activityEvents.length : 0,
+  };
+
+  if (options.dryRun) {
+    cleanupResolved(resolved, deps);
+    return finalize(options, {
+      success: true,
+      from: 'beads',
+      dryRun: true,
+      source: resolved.dir,
+      sourceKind: resolved.kind,
+      planned,
+      gaps,
+    });
+  }
+
+  try {
+    let broker = opts._broker;
+    if (!broker) {
+      const built = await buildMigratedKernelIssueDeps({ projectRoot });
+      broker = built.kernelBroker;
+    }
+    const summary = await broker.importIssues(kernel, { now });
+    cleanupResolved(resolved, deps);
+    return finalize(options, {
+      success: true,
+      from: 'beads',
+      dryRun: false,
+      source: resolved.dir,
+      sourceKind: resolved.kind,
+      planned,
+      imported: {
+        issues: summary.issues,
+        comments: summary.comments,
+        dependencies: summary.dependencies,
+        events: summary.events,
+      },
+      gaps,
+    });
+  } catch (err) {
+    cleanupResolved(resolved, deps);
+    return finalize(
+      options,
+      { success: false, from: 'beads', source: resolved.dir, error: `Kernel import failed: ${err.message}` },
+      1,
+    );
+  }
+}
+
+module.exports = {
+  name: 'migrate',
+  description: 'Migrate a Beads issue store into the Forge Kernel with --from beads, '
+    + 'or preview the v2→v3 migration (preview only — --dry-run required; applying it is not yet available)',
+  usage: 'forge migrate --from beads [--dry-run] [--source <dir>] [--json]',
+  flags: {
+    '--from <source>': 'Migration source. Use "beads" to import a Beads issue store into the Kernel.',
+    '--source <dir>': 'Directory of exported beads *.jsonl files (defaults to auto-detecting .beads/). '
+      + 'A split .beads layout is tolerated: files missing from the given dir are also read from a '
+      + 'backup/ subdir and the parent dir, so events (under .beads/backup/) and interactions '
+      + '(at .beads/interactions.jsonl) are both picked up regardless of which you point at.',
+    '--dry-run': 'Read + map only; print what WOULD be imported without writing to the Kernel. '
+      + 'Without --from, this is the only supported mode (preview only).',
+    '--json': 'Emit a structured JSON result (counts + gaps + dryRun flag).',
+    '--fixture-corpus': 'v2→v3 preview only: also dry-run the source-tree v2 fixture corpus when available.',
+  },
+
+  async handler(args, flags, projectRoot, opts = {}) {
+    const options = parseMigrateOptions(args, flags);
+    if (options.errors.length > 0) {
+      return finalize(options, { success: false, error: options.errors.join('; ') }, 1);
+    }
+
+    // New beads → kernel transport, gated on `--from beads`. Any other (or absent)
+    // `--from` falls through to the pre-existing v2→v3 dry-run PoC so its contract
+    // (and tests) stay intact.
+    if (options.from) {
+      if (options.from === 'beads') {
+        return runBeadsMigration(options, projectRoot, opts);
+      }
+      return finalize(
+        options,
+        { success: false, error: `Unsupported migration source '${options.from}'. Supported sources: beads.` },
+        1,
+      );
+    }
+
+    // --- legacy v2 → v3 dry-run PoC (unchanged) ---
+    const dryRun = flags?.dryRun === true || hasArg(args, '--dry-run');
+    if (!dryRun) {
+      return {
+        success: false,
+        error: "forge migrate currently supports preview only. Run 'forge migrate --dry-run' "
+          + 'to see what would change; applying migrations is not yet available.',
+      };
+    }
+
+    const report = buildMigrationDryRunReport(projectRoot, {
+      fixtureCorpus: hasArg(args, '--fixture-corpus'),
+    });
+    const output = renderMigrationDryRunReport(report);
+
+    return {
+      success: report.ok,
+      output,
+      error: report.ok ? undefined : output,
+    };
+  },
+};

package/lib/commands/new.js

@@ -0,0 +1,12 @@
+'use strict';
+
+const { scaffoldAdapter } = require('../adapter-cli');
+
+module.exports = {
+  name: 'new',
+  description: 'Create Forge extension scaffolds',
+  usage: 'forge new adapter <name> --kind=review --template=greptile',
+  async handler(args, _flags, projectRoot) {
+    return scaffoldAdapter(args, projectRoot);
+  },
+};

package/lib/commands/options.js

@@ -0,0 +1,241 @@
+'use strict';
+
+const {
+  getDefaultRuntimeGraph,
+  getResolvedRuntimeGraph,
+  lintRuntimeGraphConfig,
+} = require('../core/runtime-graph');
+const { describeControl } = require('../control-plane');
+
+const COLLECTIONS = {
+  stages: { key: 'phases', label: 'Stages' },
+  gates: { key: 'gates', label: 'Gates' },
+  adapters: { key: 'adapters', label: 'Adapters' },
+  roles: { key: 'roles', label: 'Roles' },
+};
+
+function hasJson(args) {
+  return args.includes('--json');
+}
+
+function withoutFlags(args) {
+  return args.filter(arg => arg !== '--json');
+}
+
+function jsonOutput(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function summarizeRole(item) {
+  const parts = [`skill=${item.skill}`];
+  if (item.ideology) parts.push(`ideology=${item.ideology}`);
+  return `${item.id} (${parts.join(', ')})`;
+}
+
+function summarizeItem(item) {
+  if (item.role) return summarizeRole(item);
+  const state = item.enabled === false ? 'disabled' : 'enabled';
+  const locked = item.locked ? ', locked' : '';
+  const label = item.label ?? item.kind ?? item.command ?? 'graph primitive';
+  const badge = item.badge ? `  [${item.badge}]` : '';
+  return `${item.id} (${state}${locked}) - ${label}${badge}`;
+}
+
+function renderCollection(label, items) {
+  return [
+    label,
+    ...items.map(item => `- ${summarizeItem(item)}`),
+  ].join('\n') + '\n';
+}
+
+function allPrimitiveEntries(graph) {
+  return [
+    ...graph.phases.map(item => ['stage', item]),
+    ...graph.gates.map(item => ['gate', item]),
+    ...graph.adapters.map(item => ['adapter', item]),
+    ...graph.rails.map(item => ['rail', item]),
+    ...graph.actions.map(item => ['action', item]),
+    ...graph.artifacts.map(item => ['artifact', item]),
+    ...graph.evaluatorRegions.map(item => ['evaluatorRegion', item]),
+    ...graph.evidence.map(item => ['evidence', item]),
+    ...(graph.planning?.subSkills ?? []).map(item => ['planningSubSkill', item]),
+  ];
+}
+
+function findPrimitive(graph, id) {
+  return allPrimitiveEntries(graph).find(([type, item]) => item.id === id || item.key === id || `${type}.${item.id}` === id);
+}
+
+function renderWhy(type, item) {
+  const lines = [
+    `${item.id}`,
+    `type: ${type}`,
+    `state: ${item.enabled === false ? 'disabled' : 'enabled'}`,
+    `source: ${item.configSource ?? 'package-defaults'}`,
+  ];
+  if (item.locked) lines.push('locked: true');
+  if (item.requires) lines.push(`requires: ${item.requires.join(', ')}`);
+  if (item.reads?.length) lines.push(`reads: ${item.reads.join(', ')}`);
+  if (item.writes?.length) lines.push(`writes: ${item.writes.join(', ')}`);
+  if (item.description) lines.push(`description: ${item.description}`);
+  return `${lines.join('\n')}\n`;
+}
+
+function primitiveMap(graph, key) {
+  return new Map((graph[key] ?? []).map(item => [item.id, item]));
+}
+
+function collectDiff(defaultGraph, resolvedGraph) {
+  const changes = [];
+  for (const key of ['phases', 'gates', 'adapters', 'rails']) {
+    const defaults = primitiveMap(defaultGraph, key);
+    const resolved = primitiveMap(resolvedGraph, key);
+    for (const [id, afterItem] of resolved) {
+      const beforeItem = defaults.get(id);
+      if (!beforeItem) continue;
+      for (const field of ['enabled', 'disabled', 'configSource', 'config']) {
+        const before = beforeItem[field];
+        const after = afterItem[field];
+        if (JSON.stringify(before) !== JSON.stringify(after)) {
+          changes.push({ collection: key, id, field, before, after });
+        }
+      }
+    }
+  }
+  if (JSON.stringify(defaultGraph.protectedPaths) !== JSON.stringify(resolvedGraph.protectedPaths)) {
+    changes.push({
+      collection: 'protectedPaths',
+      id: 'protectedPaths',
+      field: 'patterns',
+      before: defaultGraph.protectedPaths,
+      after: resolvedGraph.protectedPaths,
+    });
+  }
+  if (JSON.stringify(defaultGraph.planning?.template) !== JSON.stringify(resolvedGraph.planning?.template)) {
+    changes.push({
+      collection: 'planning',
+      id: 'planning.template',
+      field: 'config',
+      before: defaultGraph.planning?.template,
+      after: resolvedGraph.planning?.template,
+    });
+  }
+  return changes;
+}
+
+function renderDiff(changes) {
+  if (changes.length === 0) {
+    return 'No graph config changes.\n';
+  }
+  return changes
+    .map(change => `${change.id}.${change.field}: ${JSON.stringify(change.before)} -> ${JSON.stringify(change.after)}`)
+    .join('\n') + '\n';
+}
+
+function renderLint(result) {
+  if (result.ok) {
+    return 'Graph config lint passed.\n';
+  }
+  return [
+    'Graph config lint failed.',
+    ...result.errors.map(error => `- ${error.code}: ${error.message}`),
+  ].join('\n') + '\n';
+}
+
+function usage() {
+  return [
+    'Usage: forge options <stages|gates|adapters|roles|diff|why <id>|lint> [--json]',
+    '',
+    'Inspect resolved runtime graph primitives and project config effects.',
+  ].join('\n');
+}
+
+function lintCommand(projectRoot, json) {
+  const result = lintRuntimeGraphConfig({ projectRoot });
+  const output = json ? jsonOutput(result) : renderLint(result);
+  return {
+    success: result.ok,
+    output,
+    error: result.ok ? undefined : output,
+  };
+}
+
+function resolveGraphResult(projectRoot, json) {
+  try {
+    return { success: true, graph: getResolvedRuntimeGraph({ projectRoot }) };
+  } catch (err) {
+    const output = json
+      ? jsonOutput({ ok: false, errors: err.message.split('\n').map(message => ({ message })) })
+      : `${err.message}\n`;
+    return { success: false, output, error: output };
+  }
+}
+
+// Gates carry enforcement-locus badges (724356ea): decorate each with the
+// honest surface/state/locus/badge from the guarantee matrix so the read view
+// never implies enforcement a surface lacks (human gates read PERMISSION,
+// ordinary gates read ENFORCED).
+function decorateWithLocus(subcommand, items) {
+  if (subcommand !== 'gates') return items;
+  return items.map(item => ({ ...item, ...describeControl(item) }));
+}
+
+function collectionCommand(graph, subcommand, json) {
+  const { key, label } = COLLECTIONS[subcommand];
+  const items = decorateWithLocus(subcommand, graph[key]);
+  return {
+    success: true,
+    output: json ? jsonOutput({ kind: subcommand, items }) : renderCollection(label, items),
+  };
+}
+
+function whyCommand(graph, id, json) {
+  const match = id ? findPrimitive(graph, id) : null;
+  if (!match) {
+    const message = `Unknown graph primitive: ${id ?? '<missing>'}`;
+    const output = json
+      ? jsonOutput({ ok: false, errors: [{ code: 'UNKNOWN_GRAPH_PRIMITIVE', message }] })
+      : message;
+    return { success: false, output, error: output };
+  }
+  const [type, item] = match;
+  return {
+    success: true,
+    output: json ? jsonOutput({ type, item }) : renderWhy(type, item),
+  };
+}
+
+function diffCommand(graph, json) {
+  const changes = collectDiff(getDefaultRuntimeGraph(), graph);
+  return {
+    success: true,
+    output: json ? jsonOutput({ changes }) : renderDiff(changes),
+  };
+}
+
+async function handler(args, _flags, projectRoot) {
+  const json = hasJson(args);
+  const tokens = withoutFlags(args);
+  const subcommand = tokens[0];
+
+  if (!subcommand) return { success: false, error: usage() };
+  if (subcommand === 'lint') return lintCommand(projectRoot, json);
+
+  const graphResult = resolveGraphResult(projectRoot, json);
+  if (!graphResult.success) return graphResult;
+  if (COLLECTIONS[subcommand]) return collectionCommand(graphResult.graph, subcommand, json);
+  if (subcommand === 'why') return whyCommand(graphResult.graph, tokens[1], json);
+  if (subcommand === 'diff') return diffCommand(graphResult.graph, json);
+  return { success: false, error: usage() };
+}
+
+module.exports = {
+  name: 'options',
+  description: 'Inspect runtime graph primitives and config',
+  usage: usage(),
+  flags: {
+    '--json': 'Emit machine-readable JSON output',
+  },
+  handler,
+  collectDiff,
+};

package/lib/commands/orient.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const {
+  buildOrientation,
+  runOrientationCommand,
+} = require('../orientation');
+
+module.exports = {
+  name: 'orient',
+  description: 'Emit bounded project orientation from deterministic source files',
+  usage: 'Usage: forge orient [--budget N] [--json]',
+  handler: (args, _flags, projectRoot) => runOrientationCommand(buildOrientation, args, projectRoot),
+};

package/lib/commands/orphans.js

@@ -0,0 +1,5 @@
+'use strict';
+
+const { createIssueSubcommand } = require('./_issue');
+
+module.exports = createIssueSubcommand('orphans');

package/lib/commands/patch.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const {
+  recordPatchIntentFromDiff,
+  resolvePatchIntentRecords,
+} = require('../patch-intent');
+
+const usage = [
+  'forge patch record --from-diff',
+  'forge patch status',
+].join('\n');
+
+function formatRecordSummary(result) {
+  const count = result.records.length;
+  const label = count === 1 ? 'patch intent' : 'patch intents';
+  return [
+    `Recorded ${count} ${label} in ${result.path}.`,
+    ...result.records.map(record => `- ${record.id} -> ${record.anchorId} (${record.path})`),
+  ].join('\n');
+}
+
+async function handler(args, _flags, projectRoot) {
+  const [subcommand, ...rest] = args;
+
+  if (subcommand === 'record') {
+    if (!rest.includes('--from-diff')) {
+      return {
+        success: false,
+        error: `Missing --from-diff.\n\nUsage:\n${usage}`,
+      };
+    }
+    const result = recordPatchIntentFromDiff(projectRoot);
+    return {
+      success: true,
+      output: formatRecordSummary(result),
+    };
+  }
+
+  if (subcommand === 'status') {
+    const result = resolvePatchIntentRecords(projectRoot);
+    const lines = [
+      `Patch intent file: ${result.path}`,
+      `Records: ${result.records.length}`,
+      `Orphans: ${result.orphans.length}`,
+    ];
+    for (const record of result.records) {
+      lines.push(`- ${record.id}: ${record.status} ${record.anchorId} -> ${record.currentPath || record.path}`);
+    }
+    return {
+      success: true,
+      output: lines.join('\n'),
+    };
+  }
+
+  return {
+    success: false,
+    error: `Unknown patch subcommand: ${subcommand || '(none)'}\n\nUsage:\n${usage}`,
+  };
+}
+
+module.exports = {
+  name: 'patch',
+  description: 'Record and inspect patch intent anchored in patch.md',
+  usage,
+  handler,
+};
+