mandrel 2.13.0 → 2.15.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

@@ -23,12 +23,25 @@
  *   - **gate** (default) — judge a prompt's predicted footprint. On
  *     `proceed-light` it authors the receipt Story (via the plan-persist
  *     `createStoryIssues` surface) and prints the init/close hand-off. On
- *     over-scope it prints `ask-operator` (attended) or `escalate-plan`
- *     (`--yes`), never landing silently.
+ *     over-scope it prints `ask-operator` (attended) or emits an `escalated`
+ *     terminal envelope (`--yes`), never landing silently.
  *   - **backstop** (`--backstop --story <id>`) — re-check the ACTUAL diff of
  *     the Story branch after implementation; exit non-zero when it exceeds the
  *     light ceilings, so an over-scope diff is blocked rather than landed.
  *
+ * ## Escalation is terminal, not advisory (Story #4746)
+ *
+ * Over-scope under `--yes` emits a schema-validated `story-deliver-terminal`
+ * envelope with status `escalated` and **ends the session**. Before that it was
+ * an ordinary gate envelope plus exit 2 — a warning a caller could walk past,
+ * and one mandrel-bench 2.13.0 light-arm run did exactly that: it read the
+ * escalation, invoked `/plan` in the same session, and delivered. In-session
+ * planning under-decomposed (ONE Story against the scenario's 3-5 contract,
+ * where a fresh `/plan` session on the identical seed authored four), so
+ * escalation silently produced the outcome the guard exists to prevent.
+ * {@link module:lib/orchestration/story-deliver-terminal.buildEscalationTerminal}
+ * carries the guarantees the schema then enforces.
+ *
  * Usage:
  *   node .agents/scripts/deliver-light.js --prompt "<text>" \
  *     --creates path,path --acceptance 1 --route lite --reason "<why>"
@@ -36,7 +49,8 @@
  *   node .agents/scripts/deliver-light.js --backstop --story 4741
  *
  * Exit codes: 0 ok (proceed / clean backstop), 1 usage error, 2 the gate did
- * not proceed light (ask-operator / escalate-plan), 3 the diff backstop blocked.
+ * not proceed light (ask-operator, or an `escalated` terminal), 3 the diff
+ * backstop blocked.
  */
 
 import { parseArgs } from 'node:util';
@@ -55,6 +69,11 @@ import {
   assemblePlanStories,
   createStoryIssues,
 } from './lib/orchestration/plan-persist/story-ops.js';
+import {
+  buildEscalationTerminal,
+  emitTerminalEnvelope,
+  exitCodeForTerminal,
+} from './lib/orchestration/story-deliver-terminal.js';
 import { createProvider } from './lib/provider-factory.js';
 
 const HELP = `\
@@ -75,7 +94,8 @@ Gate options:
   --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.
-  --yes              Unattended: over-scope fails closed to /plan (no prompt).
+  --yes              Unattended: over-scope emits an escalated terminal
+                     envelope and ENDS the session (no prompt, no fallback).
 
 Backstop options:
   --backstop         Re-check the ACTUAL diff after implementation.
@@ -291,10 +311,39 @@ async function runBackstopMode(values) {
 /**
  * Gate mode — judge the prompt and, on proceed, author the receipt Story.
  *
+ * The three outcomes are deliberately asymmetric in what they emit:
+ *
+ *   - **`escalate-plan`** returns a schema-validated `escalated` **terminal
+ *     envelope** and stops (Story #4746). It is placed **first**, above every
+ *     creation call site, so "nothing was started" is a property of the
+ *     control flow rather than a claim the envelope makes about itself.
+ *   - **`ask-operator`** is unchanged: the plain gate envelope and exit 2. It
+ *     is not terminal — the operator has a choice to make, and manufacturing a
+ *     terminal for it would end a session that is supposed to be waiting.
+ *   - **`proceed-light`** authors the receipt Story and prints the hand-off.
+ *
+ * The injectable seams exist so the no-side-effect guarantee is testable
+ * without a network: a test asserts the escalate path never reaches them.
+ *
  * @param {object} values Parsed CLI values.
+ * @param {{
+ *   createProviderFn?: typeof createProvider,
+ *   resolveConfigFn?: typeof resolveConfig,
+ *   createReceiptFn?: typeof createLightReceipt,
+ *   emitFn?: typeof emit,
+ *   emitTerminalFn?: typeof emitTerminalEnvelope,
+ * }} [deps]
  * @returns {Promise<number>}
  */
-async function runGateMode(values) {
+export async function runGateMode(values, deps = {}) {
+  const {
+    createProviderFn = createProvider,
+    resolveConfigFn = resolveConfig,
+    createReceiptFn = createLightReceipt,
+    emitFn = emit,
+    emitTerminalFn = emitTerminalEnvelope,
+  } = deps;
+
   if (!values.prompt || String(values.prompt).trim() === '') {
     process.stderr.write(HELP);
     throw new Error('[deliver-light] --prompt <text> is required for the gate');
@@ -311,8 +360,20 @@ async function runGateMode(values) {
     yes: values.yes === true,
   });
 
+  if (gate.action === 'escalate-plan') {
+    const envelope = buildEscalationTerminal({
+      prompt: String(values.prompt),
+      reasons: gate.outcome.reasons,
+    });
+    emitTerminalFn(envelope);
+    Logger.warn(
+      `[deliver-light] ESCALATED to /plan — this session ENDS here; run ${envelope.nextCommand} in a FRESH session: ${gate.outcome.reasons.join('; ')}`,
+    );
+    return exitCodeForTerminal(envelope);
+  }
+
   if (gate.action !== 'proceed-light') {
-    emit(
+    emitFn(
       { mode: 'gate', action: gate.action, outcome: gate.outcome },
       values.pretty,
     );
@@ -322,8 +383,8 @@ async function runGateMode(values) {
     return EXIT_NOT_PROCEED;
   }
 
-  const provider = createProvider(resolveConfig());
-  const receipt = await createLightReceipt({
+  const provider = createProviderFn(resolveConfigFn());
+  const receipt = await createReceiptFn({
     provider,
     prompt: String(values.prompt),
     changedFiles: [
@@ -332,7 +393,7 @@ async function runGateMode(values) {
     ],
     amends: values.amends ?? null,
   });
-  emit(
+  emitFn(
     {
       mode: 'gate',
       action: 'proceed-light',
@@ -382,4 +443,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.',
+      ],
+    ],
+  },
+});