mandrel 2.34.0 → 2.36.0

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

@@ -340,7 +340,9 @@
         "maxResumes": 3,
         "attachWindowMs": 1200000
       },
-      "autoMerge": "trust-ci"
+      "autoMerge": "trust-ci",
+      "blockOnAdvisoryFailure": true,
+      "advisoryAllowlist": []
     },
     "routing": {
       "roleScopedAgents": true,

package/.agents/docs/configuration.md

@@ -320,6 +320,8 @@ Everything `/deliver` and `single-story-close` consume: execution timeouts, work
 | `ci.watch.maxResumes` | No | `integer` | `3` | How many times the watcher may resume after a transient stall. 0 disables resuming. |
 | `ci.watch.attachWindowMs` | No | `integer` | `1200000` | Story #4890. How long (ms) the watch keeps re-resolving an EMPTY `gh pr checks --required` set before it stops waiting for a required context to attach. A ruleset attaches its contexts asynchronously and the arrival latency is set by the slowest one, so a required context that is an aggregator job gated on every other tier is the last to appear — measured at 16m52s on this repository. Default 1200000 (20 minutes). Raise it for a repository whose contexts arrive later still; exhausting the window is never reported as a red check (the watch exits 2, not-yet-started). |
 | `ci.autoMerge` | No | `"trust-ci"` \| `"strict"` | `"trust-ci"` | Story #4356 (Epic #4355). Merge posture. 'trust-ci' (default) merges once required checks pass; 'strict' additionally requires a clean review gate. |
+| `ci.blockOnAdvisoryFailure` | No | `boolean` | `true` | Story #5096. When true (default), delivery refuses to arm — and disarms — GitHub native auto-merge while a non-required (advisory) check is genuinely red on the PR head and GitHub reports the PR mergeable anyway (mergeStateStatus=UNSTABLE). `--auto` waits on REQUIRED contexts only, so without this a red advisory quality gate merges unattended. Set false to restore the pre-#5096 behaviour verbatim. |
+| `ci.advisoryAllowlist` | No | `array<string>` | `[]` | Story #5096. Check-run names exempt from blockOnAdvisoryFailure — a red run whose name matches exactly never blocks arming. Matching is exact; an unnamed run can never match and always blocks. |
 | `routing` | No | `object` | — | v2 delivery-spawn routing: role-scoped boot contexts and maker-checker sampling. The v1 singleDelivery epic-route kill-switch was removed in Stage 6. |
 | `routing.roleScopedAgents` | No | `boolean` | `true` | Epic #4478 (M7-B). Kill-switch for the role-scoped boot contexts. When true (default), a converted delivery spawn (`story-worker`, `acceptance-critic`) boots on its own `.claude/agents/<role>.md` system prompt instead of re-paying the full CLAUDE.md @-import closure. When false, every converted spawn falls back to `subagent_type: general-purpose` — the instant, code-rollback-free per-consumer revert, and the universal escape for hosts that ignore `.claude/agents/`. The fallback is the full-closure agent that ran before M7-B, so flipping it off never drops a gate. |
 | `routing.freshCriticSampleRate` | No | `number` | `0.2` | Epic #4478 (M7-B, Part 2). Maker-checker sampling floor. Under the standard profile, a change set touching no sensitive path routes its acceptance clusters down the contract-identical inline critic path, but this fraction of them is still forced through a fresh-context critic so a low derived level never means zero independent checking. Clamped to [0, 1]; 0 disables the floor, 1 forces every cluster fresh. Consumed by resolveCeremonyForRisk (lib/orchestration/ceremony-routing.js). |

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

@@ -424,6 +424,36 @@ refresh-guardrail accepts it on the next PR.
 If your test runner doesn't produce per-method coverage, see "Disabling the
 gate" below.
 
+### Coverage freshness — what triggers a capture
+
+The CRAP scorer treats "no coverage" as "skip the method", so a missing or
+stale `coverage/coverage-final.json` silently weakens the gate.
+`coverage-capture.js` closes that hole by capturing coverage in-band, and
+decides whether it needs to by two rules (Story #5076):
+
+- **The source set is derived, not configured.** Freshness is measured over
+  exactly the extensions the CRAP scanner walks — `.js`, `.mjs`, `.cjs`,
+  `.ts`, `.tsx`, `.mts`, `.cts` — defined once in
+  `.agents/scripts/lib/source-extensions.js`. There is deliberately no
+  `.agentrc.json` key for this: a consumer-settable list would be a second
+  way to mis-scope the same gate. Formats the engines cannot parse
+  (`.astro`, `.vue`, `.svelte`) are not part of it — a project written in
+  those still has its `.ts`/`.tsx` measured.
+- **Both freshness paths fail closed on an empty source set.** Finding no
+  scorable source under `crap.targetDirs` means the check learned nothing,
+  so it captures rather than assuming coverage is current, and warns naming
+  the configured dirs. If you see that warning, `targetDirs` almost
+  certainly does not point at your sources — fix it rather than living with
+  a full capture on every run.
+
+**Upgrading from a version before this fix:** a TypeScript project's sources
+matched neither path, so the capture was skipped on every run and
+`crap:check` compared the committed baseline against itself. The first run
+after upgrading captures for real and measures your committed floors for the
+first time, which may surface breaches that were always there. That is a
+one-off re-baseline (`npm run crap:update`, committed with a
+`baseline-refresh:` subject), not a regression.
+
 ### Disabling the gate (single-flag opt-out)
 
 If your repo doesn't run coverage, set `enabled: false` in your

package/.agents/docs/workflows.md

@@ -32,11 +32,12 @@ by `node .agents/scripts/generate-workflows-doc.js`; `npm run docs:check`
 fails when it drifts from the on-disk workflow set. To change a command’s
 description, edit the workflow file’s front-matter and regenerate.
 
-## Commands (27)
+## Commands (28)
 
 | Command | Description |
 | --- | --- |
 | `/audit-accessibility` | Audit WCAG accessibility conformance (static-first) with an optional runtime verification pass, and produce a structured findings report |
+| `/audit-adrs` | Audit the decisions log as a live contract — Accepted ADRs whose claims the tree has outgrown, broken supersede chains, structural gaps, and directional changes that landed with no decision recorded. A deliberately-global lens over whichever decisions-log layout the consumer ships. |
 | `/audit-architecture` | Audit architectural boundaries, module coupling, layering violations, and shipped-but-uncalled seams; emit a structured findings report keyed to the canonical severity scale. |
 | `/audit-baselines` | Audit the committed baseline surface — dead instruments, stale baselines, cross-gate hotspot clusters, trend drift, and floor-tightening headroom — and emit findings whose remediation burns the measured debt down and tightens the ratchet behind it. |
 | `/audit-clean-code` | Audit code smells, dead code, complexity hotspots, and maintainability-index outliers; emit a structured findings report. |

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

@@ -1913,6 +1913,17 @@
               "enum": ["trust-ci", "strict"],
               "description": "Story #4356 (Epic #4355). Merge posture. 'trust-ci' (default) merges once required checks pass; 'strict' additionally requires a clean review gate.",
               "default": "trust-ci"
+            },
+            "blockOnAdvisoryFailure": {
+              "type": "boolean",
+              "description": "Story #5096. When true (default), delivery refuses to arm — and disarms — GitHub native auto-merge while a non-required (advisory) check is genuinely red on the PR head and GitHub reports the PR mergeable anyway (mergeStateStatus=UNSTABLE). `--auto` waits on REQUIRED contexts only, so without this a red advisory quality gate merges unattended. Set false to restore the pre-#5096 behaviour verbatim.",
+              "default": true
+            },
+            "advisoryAllowlist": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Story #5096. Check-run names exempt from blockOnAdvisoryFailure — a red run whose name matches exactly never blocks arming. Matching is exact; an unnamed run can never match and always blocks.",
+              "default": []
             }
           },
           "additionalProperties": false

package/.agents/schemas/audit-rules.json

@@ -312,6 +312,23 @@
       "target": "web",
       "scope": "global",
       "substitutionKeys": []
+    },
+    "audit-adrs": {
+      "triggers": {
+        "gates": ["gate1", "gate3"],
+        "keywords": [
+          "adr",
+          "adrs",
+          "decision record",
+          "architecture decision",
+          "decisions log",
+          "supersede",
+          "superseded"
+        ],
+        "filePatterns": ["**/decisions.md", "**/decisions/**"]
+      },
+      "scope": "global",
+      "substitutionKeys": []
     }
   },
   "sensitivePaths": {
@@ -363,6 +380,33 @@
         "**/openapi/**",
         "**/graphql/**"
       ]
+    },
+    "deploy-runtime": {
+      "description": "Deployment and runtime topology: the CI/CD pipeline, infrastructure-as-code, container images, and the server/serverless entrypoint with its platform and build config. A change here alters how the product is built, bound, and run in production without necessarily touching application logic. Build configs are enumerated by name rather than matched with a blanket `**/*.config.*` glob, which would swallow the test and lint configs and flip nearly every change set to high.",
+      "filePatterns": [
+        ".github/workflows/**",
+        ".github/actions/**",
+        "**/Dockerfile",
+        "**/docker-compose*.yml",
+        "**/docker-compose*.yaml",
+        "infra/**",
+        "**/*.tf",
+        "**/*.tfvars",
+        "**/wrangler.json",
+        "**/wrangler.jsonc",
+        "**/wrangler.toml",
+        "**/worker-entry.ts",
+        "**/worker-entry.js",
+        "**/astro.config.*",
+        "**/next.config.*",
+        "**/nuxt.config.*",
+        "**/svelte.config.*",
+        "**/fly.toml",
+        "**/vercel.json",
+        "**/netlify.toml",
+        "**/serverless.yml",
+        "**/serverless.yaml"
+      ]
     }
   }
 }

package/.agents/schemas/audit-rules.schema.json

@@ -22,7 +22,7 @@
     },
     "sensitivePaths": {
       "type": "object",
-      "description": "Map of sensitive-path class name to the globs that identify it. A change set touching any registered pattern derives a `high` change level, which resolves review depth to `deep` and the acceptance critic to `fresh` regardless of how narrow the diff is (deriveChangeLevel in lib/orchestration/review-depth.js). This is configuration, not code: an operator extends the classes or their globs here without editing a module, and the globs run through the same picomatch machinery as the audit-lens `filePatterns` triggers above. An absent or empty block means no path is sensitive and depth falls back to diff width alone.",
+      "description": "Map of sensitive-path class name to the globs that identify it. A change set touching any registered pattern derives a `high` change level, which resolves review depth to `deep` and the acceptance critic to `fresh` regardless of how narrow the diff is (deriveChangeLevel in lib/orchestration/review-depth.js). This is configuration, not code: an operator extends the classes or their globs here without editing a module, and the globs run through the same picomatch machinery as the audit-lens `filePatterns` triggers above. Those lens triggers are a SEPARATE block with a separate job — they select which lens runs, never the change level — so a path registered there is not sensitive here unless it is also registered in this block. An absent or empty block means no path is sensitive and depth falls back to diff width alone.",
       "patternProperties": {
         "^[a-z][a-z0-9-]*$": { "$ref": "#/definitions/sensitivePathClass" }
       },

package/.agents/schemas/lifecycle/merge.unlanded.schema.json

@@ -29,7 +29,8 @@
         "branch-protection-human-required",
         "arm-failure",
         "api-race-other",
-        "predicate-refused"
+        "predicate-refused",
+        "advisory-gate-red"
       ]
     },
     "reason": { "type": "string", "minLength": 1 },

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

@@ -125,6 +125,7 @@
             "arm-failure",
             "api-race-other",
             "predicate-refused",
+            "advisory-gate-red",
             "merged-flip-failed"
           ]
         },

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

@@ -325,6 +325,22 @@ function stripAnchorAndQuery(target) {
   return t;
 }
 
+// Percent-decode a link target's path portion (Story #5090). A correctly
+// encoded Markdown destination escapes URL-reserved characters — a
+// file-based router's `[token]` segment is written `%5Btoken%5D`, the form
+// CommonMark renderers require — but the filesystem knows only the decoded
+// name. The decode is one-way and total: a malformed escape (`%zz`) degrades
+// to the raw string instead of throwing `URIError`, so an undecodable target
+// is resolved exactly as it was before.
+function decodeLinkPath(pathOnly) {
+  if (!pathOnly.includes('%')) return pathOnly;
+  try {
+    return decodeURIComponent(pathOnly);
+  } catch {
+    return pathOnly;
+  }
+}
+
 // --- Slash-token extraction ------------------------------------------------
 
 // Tokens look like `/<lowercase-alphanum-with-hyphens>`. We exclude tokens
@@ -394,8 +410,13 @@ export function checkFile(absPath, repoRoot) {
   // 2. Relative-link resolution.
   for (const { target, line } of extractLinks(masked)) {
     if (isExternalOrInternalAnchor(target)) continue;
-    const pathOnly = stripAnchorAndQuery(target);
-    if (!pathOnly) continue; // pure anchor that survived earlier check
+    const rawPathOnly = stripAnchorAndQuery(target);
+    if (!rawPathOnly) continue; // pure anchor that survived earlier check
+    // Decode AFTER anchor/query stripping — so an escaped `%23` cannot
+    // collapse into an anchor delimiter and truncate the target — and BEFORE
+    // resolution, so the payload-boundary branch below reports the decoded
+    // path rather than the escaped one.
+    const pathOnly = decodeLinkPath(rawPathOnly);
     let resolved;
     if (pathOnly.startsWith('/')) {
       // Treat root-absolute paths as repo-root relative.

package/.agents/scripts/git-cleanup.js

@@ -64,6 +64,7 @@ import {
   probeMergedPr,
   refExists,
 } from './lib/orchestration/git-cleanup/phases/git-probes.js';
+import { probeAncestry } from './lib/orchestration/git-cleanup/phases/merged-tip.js';
 import { parseCleanupArgs } from './lib/orchestration/git-cleanup/phases/parse-args.js';
 import {
   executePrune,
@@ -110,6 +111,7 @@ export {
   planFastForward,
   planStashes,
   probeAllPrs,
+  probeAncestry,
   probeContentEquivalent,
   probeLatestPr,
   probeMergedPr,

package/.agents/scripts/lib/baselines/kinds/crap.js

@@ -673,8 +673,13 @@ export function assessComparisonBasis(compareResult, opts = {}) {
  *
  * Story #791 retired the transitional `bootstrap` exit-0 path: a missing
  * baseline still fails closed. Story #829 (5.29.0) softened `kernelVersion`
- * and `tsTranspilerVersion` drift to **warn**, not fail; `escomplexVersion`
- * mismatch continues to fail closed.
+ * drift to **warn**, not fail, and did the same for `tsTranspilerVersion` —
+ * but that second half was re-escalated to **fatal** once Story #4866 made a
+ * TS row's `startLine` an original-source coordinate resolved through the
+ * transpiler's sourcemap. `startLine` is half the row identity key, so a
+ * transpiler change makes the rows incomparable rather than merely stale; see
+ * the `ts-transpiler-drift` axis below for the two exemptions that bound it.
+ * `escomplexVersion` mismatch has always failed closed.
  */
 /**
  * The one re-seed recipe every coordinate-invalidating axis ends on. Three

package/.agents/scripts/lib/close-validation/projections/crap.js

@@ -36,6 +36,7 @@ import { loadCoverage } from '../../coverage-utils.js';
 import { scanAndScore } from '../../crap-utils.js';
 import { cachedGitFetchSync } from '../../git/cached-fetch.js';
 import { gitSpawn as defaultGitSpawn } from '../../git-utils.js';
+import { SCORABLE_SOURCE_EXT_RE } from '../../source-extensions.js';
 import { MISSING_ARG_REASONS, validateProjectionInputs } from './inputs.js';
 
 /**
@@ -48,9 +49,6 @@ export const DEFAULT_CRAP_TOLERANCE = 0.001;
 /** Framework default for the new-method ceiling (`gates.crap.newMethodCeiling`). */
 export const DEFAULT_NEW_METHOD_CEILING = 30;
 
-/** Extensions the CRAP scanner can score. */
-const SCORABLE = /\.(?:js|mjs|cjs|ts|tsx)$/;
-
 /**
  * Map the shared predicate's fine-grained `missing-*` reason onto the
  * `missing-args` skipped-reason the sibling MI projection reports, so both
@@ -155,8 +153,9 @@ function refreshBaseRef(cwd, baseBranch, git) {
 }
 
 /**
- * Enumerate the Story branch's changed files, narrowed to the extensions
- * the CRAP scanner can score.
+ * Enumerate the Story branch's changed files, narrowed by the shared
+ * scorable-source extension set (`source-extensions.js`) so the projection
+ * selects exactly the files the CRAP scanner walks.
  *
  * @param {{ cwd: string, baseBranch: string, storyBranch: string, git: { gitSpawn: typeof defaultGitSpawn } }} opts
  * @returns {{ ok: true, files: string[] } | { ok: false, detail: string }}
@@ -168,7 +167,10 @@ function diffScorableFiles({ cwd, baseBranch, storyBranch, git }) {
       cwd,
       gitSpawn: git.gitSpawn,
     });
-    return { ok: true, files: files.filter((f) => SCORABLE.test(f)) };
+    return {
+      ok: true,
+      files: files.filter((f) => SCORABLE_SOURCE_EXT_RE.test(f)),
+    };
   } catch (err) {
     return { ok: false, detail: err.message };
   }

package/.agents/scripts/lib/config/ci.js

@@ -5,6 +5,13 @@
  * (default `"trust-ci"`) selects the merge posture — `"trust-ci"` merges once
  * required checks pass, `"strict"` additionally requires a clean review gate.
  *
+ * Story #5096 added `blockOnAdvisoryFailure` (default `true`) and
+ * `advisoryAllowlist` (default `[]`). GitHub native auto-merge waits on
+ * REQUIRED contexts only, so a red ADVISORY gate would otherwise be merged
+ * straight past; these knobs own mandrel's side of that decision. Set
+ * `blockOnAdvisoryFailure: false` to restore the pre-#5096 behaviour verbatim,
+ * or list a job name in `advisoryAllowlist` to exempt just that one.
+ *
  * Retired (no production readers on v2 Story-only delivery): `earlyPr`
  * (Epic early-PR warmup) and `requireChecks` (AutomergePredicate escape hatch
  * whose listener was never landed).
@@ -12,6 +19,8 @@
 
 export const CI_DELIVERY_DEFAULTS = Object.freeze({
   autoMerge: 'trust-ci',
+  blockOnAdvisoryFailure: true,
+  advisoryAllowlist: Object.freeze([]),
 });
 
 /**
@@ -31,6 +40,15 @@ export function getCiDelivery(config) {
       ci.autoMerge === 'trust-ci' || ci.autoMerge === 'strict'
         ? ci.autoMerge
         : CI_DELIVERY_DEFAULTS.autoMerge,
+    blockOnAdvisoryFailure:
+      typeof ci.blockOnAdvisoryFailure === 'boolean'
+        ? ci.blockOnAdvisoryFailure
+        : CI_DELIVERY_DEFAULTS.blockOnAdvisoryFailure,
+    advisoryAllowlist: Array.isArray(ci.advisoryAllowlist)
+      ? ci.advisoryAllowlist.filter(
+          (entry) => typeof entry === 'string' && entry,
+        )
+      : [...CI_DELIVERY_DEFAULTS.advisoryAllowlist],
     watch:
       ci.watch && typeof ci.watch === 'object' ? { ...ci.watch } : undefined,
   };

package/.agents/scripts/lib/config-settings-schema-delivery.js

@@ -389,6 +389,19 @@ const CI_DELIVERY_SCHEMA = {
         "Story #4356 (Epic #4355). Merge posture. 'trust-ci' (default) merges once required checks pass; 'strict' additionally requires a clean review gate.",
       default: CI_DELIVERY_DEFAULTS.autoMerge,
     },
+    blockOnAdvisoryFailure: {
+      type: 'boolean',
+      description:
+        'Story #5096. When true (default), delivery refuses to arm — and disarms — GitHub native auto-merge while a non-required (advisory) check is genuinely red on the PR head and GitHub reports the PR mergeable anyway (mergeStateStatus=UNSTABLE). `--auto` waits on REQUIRED contexts only, so without this a red advisory quality gate merges unattended. Set false to restore the pre-#5096 behaviour verbatim.',
+      default: CI_DELIVERY_DEFAULTS.blockOnAdvisoryFailure,
+    },
+    advisoryAllowlist: {
+      type: 'array',
+      items: { type: 'string' },
+      description:
+        'Story #5096. Check-run names exempt from blockOnAdvisoryFailure — a red run whose name matches exactly never blocks arming. Matching is exact; an unnamed run can never match and always blocks.',
+      default: [...CI_DELIVERY_DEFAULTS.advisoryAllowlist],
+    },
   },
   additionalProperties: false,
 };

package/.agents/scripts/lib/coverage-capture-fullscope.js

@@ -8,7 +8,10 @@
  * logic; behaviour is byte-for-byte the pre-#4981 body.
  */
 import path from 'node:path';
-import { anyChangedUnderTargets } from './coverage-capture.js';
+import {
+  anyChangedUnderTargets,
+  describeFreshness,
+} from './coverage-capture.js';
 
 /**
  * Run the `--skip-when-no-crap-files` check (when requested), the
@@ -72,7 +75,7 @@ export function runFullScopeCapture({
   }
 
   logger.info(
-    `[coverage-capture] Coverage at ${crap.coveragePath} is ${freshness.reason}; running npm run test:coverage…`,
+    `[coverage-capture] Coverage at ${crap.coveragePath} is ${describeFreshness(freshness, crap.targetDirs)}; running npm run test:coverage…`,
   );
   const code = runCaptureImpl({
     cwd: args.cwd,

package/.agents/scripts/lib/coverage-capture.js

@@ -14,12 +14,20 @@ import { spawnSync } from 'node:child_process';
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import {
+  isScorableSourceFile,
+  SCORABLE_SOURCE_EXT_RE,
+} from './source-extensions.js';
 
 /**
  * Walk a directory tree and return the newest mtime (ms since epoch) seen
- * across `.js` and `.mjs` files. Symlinks, missing dirs, and unreadable nodes
- * resolve to 0 so the caller treats "no sources" the same as "ancient sources"
- * — both mean "any existing coverage is fresh enough".
+ * across the scorable source files (`source-extensions.js`) — the same set
+ * the CRAP scanner walks, so freshness tracks exactly what the gate scores.
+ * Symlinks, missing dirs, and unreadable nodes resolve to 0.
+ *
+ * A 0 return means "discovery found nothing", which {@link isCoverageFresh}
+ * treats as an absence of evidence rather than as freshness — see its
+ * `no-sources` contract.
  *
  * Exported for unit testing.
  *
@@ -48,7 +56,7 @@ export function newestSourceMtime(cwd, targetDirs, io = {}) {
         continue;
       }
       if (!entry.isFile()) continue;
-      if (!entry.name.endsWith('.js') && !entry.name.endsWith('.mjs')) continue;
+      if (!isScorableSourceFile(entry.name)) continue;
       try {
         const m = statSync(childAbs).mtimeMs;
         if (m > newest) newest = m;
@@ -83,17 +91,55 @@ export function captureStampPath(cwd, coveragePath) {
   );
 }
 
-const SOURCE_EXT_RE = /\.(?:js|mjs)$/;
+/**
+ * Fold every dirty scorable working-tree file under the scanned dirs into
+ * `hash`, and report how many there were.
+ *
+ * Dirty files are not represented by their index blob SHA, so their on-disk
+ * bytes (or absence) go in explicitly. Split out of
+ * {@link computeContentDigest} to keep that function's complexity at its
+ * committed CRAP floor.
+ *
+ * @param {{
+ *   hash: import('node:crypto').Hash,
+ *   cwd: string,
+ *   readFileSync: typeof fs.readFileSync,
+ *   porcelain: string,
+ * }} opts `porcelain` is raw `git status --porcelain` output.
+ * @returns {number} Count of scorable dirty files folded in.
+ */
+function foldDirtySources({ hash, cwd, readFileSync, porcelain }) {
+  let count = 0;
+  for (const line of porcelain.split('\n').filter((l) => l.length > 3)) {
+    let file = line.slice(3).trim();
+    if (file.includes(' -> ')) file = file.split(' -> ').pop();
+    file = file.replace(/^"|"$/g, '');
+    if (!SCORABLE_SOURCE_EXT_RE.test(file)) continue;
+    count += 1;
+    hash.update(`\0${file}\0`);
+    try {
+      hash.update(readFileSync(path.resolve(cwd, file)));
+    } catch {
+      hash.update('<absent>');
+    }
+  }
+  return count;
+}
 
 /**
- * Compute a stable content digest of the `.js`/`.mjs` sources under
- * `targetDirs`: the `git ls-files -s` listing (mode + blob SHA + path) of
+ * Compute a stable content digest of the scorable sources
+ * (`source-extensions.js`) under `targetDirs`: the `git ls-files -s` listing (mode + blob SHA + path) of
  * tracked content, plus the on-disk bytes of any dirty working-tree files.
  * Checkout/branch churn leaves blob SHAs untouched, so the digest only moves
  * when content actually changes.
  *
  * Returns `null` when the digest cannot be computed (git unavailable, not a
  * repo, empty target list) so callers can fall back to the mtime heuristic.
+ * A target list that matches **no** scorable file is the same "unavailable"
+ * case, not a digest over zero files: this path is the primary freshness
+ * test, so returning a real hash of empty input would pin the artifact
+ * permanently fresh and make the mtime path's fail-closed verdict
+ * unreachable (Story #5076).
  *
  * @param {string} cwd Absolute repo root.
  * @param {string[]} targetDirs Repo-relative directories to digest.
@@ -120,26 +166,19 @@ export function computeContentDigest(cwd, targetDirs, io = {}) {
     const hash = crypto.createHash('sha256');
     const tracked = git('ls-files', '-s', '--', ...dirs)
       .split('\n')
-      .filter((line) => SOURCE_EXT_RE.test(line.trimEnd()));
+      .filter((line) => SCORABLE_SOURCE_EXT_RE.test(line.trimEnd()));
     hash.update(tracked.join('\n'));
 
-    // Dirty working-tree files are not represented by their index blob SHA,
-    // so fold in their on-disk bytes (or absence) explicitly.
-    const dirty = git('status', '--porcelain', '--', ...dirs)
-      .split('\n')
-      .filter((line) => line.length > 3);
-    for (const line of dirty) {
-      let file = line.slice(3).trim();
-      if (file.includes(' -> ')) file = file.split(' -> ').pop();
-      file = file.replace(/^"|"$/g, '');
-      if (!SOURCE_EXT_RE.test(file)) continue;
-      hash.update(`\0${file}\0`);
-      try {
-        hash.update(readFileSync(path.resolve(cwd, file)));
-      } catch {
-        hash.update('<absent>');
-      }
-    }
+    const scorableDirty = foldDirtySources({
+      hash,
+      cwd,
+      readFileSync,
+      porcelain: git('status', '--porcelain', '--', ...dirs),
+    });
+    // Discovery found nothing to digest: hashing the empty input would yield
+    // a constant that can never go stale, so report "unavailable" instead and
+    // let the caller's fail-closed mtime path decide.
+    if (tracked.length + scorableDirty === 0) return null;
     return hash.digest('hex');
   } catch {
     return null;
@@ -231,6 +270,13 @@ function readStampForScope(stamp, requireScope) {
  * under `targetDirs`. Missing files, missing target dirs, or any IO error
  * resolve to `false` so the caller captures rather than trusting stale data.
  *
+ * **Both paths fail closed on an empty source set (Story #5076).** Finding no
+ * scorable source under `targetDirs` means the check learned nothing, so it
+ * reports `{ fresh: false, reason: 'no-sources' }` and the caller captures.
+ * The alternative — treating "found nothing" as "nothing changed" — is how a
+ * `js|mjs`-only selector left the CRAP gate green while measuring nothing in
+ * every TypeScript consumer.
+ *
  * **Scope asymmetry (Story #4981, AC-4).** A stamp written by an incremental
  * capture (`scope: 'incremental'`) only covers the files the diff touched —
  * it must never satisfy a caller that requires the full-scope guarantee
@@ -299,12 +345,36 @@ export function isCoverageFresh({
     statSync,
     readdirSync,
   });
-  if (newestSrc === 0) return { fresh: true, reason: 'no-sources' };
+  // Source discovery found nothing. That is an absence of evidence, never a
+  // freshness guarantee — trusting it silently disables the capture (and with
+  // it the CRAP gate) for any tree the walk cannot see (Story #5076).
+  if (newestSrc === 0) return { fresh: false, reason: 'no-sources' };
   return coverageMtime >= newestSrc
     ? { fresh: true, reason: 'fresh' }
     : { fresh: false, reason: 'stale' };
 }
 
+/**
+ * Render a freshness verdict for the operator-facing capture log.
+ *
+ * Every reason but `no-sources` speaks for itself. That one does not: failing
+ * closed on an empty source walk is correct, but bare it reads as an
+ * unexplained full capture on every run, and the cause is far more often a
+ * `targetDirs` that does not name the project's sources than a genuine
+ * recapture — so the walked dirs and the key to fix are named inline
+ * (Story #5076).
+ *
+ * @param {{ reason?: string }} freshness Verdict from {@link isCoverageFresh}.
+ * @param {string[]} targetDirs The CRAP scan scope that was walked.
+ * @returns {string} The reason, annotated when it needs explaining.
+ */
+export function describeFreshness(freshness, targetDirs) {
+  const reason = freshness?.reason;
+  if (reason !== 'no-sources') return String(reason);
+  const dirs = (targetDirs ?? []).join(', ');
+  return `${reason} — no scorable source file found under [${dirs}]; if that does not name this project's sources, fix quality.gates.crap.targetDirs`;
+}
+
 /**
  * Narrow `changedFiles` to the subset that lives under one of `targetDirs`.
  *