mandrel 2.16.0 → 2.18.0

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

@@ -128,6 +128,16 @@
     "docsFreshness": {
       "paths": ["README.md"]
     },
+    "tempRetention": {
+      "enabled": true,
+      "staleDays": 7,
+      "classes": {
+        "orchestrationLogs": true,
+        "validationEvidence": true,
+        "auditResults": true,
+        "planDirs": true
+      }
+    },
     "deliverRunner": {
       "concurrencyCap": 3
     },

package/.agents/docs/configuration.md

@@ -125,6 +125,14 @@ top-level keys are validation errors.
 | `lease.ttlMs` | No | `integer` | — | — |
 | `docsFreshness` | No | `object` | — | Nested configuration block. |
 | `docsFreshness.paths` | No | `array` | — | — |
+| `tempRetention` | No | `object` | — | Story #4794. Auto-purge of spent temp artifacts once their Story lands. Classification is an allowlist: only the declared classes below are ever deleted, so operator scratch files under tempRoot are reported with their size and left alone. signals.ndjson is never purged by any path. |
+| `tempRetention.enabled` | No | `boolean` | — | Master switch. Default true — reclaiming a landed Story's gate transcripts and validation evidence is the behaviour, and this knob turns it off. When false every purge path is a reported no-op. |
+| `tempRetention.staleDays` | No | `integer` | — | Age floor (days, default 7) for the families no Story id can be recovered from — roster-level audit reports and abandoned plan-<slug>/ dirs. Story-keyed artifacts do not wait for it: they are purged as soon as their merge is confirmed. |
+| `tempRetention.classes` | No | `object` | — | Per-class opt-out. Each defaults to true; set one false to keep that family while the rest are purged. |
+| `tempRetention.classes.orchestrationLogs` | No | `boolean` | — | <tempRoot>/orchestration/*.log — close gate transcripts and terse-result detail dumps. |
+| `tempRetention.classes.validationEvidence` | No | `boolean` | — | Per-Story validation-evidence.json, lifecycle.ndjson, and manifest.md under the standalone and per-run story trees. |
+| `tempRetention.classes.auditResults` | No | `boolean` | — | <tempRoot>/audits/ — audit lens reports. |
+| `tempRetention.classes.planDirs` | No | `boolean` | — | <tempRoot>/plan-<slug>/ — abandoned plan authoring dirs. Age-floored only; the current run is always excluded. |
 | `deliverRunner` | No | `object` | — | Nested configuration block. |
 | `deliverRunner.concurrencyCap` | No | `integer` | — | 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. |
 | `worktreeIsolation` | No | `object` | — | Nested configuration block. |
@@ -174,6 +182,7 @@ top-level keys are validation errors.
 | `quality.gates.crap.targetDirs` | No | `string[]` or `{ append?, prepend? }` | — | Directories whose JS sources the CRAP gate scores. Mandrel ships a `src/`-centric default; projects whose executable code lives elsewhere (e.g. this repo's `.agents/scripts/`) override here. The framework default is intentionally not auto-discovered, so an override is the explicit, auditable signal. |
 | `quality.gates.crap.newMethodCeiling` | No | `integer` | — | — |
 | `quality.gates.crap.requireCoverage` | No | `boolean` | — | — |
+| `quality.gates.crap.minMethodResolutionRate` | No | `number` | — | Fail-closed floor on the per-method coverage JOIN (Story #4775): the fraction of methods that must resolve a coverage entry, counted only over files that HAVE one, before `update-crap-baseline.js` will persist. A broken join is silent by construction — unresolved methods are simply absent — so the updater refuses rather than writing a thin baseline and logging it as success. Not enforced below 25 joinable methods, where a diff-scoped run's rate is noise. Default 0.75; a healthy repo resolves ~98%. |
 | `quality.gates.crap.friction` | No | `object` | — | Nested configuration block. |
 | `quality.gates.crap.friction.markerKey` | No | `string` | — | — |
 | `quality.gates.crap.refreshTag` | No | `string` | — | — |

package/.agents/docs/quality-gates.md

@@ -361,6 +361,143 @@ There is no CI guardrail rejecting unlabeled baseline edits; the convention is
 preserved so the operator can grep refresh commits in a PR diff, but
 self-policing is the operator's job during `/deliver`'s watch loop.
 
+### The per-method coverage join (Story #4775)
+
+CRAP is the only gate that joins two independently-produced artifacts: the
+per-method complexity escomplex derives from the source, and the per-function
+coverage istanbul derives from the test run. Everything below exists because
+that join is silent when it fails — an unresolved method is simply absent from
+the baseline, so a broken join looks exactly like a small repo.
+
+**One coordinate system.** For a TS/TSX source, escomplex parses the
+*transpiled* output and reports each method's `lineStart` in transpiled
+coordinates, while `coverage-final.json` is keyed against the *original*
+source. The scorer therefore asks `transpileIfNeeded` for a source map
+(`{ withLineMap: true }`, backed by Node's built-in `SourceMap` — no extra
+runtime dependency) and remaps each method start into original coordinates
+before the lookup. JavaScript is a passthrough: its coordinates already are
+original coordinates, so no map is computed and nothing changes. The
+maintainability path never requests a map, and the emitted code is
+byte-identical either way, so MI scores are unaffected.
+
+**Tolerant matching.** Remapping alone is insufficient: escomplex's method
+start and istanbul's `decl.start.line` disagree by a line when a decorator, a
+leading `export`, or a wrapped parameter list sits between them. The lookup is
+exact-line first (so every already-resolving row keeps its exact prior value),
+then innermost containment, then nearest declaration within ±1.
+
+**`requireCoverage: false` means score it.** A method with no coverage entry
+scores as 0% covered — `crap = c² + c`, the formula's own treatment of
+untested code — and lands in the baseline. It used to be dropped individually
+regardless of the flag, which made the flag a no-op for baseline population.
+`requireCoverage: true` still skips and counts it.
+
+**The updater fails closed on a thin result.** `update-crap-baseline.js`
+reports `resolved/joinable` over files that *have* coverage and refuses to
+persist below `delivery.quality.gates.crap.minMethodResolutionRate` (default
+`0.75`), naming the worst unresolved files. The floor is not enforced below 25
+joinable methods, where a diff-scoped run's rate is noise. A healthy repo
+resolves ~98%; the 4–6% signature of a coordinate-system mismatch is far below
+the floor.
+
+**Re-derive your floors after adopting this — but do not re-pin `max`.** A
+`crap.floors` `max` ceiling pinned before the fix was computed over the
+minority of methods the join could see, so it is not a real ceiling — it is an
+artefact. The honest scan sees far more (in this repository, 2215 → 4058
+visible methods), and the newly-visible methods include the worst ones.
+
+The tempting response — raise `*.max` until the gate is green again — produces a
+floor fitted to the tree's current high-water mark, which **can never fire**:
+nothing breaches it until something becomes worse than the worst method already
+present. Prefer a *count* budget over a max ceiling:
+
+```jsonc
+"crap": {
+  // Number of methods allowed to score above 20. Ratchet this down; it
+  // breaches the moment the count grows, which a `max` ceiling cannot do.
+  "floors": { "*": { "methodsAbove20": 40 } }
+}
+```
+
+`max` remains available and is the right instrument when you genuinely have a
+hard per-method ceiling to hold. It is the wrong instrument for absorbing
+pre-existing debt.
+
+Note that neither choice is what protects new code. `floors` is an absolute
+tree-wide comparison against the rollup; the forward pressure lives in
+`newMethodCeiling` (a *new* method scoring above it fails, default 30) and in
+`compareCrap`'s ratchet (an *existing* method fails when it regresses against
+its own baseline row). Both are unaffected by how much old debt the gate can
+now see, and neither consults `floors`.
+
+**Old baselines are invalidated explicitly.** Rows scored by the previous join
+are not comparable to rows scored by this one, and neither `kernelVersion` nor
+`escomplexVersion` moves (both track the same upstream package). The envelope
+therefore carries a `scoringSemantics` stamp; `check-baselines` fails closed on
+a mismatch with the exact re-baseline command rather than comparing across the
+boundary. Bump the stamp whenever the coverage join, the line coordinate
+system, or the unresolved-method policy changes.
+
+---
+
+## Keeping a baseline fresh (Story #4776)
+
+Populating a baseline correctly is only half the loop. The other half is
+keeping it correct as the tree grows, and that half has two distinct holes —
+one at close time, one over the long run. Both are **advisory**:
+`check-baselines` already fails closed on a real regression, and duplicating
+that would double-gate the same defect.
+
+### Pre-merge projections — the refresh nudge at close time
+
+Close-validation projects, after its gates pass, which committed baseline rows
+the post-merge tree would breach, and names the exact remedy while the operator
+still has the branch in hand:
+
+- `lib/close-validation/projections/maintainability.js` — per-file MI.
+- `lib/close-validation/projections/crap.js` — per-method CRAP, against each
+  method's baseline row or, for methods with no row, `newMethodCeiling`.
+
+Both are wired through `projections/advisories.js`, which
+`close-validation/runner.js` calls once. Each self-skips — logging the reason,
+never erroring — when its gate is disabled, when no baseline exists, when the
+diff has no scorable files, or when the CRAP scorer finds no coverage
+artifact. A projected breach never changes the close verdict.
+
+> The maintainability projection shipped in v1 fully written and fully
+> unit-tested, and the v2 Epic-tier collapse removed its only caller. It sat
+> importable-but-unimported for the whole of v2, so its advisory never fired
+> once. `tests/lib/close-validation/runner-projections.test.js` now walks the
+> import graph and fails if **any** module under `projections/` is reachable
+> from nothing in production — the orphaning itself is the regression.
+
+### `check-baseline-drift.js` — the scheduled full-scope re-score
+
+Every per-PR enforcement site (close-validation, pre-push, CI) is
+**diff-scoped**: it compares the files a branch touched against their baseline
+rows. A file nobody touches after its row is written is therefore never
+re-scored, so drift introduced *indirectly* — a dependency getting more
+complex, coverage moving underneath a method — stays invisible indefinitely.
+Full-scope scoring on every push is far too expensive to be the answer.
+
+```bash
+node .agents/scripts/check-baseline-drift.js                     # both kinds
+node .agents/scripts/check-baseline-drift.js --gate crap         # one kind
+node .agents/scripts/check-baseline-drift.js --tolerance 1 --json
+```
+
+It re-scores full-scope through the *same* scorer that writes the baseline
+(`refresh-service.resolveDefaultScorer`) — scoring by a second implementation
+would report the two implementations' disagreement as drift — and prints a
+per-row before/after table for everything that moved beyond the gate's
+tolerance, **in either direction**. A row that silently improved is equally
+strong evidence the baseline no longer describes the tree.
+
+Exit codes: `0` no drift (or every kind skipped), `1` drift detected, `2` the
+check could not run. It is designed to be wired as a scheduled CI job;
+scheduling it is deliberately consumer-side work, and nothing in this
+repository runs it automatically.
+
 ---
 
 ## Bundle-size ratchet — one-shot refresh/acknowledge (Story #151)

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

@@ -441,6 +441,45 @@
       },
       "additionalProperties": false
     },
+    "tempRetention": {
+      "type": "object",
+      "description": "Story #4794. Auto-purge of spent temp artifacts once their Story lands. Classification is an allowlist: only the declared classes below are ever deleted, so operator scratch files under tempRoot are reported with their size and left alone. signals.ndjson is never purged by any path.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Master switch. Default true — reclaiming a landed Story's gate transcripts and validation evidence is the behaviour, and this knob turns it off. When false every purge path is a reported no-op."
+        },
+        "staleDays": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Age floor (days, default 7) for the families no Story id can be recovered from — roster-level audit reports and abandoned plan-<slug>/ dirs. Story-keyed artifacts do not wait for it: they are purged as soon as their merge is confirmed."
+        },
+        "classes": {
+          "type": "object",
+          "description": "Per-class opt-out. Each defaults to true; set one false to keep that family while the rest are purged.",
+          "properties": {
+            "orchestrationLogs": {
+              "type": "boolean",
+              "description": "<tempRoot>/orchestration/*.log — close gate transcripts and terse-result detail dumps."
+            },
+            "validationEvidence": {
+              "type": "boolean",
+              "description": "Per-Story validation-evidence.json, lifecycle.ndjson, and manifest.md under the standalone and per-run story trees."
+            },
+            "auditResults": {
+              "type": "boolean",
+              "description": "<tempRoot>/audits/ — audit lens reports."
+            },
+            "planDirs": {
+              "type": "boolean",
+              "description": "<tempRoot>/plan-<slug>/ — abandoned plan authoring dirs. Age-floored only; the current run is always excluded."
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
     "docsFreshness": {
       "type": "object",
       "properties": {
@@ -774,6 +813,12 @@
         "requireCoverage": {
           "type": "boolean"
         },
+        "minMethodResolutionRate": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Fail-closed floor on the per-method coverage JOIN (Story #4775): the fraction of methods that must resolve a coverage entry, counted only over files that HAVE one, before `update-crap-baseline.js` will persist. A broken join is silent by construction — unresolved methods are simply absent — so the updater refuses rather than writing a thin baseline and logging it as success. Not enforced below 25 joinable methods, where a diff-scoped run's rate is noise. Default 0.75; a healthy repo resolves ~98%."
+        },
         "friction": {
           "type": "object",
           "properties": {
@@ -1318,6 +1363,9 @@
         "docsFreshness": {
           "$ref": "#/$defs/docsFreshness"
         },
+        "tempRetention": {
+          "$ref": "#/$defs/tempRetention"
+        },
         "deliverRunner": {
           "$ref": "#/$defs/deliverRunner"
         },

package/.agents/schemas/baselines/baseline-envelope.schema.json

@@ -21,6 +21,10 @@
       "format": "date-time",
       "description": "ISO-8601 timestamp of the baseline run. Used for stale-baseline detection and audit trails."
     },
+    "scoringSemantics": {
+      "type": "string",
+      "description": "Optional per-kind stamp identifying the SCORING SEMANTICS that produced these rows — the dimension kernelVersion cannot express, because a kind's own scoring can change while the upstream package it stamps does not. A baseline whose stamp differs from the running scorer's is incomparable and the gate fails closed with re-baseline guidance rather than comparing across the boundary."
+    },
     "rollup": {
       "type": "object",
       "description": "Aggregate metrics keyed by component. The '*' key is reserved for the whole-repo rollup and is REQUIRED; additional keys MAY be present, one per declared component.",

package/.agents/schemas/baselines/crap.schema.json

@@ -6,6 +6,10 @@
   "allOf": [{ "$ref": "baseline-envelope.schema.json" }],
   "type": "object",
   "properties": {
+    "scoringSemantics": {
+      "type": "string",
+      "description": "Identifier for the per-method coverage-join semantics that produced these rows (Story #4775). Deliberately NOT constrained to the current value here: an old-semantics baseline must reach the gate's compat axis, which fails it closed with an explicit re-baseline command, rather than being rejected with a raw schema error."
+    },
     "rollup": {
       "type": "object",
       "required": ["*"],

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

@@ -86,13 +86,18 @@
         "followUps",
         "statusResync",
         "refCleanup",
-        "baseFastForward"
+        "baseFastForward",
+        "tempPurge"
       ],
       "properties": {
         "followUps": { "type": "boolean" },
         "statusResync": { "type": "boolean" },
         "refCleanup": { "type": "boolean" },
         "baseFastForward": { "type": "boolean" },
+        "tempPurge": {
+          "type": "boolean",
+          "description": "Story #4794 — the merged Story's spent temp artifacts (gate transcripts, validation evidence) were purged under delivery.tempRetention. A disabled policy reports true: the operator turned the purge off, so doing nothing IS the correct outcome. Only a real failure — an unreadable temp root, an undeletable artifact — reports false, and like every tail step that degrades the report, never the land."
+        },
         "details": {
           "type": "object",
           "description": "Per-step diagnostic detail — the reason a false step reported false.",

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

@@ -82,10 +82,14 @@ const VERDICT_SCHEMA_PATH = path.resolve(
   'acceptance-eval-verdict.schema.json',
 );
 
-let cachedValidator = null;
-
 /**
- * Compile (and cache) the Ajv2020 validator for the verdict schema.
+ * Compile the Ajv2020 validator for the verdict schema.
+ *
+ * Deliberately **not** memoised in a module-level variable: a module-level
+ * cache is reset only on re-import, so it silently defeats the `io` seam below
+ * (the second caller's injected reader is never consulted) and makes parallel
+ * test isolation impossible — `.agents/rules/test-seams.md` rule 3. The gate
+ * compiles the schema once per CLI run, so there is nothing to memoise.
  *
  * @param {string} [schemaPath]
  * @param {{ readFileSync: typeof readFileSync }} [io]
@@ -95,12 +99,10 @@ function getVerdictValidator(
   schemaPath = VERDICT_SCHEMA_PATH,
   io = { readFileSync },
 ) {
-  if (cachedValidator) return cachedValidator;
   const ajv = new Ajv2020({ allErrors: true, strict: false });
   addFormats(ajv);
   const schema = JSON.parse(io.readFileSync(schemaPath, 'utf8'));
-  cachedValidator = ajv.compile(schema);
-  return cachedValidator;
+  return ajv.compile(schema);
 }
 
 /**
@@ -235,7 +237,37 @@ export async function runAcceptanceEval(
   return { envelope, exitCode };
 }
 
-export async function main(argv = process.argv.slice(2)) {
+/**
+ * The gate's CLI core: argv → verdict read → schema validation → decision →
+ * envelope. Extracted from the `main` shell so the whole error table (missing
+ * flags, unreadable verdict, non-JSON verdict, storyId mismatch, block) is
+ * reachable without spawning the CLI or writing a real verdict file.
+ *
+ * Every seam on the optional final `deps` parameter defaults to the real
+ * implementation (`.agents/rules/test-seams.md` rules 1-2, 4), so `main` and
+ * every production invocation are unchanged.
+ *
+ * @param {string[]} [argv]
+ * @param {{
+ *   readFileSyncImpl?: typeof readFileSync,
+ *   resolveConfigImpl?: typeof resolveConfig,
+ *   validateVerdictImpl?: typeof validateVerdict,
+ *   runAcceptanceEvalImpl?: typeof runAcceptanceEval,
+ *   logger?: { info: Function },
+ * }} [deps]
+ * @returns {Promise<object>} the emitted envelope.
+ */
+export async function runAcceptanceEvalCli(
+  argv = process.argv.slice(2),
+  deps = {},
+) {
+  const {
+    readFileSyncImpl = readFileSync,
+    resolveConfigImpl = resolveConfig,
+    validateVerdictImpl = validateVerdict,
+    runAcceptanceEvalImpl = runAcceptanceEval,
+    logger = Logger,
+  } = deps;
   const { storyId, verdictPath, emitSignal } = parseCliArgs(argv);
 
   if (!storyId) {
@@ -249,7 +281,7 @@ export async function main(argv = process.argv.slice(2)) {
 
   let raw;
   try {
-    raw = readFileSync(path.resolve(verdictPath), 'utf8');
+    raw = readFileSyncImpl(path.resolve(verdictPath), 'utf8');
   } catch (err) {
     throw new Error(
       `acceptance-eval: cannot read verdict file at ${verdictPath}: ${
@@ -269,7 +301,7 @@ export async function main(argv = process.argv.slice(2)) {
     );
   }
 
-  const verdict = validateVerdict(parsed);
+  const verdict = validateVerdictImpl(parsed);
 
   // A verdict whose embedded storyId disagrees with the CLI flag is a
   // wiring error worth failing on, not a silent mismatch.
@@ -279,15 +311,15 @@ export async function main(argv = process.argv.slice(2)) {
     );
   }
 
-  const config = resolveConfig();
-  const { envelope, exitCode } = await runAcceptanceEval({
+  const config = resolveConfigImpl();
+  const { envelope, exitCode } = await runAcceptanceEvalImpl({
     storyId,
     verdict,
     config,
     emitSignal,
   });
 
-  Logger.info(JSON.stringify(envelope));
+  logger.info(JSON.stringify(envelope));
 
   if (exitCode !== 0) {
     const names = envelope.unmetCriteria
@@ -302,6 +334,14 @@ export async function main(argv = process.argv.slice(2)) {
   return envelope;
 }
 
+/**
+ * @param {string[]} [argv]
+ * @returns {Promise<object>}
+ */
+export async function main(argv = process.argv.slice(2)) {
+  return runAcceptanceEvalCli(argv);
+}
+
 runAsCli(import.meta.url, main, {
   source: 'acceptance-eval',
   usage: {

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

@@ -224,8 +224,38 @@ function dedupDegradedWarning(entries) {
   );
 }
 
-async function buildPlan({ glob: pattern, severity, useProvider, ledger }) {
-  const reportPaths = await collectReportPaths(pattern ?? DEFAULT_GLOB);
+/**
+ * Scan → group → dedup → (optionally) reconcile the cross-run ledger, and
+ * return the plan envelope.
+ *
+ * Every seam on the optional final `deps` parameter defaults to the real
+ * implementation (`.agents/rules/test-seams.md` rules 1-2, 4), so `main`,
+ * `runAuto`, and every production caller are unchanged.
+ *
+ * @param {{ glob?: string, severity?: string, useProvider?: boolean, ledger?: object }} params
+ * @param {{
+ *   collectReportPathsImpl?: typeof collectReportPaths,
+ *   readReportsImpl?: typeof readReports,
+ *   loadProviderImpl?: typeof loadProvider,
+ *   classifyGroupsImpl?: typeof classifyGroupsAgainstGitHub,
+ *   reconcileScanLedgerImpl?: typeof reconcileScanLedger,
+ *   logger?: { warn: Function },
+ * }} [deps]
+ * @returns {Promise<object>} the plan envelope.
+ */
+async function buildPlan(
+  { glob: pattern, severity, useProvider, ledger },
+  deps = {},
+) {
+  const {
+    collectReportPathsImpl = collectReportPaths,
+    readReportsImpl = readReports,
+    loadProviderImpl = loadProvider,
+    classifyGroupsImpl = classifyGroupsAgainstGitHub,
+    reconcileScanLedgerImpl = reconcileScanLedger,
+    logger = Logger,
+  } = deps;
+  const reportPaths = await collectReportPathsImpl(pattern ?? DEFAULT_GLOB);
   if (reportPaths.length === 0) {
     return {
       generatedAt: new Date().toISOString(),
@@ -245,8 +275,8 @@ async function buildPlan({ glob: pattern, severity, useProvider, ledger }) {
     };
   }
 
-  const reports = readReports(reportPaths);
-  const allFindings = parseAuditReports(reports);
+  const reports = readReportsImpl(reportPaths);
+  const allFindings = parseAuditReports(reports, { repoRoot: process.cwd() });
   const filtered = allFindings.filter((f) => meetsSeverity(f, severity));
   const stamped = withFingerprints(filtered);
   const { groups, edges } = groupFindings(stamped);
@@ -261,9 +291,9 @@ async function buildPlan({ glob: pattern, severity, useProvider, ledger }) {
   let dedupApplied = false;
 
   if (useProvider) {
-    const provider = await loadProvider();
+    const provider = await loadProviderImpl();
     if (provider) {
-      const result = await classifyGroupsAgainstGitHub({
+      const result = await classifyGroupsImpl({
         groups,
         provider,
         searchCandidates: provider.searchCandidates,
@@ -275,19 +305,19 @@ async function buildPlan({ glob: pattern, severity, useProvider, ledger }) {
       // the --scan JSON on stdout stays clean) naming the groups that degraded
       // to create because their lookup could not complete (Story #4678).
       if (summary.dedupDegraded?.count > 0) {
-        Logger.warn(dedupDegradedWarning(summary.dedupDegraded.groups));
+        logger.warn(dedupDegradedWarning(summary.dedupDegraded.groups));
       }
     } else {
       // The provider could not resolve a searchIssues port — the dedup gate
       // is silently a no-op without this. Surface it loudly (stderr, so the
       // --scan JSON on stdout stays clean) so the operator does not read a
       // create-only plan as "no duplicates found".
-      Logger.warn(dedupSkippedWarning('no-provider-port'));
+      logger.warn(dedupSkippedWarning('no-provider-port'));
     }
   } else {
     // Operator explicitly opted out via --no-provider. Still warn so a
     // duplicate-opening re-run is never a surprise.
-    Logger.warn(dedupSkippedWarning('disabled'));
+    logger.warn(dedupSkippedWarning('disabled'));
   }
 
   // Cross-run ledger (Story #4626): fold this scan onto the committed memory,
@@ -296,7 +326,7 @@ async function buildPlan({ glob: pattern, severity, useProvider, ledger }) {
   // --scan path leaves it untouched so it never mutates a committed file.
   let ledgerSummary;
   if (ledger) {
-    const suppressed = reconcileScanLedger({
+    const suppressed = reconcileScanLedgerImpl({
       ledgerPath: ledger.path ?? DEFAULT_LEDGER_PATH,
       findings: stamped,
       classifications,
@@ -546,9 +576,42 @@ export const __testing = {
   issueStatesFromClassifications,
 };
 
-async function main() {
+/**
+ * The CLI core: dispatch one of the four sub-commands and persist its output.
+ * Extracted from the `main` shell so the whole sub-command table (including
+ * the no-sub-command usage throw) is reachable without spawning the CLI.
+ *
+ * Every seam on the optional final `deps` parameter defaults to the real
+ * implementation (`.agents/rules/test-seams.md` rules 1-2, 4), so `main` and
+ * every production invocation are unchanged.
+ *
+ * @param {string[]} [argv]
+ * @param {{
+ *   buildPlanImpl?: typeof buildPlan,
+ *   runAutoImpl?: typeof runAuto,
+ *   loadPlanImpl?: typeof loadPlan,
+ *   buildAndGateStoriesImpl?: typeof buildAndGateStories,
+ *   buildPlanSeedMarkdownImpl?: typeof buildPlanSeedMarkdown,
+ *   persistImpl?: typeof persist,
+ *   stdout?: { write: (s: string) => void },
+ * }} [deps]
+ * @returns {Promise<void>}
+ */
+export async function runAuditToStories(
+  argv = process.argv.slice(2),
+  deps = {},
+) {
+  const {
+    buildPlanImpl = buildPlan,
+    runAutoImpl = runAuto,
+    loadPlanImpl = loadPlan,
+    buildAndGateStoriesImpl = buildAndGateStories,
+    buildPlanSeedMarkdownImpl = buildPlanSeedMarkdown,
+    persistImpl = persist,
+    stdout = process.stdout,
+  } = deps;
   const { values } = parseArgs({
-    args: process.argv.slice(2),
+    args: argv,
     options: {
       scan: { type: 'boolean' },
       auto: { type: 'boolean' },
@@ -567,47 +630,47 @@ async function main() {
   });
 
   if (values.auto) {
-    const { summary } = await runAuto({
+    const { summary } = await runAutoImpl({
       glob: values.glob,
       severity: values.severity,
       dryRun: values['dry-run'],
       useProvider: !values['no-provider'],
       ledgerPath: values.ledger,
     });
-    persist(JSON.stringify(summary, null, 2), values.out);
-    if (!values.out) process.stdout.write('\n');
+    persistImpl(JSON.stringify(summary, null, 2), values.out);
+    if (!values.out) stdout.write('\n');
     return;
   }
 
   if (values.scan) {
-    const plan = await buildPlan({
+    const plan = await buildPlanImpl({
       glob: values.glob,
       severity: values.severity,
       useProvider: !values['no-provider'],
     });
     const out = JSON.stringify(plan, null, 2);
-    persist(out, values.out);
-    if (!values.out) process.stdout.write('\n');
+    persistImpl(out, values.out);
+    if (!values.out) stdout.write('\n');
     return;
   }
 
   if (values['emit-plan-seed']) {
-    const plan = loadPlan(values.plan);
-    const md = buildPlanSeedMarkdown({
+    const plan = loadPlanImpl(values.plan);
+    const md = buildPlanSeedMarkdownImpl({
       groups: plan.groups ?? [],
       findings: plan.findings ?? [],
       sourceReports: plan.sourceReports ?? [],
     });
-    persist(md, values.out);
+    persistImpl(md, values.out);
     return;
   }
 
   if (values['emit-stories']) {
-    const plan = loadPlan(values.plan);
+    const plan = loadPlanImpl(values.plan);
     const eligible = (plan.classifications ?? [])
       .filter((c) => c.action === 'create')
       .map((c) => c.group);
-    const built = buildAndGateStories(eligible, plan.edges ?? []);
+    const built = buildAndGateStoriesImpl(eligible, plan.edges ?? []);
     const out = values.json
       ? JSON.stringify(built, null, 2)
       : built
@@ -616,8 +679,8 @@ async function main() {
               `--- story ${i + 1} ---\nTitle: ${s.title}\nLabels: ${s.labels.join(', ')}\n\n${s.body}\n`,
           )
           .join('\n');
-    persist(out, values.out);
-    if (!values.out) process.stdout.write('\n');
+    persistImpl(out, values.out);
+    if (!values.out) stdout.write('\n');
     return;
   }
 
@@ -626,6 +689,10 @@ async function main() {
   );
 }
 
+async function main() {
+  await runAuditToStories();
+}
+
 runAsCli(import.meta.url, main, {
   source: 'audit-to-stories',
   usage: {