@forwardimpact/libharness 2.0.0 → 3.0.1

package/src/agent-runner.js

@@ -1,7 +1,8 @@
 /**
  * AgentRunner — runs a single Claude Agent SDK session and emits raw
- * NDJSON events to an output stream. Building block for `fit-harness run`,
- * `fit-harness supervise`, `fit-harness facilitate`, and `fit-harness discuss`.
+ * NDJSON events to an output stream. `gemba-harness run`,
+ * `gemba-harness supervise`, `gemba-harness facilitate`, and
+ * `gemba-harness discuss` build on it.
  *
  * Follows OO+DI: constructor injection, factory function, tests bypass factory.
  */
@@ -12,15 +13,16 @@ import { resolveClaudeCodeExecutable } from "./claude-code-executable.js";
 const DEFAULT_ALLOWED_TOOLS = ["Bash", "Read", "Glob", "Grep", "Write", "Edit"];
 
 /**
- * Did the session actually invoke the model? A genuine run always bills
+ * Report whether the session invoked the model. A genuine run always bills
  * tokens (the system prompt alone is thousands of input tokens) and costs
- * more than zero. A `result` message with `subtype: "success"` but zero
- * token usage and zero cost means the model was never reached — the
- * canonical signature of a Claude Code init/auth failure (e.g. an invalid
- * `ANTHROPIC_API_KEY`), which the SDK otherwise reports as a clean success.
+ * more than zero. A `result` message can carry `subtype: "success"` with
+ * zero token usage and zero cost. That combination means the run never
+ * reached the model. It is the canonical signature of a Claude Code init or
+ * auth failure (e.g. an invalid `ANTHROPIC_API_KEY`). The SDK otherwise
+ * reports that failure as a clean success.
  *
  * If the SDK gave us neither a `usage` object nor `total_cost_usd`, don't
- * second-guess the subtype — trust the reported success.
+ * second-guess the subtype. Trust the reported success.
  * @param {object|null} result - The SDK `result` message, or null.
  * @returns {boolean}
  */
@@ -37,9 +39,10 @@ function modelDidWork(result) {
   return tokens > 0 || (cost ?? 0) > 0;
 }
 
-// fit-harness and kata-action run headless in CI/CD with no human to answer
-// permission prompts. The SDK is always launched in bypass mode — not
-// overridable — so a future caller can't accidentally reduce permissions.
+// gemba-harness and kata-action run headless in CI/CD with no human to answer
+// permission prompts. The runner always launches the SDK in bypass mode. No
+// caller can override that mode, so a future caller can't accidentally
+// reduce permissions.
 const PERMISSION_MODE = "bypassPermissions";
 
 /** Run a single Claude Agent SDK session and emit raw NDJSON events to an output stream. */
@@ -47,25 +50,27 @@ export class AgentRunner {
   /**
    * @param {object} deps
    * @param {string} deps.cwd - Agent working directory
-   * @param {function} deps.query - SDK query function (injected for testing)
+   * @param {function} deps.query - SDK query function (tests inject it)
    * @param {import("stream").Writable} deps.output - Stream to emit NDJSON to
    * @param {string} [deps.model] - Claude model identifier
-   * @param {number} [deps.maxTurns] - Maximum agentic turns; 0 means unlimited
+   * @param {number} [deps.maxTurns] - Maximum agentic turns. 0 means unlimited
    * @param {string[]} [deps.allowedTools] - Tools the agent may use
-   * @param {function} [deps.onLine] - Callback invoked with each NDJSON line as it's produced
-   * @param {function} [deps.onPrompt] - Callback invoked with the effective (amend-applied) prompt of each run/resume
+   * @param {function} [deps.onLine] - Callback that receives each NDJSON line as the runner produces it
+   * @param {function} [deps.onPrompt] - Callback that receives the effective (amend-applied) prompt of each run/resume
    * @param {string[]} [deps.settingSources] - SDK setting sources (e.g. ['project'] to load CLAUDE.md)
-   * @param {string|object} [deps.systemPrompt] - SDK system prompt (string replaces default; {type:'preset', preset:'claude_code', append} appends)
+   * @param {string|object} [deps.systemPrompt] - SDK system prompt. A string replaces the default. The preset form {type:'preset', preset:'claude_code', append} appends
    * @param {string[]} [deps.disallowedTools] - Tools to explicitly remove from the model's context
    * @param {Record<string, object>} [deps.mcpServers] - MCP server configs to pass to the SDK query
    * @param {string} [deps.pathToClaudeCodeExecutable] - Absolute path to the
-   *   native `claude` CLI the SDK should spawn. Set for compiled fit-* binaries,
-   *   which can't self-resolve the SDK's platform optional dependency; omitted
-   *   from source runs so the SDK resolves its own version-matched binary.
+   *   native `claude` CLI the SDK should spawn. Set it for compiled fit-*
+   *   binaries, which can't self-resolve the SDK's platform optional
+   *   dependency. Omit it from source runs so the SDK resolves its own
+   *   version-matched binary.
    * @param {object} deps.redactor
    * @param {import("@forwardimpact/libutil/runtime").Runtime} [deps.runtime] -
-   *   Ambient collaborators. Only `proc.env` is read (to record Skill
-   *   invocations into `LIBHARNESS_SKILL`); when absent the write is skipped.
+   *   Ambient collaborators. The runner reads only `proc.env`, to record Skill
+   *   invocations into `LIBHARNESS_SKILL`. When `runtime` is absent, the
+   *   runner skips the write.
    */
   constructor(deps) {
     if (!deps.cwd) throw new Error("cwd is required");
@@ -81,15 +86,17 @@ export class AgentRunner {
     this.maxTurns = deps.maxTurns ?? 50;
     this.allowedTools = deps.allowedTools ?? DEFAULT_ALLOWED_TOOLS;
     this.onLine = deps.onLine ?? null;
-    // Optional; read only through a truthy guard in run()/resume(), so an
-    // absent value stays undefined rather than needing a `?? null` default.
+    // Optional. The code reads it only through a truthy guard in
+    // run()/resume(), so an absent value stays undefined and needs no
+    // `?? null` default.
     this.onPrompt = deps.onPrompt;
     this.settingSources = deps.settingSources ?? [];
     this.systemPrompt = deps.systemPrompt ?? null;
     this.disallowedTools = deps.disallowedTools ?? [];
     this.mcpServers = deps.mcpServers ?? null;
-    // Optional; read only through a truthy guard in #callOptions, so an absent
-    // value stays undefined rather than needing a `?? null` default.
+    // Optional. The code reads it only through a truthy guard in
+    // #callOptions, so an absent value stays undefined and needs no
+    // `?? null` default.
     this.pathToClaudeCodeExecutable = deps.pathToClaudeCodeExecutable;
     this.taskAmend = deps.taskAmend ?? null;
     this.sessionId = null;
@@ -146,16 +153,17 @@ export class AgentRunner {
   }
 
   /**
-   * Build the options passed to every SDK query() call. Shared by run()
-   * and resume() so the agent's configuration — cwd, tools, prompt,
-   * setting sources, turn budget — is identical across the session's
-   * lifetime. Only resume() layers `resume: this.sessionId` on top.
+   * Build the options for every SDK query() call. run() and resume()
+   * share this method, so the agent's configuration stays identical
+   * across the session's lifetime. That configuration is the cwd, the
+   * tools, the prompt, the setting sources, and the turn budget. Only
+   * resume() layers `resume: this.sessionId` on top.
    *
-   * SDK options are call-attached, not session-attached: the resumed
-   * call loads the prior conversation but otherwise uses whatever
-   * options this call passes. Omitting tool/prompt/setting options on
-   * resume causes the agent to silently lose its restrictions and
-   * persona between turns.
+   * SDK options attach to the call. They do not attach to the session.
+   * The resumed call loads the prior conversation. It otherwise uses
+   * whatever options this call passes. If you omit the tool, prompt, or
+   * setting options on resume, the agent silently loses its restrictions
+   * and persona between turns.
    */
   #callOptions(abortController) {
     return {
@@ -179,14 +187,14 @@ export class AgentRunner {
   }
 
   /**
-   * Iterate the SDK query iterator, mirroring every message to the
-   * output stream and the `onLine` callback. Captures `sessionId` from
-   * the SDK's `system/init` message and tracks Skill invocations into
+   * Iterate the SDK query iterator. Mirror every message to the output
+   * stream and to the `onLine` callback. Capture `sessionId` from the
+   * SDK's `system/init` message. Track Skill invocations into
    * `LIBHARNESS_SKILL` for downstream metrics.
    *
    * If the iterator throws and we triggered the abort ourselves
    * (`currentAbortController.signal.aborted`), we report `aborted:
-   * true`; otherwise the error propagates as `error`.
+   * true`. Otherwise the error propagates as `error`.
    */
   async #consumeQuery(iterator) {
     let text = "";
@@ -212,10 +220,10 @@ export class AgentRunner {
       }
     }
 
-    // A "success" subtype is necessary but not sufficient: the SDK reports a
-    // failed init (e.g. an invalid API key) as success with zero model work.
-    // Require evidence the model actually ran, and surface a clear error when
-    // it didn't, so the masked failure can't be reported as a green run.
+    // A "success" subtype is necessary. It is not sufficient. The SDK reports
+    // a failed init (e.g. an invalid API key) as success with zero model work.
+    // Require evidence that the model ran. Surface a clear error when it did
+    // not, so nobody reports the masked failure as a green run.
     const reportedSuccess = stopReason === "success";
     const success =
       reportedSuccess &&
@@ -223,7 +231,7 @@ export class AgentRunner {
       modelDidWork(resultMessage);
     if (reportedSuccess && !success && !error) {
       error = new Error(
-        "agent reported success but performed no model work (zero token usage) — likely a Claude Code init or authentication failure",
+        "agent reported success but did no model work (zero token usage), which is likely a Claude Code init or authentication failure",
       );
     }
 
@@ -251,8 +259,9 @@ export class AgentRunner {
   #trackSkillInvocation(message) {
     const content = message.message?.content ?? message.content;
     if (!Array.isArray(content)) return;
-    // Skill metric is recorded into the env map; without a runtime there is
-    // no env surface to write to, so the side-effect is simply skipped.
+    // The runner records the Skill metric into the env map. Without a
+    // runtime there is no env surface to write to, so the code simply skips
+    // the side-effect.
     const env = this.runtime?.proc?.env ?? null;
     if (!env) return;
     for (const block of content) {
@@ -268,9 +277,10 @@ export class AgentRunner {
 }
 
 /**
- * Factory function — wires real dependencies. Resolves the native `claude`
- * executable for compiled fit-* binaries so the SDK doesn't fail to find its
- * own platform optional dependency; an explicit `deps` value overrides it.
+ * Factory function — wires real dependencies. It resolves the native
+ * `claude` executable for compiled fit-* binaries, so the SDK doesn't fail
+ * to find its own platform optional dependency. An explicit `deps` value
+ * overrides it.
  */
 export function createAgentRunner(deps) {
   return new AgentRunner({

package/src/benchmark/apm-installer.js

@@ -1,13 +1,13 @@
 /**
  * ApmInstaller — runs `apm install --target claude` in the family root to
- * materialise skills and agents, copies the resulting `.claude/` into a
- * staging directory, and computes the manifest fingerprint from the lockfile.
- * Per-task copy happens later in WorkdirManager.
+ * materialise skills and agents. It copies the resulting `.claude/` into a
+ * staging directory. It computes the manifest fingerprint from the lockfile.
+ * WorkdirManager makes the per-task copy later.
  *
- * Subprocess and filesystem access route through the injected `runtime` bag
- * (`runtime.subprocess.spawn` for the streaming `apm` child, `runtime.fs` for
- * the async staging copies). See `createApmInstaller` for the real-dependency
- * wiring; `installApm` is a thin free-function wrapper.
+ * Subprocess and filesystem access route through the injected `runtime` bag.
+ * The `apm` child streams through `runtime.subprocess.spawn`. The async
+ * staging copies use `runtime.fs`. See `createApmInstaller`, which wires the
+ * real dependencies. `installApm` is a thin free-function wrapper.
  */
 
 import { createHash } from "node:crypto";
@@ -18,7 +18,7 @@ export class ApmInstaller {
   /**
    * @param {object} deps
    * @param {import("@forwardimpact/libutil/runtime").Runtime} deps.runtime -
-   *   Ambient collaborators; uses `subprocess.spawn` and `fs`.
+   *   Ambient collaborators. The installer uses `subprocess.spawn` and `fs`.
    */
   constructor({ runtime }) {
     if (!runtime) throw new Error("runtime is required");
@@ -30,8 +30,8 @@ export class ApmInstaller {
    * @param {string} outputDir - The benchmark run's output directory.
    * @param {object} [options]
    * @param {string|null} [options.skillsFrom] - Stage `.claude/` from this
-   *   directory instead of running apm install. The path is a root containing
-   *   a `.claude/` tree (e.g. a working tree), letting a run exercise local,
+   *   directory and do not run apm install. The path is a root that contains
+   *   a `.claude/` tree (e.g. a working tree). A run can then exercise local,
    *   unpublished skills.
    * @returns {Promise<{stagingDir: string, skillSetHash: string, judgeProfilesDir: string}>}
    */
@@ -44,7 +44,7 @@ export class ApmInstaller {
       : join(family.rootPath, ".claude");
     const apmYml = join(family.rootPath, "apm.yml");
 
-    // --skills-from takes precedence over apm install: the caller is supplying
+    // --skills-from takes precedence over apm install. The caller supplies
     // the skill tree explicitly, so no remote fetch runs.
     const hasApm =
       !skillsFrom &&
@@ -59,7 +59,7 @@ export class ApmInstaller {
         await fs.access(sourceClaude);
       } catch {
         throw new Error(
-          `apm install did not produce .claude/ at ${sourceClaude}; check the family's apm.yml`,
+          `apm install did not produce .claude/ at ${sourceClaude}. Check the family's apm.yml`,
         );
       }
     }
@@ -78,18 +78,18 @@ export class ApmInstaller {
       await fs.mkdir(stagedClaude, { recursive: true });
     }
 
-    // apm's claude target deploys a pack's skills/ into .claude/skills/ but
-    // never its agents/ subtree (agent profiles + references). Stage that from
-    // the installed apm_modules into .claude/agents/ so a skill that cites an
-    // agent reference (e.g. the work-item tracker matrix) resolves in the
-    // agent CWD. No-op when --skills-from supplied a tree or no apm_modules
-    // exist.
+    // apm's claude target deploys a pack's skills/ into .claude/skills/. It
+    // never deploys that pack's agents/ subtree (agent profiles +
+    // references). Stage that subtree from the installed apm_modules into
+    // .claude/agents/. A skill that cites an agent reference (e.g. the
+    // work-item tracker matrix) then resolves in the agent CWD. This is a
+    // no-op when --skills-from supplied a tree or no apm_modules exist.
     if (!skillsFrom) {
       await this.#stageApmAgents(family.rootPath, stagedClaude);
     }
 
-    // Stage the family-local judge profile outside .claude/ so it is available
-    // to the judge but never copied into the agent-under-test's CWD.
+    // Stage the family-local judge profile outside .claude/, so the judge can
+    // reach it. Nothing copies it into the agent-under-test's CWD.
     const judgeSource = join(family.rootPath, "judge.md");
     const judgeProfilesDir = join(stagingDir, "judge-profiles");
     try {
@@ -106,7 +106,7 @@ export class ApmInstaller {
         "sha256:" +
         createHash("sha256").update(normalizeLf(lockBytes)).digest("hex");
     } catch {
-      // No lockfile — family doesn't use skill packs.
+      // No lockfile. The family doesn't use skill packs.
     }
 
     return { stagingDir, skillSetHash, judgeProfilesDir };
@@ -115,8 +115,8 @@ export class ApmInstaller {
   /**
    * Merge each installed pack's `agents/` subtree (profiles + references) from
    * `apm_modules/<owner>/<pack>/agents/` into the staged `.claude/agents/`.
-   * apm's claude target deploys `skills/` only, so without this an agent
-   * reference a skill cites is absent from the agent CWD.
+   * apm's claude target deploys `skills/` only. Without this merge, an agent
+   * reference that a skill cites is absent from the agent CWD.
    * @param {string} familyRoot
    * @param {string} stagedClaude
    */
@@ -127,7 +127,7 @@ export class ApmInstaller {
     try {
       owners = await fs.readdir(modulesRoot, { withFileTypes: true });
     } catch {
-      return; // no apm_modules — nothing to stage
+      return; // no apm_modules, so nothing to stage
     }
     const stagedAgents = join(stagedClaude, "agents");
     for (const owner of owners) {
@@ -159,8 +159,8 @@ export class ApmInstaller {
       ["install", "--target", "claude"],
       { cwd, stdio: ["ignore", "pipe", "pipe"] },
     );
-    // Drain stdout concurrently so the child never blocks on backpressure;
-    // capture stderr for the failure message.
+    // Drain stdout concurrently so the child never blocks on backpressure.
+    // Capture stderr for the failure message.
     let stderr = "";
     const drainStdout = (async () => {
       for await (const _chunk of child.stdout) {
@@ -199,8 +199,8 @@ export function createApmInstaller(deps) {
  * @param {import("./task-family.js").TaskFamily} family
  * @param {string} outputDir
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
- * @param {object} [options] - Forwarded to `ApmInstaller.install` (e.g.
- *   `{ skillsFrom }`).
+ * @param {object} [options] - This function forwards these to
+ *   `ApmInstaller.install` (e.g. `{ skillsFrom }`).
  */
 export function installApm(family, outputDir, runtime, options = {}) {
   return new ApmInstaller({ runtime }).install(family, outputDir, options);

package/src/benchmark/env-loader.js

@@ -1,17 +1,20 @@
 /**
  * Env-loader — auto-discover `.env` / `.env.local` files in a task family
- * and its tasks, load them into `process.env`, and render the merged result
+ * and its tasks. Load them into `process.env`. Render the merged result
  * into each agent CWD.
  *
- * Discovery paths (loaded in this order, first value per key wins):
- *   1. process.env  (CI secrets, shell env — never overwritten)
+ * The loader reads the discovery paths in this order. The first value per
+ * key wins:
+ *   1. process.env  (CI secrets and shell env, which the loader never
+ *      overwrites)
  *   2. <family>/.env.local
  *   3. <family>/.env
  *   4. tasks/<id>/.env.local
  *   5. tasks/<id>/.env
  *
- * Every discovered env file — family or task — is loaded into process.env
- * AND rendered (with resolved values) into the agent working directory.
+ * The loader loads every discovered env file, family or task, into
+ * process.env. It also renders the file (with resolved values) into the
+ * agent working directory.
  */
 
 import { join } from "node:path";
@@ -20,7 +23,8 @@ const ENV_FILES = [".env.local", ".env"];
 
 /**
  * Parse a `.env` file into an array of {key, value} pairs.
- * Handles KEY=VALUE, # comments, blank lines, and single/double-quoted values.
+ * It handles KEY=VALUE, # comments, blank lines, and single/double-quoted
+ * values.
  * @param {string} content
  * @returns {Array<{key: string, value: string}>}
  */
@@ -46,7 +50,7 @@ export function parseEnvFile(content) {
 }
 
 /**
- * Read and parse an env file, returning [] if the file does not exist.
+ * Read and parse an env file. Return [] if the file does not exist.
  * @param {object} fs - Async filesystem surface (`runtime.fs`).
  * @param {string} filePath
  * @returns {Promise<Array<{key: string, value: string}>>}
@@ -62,10 +66,11 @@ async function readEnvFile(fs, filePath) {
 }
 
 /**
- * Load entries into the process env map. Existing keys are never overwritten.
+ * Load entries into the process env map. This function never overwrites an
+ * existing key.
  * @param {Record<string, string|undefined>} env - The `runtime.proc.env` map.
  * @param {Array<{key: string, value: string}>} entries
- * @returns {string[]} var names that were loaded
+ * @returns {string[]} the var names it loaded
  */
 function applyToProcessEnv(env, entries) {
   const names = [];
@@ -79,7 +84,8 @@ function applyToProcessEnv(env, entries) {
 }
 
 /**
- * Load one env file: apply to the env map, record keys in the merged map.
+ * Load one env file. Apply it to the env map. Record the keys in the merged
+ * map.
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @param {string} dir
  * @param {string} file
@@ -100,7 +106,7 @@ async function loadOneEnvFile(runtime, dir, file, names, merged) {
 }
 
 /**
- * Scan directories for env files, load into the env map, and collect
+ * Scan directories for env files. Load them into the env map. Collect
  * a merged key manifest per filename.
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @param {string[]} dirs
@@ -118,7 +124,7 @@ async function collectEnvEntries(runtime, dirs) {
 }
 
 /**
- * Write resolved env files into the agent CWD and warn about empty values.
+ * Write resolved env files into the agent CWD. Warn about empty values.
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @param {Map<string, Map<string, true>>} merged
  * @param {string} agentCwd
@@ -142,14 +148,16 @@ async function renderEnvFiles(runtime, merged, agentCwd) {
 }
 
 /**
- * Discover `.env` / `.env.local` in one or more directories, load them
- * into the process env map, and render the resolved values into the agent CWD.
+ * Discover `.env` / `.env.local` in one or more directories. Load them
+ * into the process env map. Render the resolved values into the agent CWD.
  *
  * @param {string[]} dirs - Directories to scan (family root, task dir, etc.)
  * @param {string} agentCwd - Agent working directory to render into.
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime - Ambient
- *   collaborators; uses `fs` (async read/write), `proc.env`, `proc.stderr`.
- * @returns {Promise<string[]>} All var names discovered (for redaction).
+ *   collaborators. It uses `fs` (async read/write), `proc.env`, and
+ *   `proc.stderr`.
+ * @returns {Promise<string[]>} Every var name the loader discovered (for
+ *   redaction).
  */
 export async function loadEnv(dirs, agentCwd, runtime) {
   const { names, merged } = await collectEnvEntries(runtime, dirs);

package/src/benchmark/grade.js

@@ -1,46 +1,50 @@
 /**
- * Grading derivation — the sole home of the check-row arithmetic.
+ * Grade derivation — the sole home of the check-row arithmetic.
  *
- * Check rows are the single authoritative grading channel. Every row is a
- * check by default; a row declares its role with its own fields, checked in
- * order:
+ * Check rows are the one authoritative input to the grade. Every row is a
+ * check by default. A row declares its role with its own fields. The
+ * classifier checks the roles in this order:
  *
  *   1. Gate       — `gate` is exactly `true`, `pass` is boolean, and no
- *                   `weight` key is present. Any failing gate → `gatesPass`
- *                   false.
- *   2. Diagnostic — no `gate` key and `weight` is exactly `0`. Free-form;
- *                   never graded.
+ *                   `weight` key is present. A gate that fails sets
+ *                   `gatesPass` to false.
+ *   2. Diagnostic — no `gate` key and `weight` is exactly `0`. The row is
+ *                   free-form. The grader never scores it.
  *   3. Scored     — no `gate` key, boolean `pass`, `weight` absent (defaults
  *                   to 1) or finite > 0.
- *   4. Malformed  — everything else: any `gate`+`weight` co-occurrence (a
- *                   stray weight must never silently disarm a gate), a
+ *   4. Malformed  — everything else: any `gate`+`weight` co-occurrence, a
  *                   non-boolean `gate`, a missing or non-boolean `pass` on a
  *                   graded row, an invalid `weight`, an fd-3 line that failed
- *                   to parse, a non-object row. Counts as a **failing scored
- *                   check** — dropping a defect could mint full marks;
- *                   failing the whole run would zero completed work.
+ *                   to parse, a non-object row. A stray weight must never
+ *                   silently disarm a gate. A malformed row counts as a
+ *                   **scored check that fails**. If the grader dropped the
+ *                   defect, the cell could mint full marks. If it failed the
+ *                   whole run, it would zero completed work.
  *
- * The producers' `source` stamp is display metadata, never a grading input.
+ * The producers' `source` stamp is display metadata. The grader never reads
+ * it.
  */
 
 /**
  * @typedef {object} GradeResult
  * @property {"pass" | "fail"} verdict - `healthy ∧ gatesPass ∧ fullMarks`.
  * @property {boolean} gatesPass - Every gate row passes (vacuously true).
- * @property {number | null} score - Weighted fraction of passing scored
- *   checks; `null` when the cell has zero scored checks (binary task).
- * @property {boolean} fullMarks - Integer count predicate: no malformed rows
- *   and every scored check passes. Never a float comparison, so fractional
- *   weights carry no equality hazard. Vacuously true with zero scored checks.
+ * @property {number | null} score - Weighted fraction of the scored checks
+ *   that pass. It is `null` when the cell has zero scored checks (binary
+ *   task).
+ * @property {boolean} fullMarks - An integer count predicate. It is true when
+ *   no row is malformed and every scored check passes. It is never a float
+ *   comparison, so fractional weights carry no equality hazard. It is
+ *   vacuously true with zero scored checks.
  * @property {number} malformed - Malformed row count.
  */
 
 /**
  * Grade the merged check rows against grader health.
  *
- * `healthy` is the completion signal a crashed grader cannot fake: when it is
- * false the verdict is `fail` whatever the rows say, so a hook that dies
- * after emitting passing rows can never mint marks.
+ * `healthy` is the completion signal a crashed grader cannot fake. When it is
+ * false, the verdict is `fail` whatever the rows say. A hook that emits rows
+ * that pass and then dies can never mint marks.
  * @param {unknown[]} details - Merged check rows from both producers.
  * @param {boolean} healthy - Invariants exited 0 AND the hidden-test engine
  *   did not throw.
@@ -73,7 +77,7 @@ export function gradeChecks(details, healthy) {
 }
 
 /**
- * Fold one row into the running tally per its classified role.
+ * Fold one row into the tally per its classified role.
  * @param {{gatesPass: boolean, malformed: number, scored: number, passing: number, weightAll: number, weightPassing: number}} tally
  * @param {unknown} row
  */
@@ -96,11 +100,10 @@ function tallyRow(tally, row) {
 }
 
 /**
- * Run both check-row producers and grade the merged rows — the one
- * composition shared by the runner and the `grade` subcommand. An engine
- * throw is grader fault: its message lands on the returned `engineError`
- * and health fails, so a crashed grader can never mint marks from rows it
- * happened to emit first.
+ * Run both check-row producers and grade the merged rows. The runner and the
+ * `grade` subcommand share this one composition. An engine throw is grader
+ * fault. Its message lands on the returned `engineError` and health fails. A
+ * crashed grader can never mint marks from rows it emitted first.
  * @param {import("./task-family.js").Task} task
  * @param {{cwd: string, port: number, runDir: string, familyDir?: string|null}} ctx
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
@@ -126,8 +129,8 @@ export async function runProducersAndGrade(task, ctx, runtime, producers) {
 
 /**
  * Merge the two producers' rows (invariants first) and stamp each row's
- * provenance. The stamp is display metadata, never a grading input, and
- * non-object rows (malformed by contract) pass through verbatim.
+ * provenance. The stamp is display metadata. The grader never reads it.
+ * Non-object rows (malformed by contract) pass through verbatim.
  * @param {unknown[]} invariantsDetails
  * @param {unknown[]} hiddenDetails
  * @returns {unknown[]}
@@ -147,9 +150,9 @@ function stampSource(row, source) {
 }
 
 /**
- * Project the raw `gradeChecks` return onto the record schema: `fullMarks`
- * is derivable and dropped, `score` is omitted on binary tasks (`null`),
- * `malformed` is omitted when clean.
+ * Project the raw `gradeChecks` return onto the record schema. `fullMarks` is
+ * derivable, so this function drops it. It omits `score` on binary tasks
+ * (`null`). It omits `malformed` when the rows are clean.
  * @param {GradeResult} raw
  * @returns {{verdict: "pass"|"fail", gatesPass: boolean, score?: number, malformed?: number}}
  */
@@ -177,9 +180,9 @@ function classifyRow(row) {
 }
 
 /**
- * A row carrying a `gate` key: valid only as `gate: true` with a boolean
- * `pass` and no `weight` key — any co-occurring weight is malformed so a
- * stray weight can never silently disarm a gate.
+ * Classify a row that has a `gate` key. The row is valid only as `gate: true`
+ * with a boolean `pass` and no `weight` key. Any weight that co-occurs makes
+ * the row malformed. A stray weight can never silently disarm a gate.
  * @param {object} row
  * @returns {"gate" | "malformed"}
  */
@@ -191,9 +194,9 @@ function classifyGateRow(row) {
 }
 
 /**
- * A gate-less row carrying a `weight` key: exactly 0 is a diagnostic, a
- * finite positive weight with a boolean `pass` is scored, anything else is
- * malformed.
+ * Classify a gate-less row that has a `weight` key. A weight of exactly 0 is
+ * a diagnostic. A finite positive weight with a boolean `pass` is scored.
+ * Anything else is malformed.
  * @param {object} row
  * @returns {"diagnostic" | "scored" | "malformed"}
  */
@@ -205,8 +208,8 @@ function classifyWeightedRow(row) {
 }
 
 /**
- * A malformed row fails at its own weight when it carries a valid positive
- * one, else at unit weight 1.
+ * A malformed row fails at its own weight when that weight is valid and
+ * positive. Otherwise it fails at unit weight 1.
  * @param {unknown} row
  * @returns {number}
  */