mandrel 2.23.0 → 2.25.0

package/.agents/scripts/lib/story-plan.js

@@ -9,16 +9,24 @@
  *   - DEFAULT_REFINE_THRESHOLD     — seed length below which refinement
  *                                    is auto-suggested.
  *   - REQUIRED_SECTIONS            — canonical section headings the body
- *                                    must carry to be accepted by
- *                                    /single-story-deliver.
+ *                                    must carry itself. Story #4874: the
+ *                                    `## Acceptance` / `## Verify` sections
+ *                                    are deliberately NOT among them —
+ *                                    those lists are the ticket's top-level
+ *                                    machine contract and persist
+ *                                    synthesizes their sections, exactly as
+ *                                    the story-author prompt instructs.
  *   - rankDuplicateCandidates({ seed, openStories, maxResults })
  *                                  — Jaccard-overlap ranking of open
  *                                    Stories whose titles fuzzy-match
  *                                    the seed.
- *   - validateStoryBody(body)      — schema-light shape check:
- *                                    required sections present, no
- *                                    `Epic:` reference, AC checklist
- *                                    non-empty.
+ *   - validateStoryBody(body, contract)
+ *                                  — schema-light shape check against the
+ *                                    canonical Story-body contract: `##
+ *                                    Goal` / `## Changes` present, no
+ *                                    `Epic:` reference, and an
+ *                                    acceptance/verify contract resolvable
+ *                                    from the top-level arrays or the body.
  *   - buildContextEnvelope(opts)   — assemble the context envelope the
  *                                    host LLM consumes.
  */
@@ -26,21 +34,25 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { overlapScore, tokenize } from './duplicate-search.js';
+import { parse as parseStoryBody } from './story-body/story-body.js';
 
 export const DEFAULT_REFINE_THRESHOLD = 200;
 export const DEFAULT_DUPLICATE_MAX_RESULTS = 5;
 export const DEFAULT_DUPLICATE_MIN_SCORE = 0.15;
 
-export const REQUIRED_SECTIONS = [
-  'Context',
-  'Acceptance Criteria',
-  'Out of Scope',
-  'Notes',
-];
+/**
+ * The sections the authored body must carry itself. Story #4874 reconciled
+ * this list with the story-author prompt: the prompt tells the author to
+ * write `acceptance[]` / `verify[]` **once** at the ticket's top level and
+ * omit the matching body sections, so demanding those sections here made a
+ * prompt-faithful body unpersistable and cost a re-author round.
+ */
+export const REQUIRED_SECTIONS = ['Goal', 'Changes'];
+
+/** The contract lists persist synthesizes into the body from the top level. */
+const CONTRACT_FIELDS = /** @type {const} */ (['acceptance', 'verify']);
 
 const EPIC_REF_PATTERN = /^\s*Epic:\s*#\d+/m;
-const AC_HEADING_PATTERN = /^##\s+Acceptance Criteria\s*$/m;
-const CHECKLIST_PATTERN = /^\s*-\s*\[\s?\]/m;
 
 /**
  * Rank open Stories by title-overlap with the seed. Reuses the same
@@ -115,54 +127,137 @@ export function shouldRefine({
 }
 
 /**
- * Schema-light validator for a standalone-Story body. Used by the persist
- * path *and* by tests asserting `--dry-run` output stability. The check
- * is deliberately tolerant of authoring whitespace: it asserts the
- * canonical headings are present, that no `Epic: #N` reference leaks
- * (the standalone contract), and that the Acceptance Criteria section
- * carries at least one unchecked checklist item.
+ * Collect the violations for one contract list (`acceptance` / `verify`).
+ *
+ * The list may be authored at the ticket's top level (the shape the
+ * story-author prompt prescribes) or written into the body as a section —
+ * either satisfies the contract, and the top level is preferred because
+ * persist synthesizes the section from it. Only two shapes are violations:
+ * the list is nowhere, or it is in both places and the two disagree (fail
+ * closed rather than guess which is authoritative, mirroring
+ * `plan-persist`'s `syncContractFieldFromTopLevel`).
+ *
+ * @param {'acceptance'|'verify'} field
+ * @param {unknown} bodyList  The parsed body's section entries.
+ * @param {unknown} topLevel  The ticket's top-level array.
+ * @returns {string[]}
+ */
+function collectContractErrors(field, bodyList, topLevel) {
+  const inBody = (Array.isArray(bodyList) ? bodyList : []).map(String);
+  const inTicket = (Array.isArray(topLevel) ? topLevel : []).map(String);
+  if (inBody.length === 0 && inTicket.length === 0) {
+    return [
+      `${field} must list at least one entry — author it as the ticket's top-level ${field}[] array; persist synthesizes the "## ${field[0].toUpperCase()}${field.slice(1)}" section from it`,
+    ];
+  }
+  if (
+    inBody.length > 0 &&
+    inTicket.length > 0 &&
+    (inBody.length !== inTicket.length ||
+      inBody.some((v, i) => v !== inTicket[i]))
+  ) {
+    return [
+      `${field} disagrees between the body section and the top-level ${field}[] array — author it once, at the top level`,
+    ];
+  }
+  return [];
+}
+
+/**
+ * Schema-light validator for a standalone-Story body, stated against the
+ * same authoring shape the story-author prompt prescribes (Story #4874).
+ *
+ * It parses the body with the canonical Story-body parser and asserts:
+ * a non-empty `## Goal`, at least one `## Changes` entry, no leaking
+ * `Epic: #N` reference (the standalone contract), and an acceptance +
+ * verify contract resolvable from the ticket's top-level arrays **or** the
+ * body's own sections. It deliberately does not demand the `## Acceptance`
+ * / `## Verify` sections of the author — persist synthesizes them.
  *
  * @param {string} body
+ * @param {{ acceptance?: string[], verify?: string[] }} [contract]
+ *   The ticket's top-level contract arrays, when the caller has them.
  * @returns {{ ok:boolean, errors:string[] }}
  */
-export function validateStoryBody(body) {
-  const errors = [];
+export function validateStoryBody(body, contract = {}) {
   if (typeof body !== 'string' || body.trim().length === 0) {
     return { ok: false, errors: ['body is empty'] };
   }
 
-  for (const section of REQUIRED_SECTIONS) {
-    const pattern = new RegExp(`^##\\s+${escapeRegex(section)}\\s*$`, 'm');
-    if (!pattern.test(body)) {
-      errors.push(`missing required section: "## ${section}"`);
-    }
+  let parsed;
+  try {
+    parsed = parseStoryBody(body).body;
+  } catch (err) {
+    return {
+      ok: false,
+      errors: [`body is not a parseable Story body: ${err.message}`],
+    };
   }
 
+  const errors = [];
+  if (typeof parsed.goal !== 'string' || parsed.goal.trim() === '') {
+    errors.push('missing required section: "## Goal"');
+  }
+  if (!Array.isArray(parsed.changes) || parsed.changes.length === 0) {
+    errors.push('missing required section: "## Changes"');
+  }
   if (EPIC_REF_PATTERN.test(body)) {
     errors.push(
       'body contains an "Epic: #N" reference — standalone Stories must not link to an Epic',
     );
   }
-
-  // AC checklist non-empty: extract from "## Acceptance Criteria" to the
-  // next "## " heading (or EOF) and assert at least one checklist item.
-  const acStart = body.search(AC_HEADING_PATTERN);
-  if (acStart !== -1) {
-    const rest = body.slice(acStart);
-    const nextHeading = rest.slice(1).search(/^##\s+/m);
-    const acBlock = nextHeading === -1 ? rest : rest.slice(0, nextHeading + 1);
-    if (!CHECKLIST_PATTERN.test(acBlock)) {
-      errors.push(
-        'Acceptance Criteria section has no unchecked checklist items (`- [ ] ...`)',
-      );
-    }
+  for (const field of CONTRACT_FIELDS) {
+    errors.push(
+      ...collectContractErrors(field, parsed[field], contract?.[field]),
+    );
   }
 
   return { ok: errors.length === 0, errors };
 }
 
-function escapeRegex(s) {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * Render the canonical `## Acceptance` / `## Verify` sections into a body
+ * that omits them, from the ticket's top-level arrays (Story #4874).
+ *
+ * This is the synthesis the story-author prompt promises: the author writes
+ * each list once at top level, and the persisted GitHub issue still reads as
+ * a complete executable document. A body that already carries a section is
+ * returned untouched — `validateStoryBody` has already refused the case
+ * where the two disagree.
+ *
+ * @param {string} body
+ * @param {{ acceptance?: string[], verify?: string[] }} [contract]
+ * @returns {string}
+ */
+export function synthesizeContractSections(body, contract = {}) {
+  let parsed;
+  try {
+    parsed = parseStoryBody(body).body;
+  } catch {
+    return body;
+  }
+  const blocks = [];
+  if (
+    (parsed.acceptance ?? []).length === 0 &&
+    Array.isArray(contract.acceptance) &&
+    contract.acceptance.length > 0
+  ) {
+    const items = contract.acceptance
+      .map((a, i) => `- [ ] AC-${i + 1}: ${a}`)
+      .join('\n');
+    blocks.push(`## Acceptance\n${items}`);
+  }
+  if (
+    (parsed.verify ?? []).length === 0 &&
+    Array.isArray(contract.verify) &&
+    contract.verify.length > 0
+  ) {
+    blocks.push(
+      `## Verify\n${contract.verify.map((v) => `- ${v}`).join('\n')}`,
+    );
+  }
+  if (blocks.length === 0) return body;
+  return `${body.trimEnd()}\n\n${blocks.join('\n\n')}\n`;
 }
 
 /**

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -113,9 +113,9 @@ You MUST respond ONLY with a valid JSON array of objects. No prose, no markdown
 
 The \`acceptance[]\` and \`verify[]\` arrays live at the **top level** of the Story ticket object — that is the machine contract the validator reads. Author each list **once, at top level**, and **omit** the \`## Acceptance\` / \`## Verify\` sections from the authored \`body\` string: persist syncs the top-level arrays into those sections so the GitHub issue stays a complete executable document. The validator resolves both fields from the top level, so an omitted section is the expected shape, not a violation.
 
-If you do write those sections into the \`body\` string anyway, they must mirror the top-level arrays **item for item** — persist fails closed on a disagreement rather than guessing which list is authoritative. Do **not** invent a second criteria list inside \`## Spec\`, and do not author a separate Acceptance Spec / PRD artifact.
+Never hand-mirror either list into the \`body\` — there is no step that asks you to. Persist fails closed on a body section that disagrees with its top-level array rather than guessing which list is authoritative, so writing one anyway only adds a way to be wrong. Do **not** invent a second criteria list inside \`## Spec\`, and do not author a separate Acceptance Spec / PRD artifact.
 
-The serialized \`body\` string renders these markdown sections (in order):
+The **persisted** \`body\` renders these markdown sections (in order) — you author every one of them except \`## Acceptance\` / \`## Verify\`, which persist synthesizes from the top-level arrays:
 
     ## Goal
     <one sentence — why this Story exists>
@@ -130,11 +130,11 @@ The serialized \`body\` string renders these markdown sections (in order):
     - {"path": "<file path>", "assumption": "creates" | "refactors-existing" | "deletes"}
     - ...
 
-    ## Acceptance
+    ## Acceptance          <-- synthesized by persist from acceptance[]; do not author
     - [ ] <testable, observable criterion>
     - ...
 
-    ## Verify
+    ## Verify              <-- synthesized by persist from verify[]; do not author
     - <exact command or test path> (<tier>)
     - ...
 

package/.agents/scripts/lib/ticket-body-sections.js

@@ -235,7 +235,7 @@ export function sliceTicketBodyForDelivery(body) {
   //    survive verbatim.
   const techLoc = locate(working, 'techSpec');
   let techRegion = null;
-  const PLACEHOLDER = 'MANDREL_TECH_SPEC_PLACEHOLDER';
+  const PLACEHOLDER = '\u0000MANDREL_TECH_SPEC_PLACEHOLDER\u0000';
   if (techLoc) {
     const { end } = descriptor('techSpec');
     techRegion = working.slice(techLoc.startIdx, techLoc.endIdx + end.length);

package/.agents/scripts/lib/util/poll-loop.js

@@ -13,6 +13,13 @@
  * `sleep` is exported as the cancellable delay primitive used internally;
  * callers that already have their own cadence (e.g. a continuous ticker)
  * can import it directly.
+ *
+ * `sleepFn` is the inter-tick delay seam (Story #4873). A caller that already
+ * owns a delay seam of its own — the close-and-land merge wait, whose suite
+ * must never actually sleep out a 30s poll interval — passes it here so
+ * adopting this primitive does not cost it that seam. It is called as
+ * `sleepFn(intervalMs, signal)`; a one-argument stub simply ignores the
+ * signal, and the default is the cancellable {@link sleep} below.
  */
 
 /**
@@ -23,11 +30,20 @@
  *   timeoutMs?: number,
  *   signal?: AbortSignal,
  *   logger?: { warn?: Function },
+ *   sleepFn?: (ms: number, signal?: AbortSignal) => Promise<void>,
  * }} opts
  * @returns {Promise<any | undefined>}
  */
 export async function pollUntil(opts) {
-  const { fn, predicate, intervalMs, timeoutMs, signal, logger } = opts;
+  const {
+    fn,
+    predicate,
+    intervalMs,
+    timeoutMs,
+    signal,
+    logger,
+    sleepFn = sleep,
+  } = opts;
   if (typeof fn !== 'function') throw new TypeError('pollUntil: fn required');
   if (typeof predicate !== 'function') {
     throw new TypeError('pollUntil: predicate required');
@@ -52,7 +68,7 @@ export async function pollUntil(opts) {
     if (deadline !== null && Date.now() >= deadline) {
       throw new Error(`pollUntil: timed out after ${timeoutMs}ms`);
     }
-    await sleep(intervalMs, signal);
+    await sleepFn(intervalMs, signal);
   }
   return undefined;
 }

package/.agents/scripts/lib/wave-runner/live-probe.js

@@ -246,7 +246,7 @@ export function createProbeContext({
  * caller tracked in-flight itself; probe mode must put them back.
  *
  * @returns {Promise<{
- *   nodes: Array<{id: number, dependsOn: number[], files: string[], labels: string[]}>,
+ *   nodes: Array<{id: number, dependsOn: number[], files: string[], body: string, labels: string[]}>,
  *   doneIds: Set<number>,
  *   inFlight: number,
  *   blockedIds: number[],
@@ -282,6 +282,11 @@ export async function probeLiveState({
   });
 
   const labelsById = new Map(stories.map((s) => [s.id, s.labels ?? []]));
+  // Bodies ride along with the node so the co-dispatch guard can widen a
+  // declared footprint from the paths a Story's own text names (Story #4875).
+  // They are consumed in-process by `selectReadySet` and never serialized into
+  // the beat envelope, which stays a list of ids.
+  const bodyById = new Map(stories.map((s) => [s.id, s.body ?? '']));
   const inFlightIds = deriveInFlightIds(stories, dispatched);
   // A Story another operator's lease holds occupies a (global) dispatch slot
   // just like an in-flight one: fold it into the in-flight set so it is both
@@ -292,6 +297,7 @@ export async function probeLiveState({
   return {
     nodes: envelope.dag.map((node) => ({
       ...node,
+      body: bodyById.get(node.id) ?? '',
       labels: projectInFlightLabels(
         labelsById.get(node.id) ?? [],
         inFlightIds.has(node.id),

package/.agents/scripts/lib/wave-runner/ready-set.js

@@ -26,10 +26,14 @@
  *     (`agent::done` OR closed issue) so a Story closed manually through
  *     the GitHub UI is recognised as done.
  *   - `storiesOverlap(a, b)` — the file-overlap co-dispatch guard: true
- *     when two Stories' declared file footprints intersect. Two Stories
- *     that would touch the same file MUST NOT be dispatched onto parallel
+ *     when two Stories' file footprints intersect. Two Stories that would
+ *     touch the same file MUST NOT be dispatched onto parallel
  *     `story-<id>` branches in the same beat (they would race the same
- *     path and produce a merge conflict at close).
+ *     path and produce a merge conflict at close). The comparison runs over
+ *     the **widened** footprint (`storyWidenedFootprint`) — a declared
+ *     `changes[]` is treated as a lower bound and widened from the paths the
+ *     Story's own text names, because a guard that trusts a prediction cannot
+ *     prevent the collision nobody predicted (Story #4875).
  *   - `selectReadySet({ stories, doneIds, inFlight, globalCap })` — the
  *     scheduler. Returns the deterministic, overlap-free set of ready
  *     Stories, capped at `globalCap − inFlight`.
@@ -168,6 +172,59 @@ function isGlobPath(path) {
   return path.includes('*') || path.includes('?') || path.includes('{');
 }
 
+/**
+ * Repo-relative file paths as they appear in Story prose: at least one `/`
+ * separator and a short file extension. Deliberately narrow — a token has to
+ * look like a real path before it can widen a footprint and withhold a Story.
+ */
+const PROSE_PATH_RE = /(?:[\w.@~-]+\/)+[\w.@-]+\.[A-Za-z0-9]{1,6}/g;
+
+/**
+ * Scrape file paths a Story's **text** mentions but its `changes[]` never
+ * declared (Story #4875).
+ *
+ * The declared footprint is a planner's *prediction*, and it is systematically
+ * a lower bound: a Story's `## Spec` names the module it must also touch, its
+ * acceptance criteria name the caller that must be updated, and none of that
+ * reaches `changes[]`. The overlap guard exists to stop two Stories racing the
+ * same file, so trusting the declaration outright means the guard is blind to
+ * precisely the collisions nobody predicted.
+ *
+ * Evidence is only ever **added** — nothing here can shrink a declared
+ * footprint, so widening can withhold a Story for a beat but can never
+ * co-dispatch one the declared comparison would have caught.
+ *
+ * @param {StoryRecord} story
+ * @returns {Set<string>}
+ */
+function storyEvidencePaths(story) {
+  const out = new Set();
+  for (const field of [story?.title, story?.body, story?.spec]) {
+    if (typeof field !== 'string' || field === '') continue;
+    for (const match of field.matchAll(PROSE_PATH_RE)) {
+      const trimmed = match[0].trim();
+      if (trimmed) out.add(trimmed);
+    }
+  }
+  return out;
+}
+
+/**
+ * A Story's footprint **widened from observable evidence** — the set the
+ * co-dispatch guard actually compares (Story #4875).
+ *
+ * `declared ∪ scraped-from-prose`. See {@link storyEvidencePaths} for why the
+ * declaration is treated as a lower bound rather than the answer.
+ *
+ * @param {StoryRecord} story
+ * @returns {Set<string>}
+ */
+function storyWidenedFootprint(story) {
+  const out = storyFootprint(story);
+  for (const path of storyEvidencePaths(story)) out.add(path);
+  return out;
+}
+
 /**
  * File-overlap co-dispatch guard. Returns `true` when two Stories' declared
  * file footprints intersect — meaning they would race the same file if
@@ -175,12 +232,19 @@ function isGlobPath(path) {
  * Stories that overlap MUST NOT both appear in one dispatch set; one is
  * withheld until the other clears.
  *
+ * Comparison runs over the **widened** footprint
+ * ({@link storyWidenedFootprint}), not the declaration: a declared `changes[]`
+ * is a lower bound on what a Story will touch, and two Stories whose real edits
+ * collide were being co-dispatched whenever the collision was not predicted
+ * (Story #4875).
+ *
  * Two deliberate asymmetries:
  *
- *   - **An empty footprint means "no known overlap"** → `false`. A Story that
- *     declares no files is never withheld. This is permissive by necessity:
- *     an undeclared footprint carries no information, and withholding on
- *     absence would serialize every run.
+ *   - **An empty footprint means "no known overlap"** → `false`. A Story with
+ *     no declared footprint and no path evidence in its text is never
+ *     withheld. This is permissive by necessity: a genuinely unknown footprint
+ *     carries no information, and withholding on absence would serialize every
+ *     run.
  *   - **A glob footprint overlaps EVERYTHING** → `true` (Story #4539/#4540).
  *     Comparison is exact-string, so a Story declaring
  *     `.agents/scripts/lib/**` would not match another declaring
@@ -193,9 +257,9 @@ function isGlobPath(path) {
  * @returns {boolean}
  */
 export function storiesOverlap(a, b) {
-  const fa = storyFootprint(a);
+  const fa = storyWidenedFootprint(a);
   if (fa.size === 0) return false;
-  const fb = storyFootprint(b);
+  const fb = storyWidenedFootprint(b);
   if (fb.size === 0) return false;
   for (const path of fa) {
     if (isGlobPath(path)) return true;

package/.agents/scripts/lib/workers/combined-mi-crap-worker.js

@@ -24,7 +24,7 @@
  *
  * Message contract — see lib/cpu-pool.js:
  *   IN  : { item: { abs: string, relPath: string, requireCoverage: boolean,
- *                   coverageEntry: object | null } }
+ *                   coverageAvailable?: boolean, coverageEntry: object | null } }
  *         { exit: true }
  *   OUT : { ok: true, result: {
  *           relPath,
@@ -88,7 +88,7 @@ export function handleCombinedMiCrapWorkerMessage(msg, deps = {}) {
       },
     };
   }
-  const { abs, relPath, requireCoverage } = item;
+  const { abs, relPath, requireCoverage, coverageAvailable = true } = item;
   const prepare = deps.prepare ?? prepareSourceForScoring;
   const analyze = deps.analyze ?? analyzeOnce;
 
@@ -150,7 +150,10 @@ export function handleCombinedMiCrapWorkerMessage(msg, deps = {}) {
   }
 
   const { rows, skippedMethodsNoCoverage, resolvedMethods, totalMethods } =
-    finalizeMethodRows(rawCrapRows, { requireCoverage });
+    finalizeMethodRows(rawCrapRows, {
+      requireCoverage,
+      coverageAvailable,
+    });
   return reply({
     miScore,
     crapRows: rows,

package/.agents/scripts/lib/workers/crap-worker.js

@@ -11,7 +11,7 @@
  *
  * Message contract — see lib/cpu-pool.js:
  *   IN  : { item: { abs: string, relPath: string, requireCoverage: boolean,
- *                   coverageEntry: object | null } }
+ *                   coverageAvailable?: boolean, coverageEntry: object | null } }
  *         { exit: true }
  *   OUT : { ok: true, result: {
  *           relPath,
@@ -80,7 +80,7 @@ export function handleCrapWorkerMessage(msg, _coverage, deps = {}) {
       },
     };
   }
-  const { abs, relPath, requireCoverage } = item;
+  const { abs, relPath, requireCoverage, coverageAvailable = true } = item;
 
   // Coverage entry is pre-resolved on the host and attached to the item.
   // `item.coverageEntry` may be explicitly `null` when the file has no
@@ -143,7 +143,10 @@ export function handleCrapWorkerMessage(msg, _coverage, deps = {}) {
     );
   }
 
-  const finalized = finalizeMethodRows(methodRows, { requireCoverage });
+  const finalized = finalizeMethodRows(methodRows, {
+    requireCoverage,
+    coverageAvailable,
+  });
   return {
     kind: 'reply',
     message: {

package/.agents/scripts/lib/workers/maintainability-worker.js

@@ -7,16 +7,20 @@
  * Message contract — see lib/cpu-pool.js:
  *   IN  : { item: string }      — absolute file path to score
  *         { exit: true }        — drain & terminate
- *   OUT : { ok: true, result: { filePath, score: number | null } }
+ *   OUT : { ok: true, result: { filePath, score, unscorable?, reason? } }
  *
  * `score` is `null` only when the file genuinely cannot be read (ENOENT
- * or other I/O error). Parse failures inside escomplex still resolve to
- * `0` to preserve byte-for-byte parity with the pre-pool serial path
- * (calculateForSource swallows parse errors and returns 0).
+ * or other I/O error).
+ *
+ * A file the kernel cannot analyse comes back as `unscorable: true` with the
+ * kernel's own `reason`, rather than as a bare `0`. The `0` is still carried in
+ * `score` for wire compatibility, but it is no longer the only signal — the
+ * point of the flag is that the caller can *report* the file instead of
+ * silently dropping it (see `maintainability-engine.js`'s `UNSCORABLE`).
  */
 
 import { parentPort } from 'node:worker_threads';
-import { calculateForFile } from '../maintainability-engine.js';
+import { scoreFile } from '../maintainability-engine.js';
 
 /**
  * Pure handler for a single inbound worker message. Exported so unit
@@ -24,7 +28,7 @@ import { calculateForFile } from '../maintainability-engine.js';
  * without spawning a real `Worker` thread.
  *
  * @param {unknown} msg
- * @param {{ score?: (filePath: string) => number | null }} [deps]
+ * @param {{ score?: (filePath: string) => { score: number, unscorable: boolean, reason: string|null } }} [deps]
  * @returns {{kind: 'exit'} | {kind: 'reply', message: object}}
  */
 export function handleMaintainabilityWorkerMessage(msg, deps = {}) {
@@ -40,12 +44,13 @@ export function handleMaintainabilityWorkerMessage(msg, deps = {}) {
     };
   }
   const filePath = msg.item;
-  const scoreFn = deps.score ?? calculateForFile;
+  const scoreFn = deps.score ?? scoreFile;
   try {
-    const score = scoreFn(filePath);
+    // `scoreFn` returns `{ score, unscorable, reason }` — spread so the flag
+    // and its reason reach the pool caller intact.
     return {
       kind: 'reply',
-      message: { ok: true, result: { filePath, score } },
+      message: { ok: true, result: { filePath, ...scoreFn(filePath) } },
     };
   } catch (err) {
     // I/O or other unexpected error — surface as a per-item null score