mandrel 2.60.0 → 2.61.0

package/.agents/scripts/lib/label-constants.js

@@ -1,43 +1,19 @@
 /**
- * Central source of truth for all GitHub label names used by the orchestrator.
- *
- * Every other module (label-taxonomy, single-story-close.js,
- * stories-wave-tick.js, etc.) should import from here rather than using string literals. Renames
- * land in one place.
+ * Single source of truth for GitHub label names — import these rather than
+ * using string literals.
  */
 
 export const AGENT_LABELS = {
   REVIEW_SPEC: 'agent::review-spec',
   READY: 'agent::ready',
   EXECUTING: 'agent::executing',
-  // Story #2144 — intermediate state owned by `single-story-close.js`. A Story
-  // flips to `agent::closing` after preflight validation succeeds and
-  // the Story PR is opened against `main`. It flips to
-  // `agent::done` only after the close pipeline confirms the PR merge
-  // landed; if the close is killed mid-flight, the Story remains at
-  // `agent::closing` so `/mandrel-deliver` can pick up at the
-  // post-merge phase rather than re-running preflight. The label is the
-  // distinguishing signal between "hung close" and "finished work".
+  // PR open, merge unconfirmed; a killed close stays here so deliver resumes.
   CLOSING: 'agent::closing',
   DONE: 'agent::done',
   BLOCKED: 'agent::blocked',
 };
 
-/**
- * Allowed state-machine transitions across `agent::*` labels.
- *
- * The validator is permissive in the directions that pre-Story #2144
- * lifecycles relied on (e.g. `executing → done` for Tasks, which never
- * route through the closing chokepoint) and restrictive on the post-
- * `closing` exits: once a ticket is at `agent::closing` it may only
- * advance to `done` (merge landed) or fall back to `blocked` (close
- * failed and the operator must intervene).
- *
- * Each key is a source label; each value is the set of permitted target
- * labels reachable in a single transition. Transitions absent from this
- * map MUST be treated as invalid by the validator. Self-transitions
- * (e.g. `executing → executing`) are not permitted.
- */
+/** Absent transitions (and self-transitions) are invalid. */
 export const VALID_TRANSITIONS = {
   'agent::review-spec': ['agent::ready', 'agent::blocked'],
   'agent::ready': ['agent::executing', 'agent::blocked'],
@@ -49,18 +25,13 @@ export const VALID_TRANSITIONS = {
     'agent::closing',
     'agent::done',
   ],
-  // Terminal: no outbound transitions from done. (A ticket can be
-  // reopened by the operator, which removes the label entirely; that
-  // is not modelled as a transition because the from-state at re-open
-  // is `null`, not `agent::done`.)
+  // Terminal. An operator re-open removes the label, so its from-state is
+  // `null`, not `done`.
   'agent::done': [],
 };
 
 /**
- * Returns true when transitioning from `fromState` to `toState` is allowed
- * by {@link VALID_TRANSITIONS}. A `null` / `undefined` `fromState` is
- * treated as the initial-entry edge and permits any state — the writer
- * is establishing a state where there was none.
+ * A `null` / `undefined` `fromState` is initial entry and permits any state.
  *
  * @param {string|null|undefined} fromState
  * @param {string} toState
@@ -75,21 +46,8 @@ export function isValidTransition(fromState, toState) {
 }
 
 /**
- * Ticket-type axis.
- *
- * `STORY` is the only type carrying an execution payload — it is what
- * `/mandrel-deliver` branches, implements and lands.
- *
- * `EPIC` (Story #5139) is a **pure container**: a grouping ticket that holds
- * a `## Goal` paragraph and a child checklist and nothing else. It is never
- * branched, never implemented, and never carries an `agent::*` label — that
- * absence is what keeps it out of the bare `/mandrel-deliver` ready list and
- * outside `lint-issue-body.js`, which is `type::story`-scoped.
- *
- * This is deliberately NOT a revival of the v1 Epic tier. Linkage runs
- * parent→child only (the Epic body's checklist plus native sub-issue edges),
- * so Story bodies stay untouched and the `Epic: #N` footer stays retired and
- * refused. See ADR `20260905-container-epic` in `docs/decisions.md`.
+ * `EPIC` is a pure container that never carries `agent::*`, keeping it out
+ * of the ready list; linkage is parent→child only.
  */
 export const TYPE_LABELS = {
   STORY: 'type::story',
@@ -100,89 +58,36 @@ export const STATUS_LABELS = {
   BLOCKED: 'status::blocked',
 };
 
-/**
- * Acceptance-axis labels for opt-out signalling on Epics that
- * intentionally have no acceptance-table coverage. (Story #4324 retired
- * the `context::tech-spec` / `context::acceptance-spec` label classes —
- * planning content now lives as managed sections of the Epic body. This
- * waiver survives with unchanged meaning: it waives the Epic body's
- * `## Acceptance Table` section instead of a ticket.)
- */
+/** Waives the Epic body's `## Acceptance Table` section. */
 export const ACCEPTANCE_LABELS = {
   N_A: 'acceptance::n-a',
 };
 
 export const ACCEPTANCE_NA = ACCEPTANCE_LABELS.N_A;
 
-/**
- * Meta-axis labels for retrospective signal routing (Epic #2547 — feedback
- * loop). `meta::framework-gap` is applied to issues that surface a defect or
- * missing capability in the framework itself; `meta::consumer-improvement`
- * is applied to issues that surface improvements to a consumer project
- * (workflow tweaks, ergonomic asks, doc polish); `meta::platform-gap` is
- * applied to issues owned by neither — a shared base config, a runner fleet,
- * a cross-repo toolchain. The three mirror the ownership buckets in
- * `lib/github/framework-repo.js`, so a routed filing's label and its
- * destination repository cannot disagree. The `/mandrel-plan` Phase 0
- * fetcher (see `lib/feedback-loop/prior-feedback-fetcher.js`) reads open
- * issues carrying either label and surfaces them to the planner so retro
- * signals are routed into durable substrates rather than lost in chat.
- */
+/** Mirror the ownership buckets in `lib/github/framework-repo.js`. */
 export const META_LABELS = {
   FRAMEWORK_GAP: 'meta::framework-gap',
   CONSUMER_IMPROVEMENT: 'meta::consumer-improvement',
   PLATFORM_GAP: 'meta::platform-gap',
 };
 
-/**
- * Risk-axis labels. Planning/audit metadata only — `risk::high` carries no
- * runtime behaviour (the single runtime pause point is `agent::blocked`, see
- * `.agents/instructions.md` § 1.J); it marks a ticket a human should look at
- * first. Applied by the audit filer to a Story whose merge contains a Critical
- * finding.
- *
- * Named here because it was a bare `'risk::high'` string literal in
- * `audit-to-stories/build-story-body.js` and defined by no taxonomy at all —
- * neither `LABEL_TAXONOMY` nor the audit bootstrap created it, so the audit
- * filer generated a label the repo did not have (Story #4877).
- */
+/** Metadata only — the runtime pause is `agent::blocked`. */
 export const RISK_LABELS = {
   HIGH: 'risk::high',
 };
 
-/**
- * Planning-axis labels (Epic #2880 F7). Currently scoped to the
- * `planning::healthcheck-waived` operator-applied waiver — a historical
- * escape hatch for the retired post-plan readiness healthcheck. The
- * label remains in the taxonomy for tickets that still carry it; the
- * healthcheck CLI itself was deleted in the v2 epic-scripts sweep.
- *
- * Future planning-axis waivers (one per failing exit condition) extend
- * this enum so consumers can reference them by symbol.
- */
+/** Legacy waiver for the retired post-plan healthcheck; kept for old tickets. */
 export const PLANNING_LABELS = {
   HEALTHCHECK_WAIVED: 'planning::healthcheck-waived',
 };
 
-/**
- * Convenience named export so callers can reach the constant without
- * indexing into PLANNING_LABELS — mirrors the ergonomics used by
- * ACCEPTANCE_NA. The literal value is
- * duplicated here (rather than aliased through PLANNING_LABELS) so a
- * grep for `PLANNING_HEALTHCHECK_WAIVED.*planning::healthcheck-waived`
- * matches a single line — see Story #2921 Task #2933 AC #1.
- */
+/** Literal duplicated on purpose so a grep for name and value hits one line. */
 export const PLANNING_HEALTHCHECK_WAIVED = 'planning::healthcheck-waived';
 
 /**
- * Palette for the taxonomy; consumed by label-taxonomy.js and by the
- * feedback loop's just-in-time label mint (`graduator-core.ensureIssueLabels`).
- *
- * `META` and `FRICTION` are not in `LABEL_TAXONOMY`: the bootstrap runs once
- * at repo setup, but `friction::<category>` names are minted from live
- * telemetry and cannot be enumerated ahead of time. The graduator mints both
- * axes on demand instead — Story #4828, where their absence made every
- * `gh issue create` fail and the whole feedback loop file zero.
+ * `META`/`FRICTION` labels are minted on demand by the graduator (friction
+ * names come from live telemetry), not by the bootstrap taxonomy.
  */
 export const LABEL_COLORS = {
   TYPE: '#7057FF',

package/.agents/scripts/lib/label-taxonomy.js

@@ -1,14 +1,6 @@
 /**
- * Shared data structures for GitHub labels and custom fields.
- * Used by the bootstrap script to idempotently configure the project.
- *
- * All label names are sourced from `label-constants.js` so renames only need
- * to happen in one place. Colors come from `LABEL_COLORS` in the same module.
- *
- * v2 deleted the behavioral persona concept (`.agents/personas/` +
- * `persona::*` labels). Role framing for spawns lives in `.agents/agents/`
- * via `delivery.routing.roleScopedAgents`; QA auth identities live in
- * `qa.personas` — neither is a GitHub label axis.
+ * GitHub label and project-field definitions the bootstrap applies
+ * idempotently. Names and colors come from `label-constants.js`.
  */
 
 import {
@@ -21,11 +13,6 @@ import {
 } from './label-constants.js';
 
 /**
- * The ticket-type axis. Both rows share one colour, so they are derived from
- * `[name, description]` pairs rather than restated as full literals — Story
- * #5139 added `type::epic` here, and the derived form absorbs it without
- * growing the file's structural weight.
- *
  * @type {Array<{ name: string, color: string, description: string }>}
  */
 const TYPE_LABEL_ROWS = [
@@ -39,10 +26,8 @@ const TYPE_LABEL_ROWS = [
 
 /** @type {Array<{ name: string, color: string, description: string }>} */
 export const LABEL_TAXONOMY = [
-  // Type
   ...TYPE_LABEL_ROWS,
 
-  // Agent State
   {
     name: AGENT_LABELS.REVIEW_SPEC,
     color: LABEL_COLORS.AGENT,
@@ -71,25 +56,18 @@ export const LABEL_TAXONOMY = [
     description: 'Agent work completed',
   },
 
-  // Status
   {
     name: STATUS_LABELS.BLOCKED,
     color: LABEL_COLORS.STATUS_BLOCKED,
     description: 'Blocked by a dependency',
   },
 
-  // Acceptance axis — explicit opt-out signal for Epics that
-  // intentionally have no acceptance-table coverage (waives the Epic
-  // body's ## Acceptance Table section — Story #4324).
   {
     name: ACCEPTANCE_LABELS.N_A,
     color: LABEL_COLORS.ACCEPTANCE,
     description: 'No acceptance specification required',
   },
 
-  // Planning axis — operator-applied waivers for the planning → delivery
-  // handoff gates. `healthcheck-waived` remains for tickets that still
-  // carry the historical label; the healthcheck CLI was retired.
   {
     name: PLANNING_LABELS.HEALTHCHECK_WAIVED,
     color: LABEL_COLORS.PLANNING,
@@ -108,12 +86,8 @@ export const PROJECT_FIELD_DEFS = [
 ];
 
 /**
- * Canonical lifecycle options for the Status single-select field. These are
- * the three stock GitHub Projects v2 options; granular lifecycle state lives
- * in the `agent::*` labels and `ColumnSync` collapses each label onto one of
- * these three buckets via `LABEL_TO_COLUMN` in
- * `lib/orchestration/column-sync.js`. Order matches the order options appear
- * on a fresh GitHub board.
+ * The stock Projects v2 options, in board order; `column-sync.js` collapses
+ * each `agent::*` label onto one.
  *
  * @type {string[]}
  */

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

@@ -3,45 +3,14 @@ import { install as installAstCompat } from './escomplex-ast-compat.js';
 import { analyzeModule } from './escomplex-kernel.js';
 import { transpileIfNeeded } from './transpile.js';
 
-/**
- * Calculates the maintainability score of a JavaScript source file or string.
- * Uses `typhonjs-escomplex` internally, which provides a maintainability index
- * based on the Halstead Volume, Cyclomatic Complexity, and Lines of Code.
- *
- * The kernel's code generator predates the Babel AST its own parser emits, so
- * ordinary modern syntax (`?.`, `await` in a loop head, a regex in a loop
- * head, object spread in a default parameter) aborts the whole analysis.
- * `escomplex-ast-compat` repairs that before any scoring runs — see that
- * module for the defect and the upstream status.
- */
 installAstCompat();
 
-/**
- * Sentinel score for a file the kernel cannot analyse.
- *
- * A real maintainability index never reaches 0 for runnable code — the
- * escomplex floor is ~10–20 — so 0 has long been used as an out-of-band
- * "unscorable" marker. That overload is the bug: consumers drop `mi === 0`
- * rows, so an unscorable file silently vanishes from the baseline instead of
- * being reported, and no amount of re-seeding can ever give it a row.
- *
- * Deliberately module-private. The numeric return is kept for backwards
- * compatibility, but the *value* is not something a caller should branch on —
- * that is the overload this change exists to stop propagating. Callers that
- * need to tell "unscorable" from "genuinely terrible" read the `unscorable`
- * flag from {@link scoreSource} / {@link scoreFile}.
- */
+/** Branch on the `unscorable` flag, never on this value. */
 const UNSCORABLE = 0;
 
 /**
- * Score a raw string, distinguishing "the kernel could not analyse this" from
- * "this scored badly".
- *
- * @param {string} sourceCode The JavaScript source code.
+ * @param {string} sourceCode
  * @returns {{ score: number, unscorable: boolean, reason: string|null }}
- *   `score` is {@link UNSCORABLE} when `unscorable` is true; `reason` carries
- *   the kernel's own error message so a consumer can report *why* rather than
- *   just omitting the file.
  */
 export function scoreSource(sourceCode) {
   try {
@@ -65,42 +34,28 @@ function unscorable(reason) {
 }
 
 /**
- * Calculate score for a raw string of source code.
- *
- * Returns 0 for unscorable input, which is ambiguous by construction — see
- * {@link UNSCORABLE}. Prefer {@link scoreSource} in new code.
+ * Ambiguous 0 when unscorable — prefer {@link scoreSource}.
  *
- * @param {string} sourceCode The JavaScript source code.
- * @returns {number} Score between 0 and 171. Higher is better.
+ * @param {string} sourceCode
+ * @returns {number}
  */
 export function calculateForSource(sourceCode) {
   return scoreSource(sourceCode).score;
 }
 
 /**
- * Calculate score for a given file. TypeScript and TSX sources are
- * pre-transpiled in memory via `transpileIfNeeded` before being fed to
- * the JS-only escomplex kernel; the score for a TS file is identical to
- * the score the same logic would produce as plain JS, because TS type
- * annotations introduce no control flow.
- *
- * @param {string} filePath Path to the JS/TS source file.
- * @returns {number} Maintainability index, or 0 when the source cannot
- *   be parsed (escomplex parse error or TS transpile failure).
+ * @param {string} filePath
+ * @returns {number}
  */
 export function calculateForFile(filePath) {
   return scoreFile(filePath).score;
 }
 
 /**
- * Score a file, distinguishing "unscorable" from "scored badly".
+ * TS is transpiled first. Transpile and kernel failures need different
+ * fixes, so they are reported separately.
  *
- * The transpile-failure and kernel-failure cases are reported separately
- * because they need different fixes: a transpile failure is usually the
- * consumer's own syntax or `tsconfig`, whereas a kernel failure is the
- * upstream generator gap described in `escomplex-ast-compat.js`.
- *
- * @param {string} filePath Path to the JS/TS source file.
+ * @param {string} filePath
  * @returns {{ score: number, unscorable: boolean, reason: string|null }}
  */
 export function scoreFile(filePath) {
@@ -120,15 +75,7 @@ export function scoreFile(filePath) {
 }
 
 /**
- * Produce a richer maintainability report that includes per-method scores.
- *
- * The module-level index from escomplex is heavily penalised by Halstead
- * volume, which means well-structured but long files (many small helpers)
- * score as "critical" even when no single function is complex. Consumers
- * that need to tier findings by real complexity should use `worstMethod`
- * (the lowest per-method maintainability) and fall back to `moduleScore`
- * for files that contain no methods (scripts that are purely top-level
- * statements).
+ * The module index is Halstead-volume dominated, so tier by `worstMethod`.
  *
  * @param {string} sourceCode
  * @returns {{
@@ -176,9 +123,6 @@ export function calculateReport(sourceCode) {
 }
 
 /**
- * Convenience wrapper that reads a file from disk and produces a report.
- * TypeScript and TSX sources are transpiled in memory before scoring.
- *
  * @param {string} filePath
  * @returns {ReturnType<typeof calculateReport>}
  */
@@ -205,19 +149,7 @@ export function calculateReportForFile(filePath) {
 }
 
 /**
- * Classify a maintainability report into a severity tier.
- *
- * Tiering rules (chosen after the v5.11 calibration issue where clean
- * multi-hundred-line scripts scored 0 at the module level):
- *
- *   - 🔴 critical  — a real hotspot: some method scores < 20, OR the file
- *                    contains no methods and the module scores < 40.
- *   - 🟡 warning   — size- or volume-driven signal: worst method < 50
- *                    OR module score < 65 (but no critical method).
- *   - 🟢 healthy   — every method scores ≥ 50 and module ≥ 65.
- *
- * File-size-driven module-score drops land in the warning tier, not the
- * critical tier — they should nudge the reviewer, not block the sprint.
+ * Size-driven module drops only reach `warning`; `critical` is a real hotspot.
  *
  * @param {ReturnType<typeof calculateReport>} report
  * @returns {'critical' | 'warning' | 'healthy' | 'parse-error'}

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

@@ -1,24 +1,12 @@
 /**
- * maintainability-unscorable.js — reporting for files the MI kernel cannot
- * analyse.
- *
- * A file the kernel throws on has no maintainability index, so it gets no
- * baseline row — a phantom `mi: 0` would poison the `min`/p50 rollup and let
- * real regressions hide behind it. Dropping the row is therefore correct; doing
- * it *silently* is not. Without a report, an unscorable file is
- * indistinguishable from a file nobody added yet: the scorer emits nothing, the
- * scope gate sees an absence it cannot explain, and re-seeding the baseline can
- * never produce the missing row no matter how many times it runs.
- *
- * Kept separate from `maintainability-utils.js` so the scoring path stays about
- * scoring and this stays about explaining.
+ * maintainability-unscorable.js — report files the MI kernel cannot analyse.
+ * They get no baseline row (a phantom `mi: 0` would poison the rollup), but
+ * dropping them silently makes them indistinguishable from unseeded files.
  */
 
 import { Logger } from './Logger.js';
 
 /**
- * Report every unscorable file, then summarise.
- *
  * @param {Array<{ relPath: string, unscorable?: boolean, reason?: string|null }>} perFile
  * @returns {number} how many files were unscorable, for the caller's own use.
  */
@@ -41,16 +29,8 @@ export function reportUnscorable(perFile) {
 }
 
 /**
- * Whether a per-file entry carries a real maintainability index and so belongs
- * in the baseline.
- *
- * An unscorable entry carries the sentinel score, not an index — letting it
- * through would write an `mi: 0` phantom and drag the rollup floor down with it
- * (Story #2467). `score === null` is the separate I/O-failure case.
- *
- * Tests for a *number* rather than `score !== null`, because the latter passes
- * anything absent: `undefined !== null` is true, so a missing entry or one with
- * no `score` key at all would have been treated as scored.
+ * Tests for a number, not `score !== null` (which lets `undefined` through);
+ * unscorable entries carry a sentinel, not an index.
  *
  * @param {{ score?: number|null, unscorable?: boolean }} entry
  * @returns {boolean}

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

@@ -13,8 +13,6 @@ const MAINTAINABILITY_WORKER_URL = new URL(
   import.meta.url,
 );
 
-// Pool-vs-serial cutover — single-sourced in cpu-pool.js (see the
-// POOL_SERIAL_THRESHOLD docstring for the tuning rationale).
 const SERIAL_THRESHOLD = POOL_SERIAL_THRESHOLD;
 
 const IGNORED_DIRS = new Set([
@@ -28,24 +26,9 @@ const IGNORED_DIRS = new Set([
 ]);
 
 /**
- * Compiled-matcher cache for `isIgnoredByGlobs`, keyed on the pattern list.
- *
- * `minimatch(path, glob)` re-parses `glob` into an AST on every call, so the
- * scan was paying O(files × globs) glob *compilations* to answer O(files ×
- * globs) glob *matches* — 12–17 ms over the 619-file tree against 0.5 ms
- * once the patterns are compiled (Story #5109). The number of distinct
- * pattern lists in a process is tiny (one per gate), and each list is
- * config-derived and immutable, so an unbounded `Map` keyed on the joined
- * patterns is bounded in practice.
- *
- * Each entry also memoises the per-path verdict. The baseline gates ask the
- * same question about the same path many times over — `crap.json` carries
- * thousands of method rows spread over a few hundred files, and the evaluate
- * phase filters every row — so the second and later asks about a path cost a
- * `Map` lookup instead of a globstar walk. Both caches are keyed on
- * config-derived, immutable inputs, and both are bounded by the tree the
- * process is scanning.
- *
+ * Compiled matchers plus a per-path verdict memo, keyed on the pattern list:
+ * functional `minimatch()` recompiles per call, and the gates ask about the
+ * same path once per CRAP row. Inputs are immutable config, so it is bounded.
  * `\u0000` is the join separator because it cannot occur in a glob, so two
  * different lists cannot collide onto one key.
  *
@@ -54,12 +37,7 @@ const IGNORED_DIRS = new Set([
 const IGNORE_MATCHER_CACHE = new Map();
 
 /**
- * Compile (once) the `Minimatch` instances for a pattern list, alongside the
- * per-path verdict memo that shares their lifetime.
- *
- * Non-string patterns are dropped rather than compiled — `minimatch()` would
- * have thrown on them, and the functional call site never fed it any, so
- * dropping preserves the observable result set.
+ * Non-string patterns are dropped rather than compiled.
  *
  * @param {string[]} ignoreGlobs
  * @returns {{matchers: import('minimatch').Minimatch[], verdicts: Map<string, boolean>}}
@@ -79,22 +57,10 @@ function ignoreMatcherEntry(ignoreGlobs) {
 }
 
 /**
- * Test whether an absolute (or repo-relative) file path matches any of the
- * configured `ignoreGlobs`. This is the single source of truth for how the
- * maintainability scorer decides a file is ignored: both the full-scope
- * directory walk (`scanDirectory` below) and the diff-scope file-list path
- * in `refresh-service.js` MUST funnel through it so an `ignoreGlobs`-listed
- * file is excluded identically in both scopes (a diff-scope refresh that
- * skipped this check would let an ignored file poison the `rollup["*"].min`
- * floor — see `buildDefaultMaintainabilityScorer`).
- *
- * Matching mirrors `scanDirectory`: the path is reduced to a canonicalised,
- * POSIX, repo-relative form and tested against each glob with minimatch's
- * `{ dot: true }` so dot-prefixed roots like `.agents/` match. The patterns
- * are compiled at most once per distinct list (see `IGNORE_MATCHER_CACHE`);
- * the matched set is identical to the functional `minimatch()` call this
- * replaced, which is what the `gate-scan-fast-path` test pins over the real
- * configured `ignoreGlobs`.
+ * The single ignore-glob test: the full-scope walk and the diff-scope refresh
+ * both funnel through it, or an ignored file could poison the
+ * `rollup["*"].min` floor in one scope. `{ dot: true }` lets `.agents/`
+ * match.
  *
  * @param {string} filePath absolute or relative path to the source file
  * @param {string[]} ignoreGlobs minimatch patterns; empty/absent is a no-op
@@ -102,9 +68,6 @@ function ignoreMatcherEntry(ignoreGlobs) {
  * @returns {boolean} true when the file matches at least one ignore glob
  */
 /**
- * Reduce an absolute-or-relative path to the canonicalised, POSIX,
- * repo-relative form the ignore patterns are written against.
- *
  * @param {string} filePath
  * @param {string} matchCwd
  * @returns {string}
@@ -118,14 +81,7 @@ function canonicalRelPath(filePath, matchCwd) {
 }
 
 /**
- * Answer "does this path match any of the entry's patterns", consulting and
- * populating the entry's verdict memo.
- *
- * Split out of `isIgnoredByGlobs` rather than inlined: the memo's
- * hit/miss test is a branch, and folding it into the caller pushed that
- * function from cyclomatic 4 to 5 — over the per-method CRAP contract the
- * pre-push preview enforces. The lookup belongs beside the cache it reads
- * anyway, and the hot function keeps a flat shape.
+ * Split out to keep `isIgnoredByGlobs` under the per-method CRAP contract.
  *
  * @param {{matchers: import('minimatch').Minimatch[], verdicts: Map<string, boolean>}} entry
  * @param {string} relPath Canonicalised, POSIX, repo-relative path.
@@ -149,22 +105,12 @@ export function isIgnoredByGlobs(filePath, ignoreGlobs = [], cwd) {
 }
 
 /**
- * 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.
+ * Recursively collect scorable source files, using the shared extension set
+ * so the walk, coverage freshness and CRAP projection cannot drift apart.
  *
  * @param {string} dir
  * @param {string[]} fileList
  * @param {{ ignoreGlobs?: string[], cwd?: string }} [opts]
- *   `ignoreGlobs` — minimatch patterns matched against the canonicalised
- *   repo-relative path of each discovered file. Files whose path matches
- *   any pattern are excluded before scoring. Absent/empty is a no-op.
- *   `cwd` — root used to compute repo-relative paths for glob matching;
- *   defaults to `process.cwd()` when omitted.
  * @returns {string[]}
  */
 export function scanDirectory(dir, fileList = [], opts = {}) {
@@ -195,35 +141,13 @@ export function scanDirectory(dir, fileList = [], opts = {}) {
 }
 
 /**
- * Calculates maintainability scores for a list of file paths.
- *
- * Each file's transpile-then-analyze unit is dispatched to a
- * worker_threads pool whose width `runOnPool` resolves. Workers
- * are recycled across files so TypeScript loads at most once per
- * worker. The pool is bypassed for batches of fewer than
- * `SERIAL_THRESHOLD` files because spawn overhead dominates at small
- * sizes — the in-process path matches the pre-pool serial behaviour
- * byte-for-byte.
- *
- * Output is sorted by relative file path so the returned object is
- * insertion-order-stable regardless of which worker happened to
- * finish first. Files that fail to read/transpile/parse are dropped
- * from the result (matching the pre-pool log-and-continue contract);
- * worker-side per-item failures surface as a `null` score that is
- * filtered out before assembly.
- *
- * A file the kernel cannot analyse is also dropped — a phantom `mi: 0` row
- * poisons the rollup — but it is **reported** on the way out, with the
- * kernel's own error text, and the count is summarised at the end of the run.
- * Silently omitting these is what let a file sit unmeasured indefinitely: the
- * scorer emitted no row, so no amount of re-seeding could ever produce one,
- * and nothing said so.
+ * Score files on a worker pool (serial below the cutover, where spawn cost
+ * dominates). Output is sorted by path so it is stable across worker timing.
+ * Failed and unscorable files are dropped — a phantom `mi: 0` poisons the
+ * rollup — but unscorable ones are reported, never silently omitted.
  *
  * @param {string[]} paths
- * @param {{serialThreshold?: number}} [opts] `serialThreshold` overrides the
- *   pool-vs-serial cutover for this call only. Production callers omit it;
- *   the parity tests use it to drive the pooled path on a small fixture set
- *   rather than materialising 256 files to clear the cutover.
+ * @param {{serialThreshold?: number}} [opts] Test seam for the cutover.
  * @returns {Promise<Record<string, number>>}
  */
 export async function calculateAll(paths, opts = {}) {