mandrel 2.31.0 → 2.33.0

package/.agents/schemas/lifecycle/README.md

@@ -1,18 +1,25 @@
 # Lifecycle event schemas
 
-JSON Schemas for the lifecycle event taxonomy consumed by the
-`/deliver` lifecycle bus
-(`lib/orchestration/lifecycle/bus.js`). The bus validates every
-emit payload against one of these schemas before invoking
-listeners; a schema mismatch fails the emit and propagates the
-throw.
+JSON Schemas for the two events a delivery run can append to its per-run
+lifecycle ledger. `appendLedgerEvent`
+(`lib/orchestration/lifecycle/emit-ledger-event.js`) validates every payload
+against one of these before the write; a schema mismatch throws and nothing is
+appended.
 
-Each event in the Tech Spec taxonomy has a `<event>.schema.json`
-file. The ledger record (`emitted | completed | failed` union)
-lives in `ledger-record.schema.json` and is consumed by
-`ledger-writer.js`.
+`ledger-record.schema.json` is the NDJSON record envelope
+(`emitted | completed | failed`), not an event. Only `emitted` has a writer —
+see the schema's own description for why the other two kinds remain.
 
-Schemas are intentionally permissive (`additionalProperties: true`)
-on inner objects whose shape is dictated by upstream tooling (e.g.
-`gh pr view` JSON, `checkOutcomes`). The required-key set is the
-contract.
+**A schema belongs here only while code emits its event.** Story #4545 applied
+that rule to the `epic.*` and `acceptance.reconcile.*` families; Story #5024
+applied it to the remaining fifteen when it retired the lifecycle bus that had
+been their only publish path. `tests/lifecycle/schema-registry.test.js` enforces
+it in both directions, so a schema file for an event nobody emits fails the
+suite rather than reading green.
+
+Schemas are intentionally permissive (`additionalProperties: true`) on inner
+objects whose shape is dictated by upstream tooling (e.g. `gh pr view` JSON).
+The required-key set is the contract.
+
+Full reference:
+[`docs/LIFECYCLE.md`](https://github.com/dsj1984/mandrel/blob/main/docs/LIFECYCLE.md).

package/.agents/schemas/lifecycle/ledger-record.schema.json

@@ -2,22 +2,41 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/ledger-record.schema.json",
   "title": "Lifecycle ledger record (emitted | completed | failed)",
-  "description": "Append-only NDJSON record shape for temp/run-<id>/lifecycle.ndjson. Three discriminated kinds; consumers (LedgerWriter, TraceLogger) discriminate on `kind`.",
+  "description": "Append-only NDJSON record shape for the per-run lifecycle ledger. Three discriminated kinds keyed on `kind`. Only `emitted` has a writer: Story #5024 retired the lifecycle bus, so the `completed` / `failed` kinds are a READ contract for ledgers archived from the bus era (`failed` requires a `listener`, which only a listener chain could supply). Reading a ledger never consults this schema; validation happens on the write path only.",
   "oneOf": [
-    { "$ref": "#/$defs/emitted" },
-    { "$ref": "#/$defs/completed" },
-    { "$ref": "#/$defs/failed" }
+    {
+      "$ref": "#/$defs/emitted"
+    },
+    {
+      "$ref": "#/$defs/completed"
+    },
+    {
+      "$ref": "#/$defs/failed"
+    }
   ],
   "$defs": {
     "emitted": {
       "type": "object",
       "required": ["kind", "seqId", "ts", "event", "payload"],
       "properties": {
-        "kind": { "const": "emitted" },
-        "seqId": { "type": "integer", "minimum": 1 },
-        "ts": { "type": "string", "format": "date-time" },
-        "event": { "type": "string", "minLength": 1 },
-        "payload": { "type": "object" }
+        "kind": {
+          "const": "emitted"
+        },
+        "seqId": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "ts": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "event": {
+          "type": "string",
+          "minLength": 1
+        },
+        "payload": {
+          "type": "object"
+        }
       },
       "additionalProperties": false
     },
@@ -25,11 +44,25 @@
       "type": "object",
       "required": ["kind", "seqId", "ts", "event"],
       "properties": {
-        "kind": { "const": "completed" },
-        "seqId": { "type": "integer", "minimum": 1 },
-        "ts": { "type": "string", "format": "date-time" },
-        "event": { "type": "string", "minLength": 1 },
-        "listener": { "type": "string", "minLength": 1 }
+        "kind": {
+          "const": "completed"
+        },
+        "seqId": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "ts": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "event": {
+          "type": "string",
+          "minLength": 1
+        },
+        "listener": {
+          "type": "string",
+          "minLength": 1
+        }
       },
       "additionalProperties": false
     },
@@ -37,18 +70,39 @@
       "type": "object",
       "required": ["kind", "seqId", "ts", "event", "listener", "error"],
       "properties": {
-        "kind": { "const": "failed" },
-        "seqId": { "type": "integer", "minimum": 1 },
-        "ts": { "type": "string", "format": "date-time" },
-        "event": { "type": "string", "minLength": 1 },
-        "listener": { "type": "string", "minLength": 1 },
+        "kind": {
+          "const": "failed"
+        },
+        "seqId": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "ts": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "event": {
+          "type": "string",
+          "minLength": 1
+        },
+        "listener": {
+          "type": "string",
+          "minLength": 1
+        },
         "error": {
           "type": "object",
           "required": ["name", "message"],
           "properties": {
-            "name": { "type": "string", "minLength": 1 },
-            "message": { "type": "string" },
-            "stack": { "type": "string" }
+            "name": {
+              "type": "string",
+              "minLength": 1
+            },
+            "message": {
+              "type": "string"
+            },
+            "stack": {
+              "type": "string"
+            }
           },
           "additionalProperties": false
         }

package/.agents/schemas/story-deliver-terminal.schema.json

@@ -73,10 +73,10 @@
     },
     "gates": {
       "type": "object",
-      "description": "Outcome of each close gate this invocation was responsible for. A gate the run skipped (--skip-validation, or a phase it never reached) reports \"skipped\" rather than being omitted, so a missing gate is never mistaken for a passing one.",
+      "description": "Outcome of each close gate this invocation was responsible for. A gate the run skipped (--skip-validation, or a phase it never reached) reports \"skipped\" rather than being omitted, so a missing gate is never mistaken for a passing one. \"overridden\" is distinct from both: the gate ran, it FAILED, and an operator authorized delivery anyway via --override-review-block with a recorded reason. Reporting that as \"passed\" would erase the one fact a reader of this envelope most needs, and reporting it as \"skipped\" would claim the gate never ran.",
       "additionalProperties": {
         "type": "string",
-        "enum": ["passed", "failed", "skipped"]
+        "enum": ["passed", "failed", "skipped", "overridden"]
       }
     },
     "tail": {

package/.agents/scripts/README.md

@@ -5,35 +5,22 @@ invoked indirectly by `npm run …`, slash-command workflows
 (`.agents/workflows/*.md`), or Husky / GitHub Actions hooks; you rarely
 need to call them by hand.
 
-This file is **not** an exhaustive index of the ~90 top-level entrypoints.
-It documents the **operator-facing scripts** that operators may want to
-run by hand and that are **not** wired into the standard quality / CI
-surface. For everything else, search `package.json` scripts and
-`.agents/workflows/` first.
-
-## Operator Scripts
-
-These scripts are kept in the distributed product but are intentionally
-not invoked by `npm test`, `npm run verify`, CI, or any Husky hook. They
-are optional operator tools; run them by hand when you need them.
-
-### `validate-docs-freshness.js`
-
-**Purpose.** Per-Epic documentation freshness gate. For each doc in
-`delivery.docsFreshness.paths` + `project.docsContextFiles`, asserts
-that the file was meaningfully updated during this Epic's lifecycle
-(commit message references `#<epicId>` or the file body does).
-
-**When to run.** Optional. Useful as a pre-merge spot check when an
-Epic should have produced documentation updates; the standard
-`/deliver` flow does **not** invoke this gate today.
-
-**Usage.**
-
-```bash
-node .agents/scripts/validate-docs-freshness.js --epic <id> \
-  [--base main] [--docs <comma-separated>] [--json]
-```
+This file is **not** an exhaustive index of the ~90 top-level entrypoints —
+it is the orientation pointer for the directory. Every script documents
+its own flags under `--help`, and each is reachable from a real caller:
+search `package.json` scripts, `.agents/workflows/`, and the Husky /
+GitHub Actions surfaces first. `check-knip-entries.js` derives that
+caller set mechanically, so a CLI no invoker names is dead, not
+operator-only.
+
+It reads the entry list from whatever configuration knip itself would
+load — `knip.json`, `knip.jsonc`, `.knip.json(c)`, `knip.ts`, `knip.js`,
+`knip.config.ts`, `knip.config.js`, or `package.json#knip` — evaluating
+TS/JS modules rather than parsing them, and counting entries declared
+per-workspace as well as at the top level. A project with no knip
+configuration at all exits 0 with a skip line, so the gate is safe to
+wire everywhere; a configuration that exists but cannot be resolved
+still exits 2.
 
 ## See Also
 

package/.agents/scripts/apply-quality-bootstrap.js

@@ -11,63 +11,56 @@
  * had no test so it silently drifted when the two helper signatures moved, and
  * it could not be invoked or dry-run independently.
  *
- * This script runs the two Epic #1386 quality-gate installs in order against
- * the consumer repo root:
+ * The script runs one install against the consumer repo root:
+ * `applyQualityBootstrap` — copies the code-quality-guardrails helper,
+ * installs the `.husky/pre-commit` quality:preview line, backfills the
+ * `quality:preview` / `quality:watch` npm scripts, seeds the
+ * `delivery.quality.{codingGuardrails,autoRefresh}` defaults, and prunes a
+ * committed pre-v2 `baselines/epic/` tree.
  *
- *   1. `applyQualityBootstrap` — copies the code-quality-guardrails helper,
- *      installs the `.husky/pre-commit` quality:preview line, backfills the
- *      `quality:preview` / `quality:watch` npm scripts, and seeds the
- *      `delivery.quality.{codingGuardrails,autoRefresh}` defaults.
- *   2. `migrateBaselinesLayout` — relocates per-Epic baseline snapshots into
- *      the `temp/epic/<id>/baselines/` namespace.
+ * Story #5007 retired the second step. `migrateBaselinesLayout` relocated
+ * per-Epic ratchet snapshots into `temp/epic/<id>/baselines/` on the contract
+ * that `/deliver` reaps that namespace on merge — a mechanism the Story-only
+ * v2 model deleted, so the migration moved dead data into a namespace no code
+ * path writes, reads, or reaps. Its one residual hygiene value (getting the
+ * committed `baselines/epic/` tree out of version control) survives as
+ * `pruneLegacyEpicBaselines`, the quality install's fifth step.
  *
- * Both helpers are idempotent by contract — a second run reports `no-change`
- * on every install path — so this wrapper is safe to re-run. It prints the
- * **same JSON result shape** the heredoc did: `{ quality, baselines }` to
- * stdout, so any tooling that parsed the old output keeps working.
+ * The helper is idempotent by contract — a second run reports `no-change` /
+ * `already-present` / `absent` on every install path — so this wrapper is safe
+ * to re-run. It prints `{ quality }` JSON to stdout.
  *
  * The effectful work is a thin pure function (`applyBootstrapAndMigration`)
- * that takes the two helpers and the project root, so the test suite can
- * drive it against a tmp directory without spawning a child process. The CLI
- * wrapper wires the real helpers and `process.cwd()`.
+ * that takes the helper and the project root, so the test suite can drive it
+ * against a tmp directory without spawning a child process. The CLI wrapper
+ * wires the real helper and `process.cwd()`.
  */
 
-import path from 'node:path';
-import { migrateBaselinesLayout } from './lib/bootstrap/baselines-layout-migration.js';
 import { applyQualityBootstrap } from './lib/bootstrap/quality-bootstrap.js';
 import { runAsCli } from './lib/cli-utils.js';
 
 /**
- * Run the quality-bootstrap install and the baselines-layout migration
- * against `projectRoot`, returning the combined `{ quality, baselines }`
- * envelope. Pure relative to its injected helpers: the default helpers touch
- * the filesystem under `projectRoot`, but tests can pass stubs to exercise
- * the composition in isolation.
+ * Run the quality-bootstrap install against `projectRoot`, returning the
+ * `{ quality }` envelope. Pure relative to its injected helper: the default
+ * helper touches the filesystem under `projectRoot`, but tests can pass a stub
+ * to exercise the composition in isolation.
  *
  * @param {object} options
  * @param {string} options.projectRoot Absolute consumer repo root.
  * @param {typeof applyQualityBootstrap} [options.applyQualityBootstrap]
- * @param {typeof migrateBaselinesLayout} [options.migrateBaselinesLayout]
- * @returns {{ quality: object, baselines: object }}
+ * @returns {{ quality: object }}
  */
 export function applyBootstrapAndMigration({
   projectRoot,
   applyQualityBootstrap: applyQuality = applyQualityBootstrap,
-  migrateBaselinesLayout: migrateBaselines = migrateBaselinesLayout,
 }) {
-  const quality = applyQuality({ projectRoot });
-  const baselines = migrateBaselines({
-    baselinesDir: path.join(projectRoot, 'baselines'),
-    repoRoot: projectRoot,
-  });
-  return { quality, baselines };
+  return { quality: applyQuality({ projectRoot }) };
 }
 
 async function main() {
   const projectRoot = process.cwd();
   const result = applyBootstrapAndMigration({ projectRoot });
-  // Mirror the retired heredoc's output: pretty-printed `{ quality, baselines }`
-  // to stdout. Use process.stdout.write (not console.log) per the no-console
+  // Use process.stdout.write (not console.log) per the no-console
   // enforcement boundary.
   process.stdout.write(`${JSON.stringify(result)}\n`);
   return 0;
@@ -79,7 +72,7 @@ runAsCli(import.meta.url, main, {
   usage: {
     invocation: 'node .agents/scripts/apply-quality-bootstrap.js',
     summary:
-      'Install the quality-gate surface into the consumer repo (guardrails helper, pre-commit line, npm scripts, config defaults) and migrate the baselines layout. Idempotent; prints { quality, baselines } JSON to stdout.',
+      'Install the quality-gate surface into the consumer repo (guardrails helper, pre-commit line, npm scripts, config defaults, legacy baselines/epic prune). Idempotent; prints { quality } JSON to stdout.',
     flags: [],
   },
 });

package/.agents/scripts/audit-to-stories.js

@@ -45,6 +45,7 @@ import {
 } from './lib/audit-to-stories/ledger.js';
 import { parseAuditReports } from './lib/audit-to-stories/parse-audit-md.js';
 import { buildPlanSeedMarkdown } from './lib/audit-to-stories/seed-from-findings.js';
+import { wireAuditStoryEdges } from './lib/audit-to-stories/wire-dependencies.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { searchSemanticCandidates } from './lib/findings/semantic-issue-search.js';
 import { SEVERITIES, SEVERITY_RANK } from './lib/findings/severity.js';
@@ -583,6 +584,81 @@ function buildAndGateStories(eligible, edges) {
   return built;
 }
 
+/**
+ * The `--wire-edges` pass: hand the opened issue numbers back so the cohort's
+ * detected group edges become declared ordering (Story #5044).
+ *
+ * This is the second half of the two-pass crossing `--emit-stories` starts. The
+ * host opens one Issue per group from the emitted drafts, then replays the
+ * `groupKey → issueNumber` map here; each Story whose blockers now exist is
+ * re-rendered with a canonical `blocked by #N` footer and the same edges are
+ * mirrored as native `blocked_by` relations.
+ *
+ * @param {object} params
+ * @param {object} params.plan   A `--scan` plan envelope.
+ * @param {Record<string, number>} params.issueByGroupKey
+ * @param {object} [deps]
+ * @param {Function} [deps.loadProviderImpl]
+ * @param {Function} [deps.wireImpl]
+ * @returns {Promise<object>} the wiring summary.
+ */
+async function wireEdges({ plan, issueByGroupKey }, deps = {}) {
+  const { loadProviderImpl = loadProvider, wireImpl = wireAuditStoryEdges } =
+    deps;
+  const groups = (plan.classifications ?? [])
+    .filter((c) => c.action === 'create')
+    .map((c) => c.group);
+  const provider = await loadProviderImpl();
+  if (typeof provider?.updateTicket !== 'function') {
+    throw new Error(
+      '--wire-edges needs a provider exposing updateTicket to rewrite the ' +
+        'Story bodies with their `blocked by #N` footers. Configure ' +
+        'github.owner/repo (and auth), or wire the edges by hand.',
+    );
+  }
+  return wireImpl({
+    groups,
+    edges: plan.edges ?? [],
+    issueByGroupKey,
+    provider,
+    updateBody: (issueNumber, body) =>
+      provider.updateTicket(issueNumber, { body }),
+  });
+}
+
+/**
+ * Parse the `--ids` argument: a JSON object mapping group key → issue number,
+ * or a path to a file containing one.
+ *
+ * @param {string|undefined} raw
+ * @returns {Record<string, number>}
+ */
+function parseIssueMap(raw) {
+  if (!raw) {
+    throw new Error(
+      '--wire-edges requires --ids \'{"<groupKey>": <issueNumber>, ...}\' ' +
+        '(or a path to a JSON file with that shape) — the issue numbers the ' +
+        'create pass opened. Without them there is nothing to resolve the ' +
+        'group edges against.',
+    );
+  }
+  const text = raw.trimStart().startsWith('{')
+    ? raw
+    : fs.readFileSync(raw, 'utf8');
+  const parsed = JSON.parse(text);
+  const out = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n <= 0) {
+      throw new Error(
+        `--ids: "${key}" maps to ${JSON.stringify(value)}, which is not a positive issue number.`,
+      );
+    }
+    out[key] = n;
+  }
+  return out;
+}
+
 function persist(text, outPath) {
   if (!outPath) {
     process.stdout.write(text);
@@ -604,6 +680,8 @@ export const __testing = {
   resolveSeverityFloor,
   reconcileScanLedger,
   issueStatesFromClassifications,
+  wireEdges,
+  parseIssueMap,
 };
 
 /**
@@ -637,6 +715,8 @@ export async function runAuditToStories(
     loadPlanImpl = loadPlan,
     buildAndGateStoriesImpl = buildAndGateStories,
     buildPlanSeedMarkdownImpl = buildPlanSeedMarkdown,
+    wireEdgesImpl = wireEdges,
+    parseIssueMapImpl = parseIssueMap,
     persistImpl = persist,
     stdout = process.stdout,
   } = deps;
@@ -648,6 +728,8 @@ export async function runAuditToStories(
       'dry-run': { type: 'boolean' },
       'emit-plan-seed': { type: 'boolean' },
       'emit-stories': { type: 'boolean' },
+      'wire-edges': { type: 'boolean' },
+      ids: { type: 'string' },
       glob: { type: 'string' },
       severity: { type: 'string' },
       ledger: { type: 'string' },
@@ -659,64 +741,93 @@ export async function runAuditToStories(
     strict: false,
   });
 
-  if (values.auto) {
-    const { summary } = await runAutoImpl({
-      glob: values.glob,
-      severity: values.severity,
-      dryRun: values['dry-run'],
-      useProvider: !values['no-provider'],
-      ledgerPath: values.ledger,
-    });
-    persistImpl(JSON.stringify(summary, null, 2), values.out);
-    if (!values.out) stdout.write('\n');
-    return;
-  }
-
-  if (values.scan) {
-    const plan = await buildPlanImpl({
+  const json = (value) => JSON.stringify(value, null, 2);
+
+  const runAutoSummary = async () =>
+    (
+      await runAutoImpl({
+        glob: values.glob,
+        severity: values.severity,
+        dryRun: values['dry-run'],
+        useProvider: !values['no-provider'],
+        ledgerPath: values.ledger,
+      })
+    ).summary;
+
+  const scanPlan = () =>
+    buildPlanImpl({
       glob: values.glob,
       severity: values.severity,
       useProvider: !values['no-provider'],
     });
-    const out = JSON.stringify(plan, null, 2);
-    persistImpl(out, values.out);
-    if (!values.out) stdout.write('\n');
-    return;
-  }
 
-  if (values['emit-plan-seed']) {
+  const seedMarkdown = () => {
     const plan = loadPlanImpl(values.plan);
-    const md = buildPlanSeedMarkdownImpl({
+    return buildPlanSeedMarkdownImpl({
       groups: plan.groups ?? [],
       findings: plan.findings ?? [],
       sourceReports: plan.sourceReports ?? [],
     });
-    persistImpl(md, values.out);
-    return;
-  }
+  };
 
-  if (values['emit-stories']) {
+  const emittedStories = () => {
     const plan = loadPlanImpl(values.plan);
     const eligible = (plan.classifications ?? [])
       .filter((c) => c.action === 'create')
       .map((c) => c.group);
     const built = buildAndGateStoriesImpl(eligible, plan.edges ?? []);
-    const out = values.json
-      ? JSON.stringify(built, null, 2)
-      : built
-          .map(
-            (s, i) =>
-              `--- story ${i + 1} ---\nTitle: ${s.title}\nLabels: ${s.labels.join(', ')}\n\n${s.body}\n`,
-          )
-          .join('\n');
-    persistImpl(out, values.out);
-    if (!values.out) stdout.write('\n');
-    return;
+    return values.json ? json(built) : renderStoryDrafts(built);
+  };
+
+  const wiredEdges = () =>
+    wireEdgesImpl({
+      plan: loadPlanImpl(values.plan),
+      issueByGroupKey: parseIssueMapImpl(values.ids),
+    });
+
+  // One table, not a chain of `if (values.X) { …; return; }`. Each entry
+  // renders its sub-command's output; persisting it — and the stdout newline a
+  // piped run needs — happens once, below. The chain restated that tail in
+  // every arm, so each new sub-command paid for it twice: once in the branch
+  // and once in the complexity budget.
+  const subcommands = [
+    ['auto', async () => json(await runAutoSummary()), true],
+    ['scan', async () => json(await scanPlan()), true],
+    ['emit-plan-seed', () => seedMarkdown(), false],
+    ['emit-stories', () => emittedStories(), true],
+    ['wire-edges', async () => json(await wiredEdges()), true],
+  ];
+
+  const entry = subcommands.find(([flag]) => values[flag]);
+  if (!entry) {
+    throw new Error(
+      'Usage: node audit-to-stories.js (--scan | --emit-plan-seed | --emit-stories | --wire-edges) [options]',
+    );
   }
+  const [, render, newlineOnStdout] = entry;
+  persistImpl(await render(), values.out);
+  if (newlineOnStdout && !values.out) stdout.write('\n');
+}
 
-  throw new Error(
-    'Usage: node audit-to-stories.js (--scan | --emit-plan-seed | --emit-stories) [options]',
-  );
+/**
+ * Render the Story drafts as the human-readable `--emit-stories` transcript
+ * (the `--json` form is the machine one). `dependsOn` is surfaced because the
+ * group edges no longer ride the body at emit time — the blockers have no issue
+ * numbers yet — so this is where a human driving the create pass by hand sees
+ * the ordering they will replay through `--wire-edges` (Story #5044).
+ *
+ * @param {Array<{ title: string, labels: string[], body: string, groupKey?: string, dependsOn?: string[] }>} built
+ * @returns {string}
+ */
+function renderStoryDrafts(built) {
+  return built
+    .map((s, i) => {
+      const deps = (s.dependsOn ?? []).length
+        ? `\nDepends on group(s): ${s.dependsOn.join(', ')}`
+        : '';
+      return `--- story ${i + 1} ---\nTitle: ${s.title}\nLabels: ${s.labels.join(', ')}\nGroup key: ${s.groupKey}${deps}\n\n${s.body}\n`;
+    })
+    .join('\n');
 }
 
 async function main() {
@@ -727,7 +838,7 @@ runAsCli(import.meta.url, main, {
   source: 'audit-to-stories',
   usage: {
     invocation:
-      'node .agents/scripts/audit-to-stories.js (--scan | --auto | --emit-plan-seed | --emit-stories) [options]',
+      'node .agents/scripts/audit-to-stories.js (--scan | --auto | --emit-plan-seed | --emit-stories | --wire-edges) [options]',
     summary:
       'Turn audit-lens findings under temp/audits/ into a dedup-checked plan seed or standalone Stories.',
     flags: [
@@ -735,6 +846,14 @@ runAsCli(import.meta.url, main, {
       ['--auto', 'Run the full scan → file pipeline and print the summary.'],
       ['--emit-plan-seed', 'Emit a /plan --seed-file document.'],
       ['--emit-stories', 'Emit the Story drafts as JSON.'],
+      [
+        '--wire-edges',
+        'Second pass: resolve the detected group edges to blocked by #N footers plus native blocked_by relations. Needs --plan and --ids.',
+      ],
+      [
+        '--ids <json|path>',
+        'Group key → opened issue number, as JSON or a path to a JSON file. Required by --wire-edges.',
+      ],
       ['--glob <pattern>', 'Override the audit-results glob.'],
       ['--severity <level>', 'Lowest severity to include (high|medium|low).'],
       ['--ledger <path>', 'Path to the dedup ledger.'],