mandrel 1.58.0 → 1.59.0

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

@@ -6,22 +6,17 @@ import {
   coverageForMethodInEntry,
   findCoverageEntry,
 } from './coverage-utils.js';
-import { runOnPool } from './cpu-pool.js';
+import { POOL_SERIAL_THRESHOLD, runOnPool } from './cpu-pool.js';
 import { crapFormula } from './crap-engine.js';
 import { Logger } from './Logger.js';
-import {
-  resolveTsTranspilerVersion,
-  scanDirectory,
-  transpileIfNeeded,
-} from './maintainability-utils.js';
+import { scanDirectory } from './maintainability-utils.js';
+import { resolveTsTranspilerVersion, transpileIfNeeded } from './transpile.js';
 
 const CRAP_WORKER_URL = new URL('./workers/crap-worker.js', import.meta.url);
 
-// Below this batch size the pool's spawn overhead dominates — fall
-// back to in-process serial scoring. The full repo (~200+ files)
-// always takes the pool path; tests with handful-of-files fixtures
-// stay serial and remain byte-identical to the pre-pool output.
-const SERIAL_THRESHOLD = 8;
+// 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;
 // 1.1.0 — TypeScript support landed in 5.29.0. Bumped from 1.0.0 because
 // the scanner now emits CRAP rows for TS/TSX paths that the previous
 // kernel could never reach. The CRAP formula and per-method scoring

package/.agents/scripts/lib/dynamic-workflow/documentation-report-contract.js

@@ -0,0 +1,87 @@
+// .agents/scripts/lib/dynamic-workflow/documentation-report-contract.js
+import { assertSectionsContract } from './report-contract-core.js';
+
+/**
+ * The `audit-documentation` report contract (Story #4024).
+ *
+ * This is the **single source of truth** for the report shape that BOTH the
+ * sequential lens (`.agents/workflows/audit-documentation.md` Step 3) and the
+ * orchestrated dynamic-workflow path
+ * (`.claude/workflows/audit-documentation.workflow.js`) MUST emit to
+ * `{{auditOutputDir}}/audit-documentation-results.md`. Keeping it here lets
+ * the contract-tier test assert report conformance against one definition
+ * rather than re-deriving headings from prose in two places.
+ *
+ * @module dynamic-workflow/documentation-report-contract
+ */
+
+/** The artifact filename the lens writes under `auditOutputDir`. */
+export const REPORT_ARTIFACT_BASENAME = 'audit-documentation-results.md';
+
+/**
+ * The required top-level (`##`) section headings, in document order, that the
+ * lens markdown's Step 3 template defines. A conformant report MUST contain
+ * each of these headings; the orchestrated path assembles its verified
+ * findings into exactly this skeleton.
+ */
+export const REQUIRED_SECTIONS = Object.freeze([
+  'Executive Summary',
+  'Target Set Coverage',
+  'Detailed Findings',
+]);
+
+/** The H1 title the report opens with. */
+export const REPORT_TITLE = 'Documentation Audit Report';
+
+/**
+ * The required field labels inside each `### <finding>` block under
+ * `## Detailed Findings`. Mirrors the strict per-finding structure in the
+ * lens template.
+ */
+export const FINDING_FIELDS = Object.freeze([
+  'Category',
+  'Impact',
+  'Current State',
+  'Recommendation & Rationale',
+  'Agent Prompt',
+]);
+
+/**
+ * The finding categories the per-finding `Category` field draws from. These
+ * mirror the lens's Step 3 template enumeration: deterministic-gate findings
+ * (Generator Drift, Link Integrity) plus semantic-verification findings
+ * (Broken Instruction, Stale Description, Missing Coverage).
+ */
+export const FINDING_CATEGORIES = Object.freeze([
+  'Broken Instruction',
+  'Stale Description',
+  'Missing Coverage',
+  'Generator Drift',
+  'Link Integrity',
+]);
+
+/**
+ * The impact buckets the Executive Summary and per-finding `Impact` field draw
+ * from. The lens speaks in High/Medium/Low; this list is the canonical
+ * taxonomy the downstream `audit-to-stories` consumer maps onto Story
+ * priority.
+ */
+export const IMPACT_LEVELS = Object.freeze(['High', 'Medium', 'Low']);
+
+/**
+ * Assert that a rendered markdown report conforms to the contract: it has the
+ * H1 title and every required `##` section heading. Returns a structured
+ * result rather than throwing, so callers (tests, the orchestrated path's
+ * self-check) can report precisely which sections are missing.
+ *
+ * Pure function — string analysis only.
+ *
+ * @param {string} markdown - The rendered report body.
+ * @returns {{ conformant: boolean, missingSections: string[], hasTitle: boolean }}
+ */
+export function assertReportContract(markdown) {
+  return assertSectionsContract(markdown, {
+    title: REPORT_TITLE,
+    requiredSections: REQUIRED_SECTIONS,
+  });
+}

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

@@ -231,25 +231,28 @@ export function __setSleep(fn, opts = {}) {
 }
 
 /**
- * Run `git fetch …` with a bounded retry loop that only triggers on known
- * packed-refs lock-contention signatures. Non-contention failures surface
- * immediately (no retry). Success short-circuits the loop.
+ * Shared bounded retry loop for git commands that can hit packed-refs lock
+ * contention. Only contention signatures trigger a retry — non-contention
+ * failures surface immediately, and success short-circuits the loop.
  *
  * Backoff schedule: 250ms, 500ms, 1000ms (3 retries → 4 attempts total).
  * Deliberately no global lock — a mutex would erase the parallelism the
- * worktree-isolation model is designed to enable.
+ * worktree-isolation model is designed to enable. The schedule and the
+ * jitter policy (`_sleep` / `_jitterFactor` seams) live only here so a
+ * backoff tuning change has a single point of application.
  *
  * @param {string} cwd
- * @param {...string} args - Arguments after `fetch` (e.g. `'origin'`).
+ * @param {string[]} argvPrefix - Leading git argv (e.g. `['fetch']`).
+ * @param {string[]} args - Trailing arguments (e.g. `['origin']`).
  * @returns {Promise<{ status: number, stdout: string, stderr: string, attempts: number }>}
  */
-export async function gitFetchWithRetry(cwd, ...args) {
+async function gitWithContentionRetry(cwd, argvPrefix, args) {
   const backoff = [250, 500, 1000];
   let attempt = 0;
   let last;
   for (;;) {
     attempt++;
-    last = gitSpawn(cwd, 'fetch', ...args);
+    last = gitSpawn(cwd, ...argvPrefix, ...args);
     if (last.status === 0) return { ...last, attempts: attempt };
     if (!isPackedRefsContention(last.stderr))
       return { ...last, attempts: attempt };
@@ -260,6 +263,18 @@ export async function gitFetchWithRetry(cwd, ...args) {
   }
 }
 
+/**
+ * Run `git fetch …` with the bounded packed-refs-contention retry loop
+ * (see `gitWithContentionRetry`).
+ *
+ * @param {string} cwd
+ * @param {...string} args - Arguments after `fetch` (e.g. `'origin'`).
+ * @returns {Promise<{ status: number, stdout: string, stderr: string, attempts: number }>}
+ */
+export function gitFetchWithRetry(cwd, ...args) {
+  return gitWithContentionRetry(cwd, ['fetch'], args);
+}
+
 /**
  * Run `git pull --rebase …` with the same bounded retry loop as
  * `gitFetchWithRetry`. Packed-refs contention can occur during pulls
@@ -269,21 +284,8 @@ export async function gitFetchWithRetry(cwd, ...args) {
  * @param {...string} args - Arguments after `pull --rebase` (e.g. `'origin', 'main'`).
  * @returns {Promise<{ status: number, stdout: string, stderr: string, attempts: number }>}
  */
-export async function gitPullWithRetry(cwd, ...args) {
-  const backoff = [250, 500, 1000];
-  let attempt = 0;
-  let last;
-  for (;;) {
-    attempt++;
-    last = gitSpawn(cwd, 'pull', '--rebase', ...args);
-    if (last.status === 0) return { ...last, attempts: attempt };
-    if (!isPackedRefsContention(last.stderr))
-      return { ...last, attempts: attempt };
-    if (attempt > backoff.length) return { ...last, attempts: attempt };
-    const base = backoff[attempt - 1];
-    const jitter = Math.floor(Math.random() * base * _jitterFactor);
-    await _sleep(base + jitter);
-  }
+export function gitPullWithRetry(cwd, ...args) {
+  return gitWithContentionRetry(cwd, ['pull', '--rebase'], args);
 }
 
 /**

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

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import escomplex from 'typhonjs-escomplex';
-import { transpileIfNeeded } from './maintainability-utils.js';
+import { transpileIfNeeded } from './transpile.js';
 
 /**
  * Calculates the maintainability score of a JavaScript source file or string.

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

@@ -1,119 +1,24 @@
 import fs from 'node:fs';
-import { createRequire } from 'node:module';
 import path from 'node:path';
 import { minimatch } from 'minimatch';
 import { canonicalise as canonicalisePath } from './baselines/path-canon.js';
-import {
-  write as writeBaselineEnvelope,
-  writeFile as writeBaselineFile,
-} from './baselines/writer.js';
-import { runOnPool } from './cpu-pool.js';
+import { POOL_SERIAL_THRESHOLD, runOnPool } from './cpu-pool.js';
 import { Logger } from './Logger.js';
 import { calculateForFile } from './maintainability-engine.js';
 
-const require = createRequire(import.meta.url);
-
 const MAINTAINABILITY_WORKER_URL = new URL(
   './workers/maintainability-worker.js',
   import.meta.url,
 );
 
-// Below this batch size the pool's spawn overhead dominates — fall back
-// to in-process serial scoring for `--changed-since` runs that touch
-// only a handful of files. Tuned against the test suite's tmpdir
-// fixtures (n=2 stays serial; the full repo n≈470 takes the pool path).
-const SERIAL_THRESHOLD = 8;
+// 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 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]);
 
-let _ts = null;
-let _tsLoadFailed = false;
-
-function loadTypeScript() {
-  if (_ts) return _ts;
-  if (_tsLoadFailed) return null;
-  try {
-    _ts = require('typescript');
-    return _ts;
-  } catch {
-    _tsLoadFailed = true;
-    return null;
-  }
-}
-
-/**
- * Resolve the `typescript` package version, used to stamp baselines so
- * consumers can detect transpiler drift. Returns `'0.0.0'` when the
- * dependency is unresolvable — callers treat that sentinel as "unknown
- * environment" and may refuse to persist a baseline that includes TS rows.
- *
- * @returns {string}
- */
-export function resolveTsTranspilerVersion() {
-  const ts = loadTypeScript();
-  if (ts && typeof ts.version === 'string') return ts.version;
-  return '0.0.0';
-}
-
-function isTypeScriptPath(filePath) {
-  return TS_EXTS.has(path.extname(String(filePath)).toLowerCase());
-}
-
-/**
- * Pre-transpile TypeScript or TSX sources to JavaScript that the
- * Esprima-based escomplex kernel can parse. Returns the input unchanged
- * for `.js` / `.mjs` / `.cjs` paths.
- *
- * Type annotations introduce no control flow, so the transpiled output
- * scores identically to the original TS for cyclomatic complexity,
- * Halstead volume, and the maintainability index. `.tsx` uses the
- * `react-jsx` emit so JSX expressions become function calls escomplex
- * can read; `.preserve` would leave JSX in the output and Esprima would
- * choke on it.
- *
- * On transpile failure the helper returns `null` — callers treat that
- * as "skip this file" rather than crashing the scan.
- *
- * @param {string} filePath
- * @param {string} source
- * @returns {string|null}
- */
-export function transpileIfNeeded(filePath, source) {
-  if (!isTypeScriptPath(filePath)) return source;
-  const ts = loadTypeScript();
-  if (!ts) {
-    Logger.warn(
-      `[Maintainability] ⚠ typescript package not resolvable; cannot score ${filePath}. ` +
-        "Install with 'npm install --save-dev typescript' (peer dep, >=5.0.0).",
-    );
-    return null;
-  }
-  try {
-    const result = ts.transpileModule(source, {
-      compilerOptions: {
-        target: ts.ScriptTarget.ESNext,
-        module: ts.ModuleKind.ESNext,
-        isolatedModules: true,
-        noEmitHelpers: true,
-        importHelpers: false,
-        removeComments: false,
-        jsx: ts.JsxEmit.ReactJSX,
-        sourceMap: false,
-      },
-      fileName: path.basename(filePath),
-      reportDiagnostics: false,
-    });
-    return result.outputText;
-  } catch (err) {
-    Logger.warn(
-      `[Maintainability] ⚠ TS transpile failed for ${filePath}: ${err?.message ?? err}; skipping.`,
-    );
-    return null;
-  }
-}
-
 /**
  * @returns {boolean} True when the path's extension is one the engines score.
  */
@@ -121,94 +26,6 @@ function isSupportedSourceFile(filePath) {
   return SUPPORTED_EXTS.has(path.extname(String(filePath)).toLowerCase());
 }
 
-/**
- * Loads the current maintainability baseline from disk. The on-disk path is
- * resolved by the caller via {@link getBaselines}; passing it explicitly
- * removes the silent-default behaviour the framework dropped in Epic #730
- * Story 5.5.
- *
- * @param {string} baselinePath  Repo-relative or absolute path to the baseline
- *   JSON. Required.
- * @returns {Record<string, number>}
- */
-/**
- * Story #1895: project the canonical maintainability envelope back to the
- * legacy flat `{ path: mi }` map so existing gate consumers keep working
- * without churn — Story #1912 will replace this shim with the shared
- * reader. Returns the parsed input unchanged when it doesn't look like an
- * envelope (legacy flat shape stays flat).
- */
-function projectMaintainabilityEnvelopeToFlat(parsed) {
-  if (
-    !parsed ||
-    typeof parsed !== 'object' ||
-    Array.isArray(parsed) ||
-    !Array.isArray(parsed.rows) ||
-    typeof parsed.$schema !== 'string'
-  ) {
-    return parsed;
-  }
-  const flat = {};
-  for (const row of parsed.rows) {
-    if (row && typeof row.path === 'string' && typeof row.mi === 'number') {
-      flat[row.path] = row.mi;
-    }
-  }
-  return flat;
-}
-
-export function getBaseline(baselinePath) {
-  if (typeof baselinePath !== 'string' || baselinePath.length === 0) {
-    throw new TypeError(
-      'maintainability-utils.getBaseline: baselinePath is required (Epic #730 ' +
-        'Story 5.5 — callers resolve the path via getBaselines(config).maintainability.path).',
-    );
-  }
-  const abs = path.isAbsolute(baselinePath)
-    ? baselinePath
-    : path.resolve(process.cwd(), baselinePath);
-  if (!fs.existsSync(abs)) return {};
-  try {
-    const parsed = JSON.parse(fs.readFileSync(abs, 'utf-8'));
-    return projectMaintainabilityEnvelopeToFlat(parsed);
-  } catch (err) {
-    Logger.warn(`[Maintainability] Failed to parse baseline: ${err.message}`);
-    return {};
-  }
-}
-
-/**
- * Saves a new maintainability baseline to disk at `baselinePath`.
- *
- * Accepts the legacy flat `{ path: mi }` shape for backwards compatibility
- * with existing callers (`regenerateMainFromTree`, refresh helpers). The
- * map is transformed into the canonical envelope shape (`$schema`,
- * `kernelVersion`, `generatedAt`, `rollup`, `rows`) via the shared
- * `lib/baselines/writer.js` pipeline before being persisted, so every
- * write produces a file that round-trips through `lib/baselines/reader.js`
- * without schema errors.
- *
- * @param {Record<string, number>} baseline  path→MI flat map.
- * @param {string} baselinePath  Required — caller supplies via getBaselines().
- */
-export function saveBaseline(baseline, baselinePath) {
-  if (typeof baselinePath !== 'string' || baselinePath.length === 0) {
-    throw new TypeError(
-      'maintainability-utils.saveBaseline: baselinePath is required.',
-    );
-  }
-  const abs = path.isAbsolute(baselinePath)
-    ? baselinePath
-    : path.resolve(process.cwd(), baselinePath);
-
-  const rows = Object.entries(baseline ?? {}).map(([p, mi]) => ({
-    path: p,
-    mi,
-  }));
-  const envelope = writeBaselineEnvelope({ kind: 'maintainability', rows });
-  writeBaselineFile(abs, envelope);
-}
-
 const IGNORED_DIRS = new Set([
   'node_modules',
   '.git',

package/.agents/scripts/lib/observability/perf-report-readers.js

@@ -16,6 +16,7 @@ import { storyArtifactPath } from '../config/temp-paths.js';
 import { gitSpawn } from '../git-utils.js';
 import { Logger } from '../Logger.js';
 import { read as readSignals } from '../signals/read.js';
+import { concurrentMap } from '../util/concurrent-map.js';
 import { extractStoryPerfSummaryFromComment } from './perf-report-render.js';
 import { forEachLine } from './signals-writer.js';
 
@@ -154,30 +155,38 @@ export async function collectStorySummaries(provider, epicId, logger) {
       ),
   );
 
-  const summaries = [];
-  for (const ticket of storyTickets) {
-    const id = Number(ticket.id ?? ticket.number);
-    if (!Number.isInteger(id) || id < 1) continue;
-    let comments;
-    try {
-      comments = (await provider.getTicketComments(id)) ?? [];
-    } catch (err) {
-      logger.warn?.(
-        `[analyze-execution] getTicketComments(${id}) failed: ${
-          err instanceof Error ? err.message : String(err)
-        }`,
-      );
-      continue;
-    }
-    for (const c of comments) {
-      const parsed = extractStoryPerfSummaryFromComment(c?.body);
-      if (parsed) {
-        summaries.push(parsed);
-        break;
+  // Bounded-parallel comment fetch (Story #3990). Each Story's comment
+  // thread is an independent paginated REST read through a fresh `gh`
+  // spawn, so a serial loop pays N sequential round-trips. concurrentMap
+  // preserves input→output index, keeping summaries in Story order; the
+  // per-Story try/catch stays inside the mapper so one failed fetch
+  // degrades to warn-and-skip without aborting the batch (mirrors
+  // verifySingleResult in lib/orchestration/wave-record-io.js, #3024).
+  const perStory = await concurrentMap(
+    storyTickets,
+    async (ticket) => {
+      const id = Number(ticket.id ?? ticket.number);
+      if (!Number.isInteger(id) || id < 1) return null;
+      let comments;
+      try {
+        comments = (await provider.getTicketComments(id)) ?? [];
+      } catch (err) {
+        logger.warn?.(
+          `[analyze-execution] getTicketComments(${id}) failed: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+        return null;
       }
-    }
-  }
-  return summaries;
+      for (const c of comments) {
+        const parsed = extractStoryPerfSummaryFromComment(c?.body);
+        if (parsed) return parsed;
+      }
+      return null;
+    },
+    { concurrency: 4 },
+  );
+  return perStory.filter((s) => s !== null);
 }
 
 /**

package/.agents/scripts/lib/orchestration/acceptance-eval-decision.js

@@ -1,12 +1,22 @@
 /**
  * Acceptance self-eval decision core (Story #3819).
  *
- * Pure, I/O-free reducer that turns one round's critic verdict plus the
- * resolved round cap into the loop's next action. The CLI wrapper
+ * Pure reducer that turns one round's critic verdict plus the resolved
+ * round cap into the loop's next action. The CLI wrapper
  * (`acceptance-eval.js`) owns the file reads, schema validation, signal
  * emission, and ticket transitions; this module owns the *decision* so it
  * can be unit-tested in isolation.
  *
+ * ## Round derivation (Story #4019)
+ *
+ * The round number is **derived from the signals ledger**, not from the
+ * critic's self-reported `verdict.round`: every prior round appended one
+ * `acceptance-eval` signal to the Story's `signals.ndjson`, so the
+ * current round is `count(prior signals) + 1`. This survives a subagent
+ * restart (the ledger is on disk) and removes the critic's scratch value
+ * from the cap enforcement path — a critic that always reports `round: 1`
+ * can no longer defeat the bounded-loop guarantee.
+ *
  * ## The three terminal actions
  *
  *   - `proceed`  — every criterion is `met`. The Story may flip to
@@ -29,6 +39,10 @@
  * possible action is `block`.
  */
 
+import { readFileSync } from 'node:fs';
+
+import { signalsFile } from '../config/temp-paths.js';
+
 /**
  * Verdicts that clear a criterion. Anything else (`partial`, `unmet`, or
  * an unrecognised value) is treated as not-yet-met and triggers rework.
@@ -87,11 +101,16 @@ function partitionCriteria(criteria) {
  * Decide the next loop action from a single round's verdict.
  *
  * @param {object} args
- * @param {{ round?: number, criteria?: Array<object> }} args.verdict
+ * @param {{ criteria?: Array<object> }} args.verdict
  *   A verdict already validated against the acceptance-eval-verdict schema.
+ *   Its `round` field, when present, is ignored — the round is supplied by
+ *   the caller (derived from the signals ledger; Story #4019).
  * @param {number} args.maxRounds
  *   The resolved (already-clamped) redraft ceiling from
  *   `getAcceptanceEval(config).maxRounds`.
+ * @param {number} [args.round]
+ *   The current round number, derived via `deriveAcceptanceEvalRound`.
+ *   Defaults to 1 when absent or invalid.
  * @returns {{
  *   decision: 'proceed' | 'redraft' | 'block',
  *   round: number,
@@ -102,10 +121,9 @@ function partitionCriteria(criteria) {
  *   capReached: boolean,
  * }}
  */
-export function decideAcceptanceEval({ verdict, maxRounds }) {
+export function decideAcceptanceEval({ verdict, maxRounds, round: roundIn }) {
   const cap = effectiveCap(maxRounds);
-  const round =
-    Number.isInteger(verdict?.round) && verdict.round >= 1 ? verdict.round : 1;
+  const round = Number.isInteger(roundIn) && roundIn >= 1 ? roundIn : 1;
   const { metCount, notMet } = partitionCriteria(verdict?.criteria);
   const totalCriteria = metCount + notMet.length;
   const allMet = notMet.length === 0;
@@ -171,3 +189,59 @@ export function buildAcceptanceEvalSignal({
     },
   };
 }
+
+/**
+ * Derive the current acceptance-eval round for a Story by counting the
+ * `acceptance-eval` signals already appended to the Story's
+ * `signals.ndjson` (Story #4019). Round = prior-signal count + 1, so the
+ * first run reports round 1 and each completed round (which appends one
+ * signal via `acceptance-eval.js`) advances the derived round by one.
+ *
+ * The derivation is restart-safe: the ledger lives on disk, so a subagent
+ * that dies mid-loop and restarts still observes every prior round. A
+ * missing or malformed ledger degrades to round 1 (no prior rounds), and
+ * malformed lines are skipped — observability corruption never wedges the
+ * gate.
+ *
+ * @param {object} args
+ * @param {number|null} args.epicId   Parent Epic ID, or `null` for a
+ *   standalone Story (routes to `<tempRoot>/standalone/stories/...`).
+ * @param {number} args.storyId
+ * @param {object} [args.config]      Resolved config (tempRoot resolution).
+ * @param {(p: string) => string} [args.readFile]  Injectable reader (tests).
+ * @param {(eid: number|null, sid: number, config?: object) => string} [args.signalsPathResolver]
+ *   Injectable path resolver (tests). Defaults to `signalsFile`.
+ * @returns {number} The 1-based current round.
+ */
+export function deriveAcceptanceEvalRound({
+  epicId,
+  storyId,
+  config,
+  readFile = (p) => readFileSync(p, 'utf8'),
+  signalsPathResolver = signalsFile,
+}) {
+  let text;
+  try {
+    text = readFile(signalsPathResolver(epicId ?? null, storyId, config));
+  } catch (_err) {
+    // No ledger yet → no prior rounds.
+    return 1;
+  }
+
+  let priorRounds = 0;
+  for (const line of String(text).split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed === '') continue;
+    let record;
+    try {
+      record = JSON.parse(trimmed);
+    } catch (_err) {
+      continue; // Malformed line — skip, never throw.
+    }
+    if (!record || typeof record !== 'object') continue;
+    if (record.kind !== 'acceptance-eval') continue;
+    if (record.storyId !== storyId) continue;
+    priorRounds += 1;
+  }
+  return priorRounds + 1;
+}