mandrel 2.14.0 → 2.16.0

package/.agents/scripts/check-workflow-citations.js

@@ -0,0 +1,332 @@
+/**
+ * CLI: ratchet-down gate on provenance citations in workflow prose.
+ *
+ * Workflow documents ride resident in an executing agent's context. A
+ * `(Story #1234)` aside costs the same tokens as instruction and teaches
+ * the model Mandrel's own history instead of the task in front of it. The
+ * citations that survive are the ones a reader must follow to act; the
+ * rest belong in the commit trail and `docs/decisions.md`.
+ *
+ * Nothing stops the tax re-accumulating one well-meaning aside at a time,
+ * so this gate holds the line: count every issue-shaped reference across
+ * `.agents/workflows/**\/*.md` and fail when the total rises above the
+ * committed baseline at `baselines/workflow-citations.json`.
+ *
+ * The counted token is the bare `#NNNN` form rather than the
+ * `(Story|Epic|issue|refs) #NNNN` phrasing, because the same citation is
+ * written both ways — `(Story #4593)` and a bare `(#4593)` — and a gate
+ * that only saw the prefixed form would wave the other one through.
+ *
+ * Ratchet semantics mirror `check-arch-cycles.js`:
+ *   - Total above the baseline → exit 1, with the files that grew.
+ *   - Total below the baseline → printed as shrinkage, exit 0. Refresh the
+ *     baseline with `--update` to lock the reduction in.
+ *   - Equal → exit 0.
+ *
+ * Flags:
+ *   --baseline <path>  override the baseline path (default
+ *                      `baselines/workflow-citations.json`, resolved from cwd)
+ *   --root <path>      scan a different workflow root (default
+ *                      `.agents/workflows`)
+ *   --update           rewrite the baseline from the live count
+ *   --json             write the structured envelope to stdout
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { runAsCli } from './lib/cli-utils.js';
+
+/** Default workflow root, relative to the repository root. */
+const DEFAULT_ROOT = path.join('.agents', 'workflows');
+
+/** Default baseline path, relative to the repository root. */
+const DEFAULT_BASELINE = path.join('baselines', 'workflow-citations.json');
+
+/**
+ * Issue-shaped reference: a `#` followed by 3–5 digits. Narrow enough to
+ * skip markdown headings and anchor links, wide enough to catch both the
+ * `(Story #1234)` and bare `(#1234)` spellings of one citation.
+ */
+const CITATION_RE = /#\d{3,5}\b/g;
+
+/**
+ * Parse argv. Exported so unit tests can pin the parser.
+ *
+ * @param {string[]} argv
+ * @returns {{ baselinePath: string | null, rootPath: string | null, update: boolean, json: boolean }}
+ */
+export function parseArgv(argv = []) {
+  const out = {
+    baselinePath: null,
+    rootPath: null,
+    update: false,
+    json: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const flag = argv[i];
+    const next = argv[i + 1];
+    const takesValue = next && !next.startsWith('--');
+    if (flag === '--baseline' && takesValue) {
+      out.baselinePath = next;
+      i += 1;
+    } else if (flag === '--root' && takesValue) {
+      out.rootPath = next;
+      i += 1;
+    } else if (flag === '--update') {
+      out.update = true;
+    } else if (flag === '--json') {
+      out.json = true;
+    }
+  }
+  return out;
+}
+
+/**
+ * Recursively collect `.md` files under `rootDir`. Returns absolute paths,
+ * sorted for determinism.
+ *
+ * @param {string} rootDir
+ * @returns {string[]}
+ */
+export function collectMarkdownFiles(rootDir) {
+  const out = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile() && entry.name.endsWith('.md')) out.push(full);
+    }
+  };
+  walk(rootDir);
+  return out.sort();
+}
+
+/**
+ * Pure helper: count citations in source text.
+ *
+ * @param {string} source
+ * @returns {number}
+ */
+export function countCitations(source) {
+  return (String(source ?? '').match(CITATION_RE) ?? []).length;
+}
+
+/**
+ * Count citations across a file set, relativizing paths against `cwd` so
+ * the report serializes identically on every platform. Files with zero
+ * citations are omitted — the baseline records where the tax lives.
+ *
+ * @param {string[]} files absolute paths
+ * @param {string} cwd
+ * @param {{ readFile?: (p: string) => string }} [opts]
+ * @returns {{ total: number, files: Array<{ path: string, count: number }> }}
+ */
+export function tallyCitations(files, cwd, { readFile } = {}) {
+  const read = readFile ?? ((p) => fs.readFileSync(p, 'utf-8'));
+  const rows = [];
+  let total = 0;
+  for (const file of files) {
+    let count;
+    try {
+      count = countCitations(read(file));
+    } catch {
+      continue;
+    }
+    if (count === 0) continue;
+    total += count;
+    rows.push({
+      path: path.relative(cwd, file).split(path.sep).join('/'),
+      count,
+    });
+  }
+  return { total, files: rows.sort((a, b) => a.path.localeCompare(b.path)) };
+}
+
+/**
+ * Pure helper: read the baseline envelope. Returns `null` when the file is
+ * missing or unparseable — the baseline is not distributed to consumers, so
+ * its absence degrades to "no ceiling" rather than a false failure.
+ *
+ * @param {string} baselinePath
+ * @returns {{ total?: number, files?: Array<{ path: string, count: number }> } | null}
+ */
+export function loadBaseline(baselinePath) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(baselinePath, 'utf-8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pure helper: diff the live tally against the baseline. `grew` names the
+ * files whose per-file count rose, so a failure points at the edit rather
+ * than only at the total.
+ *
+ * @param {{ total?: number, files?: Array<{ path: string, count: number }> } | null} baseline
+ * @param {{ total: number, files: Array<{ path: string, count: number }> }} tally
+ * @returns {{ baselineTotal: number | null, delta: number | null, grew: Array<{ path: string, from: number, to: number }> }}
+ */
+export function diffTally(baseline, tally) {
+  const baselineTotal =
+    typeof baseline?.total === 'number' ? baseline.total : null;
+  const prior = new Map(
+    (baseline?.files ?? []).map((row) => [row.path, row.count]),
+  );
+  const grew = tally.files
+    .map((row) => ({
+      path: row.path,
+      from: prior.get(row.path) ?? 0,
+      to: row.count,
+    }))
+    .filter((row) => row.to > row.from);
+  return {
+    baselineTotal,
+    delta: baselineTotal === null ? null : tally.total - baselineTotal,
+    grew,
+  };
+}
+
+/**
+ * Pure helper: render the human-readable diff, mirroring the `+` / `-`
+ * vocabulary of the sibling ratchets.
+ *
+ * @param {{ baselineTotal: number | null, delta: number | null, grew: Array<{ path: string, from: number, to: number }> }} diff
+ * @param {{ total: number }} tally
+ * @returns {string}
+ */
+export function renderDiff(diff, tally) {
+  const lines = [];
+  for (const row of diff.grew) {
+    lines.push(`+ ${row.path}: ${row.from} -> ${row.to}`);
+  }
+  if (diff.delta !== null && diff.delta < 0) {
+    lines.push(
+      `[workflow-citations] ⚠ ${-diff.delta} citation(s) below baseline — refresh with --update to lock the reduction in`,
+    );
+  }
+  const tag = diff.delta !== null && diff.delta > 0 ? '(gate fail)' : '(ok)';
+  lines.push(
+    `[workflow-citations] total=${tally.total} baseline=${diff.baselineTotal ?? 'none'} ${tag}`,
+  );
+  return lines.join('\n');
+}
+
+/**
+ * Top-level CLI entry. Exported so tests can drive the pipeline against a
+ * tmpdir fixture corpus.
+ *
+ * @param {{
+ *   argv?: string[],
+ *   cwd?: string,
+ *   stdout?: { write: (s: string) => void },
+ *   stderr?: { write: (s: string) => void },
+ * }} [opts]
+ * @returns {Promise<number>} 0 = at or below baseline; 1 = regression
+ */
+export async function runCli({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  stdout = process.stdout,
+  stderr = process.stderr,
+} = {}) {
+  const { baselinePath, rootPath, update, json } = parseArgv(argv);
+  const root = path.resolve(cwd, rootPath ?? DEFAULT_ROOT);
+  const resolvedBaselinePath = path.resolve(
+    cwd,
+    baselinePath ?? DEFAULT_BASELINE,
+  );
+  if (!fs.existsSync(root)) {
+    throw new Error(`[workflow-citations] workflow root not found: ${root}`);
+  }
+
+  const tally = tallyCitations(collectMarkdownFiles(root), cwd);
+
+  if (update) {
+    const envelope = {
+      $schema: 'https://mandrel.dev/baselines/workflow-citations.schema.json',
+      generatedAt: new Date().toISOString(),
+      total: tally.total,
+      files: tally.files,
+    };
+    fs.mkdirSync(path.dirname(resolvedBaselinePath), { recursive: true });
+    fs.writeFileSync(
+      resolvedBaselinePath,
+      `${JSON.stringify(envelope, null, 2)}\n`,
+    );
+    stdout.write(
+      `[workflow-citations] baseline written: ${resolvedBaselinePath} (total=${tally.total})\n`,
+    );
+    return 0;
+  }
+
+  const baseline = loadBaseline(resolvedBaselinePath);
+  const diff = diffTally(baseline, tally);
+  const exitCode = diff.delta !== null && diff.delta > 0 ? 1 : 0;
+
+  if (json) {
+    stdout.write(
+      `${JSON.stringify(
+        {
+          kind: 'workflow-citations-report',
+          root,
+          baselinePath: resolvedBaselinePath,
+          total: tally.total,
+          baselineTotal: diff.baselineTotal,
+          delta: diff.delta,
+          files: tally.files,
+          grew: diff.grew,
+          exitCode,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    return exitCode;
+  }
+
+  if (!baseline) {
+    stderr.write(
+      `[workflow-citations] ⚠ baseline not found at ${resolvedBaselinePath} — no ceiling enforced\n`,
+    );
+  }
+  stdout.write(`\n--- workflow-citations preview ---\n`);
+  stdout.write(`${renderDiff(diff, tally)}\n`);
+  return exitCode;
+}
+
+async function main() {
+  return runCli();
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'workflow-citations',
+  propagateExitCode: true,
+  errorPrefix: '[workflow-citations] ❌ Fatal error',
+  usage: {
+    invocation:
+      'node .agents/scripts/check-workflow-citations.js [--baseline <path>] [--root <dir>] [--update] [--json]',
+    summary:
+      'Ratchet on provenance citations in workflow prose: count issue-shaped references across .agents/workflows/** and fail when the total rises above the recorded baseline.',
+    flags: [
+      [
+        '--baseline <path>',
+        'Baseline file (default: baselines/workflow-citations.json).',
+      ],
+      ['--root <dir>', 'Workflow root to scan (default: .agents/workflows).'],
+      ['--update', 'Rewrite the baseline from the live count.'],
+      ['--json', 'Emit the comparison envelope as JSON.'],
+    ],
+    notes: [
+      'Exit codes:\n  0  at or below the baseline\n  1  the citation total regressed above the baseline',
+    ],
+  },
+});

package/.agents/scripts/deliver-light.js

@@ -79,18 +79,29 @@ import { createProvider } from './lib/provider-factory.js';
 const HELP = `\
 Usage:
   deliver-light.js --prompt <text> [--creates csv] [--refactors csv]
-                   [--acceptance n] [--route lite|full] [--reason <text>]
+                   [--acceptance n] [--kinds csv] [--magnitude m]
+                   [--uncertainty u] [--route lite|full] [--reason <text>]
                    [--amends '#id'] [--yes]
   deliver-light.js --backstop --story <id>
 
 The thin /deliver-light entry point: suitability gate → inline receipt Story →
 the same single-story-init.js / single-story-close.js engine /deliver uses.
 
+The gate judges EFFORT and RISK, not artifact counts: N instances of one
+mechanical edit is one kind at N sites. It rejects only clearly-epic work; the
+--backstop pass enforces size against the actual diff.
+
 Gate options:
   --prompt <text>    Operator prompt describing the change. Required for the gate.
   --creates <csv>    Predicted NEW file paths (comma-separated).
   --refactors <csv>  Predicted edited/existing file paths (comma-separated).
-  --acceptance <n>   Predicted acceptance-criteria count (default 1).
+  --acceptance <n>   Predicted acceptance-criteria count (default 1). Not capped.
+  --kinds <csv>      Distinct KINDS of change (default: one per assumption, so
+                     N same-shaped edits count once).
+  --magnitude <m>    Coarse effort bucket: trivial | moderate | substantial
+                     (default moderate; substantial routes to /plan).
+  --uncertainty <u>  determined (the request fixes the shape) | needs-design
+                     (default determined; needs-design routes to /plan).
   --route <r>        Ledgered model verdict route: lite | full.
   --reason <text>    Recorded reason for a lite verdict (required for lite).
   --amends <#id>     Mark this as an amendment of an existing issue.
@@ -166,17 +177,25 @@ export function synthesizeAcceptance(count) {
  *   creates?: string[],
  *   refactors?: string[],
  *   acceptance?: number,
+ *   kinds?: string[],
+ *   magnitude?: string,
+ *   uncertainty?: string,
  *   route?: string,
  *   reason?: string,
  *   yes?: boolean,
  *   injectedRules?: object,
- * }} args
+ * }} args `kinds` / `magnitude` / `uncertainty` are the declared effort-and-risk
+ *   axes the gate judges (Story #4764); omitting them declares no signal, not a
+ *   small one — an unrecognized bucket fails closed.
  * @returns {{ action: string, suitability: object, outcome: object }}
  */
 export function runLightGate({
   creates = [],
   refactors = [],
   acceptance,
+  kinds,
+  magnitude,
+  uncertainty,
   route,
   reason,
   yes = false,
@@ -186,6 +205,9 @@ export function runLightGate({
   const suitability = deriveLightSuitability({
     predictedChanges,
     predictedAcceptance: synthesizeAcceptance(acceptance),
+    predictedKinds: kinds,
+    predictedMagnitude: magnitude,
+    predictedUncertainty: uncertainty,
     verdict: { route, reason },
     injectedRules,
   });
@@ -355,6 +377,9 @@ export async function runGateMode(values, deps = {}) {
     acceptance: values.acceptance
       ? Number.parseInt(String(values.acceptance), 10)
       : 1,
+    kinds: parseCsvPaths(values.kinds),
+    magnitude: values.magnitude,
+    uncertainty: values.uncertainty,
     route: values.route,
     reason: values.reason,
     yes: values.yes === true,
@@ -417,6 +442,9 @@ async function main() {
       creates: { type: 'string' },
       refactors: { type: 'string' },
       acceptance: { type: 'string' },
+      kinds: { type: 'string' },
+      magnitude: { type: 'string' },
+      uncertainty: { type: 'string' },
       route: { type: 'string' },
       reason: { type: 'string' },
       amends: { type: 'string' },
@@ -443,4 +471,5 @@ async function main() {
 runAsCli(import.meta.url, main, {
   source: 'deliver-light',
   propagateExitCode: true,
+  usage: HELP,
 });

package/.agents/scripts/deliver-recover.js

@@ -136,4 +136,7 @@ export async function runDeliverRecover({
   return { success: true, result: recovery };
 }
 
-runAsCli(import.meta.url, runDeliverRecover, { source: 'deliver-recover' });
+runAsCli(import.meta.url, runDeliverRecover, {
+  source: 'deliver-recover',
+  usage: HELP,
+});

package/.agents/scripts/diagnose-friction.js

@@ -248,4 +248,20 @@ export async function main(args = process.argv.slice(2)) {
 
 import { runAsCli } from './lib/cli-utils.js';
 
-runAsCli(import.meta.url, main, { source: 'DiagnoseFriction' });
+runAsCli(import.meta.url, main, {
+  source: 'DiagnoseFriction',
+  usage: {
+    invocation:
+      'node .agents/scripts/diagnose-friction.js [--story <id>] [--epic <id>] --cmd <command with args...>',
+    summary:
+      'Run a command through the diagnostic interceptor: stream its output, then append a local friction signal describing the failure. Never posts to the ticket.',
+    flags: [
+      ['--story <id>', 'Story the friction belongs to.'],
+      ['--epic <id>', 'Epic the friction belongs to.'],
+      [
+        '--cmd <command...>',
+        'The command to execute; everything after it is the argv (required).',
+      ],
+    ],
+  },
+});

package/.agents/scripts/diagnose.js

@@ -47,6 +47,21 @@ import { runAsCli } from './lib/cli-utils.js';
 
 const DEFAULT_SCOPE = 'diagnose';
 
+/**
+ * The `--help` block. Single-homed here so the CLI gate in `runAsCli` and the
+ * `validateDiagnoseArgs` HELP-sentinel branch print the same bytes.
+ */
+const HELP = [
+  'Usage: diagnose [--scope <scope>] [--fail-on-blocker] [--json]',
+  '',
+  'Options:',
+  '  --scope <s>         Filter checks by scope (default: diagnose).',
+  '                      Use `all` to run every registered check.',
+  '  --fail-on-blocker   Exit 2 when at least one finding is a blocker.',
+  '  --json              Emit findings as a single line of JSON.',
+  '',
+].join('\n');
+
 /**
  * Parse the CLI argv slice (i.e. argv without the leading node/script
  * elements). Exported for direct unit testing — keeps the parse pure so
@@ -203,19 +218,7 @@ export async function runDiagnose({
  */
 export function validateDiagnoseArgs(err) {
   if (err && err.message === 'HELP') {
-    return {
-      kind: 'help',
-      text: [
-        'Usage: diagnose [--scope <scope>] [--fail-on-blocker] [--json]',
-        '',
-        'Options:',
-        '  --scope <s>         Filter checks by scope (default: diagnose).',
-        '                      Use `all` to run every registered check.',
-        '  --fail-on-blocker   Exit 2 when at least one finding is a blocker.',
-        '  --json              Emit findings as a single line of JSON.',
-        '',
-      ].join('\n'),
-    };
+    return { kind: 'help', text: HELP };
   }
   const message = err?.message ? err.message : String(err);
   return { kind: 'error', text: `[diagnose] ${message}\n`, exitCode: 1 };
@@ -237,4 +240,7 @@ async function main() {
   }
 }
 
-runAsCli(import.meta.url, main, { source: 'diagnose' });
+runAsCli(import.meta.url, main, {
+  source: 'diagnose',
+  usage: HELP,
+});

package/.agents/scripts/drain-pending-cleanup.js

@@ -144,4 +144,23 @@ async function main() {
   );
 }
 
-runAsCli(import.meta.url, main, { source: 'drain-pending-cleanup' });
+runAsCli(import.meta.url, main, {
+  source: 'drain-pending-cleanup',
+  usage: {
+    invocation:
+      'node .agents/scripts/drain-pending-cleanup.js [--dry-run] [--no-escalate] [--worktree-root <path>]',
+    summary:
+      'Drain the pending-worktree-cleanup manifest, removing trees whose holders have exited.',
+    flags: [
+      ['--dry-run', 'Report each entry and its holders; remove nothing.'],
+      [
+        '--no-escalate',
+        'Do not escalate to a forced removal for stuck entries.',
+      ],
+      [
+        '--worktree-root <path>',
+        'Worktree root (default: delivery.worktreeIsolation.root).',
+      ],
+    ],
+  },
+});

package/.agents/scripts/evidence-gate.js

@@ -238,4 +238,23 @@ async function main() {
   await runEvidenceGate({ ...args, runnerArgs });
 }
 
-runAsCli(import.meta.url, main, { source: 'evidence-gate' });
+runAsCli(import.meta.url, main, {
+  source: 'evidence-gate',
+  usage: {
+    invocation:
+      'node .agents/scripts/evidence-gate.js --scope-id <id> --gate <name> [--standalone] [--no-evidence] [--cwd <path>] [--worktree <path>]',
+    summary:
+      'Run one named gate, reusing a prior evidence stamp for the same HEAD instead of re-running it.',
+    flags: [
+      ['--scope-id <id>', 'Story id the evidence is scoped to (required).'],
+      ['--gate <name>', 'Gate to run (e.g. lint, typecheck) (required).'],
+      ['--standalone', 'Run outside a close pipeline and stamp the evidence.'],
+      [
+        '--no-evidence',
+        'Ignore and do not write evidence — always run the gate.',
+      ],
+      ['--cwd <path>', 'Repository root (default: project root).'],
+      ['--worktree <path>', 'Worktree the gate runs in.'],
+    ],
+  },
+});

package/.agents/scripts/generate-config-docs.js

@@ -608,4 +608,17 @@ export {
   spliceRegion,
 };
 
-runAsCli(import.meta.url, main, { source: 'generate-config-docs' });
+runAsCli(import.meta.url, main, {
+  source: 'generate-config-docs',
+  usage: {
+    invocation: 'node .agents/scripts/generate-config-docs.js [--check]',
+    summary:
+      'Regenerate the configuration reference from the .agentrc schema. Writes only when the generated content differs.',
+    flags: [
+      [
+        '--check',
+        'Verify the doc is current and fail if stale; write nothing.',
+      ],
+    ],
+  },
+});

package/.agents/scripts/generate-lifecycle-docs.js

@@ -221,4 +221,17 @@ export {
   spliceRegion,
 };
 
-runAsCli(import.meta.url, main, { source: 'generate-lifecycle-docs' });
+runAsCli(import.meta.url, main, {
+  source: 'generate-lifecycle-docs',
+  usage: {
+    invocation: 'node .agents/scripts/generate-lifecycle-docs.js [--check]',
+    summary:
+      'Regenerate the lifecycle-event table in docs/LIFECYCLE.md from the event schemas. Writes only when the generated content differs.',
+    flags: [
+      [
+        '--check',
+        'Verify the doc is current and fail if stale; write nothing.',
+      ],
+    ],
+  },
+});

package/.agents/scripts/generate-workflows-doc.js

@@ -198,4 +198,17 @@ async function main(argv = process.argv.slice(2)) {
 
 export { DOC_PATH, WORKFLOWS_DIR };
 
-runAsCli(import.meta.url, main, { source: 'generate-workflows-doc' });
+runAsCli(import.meta.url, main, {
+  source: 'generate-workflows-doc',
+  usage: {
+    invocation: 'node .agents/scripts/generate-workflows-doc.js [--check]',
+    summary:
+      'Regenerate the workflow catalog from .agents/workflows/. Writes only when the generated content differs.',
+    flags: [
+      [
+        '--check',
+        'Verify the doc is current and fail if stale; write nothing.',
+      ],
+    ],
+  },
+});

package/.agents/scripts/git-cleanup.js

@@ -129,4 +129,35 @@ async function main() {
   process.exit(exitCode);
 }
 
-runAsCli(import.meta.url, main, { source: 'git-cleanup' });
+runAsCli(import.meta.url, main, {
+  source: 'git-cleanup',
+  usage: {
+    invocation:
+      'node .agents/scripts/git-cleanup.js [--execute] [--yes] [--json] [phase flags] [filters]',
+    summary:
+      'Tidy the local checkout in four phases — fast-forward the base branch, prune stale remote refs, reap merged branches, triage stashes. Dry-run unless --execute.',
+    flags: [
+      ['--execute', 'Perform the mutations (default is a dry run).'],
+      ['--dry-run', 'Force a dry run even alongside --execute.'],
+      ['--yes', 'Skip the interactive confirmation prompts.'],
+      ['--json', 'Emit the plan/result envelope as JSON.'],
+      ['--remote', 'Also delete the matching remote branches.'],
+      ['--fast-forward-main', 'Run only the fast-forward-base phase.'],
+      ['--prune-remotes', 'Run only the prune-remotes phase.'],
+      ['--branches', 'Run only the merged-branch reap phase.'],
+      ['--stashes', 'Run only the stash-triage phase.'],
+      [
+        '--include <glob>',
+        'Only consider branches matching the glob (repeatable).',
+      ],
+      [
+        '--exclude <glob>',
+        'Never consider branches matching the glob (repeatable).',
+      ],
+      ['--drop-stashes <ref>', 'Stash ref approved for dropping (repeatable).'],
+      ['--base <branch>', 'Base branch (default: project.baseBranch).'],
+      ['--cwd <path>', 'Repository root (default: process cwd).'],
+    ],
+    notes: ['With no phase flag, every phase runs in order.'],
+  },
+});