@forwardimpact/libharness 3.0.0 → 3.0.2

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}}

package/src/benchmark/result.js

@@ -3,16 +3,17 @@
  *
  * Two schemas live here:
  *   - RESULT_RECORD_SCHEMA — one record per (task, runIndex) from a full
- *     benchmark run. Has a happy branch (grade + collectors + judge present)
- *     and a pre-flight-failure branch (grade/judgeVerdict/submission absent).
- *   - GRADE_RECORD_SCHEMA — narrower output of `benchmark-grade`: ad-hoc
- *     grading without a full lifecycle.
+ *     benchmark run. It has a happy branch (grade + collectors + judge
+ *     present) and a pre-flight-failure branch (grade/judgeVerdict/submission
+ *     absent).
+ *   - GRADE_RECORD_SCHEMA — narrower output of `benchmark-grade`, which
+ *     grades ad hoc without a full lifecycle.
  *
- * The check rows are the authoritative grading channel: the happy branch
- * requires a `grade` object, so a pre-break record fails validation rather
- * than rendering under semantics it never carried.
+ * The check rows are the authoritative channel for grades. The happy branch
+ * requires a `grade` object, so a pre-break record fails validation. It does
+ * not render under semantics it never carried.
  *
- * Validation is throw-on-mismatch so the runner can wrap every JSONL append
+ * The validators throw on mismatch, so the runner can wrap every JSONL append
  * in a guard and reject schema drift at write time.
  */
 
@@ -27,8 +28,8 @@ const INVARIANTS_SHAPE = z.object({
 });
 
 /**
- * The normalized grading projection: `score` appears only on scored tasks,
- * `malformed` only when at least one row was malformed.
+ * The normalized projection of a grade. `score` appears only on scored
+ * tasks. `malformed` appears only when at least one row was malformed.
  */
 const GRADE_SHAPE = z.object({
   verdict: VERDICT_ENUM,
@@ -48,9 +49,9 @@ const JUDGE_VERDICT_SHAPE = z.object({
 });
 
 /**
- * Per-participant cost attribution. `costUsd` is the sum of these; the
+ * Per-participant cost attribution. `costUsd` is the sum of these. The
  * breakdown lets reports show where the spend went. The judge runs as its
- * own SDK session, so its cost is tracked separately from agent/supervisor.
+ * own SDK session, so its cost stays separate from agent/supervisor.
  */
 const COST_BREAKDOWN_SHAPE = z.object({
   agent: z.number(),
@@ -98,8 +99,8 @@ const HAPPY_RECORD = z.object({
   invariants: INVARIANTS_SHAPE,
   grade: GRADE_SHAPE,
   hiddenTests: HIDDEN_TESTS_SHAPE.optional(),
-  // The effective, judge-zeroed score `report` aggregates — present only on
-  // scored tasks.
+  // The effective, judge-zeroed score `report` aggregates. It is present
+  // only on scored tasks.
   score: z.number().min(0).max(1).optional(),
   submission: z.string(),
   judgeVerdict: JUDGE_VERDICT_SHAPE.optional(),
@@ -114,9 +115,9 @@ const PREFLIGHT_RECORD = z.object({
   ...COMMON_FIELDS,
   costUsd: z.literal(0),
   preflightError: PREFLIGHT_ERROR_SHAPE,
-  // Trace paths are populated even on preflight failure (the runner allocates
-  // them in WorkdirManager.start) so the record is uniform across branches
-  // and downstream consumers can reference them without conditional fields.
+  // The runner allocates the trace paths in WorkdirManager.start, even on
+  // preflight failure. The record then stays uniform across branches, and
+  // downstream consumers can reference the paths without conditional fields.
   agentTracePath: z.string(),
   supervisorTracePath: z.string(),
   judgeTracePath: z.string(),
@@ -133,15 +134,15 @@ export const RESULT_RECORD_SCHEMA = z.union([HAPPY_RECORD, PREFLIGHT_RECORD]);
 
 export const GRADE_RECORD_SCHEMA = z.object({
   taskId: z.string().min(1),
-  // Unlike the happy result record — where `grade.score` is the raw
-  // weighted fraction and the effective (zeroed) value lives on the
-  // top-level `score` — this record has no second score field, so its
-  // `grade.score` carries the effective health/gate-zeroed value.
+  // In the happy result record, `grade.score` is the raw weighted fraction,
+  // and the effective (zeroed) value lives on the top-level `score`. This
+  // record has no second score field, so its `grade.score` carries the
+  // effective health/gate-zeroed value.
   grade: GRADE_SHAPE,
   invariants: INVARIANTS_SHAPE,
   hiddenTests: HIDDEN_TESTS_SHAPE.optional(),
-  // Mirrors the invariants script's exit for diagnosis; the graded verdict
-  // is what drives the command's process exit.
+  // This mirrors the invariants script's exit for diagnosis. The graded
+  // verdict drives the command's process exit.
   exitCode: z.number().int(),
 });