mandrel 2.0.0 → 2.2.0

package/.agents/scripts/acceptance-eval.js

@@ -4,8 +4,8 @@
  * acceptance-eval.js — bounded per-Story acceptance self-eval gate (Story #3819).
  *
  * The Story-implementation phase runs an independent (fresh-context)
- * critic pass that scores the working diff against each inline
- * `acceptance[]` item, emitting one verdict file per round
+ * critic pass that scores the caller-injected change set against each
+ * inline `acceptance[]` item, emitting one verdict file per round
  * (`.agents/schemas/acceptance-eval-verdict.schema.json`). This CLI is the
  * deterministic substrate that turns that verdict into the loop's next
  * action:
@@ -32,26 +32,20 @@
  * — this CLI is the decision + signal boundary, mirroring how the existing
  * gates separate decision from ticket mutation.
  *
- * Two invocation shapes (Epic #4475, M4-B):
- *   - Per-Story (fan-out): the diff is one Story's; round scoping is per
- *     Story off the Story's `signals.ndjson`.
- *   - Per-AC-cluster (single delivery): `--epic <id> --cluster <clusterId>`
- *     with NO `--story`. The verdict scores one AC cluster of the Epic's
- *     `## Acceptance Table` against the cumulative `main..epic/<id>` diff;
- *     round scoping is per cluster off the Epic's `signals.ndjson`. This is
- *     the acceptance-dilution guard — `ceil(totalACs / clusterCeiling)`
- *     independent maker-blind critic passes, one per cluster.
+ * One invocation shape: per-Story. The diff is one Story's; round scoping
+ * is per Story off the Story's `signals.ndjson`. (v2.0.0 removed the Epic
+ * tier along with the per-AC-cluster `--epic <id> --cluster <id>` mode that
+ * scored an Epic `## Acceptance Table` against a `main..epic/<id>` diff.)
  *
  * CLI:
- *   --story <id>           Story ID (required unless --cluster is given).
- *   --epic <id>            Parent Epic ID (required with --cluster).
- *   --cluster <id>         AC-cluster id for the single-delivery critic.
+ *   --story <id>           Story ID (required).
  *   --verdict <path>       Path to the round's verdict JSON (required).
  *   --no-signal            Suppress the signal emit (tests).
  *
  * Stdout: a single JSON envelope
  *   { storyId, epicId, decision, round, cap, capReached, totalCriteria,
  *     metCount, unmetCriteria[], signalEmitted }
+ *   (`epicId` is retained as a always-null field for envelope stability.)
  *
  * @see .agents/scripts/lib/orchestration/acceptance-eval-decision.js
  * @see .agents/schemas/acceptance-eval-verdict.schema.json
@@ -68,10 +62,7 @@ import addFormats from 'ajv-formats';
 import { runAsCli } from './lib/cli-utils.js';
 import { getAcceptanceEval, resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
-import {
-  appendEpicSignal,
-  appendSignal,
-} from './lib/observability/signals-writer.js';
+import { appendSignal } from './lib/observability/signals-writer.js';
 import {
   buildAcceptanceEvalSignal,
   decideAcceptanceEval,
@@ -139,22 +130,14 @@ function parseCliArgs(argv) {
     args: argv,
     options: {
       story: { type: 'string' },
-      epic: { type: 'string' },
-      cluster: { type: 'string' },
       verdict: { type: 'string' },
       'no-signal': { type: 'boolean', default: false },
     },
     strict: false,
   });
   const storyId = Number.parseInt(values.story ?? '', 10);
-  const epicRaw = Number.parseInt(values.epic ?? '', 10);
   return {
     storyId: Number.isInteger(storyId) && storyId > 0 ? storyId : null,
-    epicId: Number.isInteger(epicRaw) && epicRaw > 0 ? epicRaw : null,
-    clusterId:
-      typeof values.cluster === 'string' && values.cluster.length > 0
-        ? values.cluster
-        : null,
     verdictPath: values.verdict ?? null,
     emitSignal: values['no-signal'] !== true,
   };
@@ -168,7 +151,6 @@ function parseCliArgs(argv) {
  *
  * @param {object} args
  * @param {number} args.storyId
- * @param {number | null} args.epicId
  * @param {object} args.verdict — validated verdict object.
  * @param {object} args.config — resolved `.agentrc.json`.
  * @param {boolean} args.emitSignal
@@ -182,23 +164,18 @@ function parseCliArgs(argv) {
  * @returns {Promise<{ envelope: object, exitCode: number }>}
  */
 export async function runAcceptanceEval(
-  { storyId, epicId, clusterId = null, verdict, config, emitSignal, round },
+  { storyId, verdict, config, emitSignal, round },
   deps = {},
 ) {
   const {
     appendSignalFn = appendSignal,
-    appendEpicSignalFn = appendEpicSignal,
     deriveRoundFn = deriveAcceptanceEvalRound,
   } = deps;
-  const clusterMode =
-    typeof clusterId === 'string' &&
-    clusterId.length > 0 &&
-    Number.isInteger(epicId);
   const { maxRounds } = getAcceptanceEval(config);
   const resolvedRound =
     Number.isInteger(round) && round >= 1
       ? round
-      : deriveRoundFn({ epicId: epicId ?? null, storyId, clusterId, config });
+      : deriveRoundFn({ epicId: null, storyId, config });
   const outcome = decideAcceptanceEval({
     verdict,
     maxRounds,
@@ -208,21 +185,16 @@ export async function runAcceptanceEval(
   let signalEmitted = false;
   if (emitSignal) {
     const signal = {
-      ...buildAcceptanceEvalSignal({ storyId, epicId, outcome, clusterId }),
+      ...buildAcceptanceEvalSignal({ storyId, epicId: null, outcome }),
       ts: new Date().toISOString(),
     };
     try {
-      // Cluster mode (single delivery) writes to the epic-level signals
-      // stream so per-cluster round counts survive resume; the per-Story
-      // path writes to the Story stream (unchanged).
-      signalEmitted = clusterMode
-        ? await appendEpicSignalFn({ epicId, signal, config })
-        : await appendSignalFn({
-            epicId,
-            storyId,
-            signal,
-            config,
-          });
+      signalEmitted = await appendSignalFn({
+        epicId: null,
+        storyId,
+        signal,
+        config,
+      });
     } catch (err) {
       // Observability is best-effort — a failed signal write must never
       // take down the gate. The decision still stands.
@@ -236,8 +208,7 @@ export async function runAcceptanceEval(
 
   const envelope = {
     storyId: storyId ?? null,
-    epicId: epicId ?? null,
-    ...(clusterMode ? { clusterId } : {}),
+    epicId: null,
     decision: outcome.decision,
     round: outcome.round,
     cap: outcome.cap,
@@ -261,19 +232,11 @@ export async function runAcceptanceEval(
 }
 
 export async function main(argv = process.argv.slice(2)) {
-  const { storyId, epicId, clusterId, verdictPath, emitSignal } =
-    parseCliArgs(argv);
+  const { storyId, verdictPath, emitSignal } = parseCliArgs(argv);
 
-  // Epic #4475 (M4-B): two invocation shapes.
-  //   - Per-Story (fan-out): --story <id> [--epic <id>].
-  //   - Per-AC-cluster (single delivery): --epic <id> --cluster <id> (no
-  //     --story); the verdict scores one AC cluster of the Epic's Acceptance
-  //     Table against the cumulative main..epic/<id> diff.
-  const clusterMode = Boolean(clusterId) && Number.isInteger(epicId);
-  if (!storyId && !clusterMode) {
+  if (!storyId) {
     throw new Error(
-      'Usage: node acceptance-eval.js --story <id> [--epic <id>] --verdict <path> [--no-signal]\n' +
-        '   or: node acceptance-eval.js --epic <id> --cluster <clusterId> --verdict <path> [--no-signal]',
+      'Usage: node acceptance-eval.js --story <id> --verdict <path> [--no-signal]',
     );
   }
   if (!verdictPath) {
@@ -305,13 +268,8 @@ export async function main(argv = process.argv.slice(2)) {
   const verdict = validateVerdict(parsed);
 
   // A verdict whose embedded storyId disagrees with the CLI flag is a
-  // wiring error worth failing on, not a silent mismatch. Skipped in cluster
-  // mode (no --story; the verdict scores an AC cluster, not a Story).
-  if (
-    !clusterMode &&
-    Number.isInteger(verdict.storyId) &&
-    verdict.storyId !== storyId
-  ) {
+  // wiring error worth failing on, not a silent mismatch.
+  if (Number.isInteger(verdict.storyId) && verdict.storyId !== storyId) {
     throw new Error(
       `acceptance-eval: verdict storyId (${verdict.storyId}) does not match --story ${storyId}.`,
     );
@@ -320,8 +278,6 @@ export async function main(argv = process.argv.slice(2)) {
   const config = resolveConfig();
   const { envelope, exitCode } = await runAcceptanceEval({
     storyId,
-    epicId,
-    clusterId,
     verdict,
     config,
     emitSignal,

package/.agents/scripts/agents-bootstrap-github.js

@@ -3,7 +3,7 @@
  * agents-bootstrap-github — Idempotent Label & Field Setup
  *
  * Creates the required label taxonomy and project board custom fields
- * for the v5 Epic-centric flow on a target GitHub repo. Idempotent —
+ * for the v5 Story-centric flow on a target GitHub repo. Idempotent —
  * skips resources that already exist.
  *
  * Usage:

package/.agents/scripts/bootstrap.js

@@ -45,8 +45,8 @@
  *                             and custom fields. Off by default — the project
  *                             board object is still created when a project
  *                             name is supplied, but decoration is skipped.
- *   --with-issue-forms        Opt-in: generate .github/ISSUE_TEMPLATE/story.yml
- *                             and epic.yml. Off by default.
+ *   --with-issue-forms        Opt-in: generate .github/ISSUE_TEMPLATE/story.yml.
+ *                             Off by default.
  *   --reap-conflicting-workflows  Delete Projects V2 built-in workflows that
  *                             race against the orchestrator (destructive)
  *   --help                    Print this help
@@ -112,7 +112,7 @@ Flags:
   --with-project-board      Opt-in: provision the Projects V2 Status field
                             and custom fields (default: off — prompted y/N).
   --with-issue-forms        Opt-in: generate .github/ISSUE_TEMPLATE/story.yml
-                            and epic.yml (default: off — prompted y/N).
+                            (default: off — prompted y/N).
   --reap-conflicting-workflows  Delete Projects V2 built-in workflows that
                             race against the orchestrator (destructive)
   --help                    Print this help

package/.agents/scripts/check-dead-exports.js

@@ -9,12 +9,18 @@
  * misconfigured knip installation cannot block CI when we have no current
  * snapshot to compare against.
  *
+ * Story #4575 adds the **production pass** (`--production`), the test-only-
+ * importer discount: default mode counts a test as an importer, so
+ * production-dead code hides behind its own tests. See
+ * `lib/dead-exports-mode.js` for why the two passes carry separate baselines.
+ *
  * Contract:
- *   - Reads the committed baseline at `baselines/dead-exports.json`
- *     (override with `--baseline <path>`). Envelope shape:
+ *   - Reads the committed baseline at `baselines/dead-exports.json` — or
+ *     `baselines/dead-exports-production.json` under `--production`
+ *     (override either with `--baseline <path>`). Envelope shape:
  *       { $schema, kernelVersion, generatedAt, rows: [{ file, symbol }] }
- *   - Spawns `npx knip --reporter json --no-progress`, parses stdout,
- *     extracts `{ file, symbol }` rows from `issues[].exports[]`.
+ *   - Spawns `npx knip --reporter json --no-progress` (plus `--production`),
+ *     parses stdout, extracts `{ file, symbol }` rows from `issues[].exports[]`.
  *   - Diffs current vs. baseline by `(file, symbol)` identity.
  *   - Prints `+ <file>: <symbol>` for each added dead export and
  *     `- <file>: <symbol>` for each removed one, then a summary line.
@@ -25,24 +31,30 @@
  *     Knip spawn/parse failure exits 0 (advisory) with a stderr warning.
  */
 
-import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
 import { runAsCli } from './lib/cli-utils.js';
+import {
+  extractRowsFromKnip,
+  readKnipOutput,
+  runKnip,
+} from './lib/dead-exports-knip.js';
+import { resolveDeadExportsMode } from './lib/dead-exports-mode.js';
 
 /**
- * Parse argv for `--baseline <path>`, `--json`, and `--knip-output <path>`.
- * `--knip-output` is a test seam: pass a pre-captured knip JSON file instead
- * of spawning knip. Exported so unit tests can pin the parser.
+ * Parse argv for `--baseline <path>`, `--json`, `--knip-output <path>`, and
+ * `--production`. `--knip-output` is a test seam: pass a pre-captured knip JSON
+ * file instead of spawning knip. Exported so unit tests can pin the parser.
  *
  * @param {string[]} argv
- * @returns {{ baselinePath: string | null, json: boolean, knipOutputPath: string | null }}
+ * @returns {{ baselinePath: string | null, json: boolean, knipOutputPath: string | null, production: boolean }}
  */
 export function parseArgv(argv = []) {
   let baselinePath = null;
   let json = false;
   let knipOutputPath = null;
+  let production = false;
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === '--baseline') {
@@ -53,6 +65,8 @@ export function parseArgv(argv = []) {
       }
     } else if (a === '--json') {
       json = true;
+    } else if (a === '--production') {
+      production = true;
     } else if (a === '--knip-output') {
       const next = argv[i + 1];
       if (next && !next.startsWith('--')) {
@@ -61,7 +75,7 @@ export function parseArgv(argv = []) {
       }
     }
   }
-  return { baselinePath, json, knipOutputPath };
+  return { baselinePath, json, knipOutputPath, production };
 }
 
 /**
@@ -84,36 +98,6 @@ export function loadBaseline(baselinePath) {
   }
 }
 
-/**
- * Pure helper: normalize knip's `--reporter json` output into a flat array of
- * `{ file, symbol }` rows. Knip emits `{ issues: [{ file, exports: [{ name, ... }], ... }, ...] }`.
- * Only `exports` rows are mapped — the dead-export ratchet ignores file-level,
- * dependency-level, and duplicate-level issues (knip surfaces those via
- * separate `rules` keys).
- *
- * @param {unknown} knipEnvelope The parsed knip JSON report.
- * @returns {Array<{ file: string, symbol: string }>}
- */
-export function extractRowsFromKnip(knipEnvelope) {
-  const rows = [];
-  if (!knipEnvelope || typeof knipEnvelope !== 'object') return rows;
-  const issues = Array.isArray(knipEnvelope.issues) ? knipEnvelope.issues : [];
-  for (const issue of issues) {
-    const file = issue?.file;
-    if (typeof file !== 'string' || file.length === 0) continue;
-    const exports_ = Array.isArray(issue.exports) ? issue.exports : [];
-    for (const e of exports_) {
-      const symbol =
-        (e && typeof e.name === 'string' && e.name) ||
-        (e && typeof e.symbol === 'string' && e.symbol) ||
-        null;
-      if (!symbol) continue;
-      rows.push({ file, symbol });
-    }
-  }
-  return rows;
-}
-
 /**
  * Pure helper: diff two `{ file, symbol }` row sets. Returns `added` (in
  * current but not baseline) and `removed` (in baseline but not current).
@@ -151,75 +135,24 @@ export function diffRows(baselineRows, currentRows) {
  * "no drift" signal. When added rows are present the summary includes a
  * "(gate fail)" marker so the ratchet violation is visible in CI output.
  *
+ * `label` distinguishes the two passes in CI logs, which run back to back and
+ * would otherwise emit two identical-looking summaries.
+ *
  * @param {{ added: Array, removed: Array }} diff
+ * @param {string} [label='dead-exports']
  * @returns {string}
  */
-export function renderDiff(diff) {
+export function renderDiff(diff, label = 'dead-exports') {
   const lines = [];
   for (const r of diff.added) lines.push(`+ ${r.file}: ${r.symbol}`);
   for (const r of diff.removed) lines.push(`- ${r.file}: ${r.symbol}`);
   const tag = diff.added.length > 0 ? '(gate fail)' : '(ok)';
   lines.push(
-    `[dead-exports] added=${diff.added.length} removed=${diff.removed.length} ${tag}`,
+    `[${label}] added=${diff.added.length} removed=${diff.removed.length} ${tag}`,
   );
   return lines.join('\n');
 }
 
-/**
- * Spawn `npx knip --reporter json --no-progress` and return the parsed
- * envelope. Returns `null` on spawn / parse failure — the caller logs the
- * underlying error and falls back to treating current rows as empty (which
- * surfaces every baseline row as "removed", a loud-but-safe signal).
- *
- * Exported as a hook so tests can stub the spawn without setting up a
- * functioning knip workspace.
- *
- * @param {{ cwd?: string, spawn?: typeof spawnSync }} [opts]
- * @returns {{ ok: true, envelope: unknown } | { ok: false, error: string }}
- */
-export function runKnip({ cwd = process.cwd(), spawn = spawnSync } = {}) {
-  const result = spawn(
-    process.platform === 'win32' ? 'npx.cmd' : 'npx',
-    ['knip', '--reporter', 'json', '--no-progress'],
-    {
-      cwd,
-      stdio: ['ignore', 'pipe', 'pipe'],
-      encoding: 'utf-8',
-      shell: process.platform === 'win32',
-    },
-  );
-  if (result.error) {
-    return { ok: false, error: `spawn failed: ${result.error.message}` };
-  }
-  const stdout = typeof result.stdout === 'string' ? result.stdout : '';
-  if (stdout.trim().length === 0) {
-    return { ok: false, error: 'knip produced empty stdout' };
-  }
-  try {
-    return { ok: true, envelope: JSON.parse(stdout) };
-  } catch (err) {
-    return {
-      ok: false,
-      error: `knip JSON parse failed: ${err?.message ?? err}`,
-    };
-  }
-}
-
-/**
- * Read a pre-captured knip JSON envelope from disk (for the `--knip-output`
- * test seam). Returns the parsed envelope or `null` on failure.
- *
- * @param {string} filePath
- * @returns {unknown}
- */
-function readKnipOutput(filePath) {
-  try {
-    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
-  } catch {
-    return null;
-  }
-}
-
 /**
  * Top-level CLI entry. Exported so tests can drive the full pipeline through
  * injected hooks without spawning knip.
@@ -242,10 +175,15 @@ export async function runCli({
   runKnipImpl = runKnip,
   loadBaselineImpl = loadBaseline,
 } = {}) {
-  const { baselinePath, json, knipOutputPath } = parseArgv(argv);
+  const { baselinePath, json, knipOutputPath, production } = parseArgv(argv);
+  const {
+    mode,
+    label,
+    baseline: defaultBaseline,
+  } = resolveDeadExportsMode(production);
   const resolvedBaselinePath = path.resolve(
     cwd,
-    baselinePath ?? path.join('baselines', 'dead-exports.json'),
+    baselinePath ?? defaultBaseline,
   );
   const baseline = loadBaselineImpl(resolvedBaselinePath);
   const baselineRows = Array.isArray(baseline?.rows) ? baseline.rows : [];
@@ -256,7 +194,7 @@ export async function runCli({
     knipEnvelope = readKnipOutput(path.resolve(cwd, knipOutputPath));
     if (!knipEnvelope) knipError = `failed to read ${knipOutputPath}`;
   } else {
-    const result = runKnipImpl({ cwd });
+    const result = runKnipImpl({ cwd, production });
     if (result.ok) {
       knipEnvelope = result.envelope;
     } else {
@@ -275,6 +213,7 @@ export async function runCli({
   if (json) {
     const envelope = {
       kind: 'dead-exports-report',
+      mode,
       baselinePath: resolvedBaselinePath,
       baselineRows,
       currentRows,
@@ -287,14 +226,14 @@ export async function runCli({
   } else {
     if (!baseline) {
       stderr.write(
-        `[dead-exports] ⚠ baseline not found at ${resolvedBaselinePath} — treating as empty\n`,
+        `[${label}] ⚠ baseline not found at ${resolvedBaselinePath} — treating as empty\n`,
       );
     }
     if (knipError) {
-      stderr.write(`[dead-exports] ⚠ knip run failed: ${knipError}\n`);
+      stderr.write(`[${label}] ⚠ knip run failed: ${knipError}\n`);
     }
-    stdout.write(`\n--- dead-exports preview ---\n`);
-    stdout.write(`${renderDiff(diff)}\n`);
+    stdout.write(`\n--- ${label} preview ---\n`);
+    stdout.write(`${renderDiff(diff, label)}\n`);
   }
 
   return exitCode;

package/.agents/scripts/check-doc-links.js

@@ -257,8 +257,8 @@ function stripAnchorAndQuery(target) {
 // A slash token is `/<name>` where:
 //   - the preceding char is NOT a word char, `/`, `:`, `.`, `>`, `]`, `)`,
 //     so we don't match URL path segments or fragments embedded in paths
-//     like `temp/epic-<id>/lifecycle.ndjson` (preceded by `>`) or
-//     `temp/epic-[ID]/tickets.json` (preceded by `]`).
+//     like `temp/run-<id>/lifecycle.ndjson` (preceded by `>`) or
+//     `temp/run-[ID]/tickets.json` (preceded by `]`).
 //   - the following char is NOT a word char, `-`, or `.`, so file
 //     extensions like `/tickets.json` and identifier suffixes don't match.
 // The optional `(?::[a-z][a-z0-9-]*)?` tail captures the namespaced

package/.agents/scripts/check-lifecycle-lint.js

@@ -17,7 +17,7 @@
  *   Any module under `.agents/scripts/lib/orchestration/lifecycle/listeners/**`
  *   that calls `bus.on('*', …)` MUST NOT import a side-effecting module.
  *   The static blocklist is small (the modules that mutate GitHub state,
- *   the worktree, or write outside `temp/epic-<id>/`); we match by module
+ *   the worktree, or write outside `temp/run-<id>/`); we match by module
  *   specifier suffix to keep the rule simple and stable.
  *
  * Rule 3 — "Auto-merge lockout" (Story #2253 / Task #2255, Epic #2172

package/.agents/scripts/check-workflow-cli-lint.js

@@ -61,6 +61,19 @@ const BACKTICK_CALL_RE = /`[A-Za-z_$][\w$]*\s*\(/;
 const EXPORTED_FROM_RE = /\bexported from\b/;
 const LIB_IMPORT_RE = /\b(?:import|require)\(\s*['"`][^'"`]*scripts\/lib\//;
 
+/** A markdown table row (leading pipe, optionally indented). */
+const TABLE_ROW_RE = /^\s*\|/;
+/** A markdown heading of any level — the lookback boundary for Rule 4. */
+const HEADING_RE = /^\s*#{1,6}\s/;
+/** A backticked `--flag` occupying a table row's first cell. */
+const FLAG_CELL_RE = /^\s*\|\s*`?--[\w-]+/;
+/** A `.js` script filename — bare or path-qualified. */
+const SCRIPT_NAME_RE = /([\w./-]*[\w-]+\.js)\b/;
+/** A markdown table's delimiter row (`| --- | --- |`). */
+const TABLE_DELIMITER_RE = /^\s*\|[\s|:-]+\|?\s*$/;
+/** Minimum `--flag` rows before a table counts as a flag *table*. */
+export const MIN_FLAG_ROWS = 2;
+
 /**
  * Strip fenced code blocks (``` / ~~~), replacing their lines with empty
  * strings so line numbers stay stable. Complete runnable commands live in
@@ -106,6 +119,82 @@ export function toParagraphs(lines) {
   return paragraphs;
 }
 
+/**
+ * Rule 4 — CLI flag table. Find markdown tables that enumerate the `--flags`
+ * of a script the repo already owns, and flag them as duplicated surface.
+ *
+ * The script's own argument parser is the source of truth for its flags, and
+ * it prints them itself; a copy in prose is drift waiting to happen (the very
+ * drift Story #4546 removed). Prose must point at the command instead.
+ *
+ * The signal is deliberately narrow, to stay at zero false positives:
+ *
+ *   1. The table has at least `MIN_FLAG_ROWS` data rows whose **first cell**
+ *      is a `--flag`. One flag row among prose rows is a contract/behaviour
+ *      table (e.g. "Default | …", "`--dry-run` | …"), not a flag enumeration.
+ *   2. A `.js` script is named between the table and the nearest preceding
+ *      heading (inclusive) — i.e. the section is *about* that script, so the
+ *      table is restating its surface.
+ *
+ * A slash command's own argument table (`/plan`, `/deliver`) has no script
+ * behind it — nothing owns those flags but the workflow prose itself — so
+ * condition 2 leaves it alone by design.
+ *
+ * @param {string[]} rawLines unstripped source lines (fenced commands are the
+ *   usual place a script is named, so this rule reads the original text).
+ * @returns {Array<{ rule: string, line: number, hint: string }>}
+ */
+export function lintFlagTables(rawLines) {
+  const violations = [];
+  let inFence = false;
+
+  for (let i = 0; i < rawLines.length; i++) {
+    if (/^\s*(```|~~~)/.test(rawLines[i])) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence || !TABLE_ROW_RE.test(rawLines[i])) continue;
+
+    // Collect the contiguous table block starting here.
+    const start = i;
+    let end = i;
+    while (end + 1 < rawLines.length && TABLE_ROW_RE.test(rawLines[end + 1])) {
+      end += 1;
+    }
+    i = end; // continue scanning after this table
+
+    const flagRows = rawLines
+      .slice(start, end + 1)
+      .filter((l) => !TABLE_DELIMITER_RE.test(l) && FLAG_CELL_RE.test(l));
+    if (flagRows.length < MIN_FLAG_ROWS) continue;
+
+    // Look back to the nearest heading (inclusive) for a named script.
+    let script = null;
+    for (let j = start - 1; j >= 0; j--) {
+      const m = SCRIPT_NAME_RE.exec(rawLines[j]);
+      if (m) {
+        script = m[1];
+        break;
+      }
+      if (HEADING_RE.test(rawLines[j])) break;
+    }
+    if (!script) continue;
+
+    const base = script.split('/').pop();
+    violations.push({
+      rule: 'no-cli-flag-table',
+      line: start + 1,
+      hint:
+        `Workflow prose restates the flag surface of \`${base}\` as a table (${flagRows.length} flag rows). ` +
+        "The script's argument parser owns those flags, so a prose copy is drift waiting to happen. " +
+        `Delete the table and point at the command (\`node .agents/scripts/${base} …\`), keeping only the ` +
+        'judgement a reader cannot get from the command itself. If the script has no help output to point ' +
+        'at, add one — do not re-inline the table.',
+    });
+  }
+  return violations;
+}
+
 /**
  * Lint one markdown source. Returns violations
  * `{ rule, line, hint }[]` (empty when clean).
@@ -115,7 +204,9 @@ export function toParagraphs(lines) {
  */
 export function lintWorkflowSource(source) {
   const violations = [];
+  const rawLines = source.split('\n');
   const lines = stripFences(source);
+  violations.push(...lintFlagTables(rawLines));
   for (const para of toParagraphs(lines)) {
     if (IMPERATIVE_CALL_RE.test(para.text)) {
       violations.push({