mandrel 2.24.0 → 2.26.0

package/.agents/scripts/providers/github/tickets.js

@@ -321,6 +321,16 @@ export class TicketGateway {
    * avoid a read-before-write. When other PATCH fields are present, or when
    * removing labels, computes the final label set and returns it to the
    * caller for inclusion in the PATCH.
+   *
+   * The additive POST goes through `withTransientRetry` (Story #4961) on the
+   * same policy as every other call in this file. Story #4952 raised the
+   * `/plan` write loops that reach this endpoint — the `agent::ready` flips
+   * and the checkpoint fan-out — off serial, which is precisely what makes
+   * GitHub's secondary rate limit likelier; `gh-exec` already classifies that
+   * as transient, so the only thing missing was a backoff behind it.
+   * Retry does not change what the caller observes on a genuine failure: an
+   * exhausted or non-transient error still throws, so `markStoriesReady`
+   * still collects it into the complete failure set.
    */
   async _applyLabelMutations(
     ticketId,
@@ -331,11 +341,15 @@ export class TicketGateway {
     const { add = [], remove = [] } = labelMutations;
 
     if (add.length > 0 && remove.length === 0 && !hasOtherPatchFields) {
-      await this._gh.api({
-        method: 'POST',
-        endpoint: `/repos/${this.owner}/${this.repo}/issues/${ticketId}/labels`,
-        body: { labels: add },
-      });
+      await withTransientRetry(
+        () =>
+          this._gh.api({
+            method: 'POST',
+            endpoint: `/repos/${this.owner}/${this.repo}/issues/${ticketId}/labels`,
+            body: { labels: add },
+          }),
+        { label: `addLabels #${ticketId}`, onRetry: defaultRetryWarn },
+      );
       return { skipPatch: true };
     }
 
@@ -351,6 +365,11 @@ export class TicketGateway {
   }
 
   /**
+   * The issue PATCH is wrapped in `withTransientRetry` (Story #4961) for the
+   * same reason as the additive label POST above — see
+   * {@link TicketGateway#_applyLabelMutations}. Both are the write half of the
+   * fan-outs Story #4952 raised; the reads in this file were already wrapped.
+   *
    * @field-manifest PATCH /repos/{owner}/{repo}/issues/{n}:
    *                 body, assignees, state, state_reason, labels
    */
@@ -379,11 +398,15 @@ export class TicketGateway {
     }
 
     if (Object.keys(patch).length > 0) {
-      await this._gh.api({
-        method: 'PATCH',
-        endpoint: `/repos/${this.owner}/${this.repo}/issues/${ticketId}`,
-        body: patch,
-      });
+      await withTransientRetry(
+        () =>
+          this._gh.api({
+            method: 'PATCH',
+            endpoint: `/repos/${this.owner}/${this.repo}/issues/${ticketId}`,
+            body: patch,
+          }),
+        { label: `updateTicket #${ticketId}`, onRetry: defaultRetryWarn },
+      );
       this.invalidateTicket(ticketId);
     }
   }

package/.agents/scripts/provision-git-hooks.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+/**
+ * provision-git-hooks.js
+ *
+ * Materialize the repository's git hooks into a linked worktree, so commits
+ * made there are subject to the same `commit-msg` / `pre-commit` / `pre-push`
+ * gates as commits made in the main checkout.
+ *
+ * Worktrees created by `single-story-init.js` are provisioned automatically as
+ * part of `worktree.bootstrap`. This entry point exists for the worktrees the
+ * orchestrator never creates — a harness or hand-made `git worktree add` —
+ * which are otherwise unreachable. Run it from inside such a worktree with no
+ * arguments.
+ */
+
+import path from 'node:path';
+import { runAsCli } from './lib/cli-utils.js';
+import {
+  materializeGitHooks,
+  resolveCommonCheckout,
+} from './lib/worktree/git-hooks.js';
+
+/**
+ * @param {object} [opts]
+ * @param {string[]} [opts.argv]
+ * @param {string} [opts.cwd]
+ * @returns {{ action: string, reason?: string, hooksPath: string|null,
+ *   target: string|null, hooks: string[], worktree: string, repoRoot: string }}
+ */
+export function runProvisionGitHooks({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+} = {}) {
+  const positional = [];
+  let repoRootFlag = null;
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--repo-root') {
+      repoRootFlag = argv[i + 1];
+      if (!repoRootFlag) {
+        throw new Error('--repo-root requires a path');
+      }
+      i += 1;
+      continue;
+    }
+    positional.push(argv[i]);
+  }
+
+  const worktree = path.resolve(cwd, positional[0] ?? '.');
+  const repoRoot = repoRootFlag
+    ? path.resolve(cwd, repoRootFlag)
+    : resolveCommonCheckout(worktree);
+
+  const result = materializeGitHooks({ repoRoot, worktree });
+  return { ...result, worktree, repoRoot };
+}
+
+runAsCli(
+  import.meta.url,
+  async () => {
+    const result = runProvisionGitHooks();
+    // Compact single-line digest: this is the machine contract, and the
+    // hook file list is bounded by the hooks directory itself.
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  },
+  {
+    source: 'provision-git-hooks',
+    usage: {
+      invocation:
+        'node .agents/scripts/provision-git-hooks.js [<worktree-path>] [--repo-root <path>]',
+      summary:
+        "Materialize the repository's git hooks into a linked worktree so its commits are gated.",
+      flags: [
+        [
+          '<worktree-path>',
+          'Worktree to provision (default: the current directory).',
+        ],
+        [
+          '--repo-root <path>',
+          'Checkout that owns the hooks (default: derived from --git-common-dir).',
+        ],
+      ],
+    },
+  },
+);

package/.agents/scripts/quality-preview.js

@@ -30,6 +30,8 @@ import {
   runMaintainabilityPreview,
 } from './lib/baselines/preview-gates.js';
 import { respondToHelp } from './lib/cli-usage.js';
+import { getQuality, resolveConfig } from './lib/config-resolver.js';
+import { resolveCyclomaticPolicy } from './lib/cyclomatic-ceiling.js';
 
 const USAGE = {
   invocation:
@@ -46,6 +48,14 @@ const USAGE = {
   ],
 };
 
+/**
+ * Framework default for `delivery.quality.codingGuardrails.cyclomaticFlag`,
+ * used only when a caller drives `mergeEnvelopes` / `renderTable` without a
+ * resolved config in hand (tests, and the pure-function surface). `runCli`
+ * always passes the resolved value.
+ */
+const DEFAULT_CYCLOMATIC_FLAG = 8;
+
 /**
  * Parse `--changed-since <ref>` from argv. Defaults to `HEAD` when the flag is
  * present without a value. Returns `null` when the flag is absent so callers
@@ -97,6 +107,47 @@ export function parseStagedFlag(argv) {
   return argv.includes('--staged');
 }
 
+/**
+ * Coerce a caller-supplied flag ceiling to a usable number, falling back to
+ * the framework default for anything non-finite.
+ *
+ * @param {unknown} value
+ * @returns {number}
+ */
+function normalizeFlag(value) {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : DEFAULT_CYCLOMATIC_FLAG;
+}
+
+/**
+ * Fold one CRAP violation into its per-file aggregate row. Mutates `row`.
+ *
+ * Split out of `mergeEnvelopes` (Story #4923): threading the resolved
+ * `cyclomaticFlag` through pushed that function from c=12 — exactly at the
+ * must-fix ceiling — to c=13, and the same Story starts *enforcing* that
+ * ceiling. Recording its own breach in `baselines/cyclomatic.json` would have
+ * been the first re-spend of the slack the Story reclaims.
+ *
+ * @param {{ worstCrapDelta: number, newOverCeilingMethods: number }} row
+ * @param {{ crap?: number, ceiling?: number, baseline?: number, cyclomatic?: number, kind?: string }} v
+ * @param {number} flag resolved `codingGuardrails.cyclomaticFlag`
+ * @returns {void}
+ */
+function foldCrapViolation(row, v, flag) {
+  const crap = Number(v.crap ?? 0);
+  const isNew = v.kind === 'new';
+  const against = Number((isNew ? v.ceiling : v.baseline) ?? 0);
+  const delta = crap - against;
+  if (Number.isFinite(delta) && delta > row.worstCrapDelta) {
+    row.worstCrapDelta = delta;
+  }
+  if (!isNew) return;
+  const cyclomatic = Number(v.cyclomatic ?? 0);
+  if (Number.isFinite(cyclomatic) && cyclomatic > flag) {
+    row.newOverCeilingMethods += 1;
+  }
+}
+
 /**
  * Merge an MI envelope (from `runMaintainabilityPreview`) and a CRAP
  * envelope (from `runCrapPreview`) into a per-file delta map. Pure —
@@ -109,9 +160,16 @@ export function parseStagedFlag(argv) {
  *     methods (max of `crap - baseline` for matched-baseline rows, `crap`
  *     for new-method rows). 0 when the file has no CRAP violations.
  *   - `newOverCeilingMethods`: count of new-method violations (kind:'new')
- *     scoring above the `c=8` ceiling (matches the column header
- *     "new-method count over c=8" in the AC). The CRAP envelope's
- *     `cyclomatic` field is the per-method `c` reading.
+ *     scoring above the flag ceiling. The CRAP envelope's `cyclomatic` field
+ *     is the per-method `c` reading.
+ *
+ * `cyclomaticFlag` is the resolved
+ * `delivery.quality.codingGuardrails.cyclomaticFlag` (Story #4923). It used to
+ * be the literal `8` written into this function and into the column header, so
+ * a consumer that tuned the knob saw its own value validated by the schema,
+ * defaulted by the bootstrap, resolved by `lib/config/quality.js` — and then
+ * ignored here. The parameter defaults to the framework default so a caller
+ * with no config in hand still gets the historical reading.
  *
  * @param {{ violations?: Array<{ file: string, drop?: number }> } | null} miEnvelope
  * @param {{ violations?: Array<{
@@ -122,6 +180,7 @@ export function parseStagedFlag(argv) {
  *   cyclomatic: number,
  *   kind: 'new' | 'regression' | 'drifted-regression' | string,
  * }>} | null} crapEnvelope
+ * @param {{ cyclomaticFlag?: number }} [opts]
  * @returns {{
  *   rows: Array<{
  *     file: string,
@@ -130,9 +189,15 @@ export function parseStagedFlag(argv) {
  *     newOverCeilingMethods: number,
  *   }>,
  *   totals: { miRegressions: number, crapViolations: number },
+ *   cyclomaticFlag: number,
  * }}
  */
-export function mergeEnvelopes(miEnvelope, crapEnvelope) {
+export function mergeEnvelopes(
+  miEnvelope,
+  crapEnvelope,
+  { cyclomaticFlag = DEFAULT_CYCLOMATIC_FLAG } = {},
+) {
+  const flag = normalizeFlag(cyclomaticFlag);
   /** @type {Map<string, { miDrop: number, worstCrapDelta: number, newOverCeilingMethods: number }>} */
   const byFile = new Map();
   const ensure = (file) => {
@@ -155,25 +220,7 @@ export function mergeEnvelopes(miEnvelope, crapEnvelope) {
   const crapViolations = crapEnvelope?.violations ?? [];
   for (const v of crapViolations) {
     if (!v?.file) continue;
-    const row = ensure(v.file);
-    const crap = Number(v.crap ?? 0);
-    if (v.kind === 'new') {
-      const ceiling = Number(v.ceiling ?? 0);
-      const delta = crap - ceiling;
-      if (Number.isFinite(delta) && delta > row.worstCrapDelta) {
-        row.worstCrapDelta = delta;
-      }
-      const cyclomatic = Number(v.cyclomatic ?? 0);
-      if (Number.isFinite(cyclomatic) && cyclomatic > 8) {
-        row.newOverCeilingMethods += 1;
-      }
-    } else {
-      const baseline = Number(v.baseline ?? 0);
-      const delta = crap - baseline;
-      if (Number.isFinite(delta) && delta > row.worstCrapDelta) {
-        row.worstCrapDelta = delta;
-      }
-    }
+    foldCrapViolation(ensure(v.file), v, flag);
   }
 
   const rows = Array.from(byFile.entries())
@@ -188,9 +235,33 @@ export function mergeEnvelopes(miEnvelope, crapEnvelope) {
         (crapEnvelope?.summary?.regressions ?? 0) +
         (crapEnvelope?.summary?.newViolations ?? 0),
     },
+    cyclomaticFlag: flag,
   };
 }
 
+/**
+ * Render the named diagnostics a gate envelope carries, or `null` when it
+ * carries none (Story #4866).
+ *
+ * A diagnostic is what a gate emits *instead of* per-method verdicts when it
+ * has established that no verdict it could produce would be meaningful — an
+ * incomparable baseline, or a comparison basis whose drifted-row ratio proves
+ * the two sides disagree on line coordinates. It must reach the operator
+ * verbatim: the gate exits 0, so silence would read as a clean run.
+ *
+ * @param {Array<{ envelope: { diagnostics?: Array<{name: string, message: string}> } | null }>} results
+ * @returns {string | null}
+ */
+export function renderDiagnostics(results) {
+  const lines = [];
+  for (const { envelope } of results ?? []) {
+    for (const d of envelope?.diagnostics ?? []) {
+      lines.push(`[${d.name}] ${d.message}`);
+    }
+  }
+  return lines.length === 0 ? null : lines.join('\n');
+}
+
 /**
  * Compute the CLI exit code from a merge result + per-gate exit codes. Pure.
  *
@@ -216,21 +287,28 @@ export function computeExitCode(merged, miExit, crapExit) {
 }
 
 /**
- * Render the per-file delta table. Header columns match the AC verbatim:
- *   "file", "MI delta", "worst CRAP delta", "new-method count over c=8".
+ * Render the per-file delta table. Columns:
+ *   "file", "MI delta", "worst CRAP delta", "new-method count over c=<flag>".
+ *
+ * The last header used to hardcode `c=8`, which quietly lied to any consumer
+ * that had tuned `codingGuardrails.cyclomaticFlag`. It now names the value the
+ * count was actually taken against, read off the merge result.
  *
  * Pure — accepts pre-computed merge rows and returns a multi-line string. The
  * table renders even on a clean diff so operators see the "no drift" signal.
  *
- * @param {{ rows: Array<{ file: string, miDrop: number, worstCrapDelta: number, newOverCeilingMethods: number }>, totals: { miRegressions: number, crapViolations: number } }} merged
+ * @param {{ rows: Array<{ file: string, miDrop: number, worstCrapDelta: number, newOverCeilingMethods: number }>, totals: { miRegressions: number, crapViolations: number }, cyclomaticFlag?: number }} merged
  * @returns {string}
  */
 export function renderTable(merged) {
+  const flag = Number.isFinite(Number(merged?.cyclomaticFlag))
+    ? Number(merged.cyclomaticFlag)
+    : DEFAULT_CYCLOMATIC_FLAG;
   const header = [
     'file',
     'MI delta',
     'worst CRAP delta',
-    'new-method count over c=8',
+    `new-method count over c=${flag}`,
   ];
   const lines = [];
   lines.push(`| ${header.join(' | ')} |`);
@@ -251,6 +329,31 @@ export function renderTable(merged) {
   return lines.join('\n');
 }
 
+/**
+ * Resolve `codingGuardrails.cyclomaticFlag` for the tree at `cwd`
+ * (Story #4923), falling back to the framework default when the config cannot
+ * be resolved at all.
+ *
+ * Best-effort by design: `quality:preview` is a developer-facing report, and a
+ * run in a tree with no readable `.agentrc.json` should still render its table
+ * rather than abort. Extracted from `runCli` rather than inlined so the CLI
+ * body stays under the cyclomatic must-fix ceiling this same Story starts
+ * enforcing — a gate whose own delivery breaches it is not a gate.
+ *
+ * @param {{ cwd: string, stderr: { write: (s: string) => void } }} args
+ * @returns {number}
+ */
+function resolveCyclomaticFlag({ cwd, stderr }) {
+  try {
+    return resolveCyclomaticPolicy(getQuality(resolveConfig({ cwd }))).flag;
+  } catch (err) {
+    stderr.write(
+      `[quality:preview] config resolution failed, using cyclomaticFlag=${DEFAULT_CYCLOMATIC_FLAG}: ${err?.message ?? err}\n`,
+    );
+    return DEFAULT_CYCLOMATIC_FLAG;
+  }
+}
+
 /**
  * Top-level CLI entry: invoke both per-kind preview runners, merge, render,
  * and exit with the right code. Exposed as `runCli` so tests can drive the
@@ -296,7 +399,11 @@ export async function runCli({
   const crapExit = crapResult.exitCode;
   const miEnvelope = miResult.envelope;
   const crapEnvelope = crapResult.envelope;
-  const merged = mergeEnvelopes(miEnvelope, crapEnvelope);
+  // Story #4923 — the over-ceiling column counts against the *resolved*
+  // `codingGuardrails.cyclomaticFlag`, not the literal that used to be written
+  // into `mergeEnvelopes` and the column header.
+  const cyclomaticFlag = resolveCyclomaticFlag({ cwd, stderr });
+  const merged = mergeEnvelopes(miEnvelope, crapEnvelope, { cyclomaticFlag });
 
   if (json) {
     stdout.write(
@@ -320,6 +427,8 @@ export async function runCli({
         : `scope=diff ref=${ref}\n\n`,
     );
     stdout.write(`${renderTable(merged)}\n`);
+    const diagnostics = renderDiagnostics([miResult, crapResult]);
+    if (diagnostics) stdout.write(`\n${diagnostics}\n`);
     if (miExit !== 0 || crapExit !== 0) {
       stderr.write(
         `\n[quality:preview] gate exits: mi=${miExit} crap=${crapExit}\n`,

package/.agents/scripts/resolve-stories.js

@@ -24,6 +24,7 @@
  *
  * Usage:
  *   node .agents/scripts/resolve-stories.js --ids 101,102
+ *   node .agents/scripts/resolve-stories.js --ids 101-104        # inclusive range
  *   node .agents/scripts/resolve-stories.js --ids 101,102 --pretty
  *   node .agents/scripts/resolve-stories.js --ids 101 --no-native   # skip the dependencies API
  *
@@ -65,7 +66,9 @@ blocked_by edges, with every blocker (in-set or foreign) resolved against its
 real issue state.
 
 Options:
-  --ids <csv>    Comma-separated Story issue numbers. Required.
+  --ids <csv>    Comma-separated Story issue numbers. Required. A token may be
+                 a single id (4922) or an inclusive dash range (4922-4926);
+                 ranges expand in place and dedupe against the rest.
   --pretty       Pretty-print the JSON envelope.
   --no-native    Skip the native blocked_by read (body edges only).
   --help         Show this help.

package/.agents/scripts/run-coverage.js

@@ -10,8 +10,16 @@
  * Node script keeps the env injection portable.
  *
  * Pipeline:
+ *   0. Run the full tier's preflight (`runTierPreflight`). Story #4936: this
+ *      used to be a `pretest:coverage` npm script that CI had to name
+ *      explicitly, because `.npmrc`'s `ignore-scripts=true` (CWE-1357
+ *      defence, which stays) suppresses every `pre*` hook. The runner
+ *      invokes it now, so it executes however the coverage run is started.
  *   1. Run the test suite under `NODE_V8_COVERAGE` so each worker writes
- *      raw V8 dumps under `coverage/tmp/`.
+ *      raw V8 dumps under `coverage/tmp/`. The suite targets are the
+ *      shared `FULL_TIER_GLOBS` from `lib/test-tiers.js` — the same set
+ *      `run-tests.js` walks — so the measured surface and `npm test`'s
+ *      surface are the same set by construction.
  *   2. `c8 report` post-processes the dumps into `coverage/coverage-final.json`
  *      plus the printed text table. Include/exclude scope from `.c8rc.cjs`
  *      is passed explicitly because `c8 report` does not auto-load the
@@ -28,13 +36,15 @@
  * while producing an identical `coverage-final.json` artifact for the
  * CRAP gate.
  *
- * Test-runner concurrency: the suite spawn reuses `TEST_RUNNER_FLAGS`
- * from `run-tests.js` — the single source of truth for the
- * `--test-concurrency` value, derived at startup from the host's
- * available parallelism and clamped to `[TEST_CONCURRENCY_MIN,
- * TEST_CONCURRENCY_MAX]`. This keeps the coverage gate (which runs the
- * suite at every story close on both delivery paths) host-aware instead
- * of pinned to the historical literal of 8.
+ * Test-runner flags: the suite spawn reuses `TEST_RUNNER_FLAGS` from
+ * `lib/test-runner-contract.js` — the single source of truth for the
+ * `node --test` flag set, including the host-derived
+ * `--test-concurrency` value clamped to `[TEST_CONCURRENCY_MIN,
+ * TEST_CONCURRENCY_MAX]`. Story #4936: sharing the whole flag set (not
+ * just the concurrency number) is what stops this runner and
+ * `run-tests.js` disagreeing about whether a test can execute at all —
+ * `--experimental-test-module-mocks` decides whether `t.mock.module`
+ * works, and this is the *required* CI job.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -46,56 +56,90 @@ import { fileURLToPath } from 'node:url';
 import { cleanupRepoTestTempArtifacts } from './cleanup-repo-test-temp.js';
 import { C8_CLI } from './lib/c8-cli-path.js';
 import { buildWebhookSafeTestEnv } from './lib/test-env.js';
-import { TEST_RUNNER_FLAGS } from './run-tests.js';
+import {
+  runTierPreflight,
+  TEST_RUNNER_FLAGS,
+} from './lib/test-runner-contract.js';
+import { FULL_TIER_GLOBS } from './lib/test-tiers.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..', '..');
-const COVERAGE_DIR = path.join(ROOT, 'coverage');
 const require = createRequire(import.meta.url);
 const C8_CONFIG = require('../../.c8rc.cjs');
-const V8_TMP = path.join(COVERAGE_DIR, 'tmp');
 
 /**
  * Build the `node --test` argv for the coverage suite spawn.
  *
- * Reuses the shared `TEST_RUNNER_FLAGS` (the single source of truth for
- * the host-aware, clamped `--test-concurrency` value) so the coverage
- * path never drifts from `run-tests.js`. The `runnerFlags` parameter is
- * injected in tests so the argv can be asserted without touching the OS.
+ * Reuses two shared constants so the coverage path cannot drift from
+ * `run-tests.js`:
+ *
+ *   - `TEST_RUNNER_FLAGS` — the single source of truth for the host-aware,
+ *     clamped `--test-concurrency` value.
+ *   - `FULL_TIER_GLOBS` — the single source of truth for *which files the
+ *     full tier runs*. Story #4922: this script used to restate
+ *     `tests/**\/*.test.js` on its own, so the 47 colocated `__tests__`
+ *     suites under `lib/` and `.agents/scripts/` executed under `npm test`
+ *     but never under the measuring run — the coverage and CRAP numbers
+ *     were computed over code the coverage run had not executed.
+ *
+ * Both parameters are injected in tests so the argv can be asserted without
+ * touching the OS.
  *
  * @param {object} [opts]
  * @param {readonly string[]} [opts.runnerFlags]
- * @param {string} [opts.testGlob]
+ * @param {readonly string[]} [opts.testGlobs]
  * @returns {string[]}
  */
 export function buildCoverageTestArgs({
   runnerFlags = TEST_RUNNER_FLAGS,
-  testGlob = 'tests/**/*.test.js',
+  testGlobs = FULL_TIER_GLOBS,
 } = {}) {
-  return [...runnerFlags, testGlob];
+  return [...runnerFlags, ...testGlobs];
 }
 
 /**
- * Execute the coverage pipeline: run the suite under `NODE_V8_COVERAGE`,
- * post-process the dumps with `c8 report`, then gate on the coverage
- * baseline. Returns the first non-zero exit code across the three stages
- * (or the baseline check's status when both prior stages pass).
+ * Execute the coverage pipeline: run the full tier's preflight, run the
+ * suite under `NODE_V8_COVERAGE`, post-process the dumps with `c8 report`,
+ * then gate on the coverage baseline. Returns the first non-zero exit code
+ * across the stages (or the baseline check's status when the prior stages
+ * pass); a refused preflight short-circuits before anything is spawned or
+ * removed.
  *
+ * Every collaborator is injected so the pipeline's wiring — above all
+ * *that the preflight actually runs, and runs first* — is assertable
+ * without spawning the real suite.
+ *
+ * @param {object} [opts]
+ * @param {typeof spawnSync} [opts.spawn]
+ * @param {(opts: { tier: string, repoRoot: string }) => number} [opts.preflight]
+ * @param {(opts: { repoRoot: string }) => unknown} [opts.cleanup]
+ * @param {string} [opts.repoRoot]
  * @returns {number}
  */
-function runCoveragePipeline() {
-  rmSync(COVERAGE_DIR, { recursive: true, force: true });
-  mkdirSync(V8_TMP, { recursive: true });
+export function runCoveragePipeline({
+  spawn = spawnSync,
+  preflight = runTierPreflight,
+  cleanup = cleanupRepoTestTempArtifacts,
+  repoRoot = ROOT,
+} = {}) {
+  const coverageDir = path.join(repoRoot, 'coverage');
+  const v8Tmp = path.join(coverageDir, 'tmp');
+
+  const preflightStatus = preflight({ tier: 'full', repoRoot });
+  if (preflightStatus !== 0) return preflightStatus;
 
-  const testRun = spawnSync(process.execPath, buildCoverageTestArgs(), {
-    cwd: ROOT,
+  rmSync(coverageDir, { recursive: true, force: true });
+  mkdirSync(v8Tmp, { recursive: true });
+
+  const testRun = spawn(process.execPath, buildCoverageTestArgs(), {
+    cwd: repoRoot,
     stdio: 'inherit',
     // GIT_*-scrubbed: under a husky pre-push from a linked worktree the
     // inherited GIT_DIR poisons fixture `git init` runs (#4580).
-    env: { ...buildWebhookSafeTestEnv(process.env), NODE_V8_COVERAGE: V8_TMP },
+    env: { ...buildWebhookSafeTestEnv(process.env), NODE_V8_COVERAGE: v8Tmp },
   });
 
-  cleanupRepoTestTempArtifacts({ repoRoot: ROOT });
+  cleanup({ repoRoot });
 
   const includeArgs = (C8_CONFIG.include ?? []).flatMap((p) => [
     '--include',
@@ -106,29 +150,36 @@ function runCoveragePipeline() {
     p,
   ]);
 
-  const reportRun = spawnSync(
+  // `c8 report` does not auto-load `.c8rc.cjs`, so every scope knob it needs
+  // is forwarded explicitly from the config object — including `all`, which
+  // is what puts a 0 % row on a source file no test ever loaded (Story
+  // #4922). Reading it off the config keeps `.c8rc.cjs` the one declaration.
+  const allArgs = C8_CONFIG.all ? ['--all'] : [];
+
+  const reportRun = spawn(
     process.execPath,
     [
       C8_CLI,
       'report',
       '--reporter=json',
       '--reporter=text',
+      ...allArgs,
       '--temp-directory',
-      V8_TMP,
+      v8Tmp,
       ...includeArgs,
       ...excludeArgs,
     ],
-    { cwd: ROOT, stdio: 'inherit', shell: false },
+    { cwd: repoRoot, stdio: 'inherit', shell: false },
   );
 
-  const checkRun = spawnSync(
+  const checkRun = spawn(
     process.execPath,
     [
-      path.join(ROOT, '.agents', 'scripts', 'check-baselines.js'),
+      path.join(repoRoot, '.agents', 'scripts', 'check-baselines.js'),
       '--gate',
       'coverage',
     ],
-    { cwd: ROOT, stdio: 'inherit' },
+    { cwd: repoRoot, stdio: 'inherit' },
   );
 
   return testRun.status !== 0

package/.agents/scripts/run-lint.js

@@ -28,11 +28,20 @@ const tasks = [
     args: ['biome', 'ci', '.'],
   },
   {
+    // `docs/**/*.md` sat outside these globs until PR #4970's follow-up,
+    // so `npm run lint` reported "0 error(s)" while the close-time
+    // code-review lens — which lints the whole changed surface, not just
+    // what this driver globs — raised pre-existing `docs/` violations
+    // against whichever Story happened to touch the file. Keep `docs/`
+    // here so the two surfaces agree. `docs/CHANGELOG.md` is linted too;
+    // the generator-owned rules it can never satisfy are exempted by a
+    // `markdownlint-disable-file` directive in its own header.
     name: 'markdownlint',
     cmd: 'npx',
     args: [
       'markdownlint-cli2',
       '.agents/**/*.md',
+      'docs/**/*.md',
       '*.md',
       '!node_modules/**',
       '!.worktrees/**',
@@ -79,6 +88,17 @@ const tasks = [
     cmd: 'node',
     args: ['.agents/scripts/lint-label-vocabulary.js'],
   },
+  {
+    // GitHub Actions job-timeout gate (Story #4936). Enumerates every
+    // `jobs.<id>` key across `.github/workflows/*.yml` and fails when one
+    // sets no `timeout-minutes` (inheriting GitHub's 360-minute default) or
+    // sets one above the ceiling. A deadlocked Windows job burned 44 minutes
+    // of a runner and withheld the failing required check's logs for the
+    // whole time; nothing but this check would have caught the gap.
+    name: 'workflow-timeouts',
+    cmd: 'node',
+    args: ['.agents/scripts/check-workflow-timeouts.js'],
+  },
   {
     // Architecture cycle ratchet (Story #3991). Detects directed import
     // cycles under `.agents/scripts/` and fails on any cycle not in the