mandrel 2.32.0 → 2.33.0

package/.agents/docs/SDLC.md

@@ -44,14 +44,17 @@ From zero to shipped:
    resolves their dependency graph from live state — body edges union native
    GitHub `blocked_by` edges, every blocker checked against its real issue
    state, so a Story whose blocker landed in an earlier plan run is simply
-   ready. `/deliver` owns input resolution and `depends_on` sequencing only;
+   ready. `/deliver` owns input resolution and dispatch order — the declared
+   `depends_on` edges plus a delivery-time file-overlap guard that withholds
+   two Stories whose footprints would race the same path (see
+   [`architecture.md` § Scheduler safety mechanics](../../docs/architecture.md));
    every Story runs through the single v2 delivery engine
    [`helpers/deliver-story`](../workflows/helpers/deliver-story.md) —
    init → implement → acceptance self-eval → ceremony → close → CI watch →
    confirm-merge — which owns its own per-step detail. For a multi-Story run,
-   `/deliver` sequences ready Stories by `depends_on` and runs the per-run
-   epilogue (audit roster · follow-up roll-up · sibling coherence) once after
-   the last Story lands.
+   `/deliver` sequences ready Stories by `depends_on` — plus that footprint
+   guard — and runs the per-run epilogue (audit roster · follow-up roll-up ·
+   sibling coherence) once after the last Story lands.
 
 That is the whole happy path. Everything below is **detail** — branching
 conventions, HITL escalation, audit lenses — that you only need when the
@@ -239,7 +242,7 @@ self-eval, ceremony, close, CI watch, confirm-merge, cleanup) lives in the
 | Mode | Entry point | When to use |
 | --- | --- | --- |
 | **Single Story** | `/deliver <storyId>` | Deliver one Story end-to-end; ends with a PR open to `main`. |
-| **Story set** | `/deliver <storyId> [<storyId>…]` | Deliver multiple Stories in `depends_on` order (default concurrency **3**), resolved from live state so edges may point at Stories from earlier plan runs; each lands through its own PR, and the per-run epilogue runs after the set lands. |
+| **Story set** | `/deliver <storyId> [<storyId>…]` | Deliver multiple Stories in `depends_on` order (default concurrency **3**), resolved from live state so edges may point at Stories from earlier plan runs; a delivery-time file-overlap guard additionally withholds two Stories whose footprints would race the same path (`delivery.deliverRunner.footprintGuard`). Each lands through its own PR, and the per-run epilogue runs after the set lands. |
 | **Story worker (internal)** | *helper* `helpers/deliver-story <storyId>` | Per-Story engine invoked internally by `/deliver`; not an operator slash command. |
 
 The single operator-facing entry point is `/deliver`. It performs no

package/.agents/docs/agentrc-reference.json

@@ -105,7 +105,8 @@
       }
     },
     "deliverRunner": {
-      "concurrencyCap": 3
+      "concurrencyCap": 3,
+      "footprintGuard": "enforce"
     },
     "worktreeIsolation": {
       "enabled": true,

package/.agents/docs/configuration.md

@@ -156,6 +156,7 @@ Everything `/deliver` and `single-story-close` consume: execution timeouts, work
 | `tempRetention.classes.planDirs` | No | `boolean` | `true` | <tempRoot>/plan-<slug>/ — abandoned plan authoring dirs. Age-floored only; the current run is always excluded. |
 | `deliverRunner` | No | `object` | — | Bounded-concurrency knob for the /deliver fan-out. |
 | `deliverRunner.concurrencyCap` | No | `integer` | `3` | Maximum ready Stories dispatched by /deliver at once. Default 3. Moderate by design — keeps host-quota consumption predictable while allowing a small ready-set fan-out. Set 1 for strictly sequential delivery; raise further on hosts with adequate parallel-agent quota. See deliver.md for the sequencing model and throughput tradeoff. |
+| `deliverRunner.footprintGuard` | No | `"enforce"` \| `"advisory"` | `"enforce"` | How a file-footprint collision affects dispatch. 'enforce' (default, and the behaviour to keep unless you have a reason) withholds a Story whose footprint races a peer admitted this beat or one still in flight — the guard encodes delivery-time-only knowledge (open implementation windows, foreign leases, ground that moved since planning) that no depends_on edge can carry. 'advisory' still DETECTS every collision and reports each would-be withhold in the tick envelope, but lets dispatch follow the declared depends_on edges alone — a deliberate throughput trade for a run whose ordering is fully declared. See stories-wave-tick.js and helpers/deliver-reference.md. |
 | `worktreeIsolation` | No | `object` | — | Per-Story git worktree provisioning. Each Story is implemented in its own checkout so concurrent siblings never share a working tree. |
 | `worktreeIsolation.enabled` | No | `boolean` | `true` | When true, `single-story-init.js` materializes a worktree per Story. False implements every Story in the main checkout, which is only safe for strictly serial delivery. |
 | `worktreeIsolation.root` | No | `string` | `".worktrees"` | Repo-relative directory the per-Story worktrees are created under. Required whenever `enabled` is explicitly true. |

package/.agents/runtime-deps.json

@@ -3,7 +3,7 @@
   "dependencies": {
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^4.3.1",
     "minimatch": "^10.0.0",
     "picomatch": "^4.0.4",
     "typhonjs-escomplex": "^0.1.0"
@@ -12,6 +12,7 @@
     "@commitlint/load": "^21.0.0",
     "chokidar": "^5.0.0",
     "jscpd": "^4.0.0",
+    "knip": "^6.17.1",
     "typescript": ">=5.0.0"
   }
 }

package/.agents/schemas/agentrc.schema.json

@@ -528,6 +528,12 @@
               "minimum": 1,
               "description": "Maximum ready Stories dispatched by /deliver at once. Default 3. Moderate by design — keeps host-quota consumption predictable while allowing a small ready-set fan-out. Set 1 for strictly sequential delivery; raise further on hosts with adequate parallel-agent quota. See deliver.md for the sequencing model and throughput tradeoff.",
               "default": 3
+            },
+            "footprintGuard": {
+              "type": "string",
+              "enum": ["enforce", "advisory"],
+              "description": "How a file-footprint collision affects dispatch. 'enforce' (default, and the behaviour to keep unless you have a reason) withholds a Story whose footprint races a peer admitted this beat or one still in flight — the guard encodes delivery-time-only knowledge (open implementation windows, foreign leases, ground that moved since planning) that no depends_on edge can carry. 'advisory' still DETECTS every collision and reports each would-be withhold in the tick envelope, but lets dispatch follow the declared depends_on edges alone — a deliberate throughput trade for a run whose ordering is fully declared. See stories-wave-tick.js and helpers/deliver-reference.md.",
+              "default": "enforce"
             }
           },
           "additionalProperties": false

package/.agents/scripts/README.md

@@ -13,6 +13,15 @@ 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
 
 - [`/.agents/README.md`](../README.md) — consumer user guide.

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.'],

package/.agents/scripts/check-knip-entries.js

@@ -19,19 +19,29 @@
 // This gate removes the luck. It derives the invoked set from the executable
 // surfaces #5001's own acceptance criterion named — package.json scripts, husky
 // hooks, `.github/workflows`, `.agents` workflow/skill/agent/rule markdown, and
-// script-to-script spawns — and asserts it matches `knip.json`'s entry array in
-// both directions. See `lib/knip-entry-sync.js` for why liveness means
-// *invoked* rather than *present*, and why documentation prose does not count.
+// script-to-script spawns — and asserts it matches the entry array of whatever
+// configuration knip itself would load, in both directions. See
+// `lib/knip-entry-sync.js` for why liveness means *invoked* rather than
+// *present*, and why documentation prose does not count.
 //
-// Measurement-free by construction: no knip spawn, no scorer, no coverage
-// artifact. It is a directory read and a handful of regexes, which is what
-// makes it cheap enough to sit in the required-check set next to
-// `check-baseline-scope.js`.
+// Analysis-free by construction: knip's config resolver is loaded (a
+// `knip.config.ts` has to be evaluated, not parsed), but nothing is scanned —
+// no knip run, no scorer, no coverage artifact. Past that it is a directory
+// read and a handful of regexes, which is what keeps it cheap enough to sit in
+// the required-check set next to `check-baseline-scope.js`.
+//
+// Not-applicable is not failure (Story #5039). A repository with no knip
+// configuration at all — and one where `knip` is not installed — exits 0 with a
+// skip line, the same opt-in posture `qa.gherkinLint` uses. Without that, the
+// gate could not be wired into a consumer that does not run knip, and #5001's
+// guard stayed unbuilt everywhere it was most needed. A configuration that
+// EXISTS but cannot be resolved still exits 2: absence and breakage are
+// different answers.
 //
 // Exit codes:
-//   0  entry list matches the invoked set
-//   1  divergence — a missing, stale, or phantom entry
-//   2  the check could not run (unreadable knip.json, unusable repository)
+//   0  entry list matches the invoked set, or there is no configuration to check
+//   1  divergence — a missing, stale, phantom, or unsuffixed entry
+//   2  the check could not run (unresolvable configuration, unusable repository)
 
 import process from 'node:process';
 import { runAsCli } from './lib/cli-utils.js';
@@ -49,17 +59,35 @@ const HELP = {
   invocation:
     'node .agents/scripts/check-knip-entries.js [--cwd <dir>] [--json]',
   summary:
-    "Assert knip.json's explicit .agents/scripts entry list matches the set of CLIs something actually invokes.",
+    "Assert the explicit .agents/scripts entry list in knip's resolved configuration matches the set of CLIs something actually invokes.",
   flags: [
     ['--cwd <dir>', 'Repository root to check. Default: process.cwd().'],
     ['--json', 'Emit the report as JSON instead of text.'],
   ],
   notes: [
-    'Exit codes:\n  0  entry list matches\n  1  divergence\n  2  the check could not run',
+    'Resolves the config through knip itself, so every location knip supports works\n(knip.json/.jsonc, .knip.json(c), knip.ts/.js, knip.config.ts/.js,\npackage.json#knip). A TS config is evaluated, so a computed entry array reads\ncorrectly, and per-workspace entries count alongside the top-level array.',
+    'Exit codes:\n  0  entry list matches, or there is no config to check (skip)\n  1  divergence\n  2  the check could not run — a config that EXISTS but will not resolve',
     'A missing entry is the dangerous one: knip calls the CLI dead, and accepting\nthe dead-exports diff would record a live CLI as expected-dead (Story #5012).',
   ],
 };
 
+/**
+ * The gate's single exit-code decision, shared by the text and `--json` paths.
+ *
+ * Kept in one place for the same reason `countDivergences` is: a direction
+ * added to the report must not be able to change one path's verdict and not
+ * the other's. Skip outranks error outranks divergence — a repository with no
+ * configuration has nothing to diverge from.
+ *
+ * @param {Awaited<ReturnType<typeof resolveEntrySync>>} report
+ * @returns {number}
+ */
+function exitCodeFor(report) {
+  if (report.skipped) return EXIT_PASS;
+  if (report.error) return EXIT_CANNOT_RUN;
+  return countDivergences(report) > 0 ? EXIT_DIVERGED : EXIT_PASS;
+}
+
 /**
  * Parse argv into an options bag. An unknown flag is a config error rather than
  * a silent no-op, matching `check-baseline-scope.js`.
@@ -107,25 +135,20 @@ export async function runCli({
     stderr.write(`[knip-entries] ❌ ${err?.message ?? String(err)}\n`);
     return EXIT_CANNOT_RUN;
   }
-  const repoRoot = args.cwd ?? cwd;
-  const report = resolveEntrySync({ repoRoot });
+  const report = await resolveEntrySync({ repoRoot: args.cwd ?? cwd });
 
   if (args.json) {
     stdout.write(
       `${JSON.stringify({ kind: 'knip-entry-sync', ...report }, null, 2)}\n`,
     );
-    if (report.error) return EXIT_CANNOT_RUN;
-    return countDivergences(report) > 0 ? EXIT_DIVERGED : EXIT_PASS;
-  }
-
-  if (report.error) {
+  } else if (report.skipped) {
+    stdout.write(`[knip-entries] ⏭️  not applicable: ${report.skipped}\n`);
+  } else if (report.error) {
     stderr.write(`[knip-entries] ❌ ${report.error}\n`);
-    return EXIT_CANNOT_RUN;
+  } else {
+    stdout.write(`\n--- knip-entries ---\n${renderEntrySyncReport(report)}\n`);
   }
-
-  stdout.write(`\n--- knip-entries ---\n`);
-  stdout.write(`${renderEntrySyncReport(report)}\n`);
-  return countDivergences(report) > 0 ? EXIT_DIVERGED : EXIT_PASS;
+  return exitCodeFor(report);
 }
 
 runAsCli(import.meta.url, async () => runCli(), {

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

@@ -46,6 +46,23 @@
  *   The exempt path is matched by suffix so it bites even before the
  *   armer file lands (Wave 7); pre-existence is not required.
  *
+ * Scan root:
+ *   --root <dir>  Scan <dir> instead of this checkout. Both surfaces are
+ *                 derived from it, so one flag moves the whole scan.
+ *                 Defaults to the repository this script ships in, which is
+ *                 what `npm run lint` gets by passing nothing.
+ *
+ *   The seam exists for tests (Story #5052). The CLI test that proves a
+ *   violation is *caught* has to plant one, and it used to plant into the
+ *   live `.agents/` tree — which `tests/e2e/sync-prune.integration.test.js`
+ *   copies with the real binary, so the two raced: the sync either lost the
+ *   file between enumeration and `copyfile` (ENOENT) or copied it once and
+ *   pruned it on the second pass, tripping an idempotence assertion. Pointing
+ *   the planting test at a temp root keeps what that test was written for —
+ *   discovery is still the CLI's own walk, not an injected file list — while
+ *   leaving the shared tree untouched. Mirrors the `--root` seam
+ *   `check-test-temp-hygiene.js` already ships for the same reason.
+ *
  * Exit codes:
  *   0 — clean.
  *   1 — at least one violation; offending file + line printed to stderr.
@@ -65,15 +82,22 @@ import { walkFilesByExtension } from './lib/fs-walk.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
 
-const LIFECYCLE_DIR = path.join(
-  REPO_ROOT,
-  '.agents',
-  'scripts',
-  'lib',
-  'orchestration',
-  'lifecycle',
-);
-const SCRIPTS_DIR = path.join(REPO_ROOT, '.agents', 'scripts');
+/** Rule 1's scan surface for a given repository root. */
+function lifecycleDirFor(root) {
+  return path.join(
+    root,
+    '.agents',
+    'scripts',
+    'lib',
+    'orchestration',
+    'lifecycle',
+  );
+}
+
+/** Rule 3's scan surface for a given repository root. */
+function scriptsDirFor(root) {
+  return path.join(root, '.agents', 'scripts');
+}
 
 /**
  * Files exempt from the merge-lockout rule. The path is matched by
@@ -269,10 +293,31 @@ export function findMergeLockoutViolations(
   return violations;
 }
 
+/**
+ * Parse the argument vector. The only option is the scan root; anything
+ * else is ignored so an extra flag can never silently narrow the scan.
+ *
+ * @param {string[]} argv Arguments without the node/script entries.
+ * @returns {{ root: string }}
+ */
+function parseArgv(argv) {
+  let root = REPO_ROOT;
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--root') {
+      i += 1;
+      root = path.resolve(String(argv[i] ?? '.'));
+    }
+  }
+  return { root };
+}
+
 async function main() {
-  // Per-rule discovery.
-  const v1 = findPromiseAllViolations(LIFECYCLE_DIR);
-  const v3 = findMergeLockoutViolations(SCRIPTS_DIR);
+  const { root } = parseArgv(process.argv.slice(2));
+  // Per-rule discovery. Both rules' exemptions match by absolute-path
+  // SUFFIX, which is what lets an injected root keep the same allow-list
+  // semantics as the live tree — do not re-anchor them to `root`.
+  const v1 = findPromiseAllViolations(lifecycleDirFor(root));
+  const v3 = findMergeLockoutViolations(scriptsDirFor(root));
   const all = [
     ...v1.map((v) => ({ rule: 'no-promise-all-lifecycle', ...v })),
     ...v3.map((v) => ({ rule: 'merge-lockout', ...v })),
@@ -297,4 +342,19 @@ async function main() {
 await runAsCli(import.meta.url, main, {
   source: 'check-lifecycle-lint',
   propagateExitCode: true,
+  usage: {
+    invocation: 'node .agents/scripts/check-lifecycle-lint.js [--root <dir>]',
+    summary:
+      'Enforce the two lifecycle lint rules biome cannot express: no Promise.all on the append-only lifecycle surface, and the auto-merge lockout on string literals under .agents/scripts/.',
+    flags: [
+      [
+        '--root <dir>',
+        'Repository root to scan (default: the checkout this script ships in). Both rule surfaces derive from it; used by tests so a planted violation never touches the shared tree.',
+      ],
+    ],
+    notes: [
+      'Ships as part of `npm run lint`, which invokes it with no arguments.',
+      'Exit codes:\n  0  clean\n  1  at least one violation; offending file and line printed to stderr',
+    ],
+  },
 });