@forwardimpact/libharness 2.0.0 → 3.0.1

package/src/benchmark/hidden-tests.js

@@ -1,14 +1,14 @@
 /**
- * Hidden-test engine — executes a task's `tests/` overlay against the
- * post-run agent CWD: stage each file at its mirrored path, run each check
- * with `node --test`, convert the exit status into one check row, and
- * restore the tree so the judge sees the workdir exactly as the agent left
- * it.
+ * Hidden-test engine — runs a task's `tests/` overlay against the post-run
+ * agent CWD. The engine stages each file at its mirrored path. It runs each
+ * check with `node --test`. It converts the exit status into one check row.
+ * It restores the tree, so the judge sees the workdir exactly as the agent
+ * left it.
  *
- * Fault attribution is the engine's contract: a stage or spawn failure (the
- * agent deleted the scaffold) is a *failing row* — agent fault; the engine
- * itself throwing is grader fault, which the caller records as unhealthy so
- * a crashed grader can never mint marks.
+ * Fault attribution is the engine's contract. A stage or spawn failure (the
+ * agent deleted the scaffold) is agent fault, so the engine returns a *row
+ * that fails*. A throw from the engine itself is grader fault. The caller
+ * records that as unhealthy, so a crashed grader can never mint marks.
  */
 
 import { dirname, join } from "node:path";
@@ -16,8 +16,8 @@ import { dirname, join } from "node:path";
 import { buildHookEnv } from "./hook-env.js";
 
 // Fixed per-check budget. A wedged test process runs outside the agent
-// watchdog, so this bound is what keeps a hung hidden test from stalling the
-// cell; the timeout row keeps the failure visible.
+// watchdog. Without this bound, a hung hidden test would stall the cell. The
+// timeout row keeps the failure visible.
 const CHECK_TIMEOUT_MS = 120_000;
 const STDERR_TAIL_CHARS = 500;
 
@@ -50,9 +50,9 @@ export async function runHiddenTests(task, ctx, runtime, opts = {}) {
 }
 
 /**
- * Stage one check, run it, and restore its staging — the check's own row is
- * the only trace it leaves. A stage failure is the agent's fault (a deleted
- * scaffold), so it becomes a failing row rather than a throw.
+ * Stage one check, run it, then put the tree back. The check's own row is the
+ * only trace it leaves. A stage failure is the agent's fault (a deleted
+ * scaffold). The engine returns a row that fails. It does not throw.
  */
 async function runOneCheck(task, ctx, runtime, timeoutMs, check) {
   const stager = newStager();
@@ -71,7 +71,8 @@ async function runOneCheck(task, ctx, runtime, timeoutMs, check) {
 /**
  * Spawn `node --test <staged path>` from the agent CWD under the hook env
  * and map the exit status onto one row. The clock timer SIGKILLs a child
- * that outlives the per-check budget; the row fails with a timeout message.
+ * that outlives the per-check budget. The row then fails with a timeout
+ * message.
  */
 async function spawnCheck(task, ctx, runtime, timeoutMs, check) {
   const env = buildHookEnv(runtime.proc.env, {
@@ -83,8 +84,8 @@ async function spawnCheck(task, ctx, runtime, timeoutMs, check) {
     familyDir: ctx.familyDir,
   });
   // An inherited test-runner context makes the child `node --test` report
-  // exit 0 even when its tests fail — a failing check would mint a passing
-  // row whenever the harness itself runs under `node --test`.
+  // exit 0 even when its tests fail. A check that fails would then mint a row
+  // that passes whenever the harness itself runs under `node --test`.
   delete env.NODE_TEST_CONTEXT;
   const child = runtime.subprocess.spawn("node", ["--test", check.stagePath], {
     cwd: ctx.cwd,
@@ -129,8 +130,8 @@ function newStager() {
 }
 
 /**
- * Copy the symlink-resolved source to its mirrored path under the agent CWD,
- * backing up a collided file's bytes and tracking every directory created so
+ * Copy the symlink-resolved source to its mirrored path under the agent CWD.
+ * Back up the bytes of a collided file. Track every directory created, so
  * `unstage` can put the tree back exactly.
  */
 async function stageFile(fs, cwd, stager, { sourcePath, stagePath }) {
@@ -154,7 +155,7 @@ async function ensureParents(fs, cwd, stager, dir) {
     await fs.access(dir);
     return;
   } catch {
-    // missing — create below
+    // missing, so create it below
   }
   await ensureParents(fs, cwd, stager, dirname(dir));
   await fs.mkdir(dir);
@@ -162,10 +163,10 @@ async function ensureParents(fs, cwd, stager, dir) {
 }
 
 /**
- * Reverse the staging: staged copies out, collided bytes back, created
- * directories removed (deepest first — a check's own artifacts inside a
- * created directory go with it, since that directory did not exist when the
- * agent finished).
+ * Reverse the stage step. Remove the staged copies. Write the collided bytes
+ * back. Remove the created directories, deepest first. A check's own
+ * artifacts inside a created directory go with it, because that directory did
+ * not exist when the agent finished.
  */
 async function unstage(fs, stager) {
   for (const target of stager.staged) {

package/src/benchmark/hook-env.js

@@ -1,12 +1,13 @@
 /**
- * Shared environment builder for the benchmark hook scripts (`preflight.sh` and
- * `invariants.sh`). Keeping both spawns on one helper guarantees they expose the
- * same variable set, so hook authors never have to wonder which vars a given
- * hook receives.
+ * Shared environment builder for the benchmark hook scripts (`preflight.sh`
+ * and `invariants.sh`). One helper serves both spawns, so both expose the
+ * same variable set. Hook authors never have to wonder which vars a hook
+ * receives.
  *
  * Path vars (TASK_DIR, FAMILY_DIR, HOOKS_DIR) let hooks reference real
- * locations instead of reconstructing them from `$0`. They are paths, not
- * secrets, so they need no redaction allowlist entry.
+ * locations. Hooks do not have to rebuild the locations from `$0`. They are
+ * paths. They are not secrets, so they need no entry in the redaction
+ * allowlist.
  */
 
 /**
@@ -27,9 +28,10 @@ export function buildHookEnv(
 ) {
   return {
     ...baseEnv,
-    // The agent CWD itself — hooks reference emitted files as `$AGENT_CWD/<path>`.
-    // Distinct from the `invariants` CLI's `--run-dir` (the parent that
-    // *contains* `cwd/`), so the two are never confused.
+    // The agent CWD itself. Hooks reference emitted files as
+    // `$AGENT_CWD/<path>`. This var is distinct from the `invariants` CLI's
+    // `--run-dir` (the parent that *contains* `cwd/`), so the two are never
+    // confused.
     AGENT_CWD: cwd,
     PORT: String(port),
     TASK_ID: taskId,

package/src/benchmark/invariants.js

@@ -1,14 +1,15 @@
 /**
  * Invariants — runs `<task.paths.hooks>/invariants.sh` from the template path
- * against the post-run agent CWD. A pure collector with no verdict of its
- * own: structured per-check rows arrive on fd 3 (`$RESULTS_FD=3`) as NDJSON
- * and grading happens downstream over the merged rows. The exit code is
- * script health only — nonzero means the grader itself failed, never that a
- * check failed.
+ * against the post-run agent CWD. The module is a pure collector with no
+ * verdict of its own. Structured per-check rows arrive on fd 3
+ * (`$RESULTS_FD=3`) as NDJSON. Downstream code grades the merged rows. The
+ * exit code is script health only. A nonzero code means the grader itself
+ * failed. It never means that a check failed.
  *
- * Subprocess access flows through `runtime.subprocess.spawn`; the fd-3 backing
- * store and the stderr log use the sync filesystem surface (`runtime.fsSync`) —
- * the only surface this module touches, per design Decision 7.
+ * Subprocess access flows through `runtime.subprocess.spawn`. The fd-3
+ * backing store and the stderr log use the sync filesystem surface
+ * (`runtime.fsSync`). That surface is the only one this module touches, per
+ * design Decision 7.
  */
 
 import { join } from "node:path";
@@ -18,11 +19,12 @@ import { buildHookEnv } from "./hook-env.js";
 /**
  * @typedef {object} InvariantsResult
  * @property {Array<object>} details
- * @property {number} exitCode - Script health: nonzero means the hook itself
- *   failed, never that a check failed.
+ * @property {number} exitCode - Script health. A nonzero code means the hook
+ *   itself failed. It never means that a check failed.
  * @property {string} [stderr] - Trimmed script stderr, present only when the
- *   script wrote to stderr. Surfaces hook failures (e.g. a missing tool) that
- *   leave `details` empty, so they read distinctly from a real invariant miss.
+ *   script wrote to stderr. This field surfaces hook failures (e.g. a missing
+ *   tool) that leave `details` empty. A reader can then tell them apart from
+ *   a real invariant miss.
  */
 
 /**
@@ -43,8 +45,8 @@ export async function runInvariants(task, ctx, runtime) {
 
   // Bun's child_process pipe setup for fd >= 3 is racy under load (it
   // creates a unix socket pair and the connect() can return ENOENT). Use
-  // a temp file as the fd-3 backing store instead — the script still
-  // writes via `$RESULTS_FD`, but we hand it a real file descriptor.
+  // a temp file as the fd-3 backing store instead. The script still writes
+  // through `$RESULTS_FD`, but we hand it a real file descriptor.
   const fd3Path = join(ctx.runDir, "invariants.fd3.ndjson");
   const fd3File = fsSync.openSync(fd3Path, "w+");
 
@@ -69,7 +71,8 @@ export async function runInvariants(task, ctx, runtime) {
     throw e;
   }
 
-  // Drain stdout (do not require consumers to read it); capture stderr to log.
+  // Drain stdout (do not require consumers to read it). Capture stderr to
+  // the log.
   const drainStdout = (async () => {
     for await (const _chunk of child.stdout) {
       // discard
@@ -127,8 +130,8 @@ function readAndUnlink(fsSync, path) {
 }
 
 /**
- * Parse the fd-3 buffer (read from the temp-file backing) into one NDJSON
- * row per detail entry.
+ * Parse the fd-3 buffer (read from the temp-file backing store) into one
+ * NDJSON row per detail entry.
  */
 function parseFd3Buffer(buf, details) {
   if (!buf) return;

package/src/benchmark/judge.js

@@ -1,8 +1,9 @@
 /**
- * Benchmark adapter for the libharness `Judge`. Templates the family's
- * `judge.task.md` with structured context variables, runs the judge against
- * the post-run agent CWD, and returns the verdict in the benchmark's
- * `pass`/`fail` vocabulary (mapped from libharness's `success`/`failure`).
+ * Benchmark adapter for the libharness `Judge`. The adapter fills the
+ * family's `judge.task.md` template with structured context variables. It
+ * runs the judge against the post-run agent CWD. It returns the verdict in
+ * the benchmark's `pass`/`fail` vocabulary (mapped from libharness's
+ * `success`/`failure`).
  *
  * Template variables available in `judge.task.md`:
  *
@@ -12,13 +13,13 @@
  *   {{GRADE_RESULT}}        — JSON grade object plus the merged check rows
  *   {{SKILL_SET_HASH}}      — SHA-256 from apm.lock.yaml
  *   {{TASK_ID}}             — task name (directory under tasks/)
- *   {{TASK_DIR}}            — agent working directory path
+ *   {{TASK_DIR}}            — path to the agent working directory
  *
- * The judge verdict is captured from the orchestration context's
- * `concluded` flag directly — no trace parsing on the happy path.
- * `parseConcludeFromTrace` is preserved for offline analysis and as a
- * fallback when the runtime ctx isn't available (e.g. re-grading a
- * historical run from its judge.ndjson file).
+ * The adapter reads the judge verdict directly from the orchestration
+ * context's `concluded` flag. It does not parse the trace on the happy path.
+ * `parseConcludeFromTrace` stays for offline analysis. It is also a fallback
+ * when the runtime ctx is not available, for example when you re-grade a
+ * historical run from its judge.ndjson file.
  */
 
 import { createJudge } from "../judge.js";
@@ -41,8 +42,8 @@ import { sumTraceCost } from "../cost.js";
 
 /**
  * Run the judge over a completed task run. The judge is a binary gate over
- * the grade's validity, never a grade itself: `gradeResult` reaches the
- * template as evidence, and the verdict stays pass/fail.
+ * the grade's validity. The judge is never a grade itself. `gradeResult`
+ * reaches the template as evidence. The verdict stays pass/fail.
  * @param {import("./task-family.js").Task} task
  * @param {import("./workdir.js").Workdir} workdir
  * @param {{verdict: string, gatesPass: boolean, score?: number, malformed?: number, rows: unknown[]}} gradeResult -
@@ -86,9 +87,9 @@ export async function runJudge(task, workdir, gradeResult, deps, context) {
     await new Promise((r) => output.end(r));
   }
 
-  // The judge is its own SDK session; its spend lands in the judge trace we
-  // just wrote, not in the supervisor's combined trace. Read it back so the
-  // benchmark record's cost includes the judge.
+  // The judge is its own SDK session. Its spend lands in the judge trace we
+  // just wrote. It does not land in the supervisor's combined trace. Read the
+  // trace back, so the benchmark record's cost includes the judge.
   const judgeTrace = await fs
     .readFile(workdir.judgeTracePath, "utf8")
     .catch(() => "");
@@ -109,10 +110,11 @@ export async function runJudge(task, workdir, gradeResult, deps, context) {
 }
 
 /**
- * Parse the last judge-source (or supervisor-source, for backward compat
- * with pre-Judge-class traces) `Conclude` tool call from an NDJSON trace
- * and map the verdict (`success → pass`, `failure → fail`). Preserved for
- * offline analysis; not used on the runtime happy path.
+ * Parse the last `Conclude` tool call from an NDJSON trace and map the
+ * verdict (`success → pass`, `failure → fail`). The call may carry a
+ * judge source or a supervisor source. The supervisor source keeps backward
+ * compatibility with pre-Judge-class traces. This function stays for offline
+ * analysis. The runtime happy path does not use it.
  * @param {string} tracePath
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @returns {Promise<JudgeVerdict | null>}
@@ -133,9 +135,9 @@ export async function parseConcludeFromTrace(tracePath, runtime) {
 }
 
 /**
- * Return the `Conclude` tool input if the line carries a judge-source or
- * supervisor-source assistant message ending in a `Conclude` tool_use
- * block; null otherwise.
+ * Return the `Conclude` tool input when the line carries a judge-source or
+ * supervisor-source assistant message that ends in a `Conclude` tool_use
+ * block. Return null otherwise.
  * @param {string} line
  * @returns {{verdict: string, summary?: string} | null}
  */
@@ -176,12 +178,11 @@ function extractConcludeInput(line) {
 }
 
 /**
- * The Claude Agent SDK reports MCP tool names as
- * `mcp__<server>__<tool>` when the model invokes them — the orchestration
- * `Conclude` arrives as `mcp__orchestration__Conclude`. Pre-baked
- * supervisor traces (and the libharness-internal envelopes) sometimes carry
- * the bare `Conclude` name. Accept both forms so the parser is robust to
- * trace source.
+ * The Claude Agent SDK reports MCP tool names as `mcp__<server>__<tool>` when
+ * the model invokes them. The orchestration `Conclude` arrives as
+ * `mcp__orchestration__Conclude`. Pre-baked supervisor traces (and the
+ * libharness-internal envelopes) sometimes carry the bare `Conclude` name.
+ * Accept both forms, so the parser is robust to the trace source.
  */
 function isConcludeToolName(name) {
   if (typeof name !== "string") return false;

package/src/benchmark/npm-installer.js

@@ -1,10 +1,11 @@
 /**
- * NpmInstaller — runs `bun install` in the family root when a package.json
- * is present, then copies the resulting `node_modules/` into the staging
- * directory so WorkdirManager can seed each per-task CWD.
+ * NpmInstaller — runs `bun install` in the family root when a package.json is
+ * present. It then copies the `node_modules/` that `bun install` produced
+ * into the staging directory, so WorkdirManager can seed each per-task CWD.
  *
- * Symmetric to ApmInstaller: the subprocess and filesystem flow through the
- * injected `runtime` bag (`runtime.subprocess.spawn` + `runtime.fs`).
+ * NpmInstaller is symmetric to ApmInstaller. The subprocess and the
+ * filesystem flow through the injected `runtime` bag
+ * (`runtime.subprocess.spawn` + `runtime.fs`).
  */
 
 import { join } from "node:path";
@@ -14,7 +15,7 @@ export class NpmInstaller {
   /**
    * @param {object} deps
    * @param {import("@forwardimpact/libutil/runtime").Runtime} deps.runtime -
-   *   Ambient collaborators; uses `subprocess.spawn` and `fs`.
+   *   Ambient collaborators. This class uses `subprocess.spawn` and `fs`.
    */
   constructor({ runtime }) {
     if (!runtime) throw new Error("runtime is required");
@@ -23,7 +24,7 @@ export class NpmInstaller {
 
   /**
    * @param {import("./task-family.js").TaskFamily} family
-   * @param {string} stagingDir - The staging directory (created by ApmInstaller).
+   * @param {string} stagingDir - The staging directory ApmInstaller creates.
    * @returns {Promise<void>}
    */
   async install(family, stagingDir) {
@@ -42,7 +43,7 @@ export class NpmInstaller {
       await fs.access(sourceModules);
     } catch {
       throw new Error(
-        `bun install did not produce node_modules/ at ${sourceModules}; check the family's package.json`,
+        `bun install did not produce node_modules/ at ${sourceModules}. Check the family's package.json`,
       );
     }
 

package/src/benchmark/report.js

@@ -1,15 +1,15 @@
 /**
- * ReportAggregator — read a run-output directory's `results.jsonl`, group
- * records by `taskId`, and compute pass@k via the OpenAI HumanEval
+ * ReportAggregator — read a run-output directory's `results.jsonl`. Group
+ * the records by `taskId`. Compute pass@k with the OpenAI HumanEval
  * unbiased estimator: `1 - C(n-c, k) / C(n, k)`.
  *
  * When `includeRuns` is true, each task carries per-run detail (invariant
- * checks, judge commentary, cost, duration) and the text renderer produces
+ * checks, judge commentary, cost, duration). The text renderer then produces
  * a full markdown report instead of just the pass@k table.
  *
- * Records that fail schema validation are skipped with a stderr warning
- * (counted under `totals.skipped`) so a corrupt line cannot abort the
- * whole report.
+ * The loader skips records that fail schema validation. It writes a stderr
+ * warning and counts each skip under `totals.skipped`. A corrupt line cannot
+ * abort the whole report.
  */
 
 import { join } from "node:path";
@@ -37,7 +37,7 @@ import { mergeRows } from "./grade.js";
  * @typedef {object} TaskReport
  * @property {string} taskId
  * @property {number} n - Total runs.
- * @property {number} c - Passing runs.
+ * @property {number} c - Runs that passed.
  * @property {Record<string|number, number|null>} passAtK
  * @property {RunDetail[]} [runs] - Per-run detail (only when includeRuns).
  */
@@ -109,12 +109,12 @@ export async function aggregate({
 
 /**
  * Attach `meanScore` and `scoreAtK` to a scored task group. A group is
- * scored iff any record carries an effective score; a score-less record in
- * a scored group (a preflight failure never reached grading, or a binary
- * run) contributes its verdict as the degenerate score — skipping it would
- * inflate the mean exactly when the agent fails hardest. Binary groups gain
- * neither field.
- * @param {object} task - Mutated.
+ * scored iff any record carries an effective score. A score-less record in a
+ * scored group contributes its verdict as the degenerate score. Such a record
+ * comes from a preflight failure that never reached the grade step, or from a
+ * binary run. A skip would inflate the mean exactly when the agent fails
+ * hardest. Binary groups gain neither field.
+ * @param {object} task - The function mutates it.
  * @param {object[]} group
  * @param {number[]} kValues
  */
@@ -127,9 +127,9 @@ function applyScoreFields(task, group, kValues) {
 }
 
 /**
- * Build a normalized per-run detail object and accumulate duration/turn
- * samples for median calculation. Extracted from `aggregate` to keep its
- * cognitive complexity below the lint ceiling.
+ * Build a normalized per-run detail object. Accumulate duration/turn samples
+ * so the caller can calculate the median. It is separate from `aggregate` to
+ * keep that function's cognitive complexity below the lint ceiling.
  * @param {object} r - Raw record.
  * @param {{allDurations: number[], allTurns: number[]}} acc
  * @returns {RunDetail}
@@ -155,9 +155,9 @@ function buildRunDetail(r, acc) {
 
 /**
  * Render an aggregate report as markdown. When the report contains per-run
- * detail (from `includeRuns: true`), renders a full report with summary,
- * pass@k table, and per-task detail sections. Otherwise falls back to the
- * compact pass@k table.
+ * detail (from `includeRuns: true`), the renderer produces a full report.
+ * That report has a summary, a pass@k table, and per-task detail sections.
+ * Otherwise the renderer falls back to the compact pass@k table.
  * @param {Awaited<ReturnType<typeof aggregate>>} report
  * @param {number[]} kValues
  * @returns {string}
@@ -170,10 +170,10 @@ export function renderTextReport(report, kValues) {
 }
 
 // ---------------------------------------------------------------------------
-// Compact report — status line + pass@k table, no per-task detail. Selected by
-// `report --detail=compact` (aggregate without `includeRuns`); the per-shard
-// summary uses it so a sharded run stays short while the merge job renders the
-// full report over the combined ledger.
+// Compact report — status line + pass@k table, no per-task detail.
+// `report --detail=compact` selects it (aggregate without `includeRuns`).
+// The per-shard summary uses it so a sharded run stays short. The merge job
+// renders the full report over the combined ledger.
 // ---------------------------------------------------------------------------
 
 function renderCompactReport(report, kValues) {
@@ -500,17 +500,18 @@ function median(arr) {
 // Record loading
 // ---------------------------------------------------------------------------
 
-// Directories never worth descending for a `results.jsonl`.
+// The walk never descends into these directories for a `results.jsonl`.
 const SKIP_DIRS = new Set([".git", "node_modules"]);
 
 /**
  * Load and union every `results.jsonl` found recursively under `inputDir`.
  *
- * A single non-sharded run has one root-level ledger — the trivial one-match
- * case of the same walk. A sharded run lays each shard's partial ledger in its
- * own subdirectory; merging them equals reporting a single run over the same
- * cells. An *existing* dir with no ledger yields the empty union (exit 0); a
- * *missing* dir lets `readdir`'s ENOENT propagate so `report` still errors.
+ * A single non-sharded run has one root-level ledger. That is the trivial
+ * one-match case of the same walk. A sharded run lays each shard's partial
+ * ledger in its own subdirectory. A merge of those ledgers equals a report of
+ * a single run over the same cells. An *existing* dir with no ledger yields
+ * the empty union (exit 0). A *missing* dir lets `readdir`'s ENOENT
+ * propagate, so `report` still errors.
  * @param {string} inputDir
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @returns {Promise<{records: object[], skipped: number}>}
@@ -520,10 +521,10 @@ async function loadRecords(inputDir, runtime) {
   try {
     files = await collectResultsFiles(inputDir, runtime);
   } catch (e) {
-    // Re-throw with the stack collapsed to the message line so the CLI's
-    // error rendering stays free of node-internal async `readdir` frames
-    // (a missing --input dir surfaces its ENOENT as exit 1, matching the
-    // pre-1370 stream-error shape the golden captured).
+    // Re-throw with the stack collapsed to the message line. The CLI error
+    // output then stays free of node-internal async `readdir` frames. A
+    // missing --input dir surfaces its ENOENT as exit 1, which matches the
+    // pre-1370 stream-error shape the golden captured.
     const err = new Error(e.message);
     if (e.code) err.code = e.code;
     err.stack = `Error: ${e.message}`;
@@ -540,11 +541,12 @@ async function loadRecords(inputDir, runtime) {
 }
 
 /**
- * Parse one ledger's JSONL into `records`, skipping malformed or schema-invalid
- * lines with a stderr warning. Returns the skipped count. Extracted from
- * `loadRecords` to keep its cognitive complexity under the lint ceiling.
+ * Parse one ledger's JSONL into `records`. Skip each malformed or
+ * schema-invalid line and write a stderr warning. Return the skipped count.
+ * It is separate from `loadRecords` to keep that function's cognitive
+ * complexity under the lint ceiling.
  * @param {string} content
- * @param {object[]} records - Accumulator, appended in place.
+ * @param {object[]} records - Accumulator. The function appends in place.
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @returns {number} Skipped line count.
  */
@@ -567,7 +569,7 @@ function parseLedgerInto(content, records, runtime) {
       validateResultRecord(record);
     } catch (e) {
       runtime.proc.stderr.write(
-        `benchmark report: skipped record failing schema — ${describeError(e)}\n`,
+        `benchmark report: skipped schema-invalid record — ${describeError(e)}\n`,
       );
       skipped++;
       continue;
@@ -578,10 +580,10 @@ function parseLedgerInto(content, records, runtime) {
 }
 
 /**
- * Recursively collect paths of every file named `results.jsonl` under `dir`,
- * skipping `.git`/`node_modules` and never following symlinks. A purpose-built
- * `readdir` walk — `task-family.js`'s private `walkFiles` resolves symlinks and
- * is unexported, which is the wrong contract here.
+ * Recursively collect paths of every file named `results.jsonl` under `dir`.
+ * Skip `.git` and `node_modules`. Never follow a symlink. This is a
+ * purpose-built `readdir` walk. `task-family.js`'s private `walkFiles`
+ * resolves symlinks and is unexported, which is the wrong contract here.
  * @param {string} dir
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @returns {Promise<string[]>}
@@ -604,10 +606,10 @@ async function collectResultsFiles(dir, runtime) {
 }
 
 /**
- * Warn (do not silently merge) when a `(taskId, runIndex)` cell appears more
- * than once across shard ledgers. The shard partition guarantees uniqueness, so
- * a duplicate signals misconfiguration; both copies stay in the group so the
- * count is honest.
+ * Warn when a `(taskId, runIndex)` cell appears more than once across shard
+ * ledgers. Do not silently merge the copies. The shard partition guarantees
+ * uniqueness, so a duplicate signals misconfiguration. Both copies stay in
+ * the group so the count is honest.
  * @param {object[]} records
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  */
@@ -620,7 +622,7 @@ function warnOnDuplicateCells(records, runtime) {
   for (const [key, n] of counts) {
     if (n > 1)
       runtime.proc.stderr.write(
-        `benchmark report: duplicate cell ${key} appears ${n} times across shard ledgers — the shard partition should make each cell unique\n`,
+        `benchmark report: duplicate cell ${key} appears ${n} times across shard ledgers. The shard partition should make each cell unique\n`,
       );
   }
 }
@@ -660,14 +662,15 @@ function passAtKValue(n, c, k) {
 
 /**
  * score@k — the expected **maximum** score over k runs drawn without
- * replacement from the n recorded scores; the continuous analog of pass@k.
- * With scores sorted ascending s₍₁₎…s₍ₙ₎:
+ * replacement from the n recorded scores. It is the continuous analog of
+ * pass@k. With scores sorted ascending s₍₁₎…s₍ₙ₎:
  *
  *   score@k = Σ_{i=k..n} s₍ᵢ₎ · C(i−1, k−1) / C(n, k)
  *
  * Each term weights s₍ᵢ₎ by the probability it is the k-subset's maximum.
  * Binary scores reduce exactly to the pass@k estimator (same BigInt binomial
- * helper); `k > n` yields the same `{error}` value — one idiom.
+ * helper). `k > n` yields the same `{error}` value, so both functions use
+ * one idiom.
  * @param {number[]} scores - Effective per-record scores.
  * @param {number} k
  * @returns {number | {error: string}}