mandrel 2.33.0 → 2.35.0

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`.
  *
@@ -363,20 +433,21 @@ export const COVERAGE_TIMEOUT_EXIT_CODE = 124;
  * `timeout(1)` convention exit code 124 so callers can pattern-match a
  * runaway runner without inspecting signal names.
  *
- * `files` (Story #4981) scopes the spawn to a file list — `npm run
- * test:coverage -- <files...>`, the standard npm convention for forwarding
- * argv to the underlying script (which most test runners, including Node's
- * own, treat as positional file filters). Omitted or empty means the
- * default full-scope invocation, byte-identical to the pre-#4981 argv
- * (AC-5); a non-empty list makes the scope observable on the emitted
- * command line (AC-1).
+ * The spawn takes **no positional file arguments**. Story #4981 forwarded the
+ * changed-file list as `npm run test:coverage -- <files...>` on the premise
+ * that a test runner treats trailing positionals as filters over the suite.
+ * Node's runner does not: it treats each path as a test file to execute, so a
+ * forwarded *source* file runs as a trivially-passing test and the real suite
+ * never runs. `run-coverage.js` discarded the list, which is the only reason
+ * that never bit; Story #5063 measured it and Story #5065 removed the
+ * plumbing rather than leave a parameter whose obvious "fix" empties the
+ * coverage artifact.
  *
  * @param {{
  *   cwd: string,
  *   timeoutMs?: number,
  *   runner?: typeof spawnSync,
  *   log?: (m: string) => void,
- *   files?: string[] | null,
  * }} opts
  * @returns {number}
  */
@@ -385,14 +456,8 @@ export function runCapture({
   timeoutMs,
   runner = spawnSync,
   log = () => {},
-  files = null,
 } = {}) {
-  const scopedFiles = Array.isArray(files) && files.length > 0 ? files : null;
-  const args = [
-    'run',
-    'test:coverage',
-    ...(scopedFiles ? ['--', ...scopedFiles] : []),
-  ];
+  const args = ['run', 'test:coverage'];
   log(`[coverage-capture] ▶ npm ${args.join(' ')}`);
   const spawnOpts = {
     cwd,

package/.agents/scripts/lib/findings/route-finding.js

@@ -13,14 +13,15 @@
  *      stamped into Issue bodies.
  *   3. `routeFinding(finding, { searchIssues, searchCandidates })` — classify a
  *      finding against existing Issues into one of `new | update-existing |
- *      duplicate | regression-of-closed`. Routing is a two-stage pass: a
- *      meaning-first **semantic candidate** pass runs FIRST (when a
- *      `searchCandidates` port is injected, e.g. wired to
- *      `semantic-issue-search.js`), then the exact **fingerprint
- *      confirmation** pass runs SECOND over that candidate pool. When no
- *      semantic port is injected the helper falls back to a fingerprint-only
- *      lookup via the `searchIssues` port. Either way the ports query BOTH
- *      open and closed issues; a closed fingerprint match yields
+ *      duplicate | regression-of-closed`. Routing gathers a candidate pool,
+ *      then confirms identity against it. **Every wired port runs, and their
+ *      results union** (Story #5079): the exact `searchIssues(sha)` lookup is
+ *      what reliably retrieves an Issue by its footer sha, while the
+ *      meaning-first `searchCandidates` pass (wired to
+ *      `semantic-issue-search.js`) widens that pool to catch a reworded
+ *      finding whose sha has drifted. The semantic pass **adds** to the
+ *      fingerprint lookup; it never replaces it. Whichever ports are wired
+ *      query BOTH open and closed issues; a closed fingerprint match yields
  *      `regression-of-closed`.
  *
  * Pure orchestration: no network I/O lives here. The `searchIssues` /
@@ -455,36 +456,97 @@ function confirmCandidates(hits, { sha, semanticKey = '' }) {
 }
 
 /**
- * Route a finding against existing Issues with a two-stage pass.
- *
- * **Stage 1 — semantic candidate search (first).** When a `searchCandidates`
- * port is injected, it runs first to surface issues that *describe the same
- * problem by meaning* across BOTH open and closed issues (and, when the
- * caller wires it, an Epic's sub-issues). This widens the net beyond an exact
- * fingerprint so a reworded title or a moved file does not hide a real
- * duplicate. When no `searchCandidates` port is supplied the helper skips
- * straight to Stage 2 over the `searchIssues` lookup — the legacy
- * fingerprint-only behaviour, preserved verbatim.
- *
- * **Stage 2 — fingerprint confirmation (second).** Whatever candidates Stage 1
- * produced are filtered down to those that actually carry the finding's
- * fingerprint footer, then resolved:
+ * Union candidate pools into one flat pool, keeping first-seen order and
+ * dropping an issue number an earlier pool already contributed.
+ *
+ * The fingerprint pool is passed first, so when both ports return the same
+ * Issue it is that pool's record — the one retrieved by exact identity — that
+ * survives into confirmation. Records without a usable number are left for
+ * {@link confirmCandidates} to reject, exactly as a single port's would be.
+ *
+ * @param {Array<unknown>} pools
+ * @returns {Array<object>}
+ */
+function unionCandidatePools(pools) {
+  const seen = new Set();
+  return pools.flat().filter((issue) => {
+    const number = issue?.number;
+    if (typeof number !== 'number') return true;
+    const fresh = !seen.has(number);
+    seen.add(number);
+    return fresh;
+  });
+}
+
+/**
+ * Gather the candidate pool for a finding from every wired port.
+ *
+ * A run with a single wired port returns that port's result **verbatim**, so
+ * the fingerprint-only wiring (`qa-explore`, and every caller that injects no
+ * semantic port) keeps its behaviour exactly — including how a non-array
+ * return is handled downstream by {@link confirmCandidates}.
+ *
+ * Both ports are awaited together; a rejection from either propagates rather
+ * than degrading silently to a partial pool.
+ *
+ * @param {object} finding
+ * @param {string} sha — the finding's full fingerprint.
+ * @param {{ searchIssues?: Function, searchCandidates?: Function }} ports
+ * @returns {Promise<Array<object>|unknown>}
+ */
+async function gatherCandidates(finding, sha, ports) {
+  const call = (port, arg) => (typeof port === 'function' ? [port(arg)] : []);
+  const pools = await Promise.all([
+    ...call(ports.searchIssues, sha),
+    ...call(ports.searchCandidates, finding),
+  ]);
+  return pools.length === 1 ? pools[0] : unionCandidatePools(pools);
+}
+
+/**
+ * Route a finding against existing Issues: gather candidates, then confirm.
+ *
+ * **Gather — every wired port runs, and their pools union (Story #5079).** The
+ * two ports answer different questions and neither subsumes the other:
+ *
+ * - `searchIssues(sha)` is the **exact** lookup. A fingerprint sha is one
+ *   high-signal term, so it retrieves the Issue whose footer carries it.
+ * - `searchCandidates(finding)` is the **meaning-first** pass. It widens the
+ *   pool to Issues describing the same problem under a different title, so a
+ *   reworded finding or a moved file still confirms by semantic key.
+ *
+ * This was a ternary until Story #5079: an injected semantic port *replaced*
+ * the fingerprint lookup instead of widening it. Production always injects
+ * one, so `searchIssues` was dead code on the live path and dedup rested
+ * entirely on a ~20-token bag-of-words query that does not reliably retrieve
+ * the Issue. The audit loop consequently re-filed Stories it had already
+ * filed, against the workflow's "Never open a duplicate Issue" constraint.
+ * Running both ports and unioning their pools is what closes that loop.
+ *
+ * A port that rejects **propagates**. A pool gathered from only some of its
+ * sources is not a smaller pool, it is an unknown one, so the caller
+ * (`classifyGroupsAgainstGitHub`) must record a degraded lookup rather than
+ * report a confident `new`.
+ *
+ * **Confirm.** The pooled candidates are filtered down to those that actually
+ * carry the finding's fingerprint footer — or, when `semanticKeyConfirm` is
+ * on, its location-based semantic-key footer — then resolved:
  *   - An open match → `update-existing` (or `duplicate` when more than one
  *     open issue carries the fingerprint).
  *   - A closed match (no open match) → `regression-of-closed`.
  *   - No confirmed match → `new`.
  *
- * The decision enum is identical on both paths.
+ * The decision enum is identical however the candidates were gathered.
  *
  * @param {object} finding
  * @param {object} ports
  * @param {(sha: string) => Promise<Array<{ number: number, state: string, body?: string }>>} [ports.searchIssues]
- *   Fingerprint-keyed lookup over open+closed issues. Required when
- *   `searchCandidates` is not supplied.
+ *   Fingerprint-keyed lookup over open+closed issues. Runs whenever it is
+ *   supplied. Required when `searchCandidates` is not.
  * @param {(finding: object) => Promise<Array<{ number: number, state: string, title?: string, body?: string }>>} [ports.searchCandidates]
  *   Meaning-first candidate search over open+closed issues (and Epic
- *   sub-issues). When supplied, runs FIRST; its candidates are then
- *   fingerprint-confirmed.
+ *   sub-issues). Runs whenever it is supplied, alongside `searchIssues` rather
+ *   than instead of it; the union is then confirmed by footer.
  * @param {object} [options]
  * @param {boolean} [options.semanticKeyConfirm=false] — also confirm a
  *   candidate by the location-based semantic-key footer, not the fingerprint
@@ -510,15 +572,14 @@ export async function routeFinding(
   const { full: sha } = fingerprintFinding(finding);
   const semanticKey = options.semanticKeyConfirm ? semanticKeyFor(finding) : '';
 
-  // Stage 1: semantic candidate pass first (when wired); else fingerprint
-  // lookup. Both yield a candidate pool drawn from open AND closed issues.
-  const hits =
-    typeof searchCandidates === 'function'
-      ? await searchCandidates(finding)
-      : await searchIssues(sha);
+  // Gather: every wired port runs, and their pools union (Story #5079).
+  const hits = await gatherCandidates(finding, sha, {
+    searchIssues,
+    searchCandidates,
+  });
 
-  // Stage 2: confirm identity by fingerprint footer (and, when opted in, the
-  // location-based semantic-key footer) over the candidate pool.
+  // Confirm identity by fingerprint footer (and, when opted in, the
+  // location-based semantic-key footer) over the pooled candidates.
   const confirmed = confirmCandidates(hits, { sha, semanticKey });
 
   return decideFromConfirmed(confirmed, sha);
@@ -526,6 +587,8 @@ export async function routeFinding(
 
 export const __testing = {
   MARKER,
+  gatherCandidates,
+  unionCandidatePools,
   SEMANTIC_MARKER,
   SEP,
   confirmCandidates,

package/.agents/scripts/lib/maintainability-utils.js

@@ -6,6 +6,7 @@ import { POOL_SERIAL_THRESHOLD, runOnPool } from './cpu-pool.js';
 import { Logger } from './Logger.js';
 import { scoreFile } from './maintainability-engine.js';
 import { isScored, reportUnscorable } from './maintainability-unscorable.js';
+import { isScorableSourceFile } from './source-extensions.js';
 
 const MAINTAINABILITY_WORKER_URL = new URL(
   './workers/maintainability-worker.js',
@@ -16,17 +17,6 @@ const MAINTAINABILITY_WORKER_URL = new URL(
 // POOL_SERIAL_THRESHOLD docstring for the tuning rationale).
 const SERIAL_THRESHOLD = POOL_SERIAL_THRESHOLD;
 
-const JS_EXTS = new Set(['.js', '.mjs', '.cjs']);
-const TS_EXTS = new Set(['.ts', '.tsx', '.mts', '.cts']);
-const SUPPORTED_EXTS = new Set([...JS_EXTS, ...TS_EXTS]);
-
-/**
- * @returns {boolean} True when the path's extension is one the engines score.
- */
-function isSupportedSourceFile(filePath) {
-  return SUPPORTED_EXTS.has(path.extname(String(filePath)).toLowerCase());
-}
-
 const IGNORED_DIRS = new Set([
   'node_modules',
   '.git',
@@ -68,8 +58,10 @@ export function isIgnoredByGlobs(filePath, ignoreGlobs = [], cwd) {
 }
 
 /**
- * Recursively scans a directory for JS/TS source files. Accepts `.js`,
- * `.mjs`, `.cjs`, `.ts`, `.tsx`, `.mts`, and `.cts`. Directories listed
+ * Recursively scans a directory for JS/TS source files, selecting them by
+ * the shared `SCORABLE_SOURCE_EXTENSIONS` set (`source-extensions.js`) so the
+ * walk, the coverage-freshness check and the close-validation CRAP projection
+ * cannot drift apart. Directories listed
  * in `IGNORED_DIRS` (including `coverage` and `.next`, added in 5.29.0
  * to skip vitest's istanbul HTML scaffolding and Next.js build output)
  * are skipped.
@@ -101,7 +93,7 @@ export function scanDirectory(dir, fileList = [], opts = {}) {
       if (!IGNORED_DIRS.has(entry.name)) {
         scanDirectory(filePath, fileList, opts);
       }
-    } else if (entry.isFile() && isSupportedSourceFile(entry.name)) {
+    } else if (entry.isFile() && isScorableSourceFile(entry.name)) {
       if (isIgnoredByGlobs(filePath, ignoreGlobs, matchCwd)) {
         continue;
       }

package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js

@@ -672,13 +672,30 @@ function renderStoryBodyForCreate(story, idBySlug) {
   const dependencyRefs = story.depends_on.map(
     (slug) => `#${idBySlug.get(slug)}`,
   );
-  const base =
-    dependencyRefs.length === 0
-      ? story.body
-      : serializeStoryBody(
-          { ...story.bodyObject, depends_on: dependencyRefs },
-          { includeFooter: true },
-        );
+  let base = story.body;
+  if (dependencyRefs.length > 0) {
+    // Re-serializing from `bodyObject` is what resolves the sibling slugs to
+    // real issue ids — but `bodyObject` never held the provenance footers
+    // (`assembleOnePlanStory` appends those to the body *string*), so this
+    // branch drops them unless the carry is re-applied. That is the exact
+    // loss site Story #4935 diagnosed, #4939 fixed, and #4956 reverted
+    // wholesale hours later; Story #5056 restored it with a persist-side
+    // regression test that reads the POSTed body.
+    //
+    // `from: story.body` — not the seed — is load-bearing: it re-carries the
+    // identities *this* Story was stamped with under Story #5045 attribution
+    // rather than reintroducing the whole seed's union. `carryProvenanceFooters`
+    // is additive, union-preserving and idempotent, so re-applying is safe by
+    // construction.
+    const reserialized = serializeStoryBody(
+      { ...story.bodyObject, depends_on: dependencyRefs },
+      { includeFooter: true },
+    );
+    base = carryProvenanceFooters({
+      from: story.body,
+      into: reserialized,
+    }).body;
+  }
   return `${base}\n\n${planFingerprintMarker(story.fingerprint)}`;
 }
 

package/.agents/scripts/lib/source-extensions.js

@@ -0,0 +1,76 @@
+/**
+ * source-extensions.js — the single source of truth for which file extensions
+ * the CRAP and maintainability scanners score.
+ *
+ * Three surfaces select "the files the scanner scores" and must agree, because
+ * a selector narrower than the scanner's own walk makes a gate green while
+ * measuring nothing: the maintainability/CRAP directory walk
+ * (`maintainability-utils.js`), the coverage-freshness check
+ * (`coverage-capture.js`), and the close-validation CRAP projection's
+ * changed-file filter (`close-validation/projections/crap.js`). Story #5076
+ * folded all three onto the set below after a TypeScript consumer's entire
+ * source tree was filtered out of the freshness check by a `js|mjs`-only
+ * literal.
+ *
+ * **This module MUST import nothing outside `node:` builtins.**
+ * `coverage-capture.js` runs on the pre-push path; `maintainability-utils.js`
+ * transitively pulls `typhonjs-escomplex` and `typescript`, so the shared set
+ * cannot live there without dragging the scoring engines into every freshness
+ * probe.
+ *
+ * The set is deliberately *not* configurable. Freshness exists only to serve
+ * the CRAP gate, so the contract is "what the scanner walks" — a
+ * consumer-settable extension list would be a second way to mis-scope the same
+ * gate.
+ *
+ * Not to be confused with `transpile.js`'s `TS_EXTS`, which answers a
+ * different question ("does this file need transpiling before scoring?") and
+ * is correctly a subset of this set rather than a fork of it.
+ */
+import path from 'node:path';
+
+/**
+ * Extensions the CRAP and maintainability engines can score, lower-cased and
+ * dot-prefixed. Frozen so a caller cannot mutate the shared set in place.
+ *
+ * Formats the engines cannot parse — `.astro`, `.vue`, `.svelte` — are
+ * deliberately absent: this set selects what the scanner already scores, not
+ * every source file that exists in a consumer's tree.
+ *
+ * Module-private: production consumers select through {@link
+ * SCORABLE_SOURCE_EXT_RE} or {@link isScorableSourceFile}, so exporting the
+ * raw list would be a dead production export.
+ *
+ * @type {readonly string[]}
+ */
+const SCORABLE_SOURCE_EXTENSIONS = Object.freeze([
+  '.js',
+  '.mjs',
+  '.cjs',
+  '.ts',
+  '.tsx',
+  '.mts',
+  '.cts',
+]);
+
+/**
+ * Anchored pattern matching a scorable source path by extension, derived from
+ * {@link SCORABLE_SOURCE_EXTENSIONS} so the list stays the only definition.
+ * Use it where a path arrives as raw text (a `git ls-files` line, a porcelain
+ * status entry) and `path.extname` would be the wrong tool.
+ *
+ * @type {RegExp}
+ */
+export const SCORABLE_SOURCE_EXT_RE = new RegExp(
+  `\\.(?:${SCORABLE_SOURCE_EXTENSIONS.map((ext) => ext.slice(1)).join('|')})$`,
+);
+
+/**
+ * @param {string} filePath Absolute or relative path; only its extension is read.
+ * @returns {boolean} True when the path's extension is one the engines score.
+ */
+export function isScorableSourceFile(filePath) {
+  return SCORABLE_SOURCE_EXTENSIONS.includes(
+    path.extname(String(filePath)).toLowerCase(),
+  );
+}

package/.agents/skills/core/documentation-and-adrs/SKILL.md

@@ -13,7 +13,7 @@ description:
 - Document the **why**, not the what. Capture context, constraints, alternatives considered, and trade-offs — code already shows what was built.
 - Write an ADR for any decision that would be expensive to reverse (framework choice, data model, auth strategy, API architecture, hosting platform).
 - Mandrel ships **two first-class decisions-log layouts** — pick one at onboarding (see [Decisions-log layouts](reference.md#decisions-log-layouts)): the **single-file dated-entry** `docs/decisions.md` (default; best for small projects) or the **index + `docs/decisions/` directory** (MADR-style, one file per ADR; best once the log outgrows a single file). Either way, the canonical ADR sections are **Status, Date, Deciders, Context, Decision, (Alternatives Considered), Consequences**.
-- Mark an ADR's status as `Accepted`, `Superseded by ADR-XXX`, or `Deprecated`. Never silently delete an ADR — supersede it.
+- Mark an ADR's status as `Accepted`, `Superseded by ADR-XXX`, `Deprecated`, or `Reverted (<date>)` — a reverted decision was **undone** rather than replaced, so unlike a superseded one it has no successor to point at. Never silently delete an ADR — supersede it.
 - Do **not** document obvious code; do **not** restate what the code already says. Stale or redundant docs are worse than no docs.
 - Comments explain **non-obvious intent** (the why). If a comment describes what the code does, refactor the code instead.
 - Keep user-facing docs (README, API docs, changelog) updated as part of the change — out-of-date docs are bugs.