mandrel 2.60.0 → 2.62.0

package/.agents/scripts/lib/close-validation/process.js

@@ -1,36 +1,23 @@
-/**
- * close-validation/process.js — Child-process lifecycle plumbing for gates.
- *
- * Owns the default async gate runner (spawn + line-prefixed stdio piping)
- * and the AbortSignal / exit-code helpers it composes.
- */
+/** Default async gate runner: spawn, line-prefixed stdio, abort and exit codes. */
 
 import { spawn } from 'node:child_process';
 
-import { withFullSuiteLockAsync } from '../full-suite-lock.js';
+import {
+  LOCK_WAIT_EXPIRED_EXIT_CODE,
+  withFullSuiteLockAsync,
+} from '../full-suite-lock.js';
+import {
+  groupSpawnOptions,
+  superviseGroup,
+  TIMEOUT_EXIT_CODE,
+} from '../process-group.js';
 
 /**
- * Pipe a child stream's output line-by-line through `emit`, prepending
- * `prefix` to each line. Tail bytes without a trailing newline flush on
- * `end` so the operator never loses the last line of a gate's output.
- *
- * ## The drain must stay cheap (Story #4766)
+ * Emit each line with `prefix`; the unterminated tail flushes on `end`.
  *
- * This handler runs on the reader side of the child's stdout/stderr pipe.
- * Every microsecond spent here is a microsecond the pipe is not being read,
- * and once the OS pipe buffer fills, the child's own write blocks — or, on a
- * non-blocking pipe, fails outright with `EAGAIN`. A gate child is not
- * obliged to survive that: Biome's `biome_console` `.unwrap()`s the error and
- * aborts the process with exit 101, so a green lint verdict presents as a
- * failed close. Two consequences bind everything on this path:
- *
- *   1. Splitting is O(chunk), not O(chunk × lines) — the scan advances a
- *      `start` index instead of re-slicing the buffer once per line, so a
- *      64KB chunk carrying 500 lines does not copy 16MB.
- *   2. **`emit` MUST NOT block.** A synchronous per-line file write is
- *      exactly the stall this path cannot afford; the close path's capture
- *      sink (`single-story-close/gate-log.js`) buffers to an async stream for
- *      that reason.
+ * The drain must stay cheap: a slow reader fills the pipe and the child's
+ * write fails with `EAGAIN` (Biome then aborts with exit 101, a false red).
+ * So splitting advances an index (O(chunk)), and `emit` MUST NOT block.
  */
 function pipePrefixed(stream, prefix, emit) {
   let buf = '';
@@ -57,24 +44,6 @@ function pipePrefixed(stream, prefix, emit) {
   stream.on('error', () => {});
 }
 
-/** Wire the AbortSignal so an abort kills the child. Returns the cleanup fn. */
-export function attachGateAbortHandler(child, signal) {
-  if (!signal) return () => {};
-  const killChild = () => {
-    try {
-      child.kill('SIGTERM');
-    } catch {
-      /* race: already exited */
-    }
-  };
-  if (signal.aborted) {
-    killChild();
-    return () => {};
-  }
-  signal.addEventListener('abort', killChild, { once: true });
-  return () => signal.removeEventListener('abort', killChild);
-}
-
 /** SIGTERM (no exit code) on abort → non-zero so the gate counts as failed. */
 export function gateExitCode(code, sig) {
   if (typeof code === 'number') return code;
@@ -82,37 +51,20 @@ export function gateExitCode(code, sig) {
 }
 
 /**
- * Biome's marker for "you handed me a path set, but every one of them is
- * excluded by my own config (`files.includes` allowlist / `files.ignore` /
- * `overrides`), so I processed nothing" — biome exits 1 in that case.
- *
- * The format gate scopes biome to the changed-file subset (Story #3410). When
- * that subset is non-empty by extension but every path is biome-config-ignored,
- * the scoped invocation reports this message and exits 1 even though
- * `biome format .` over the whole tree is clean — a false negative for the
- * gate (Story #4292). Detecting the marker lets the runner treat that exit as
- * a clean skip rather than a formatting failure.
+ * Biome exits 1 with this when every path handed to it is config-ignored — a
+ * false negative for the changed-file-scoped format gate, treated as a skip.
  */
 const BIOME_NO_FILES_PROCESSED =
   'No files were processed in the specified paths';
 
 /**
- * How many trailing gate lines the "No files were processed" probe retains.
- *
- * The marker only ever appears when biome processed nothing, and in that case
- * its whole output is a handful of lines — so a bounded tail always contains
- * it when it is there at all. Retaining a tail rather than the full transcript
- * keeps the drain path's per-line work O(1) in the volume of gate output
- * (Story #4766): the previous `captured += line` grew a string without limit,
- * on the one gate (biome/format) whose output is the loudest.
+ * The marker only appears in a few-line output, so a bounded tail always
+ * holds it and keeps per-line drain work O(1).
  */
 const MARKER_PROBE_TAIL_LINES = 32;
 
 /**
- * Whether biome's combined gate output carries the "No files were processed"
- * marker. Pure function — no I/O. Exported for unit coverage (Story #4292).
- *
- * @param {string} output - Combined stdout/stderr captured from the gate child.
+ * @param {string} output - Combined stdout/stderr.
  * @returns {boolean}
  */
 function isBiomeNoFilesProcessed(output) {
@@ -122,115 +74,133 @@ function isBiomeNoFilesProcessed(output) {
 }
 
 /**
- * Default async gate runner — used by `runCloseValidation` when no `runner`
- * is injected. Spawns the gate via `child_process.spawn`, prefixes every
- * stdout/stderr line with `[gate-name] ` (so concurrent gates don't bleed
- * into each other in the operator's terminal), and resolves only once the
- * child has exited and both stdio pipes are drained.
- *
- * `opts.log` is the drain sink and **must not block** — see `pipePrefixed`
- * above for what a synchronous per-line write costs the child (Story #4766).
- *
- * Honours `opts.signal`: a TERM is delivered to the child the moment the
- * signal fires, so a sibling gate's failure aborts the rest of the wave
- * promptly. The promise still resolves (rather than rejecting) on abort —
- * `runCloseValidation` sees a non-zero status and folds it into the
- * already-recorded first-failure.
- *
- * When `opts.tolerateNoFilesProcessed` is set (the biome-scoped format gate —
- * Story #4292), a non-zero exit whose combined output carries biome's
- * "No files were processed" marker is downgraded to a clean `status: 0`,
- * because that exit means every config-included path was already excluded,
- * not that formatting drifted.
+ * Spawn a gate with `[gate-name] `-prefixed output; resolves (never rejects)
+ * once the child exits and both pipes drain. `opts.log` must not block.
+ * An abort signal TERMs the child so a sibling failure stops the wave.
  *
- * When `opts.fullSuiteLock` is set — the standalone `test` gate, the one gate
- * here that runs a whole suite (Story #5173) — the spawn is serialized behind
- * the host-level advisory lock so two concurrent closes on one checkout do not
- * run two suites against the same cores. Best-effort: a wait that expires
- * spawns anyway. The async wrapper is used rather than the synchronous one
- * precisely because this runner drives sibling gates on the same event loop,
- * which a blocking wait would stall.
+ * `fullSuiteLock` serializes the spawn behind the host lock (async, so
+ * sibling gates on this event loop are not stalled). An expired wait spawns
+ * anyway unless `deferOnLockExpiry`, which returns
+ * `LOCK_WAIT_EXPIRED_EXIT_CODE` so close ends `pending`. Each child leads its
+ * own process group so a timeout, abort or parent signal kills its workers too.
  *
  * @param {string} cmd
  * @param {string[]} args
- * @param {{ cwd: string, signal?: AbortSignal, gateName?: string, log?: (m: string) => void, env?: Record<string, string>, tolerateNoFilesProcessed?: boolean, fullSuiteLock?: boolean, skipIfSatisfied?: () => {status: number}|undefined }} opts
+ * @param {{ cwd: string, signal?: AbortSignal, gateName?: string, log?: (m: string) => void, env?: Record<string, string>, tolerateNoFilesProcessed?: boolean, fullSuiteLock?: boolean, deferOnLockExpiry?: boolean, timeoutMs?: number, lockOptions?: object, skipIfSatisfied?: () => {status: number}|undefined }} opts
  * @returns {Promise<{ status: number }>}
  */
 export function defaultGateRunner(cmd, args, opts = {}) {
   if (!opts.fullSuiteLock) return spawnGate(cmd, args, opts);
-  // `log` is passed through as-is: `withFullSuiteLockAsync` supplies its own
-  // no-op default, so a second fallback here would be an untestable branch.
-  // `skipIfSatisfied` (Story #5278) is the caller's post-wait re-probe: after
-  // queueing behind another full suite, the gate re-asks whether its evidence
-  // has since been deposited and returns that verdict instead of spawning.
-  return withFullSuiteLockAsync(
-    { cwd: opts.cwd, log: opts.log, skipIfSatisfied: opts.skipIfSatisfied },
-    () => spawnGate(cmd, args, opts),
+  // `skipIfSatisfied` re-probes after the wait: evidence another suite
+  // deposited meanwhile is returned instead of spawning.
+  return withFullSuiteLockAsync(gateLockOptions(opts), () =>
+    spawnGate(cmd, args, opts),
   );
 }
 
+function gateLockOptions(opts) {
+  return {
+    cwd: opts.cwd,
+    log: opts.log,
+    skipIfSatisfied: opts.skipIfSatisfied,
+    onWaitExpired: opts.deferOnLockExpiry ? deferredGateStatus : undefined,
+    ...opts.lockOptions, // test seam only
+  };
+}
+
+function deferredGateStatus() {
+  return { status: LOCK_WAIT_EXPIRED_EXIT_CODE };
+}
+
 /**
- * The bare gate spawn — child process, prefixed drain, abort wiring, exit-code
- * normalisation. Split from {@link defaultGateRunner} so the full-suite lock
- * composes over one named unit.
- *
  * @param {string} cmd
  * @param {string[]} args
  * @param {Parameters<typeof defaultGateRunner>[2]} opts
  * @returns {Promise<{ status: number }>}
  */
 function spawnGate(cmd, args, opts) {
-  const { cwd, signal, gateName, log, env, tolerateNoFilesProcessed } = opts;
-  const child = spawn(cmd, args, {
+  const child = spawnGateChild(cmd, args, opts);
+  const output = gateOutput(opts);
+  pipePrefixed(child.stdout, output.prefix, output.tap);
+  pipePrefixed(child.stderr, output.prefix, output.tap);
+  // A bare suite has nothing to clean up, so it gets SIGKILL; other gates
+  // (a capture holding the lock) get SIGTERM to release and kill their suite.
+  const supervisor = superviseGroup(child, {
+    timeoutMs: opts.timeoutMs,
+    abortSignal: opts.signal,
+    signalOnParentSignal: opts.fullSuiteLock ? 'SIGKILL' : 'SIGTERM',
+  });
+  return new Promise((resolve) => {
+    // 'close', not 'exit': only 'close' waits for both pipes to drain.
+    child.on('close', (code, sig) => {
+      supervisor.release();
+      resolve({
+        status: settledGateStatus({ code, sig, supervisor, opts, output }),
+      });
+    });
+    child.on('error', () => {
+      supervisor.release();
+      resolve({ status: 1 });
+    });
+  });
+}
+
+/**
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{ cwd: string, env?: Record<string, string> }} opts
+ */
+function spawnGateChild(cmd, args, { cwd, env }) {
+  return spawn(cmd, args, {
     cwd,
     shell: process.platform === 'win32',
     stdio: ['ignore', 'pipe', 'pipe'],
-    // Per-gate env overlay (Story #3890): merged over the inherited
-    // environment so a gate-scoped `BASELINE_REF` reaches the spawned
-    // `check-baselines` child without mutating the parent process env.
+    ...groupSpawnOptions(),
     ...(env ? { env: { ...process.env, ...env } } : {}),
   });
+}
+
+/**
+ * Retains a bounded tail only when the biome marker may need inspecting.
+ *
+ * @param {{ gateName?: string, log?: (m: string) => void, tolerateNoFilesProcessed?: boolean }} opts
+ */
+function gateOutput({ gateName, log, tolerateNoFilesProcessed }) {
   const prefix = gateName ? `[${gateName}] ` : '';
   const emit =
     typeof log === 'function' ? log : (m) => process.stdout.write(`${m}\n`);
-  // Retain a bounded tail only when we may need to inspect it for the biome
-  // "No files were processed" marker — otherwise the stream is purely piped
-  // through to the operator (no retained buffer).
   const recent = [];
-  const tap = tolerateNoFilesProcessed
-    ? (line) => {
-        recent.push(line);
-        if (recent.length > MARKER_PROBE_TAIL_LINES) recent.shift();
-        emit(line);
-      }
-    : emit;
-  pipePrefixed(child.stdout, prefix, tap);
-  pipePrefixed(child.stderr, prefix, tap);
-  const detach = attachGateAbortHandler(child, signal);
-  return new Promise((resolve) => {
-    // 'close', not 'exit' (Story #4766): 'close' fires only once the child has
-    // exited AND both stdio pipes have been fully drained and closed, so no
-    // gate ever reports its status while lines are still in flight. Resolving
-    // on 'exit' raced the tail of a high-volume gate's output.
-    child.on('close', (code, sig) => {
-      detach();
-      const status = gateExitCode(code, sig);
-      if (
-        status !== 0 &&
-        tolerateNoFilesProcessed &&
-        isBiomeNoFilesProcessed(recent.join('\n'))
-      ) {
-        emit(
-          `${prefix}↳ biome processed zero files (all changed paths are config-ignored); treating as a clean skip`,
-        );
-        resolve({ status: 0 });
-        return;
-      }
-      resolve({ status });
-    });
-    child.on('error', () => {
-      detach();
-      resolve({ status: 1 });
-    });
-  });
+  const tap = tolerateNoFilesProcessed ? retainTail(recent, emit) : emit;
+  return { prefix, emit, tap, recent };
+}
+
+function retainTail(recent, emit) {
+  return (line) => {
+    recent.push(line);
+    if (recent.length > MARKER_PROBE_TAIL_LINES) recent.shift();
+    emit(line);
+  };
+}
+
+function settledGateStatus(settled) {
+  return settled.supervisor.timedOut
+    ? timedOutStatus(settled)
+    : exitedStatus(settled);
+}
+
+function timedOutStatus({ opts, output }) {
+  output.emit(
+    `${output.prefix}⏱ exceeded ${opts.timeoutMs}ms — killed the gate's process group. Returning exit ${TIMEOUT_EXIT_CODE}.`,
+  );
+  return TIMEOUT_EXIT_CODE;
+}
+
+function exitedStatus({ code, sig, opts, output }) {
+  const status = gateExitCode(code, sig);
+  if (status === 0 || !opts.tolerateNoFilesProcessed) return status;
+  if (!isBiomeNoFilesProcessed(output.recent.join('\n'))) return status;
+  output.emit(
+    `${output.prefix}↳ biome processed zero files (all changed paths are config-ignored); treating as a clean skip`,
+  );
+  return 0;
 }

package/.agents/scripts/lib/close-validation/projections/advisories.js

@@ -1,24 +1,8 @@
 // .agents/scripts/lib/close-validation/projections/advisories.js
 /**
- * advisories.js — the projection layer's single call site (Story #4776).
- *
- * `projections/maintainability.js` shipped fully written, fully unit-tested
- * and imported by nothing: the v2 Epic-tier collapse removed its caller and
- * left the module behind. The practical consequence was that the advisory
- * telling an operator to run `npm run maintainability:update` and commit a
- * `baseline-refresh:` subject had never fired in v2 — consumers refreshed
- * their baselines by hand or not at all.
- *
- * This module is that caller, for both projections. It is deliberately the
- * only door: `close-validation/runner.js` invokes `runProjectionAdvisories`
- * once, after the gate chain has passed, and every per-kind concern (gate
- * enablement, baseline path resolution, scorer construction, formatting)
- * lives here rather than being re-derived at the runner boundary.
- *
- * **Advisory, always.** Nothing in here can fail a close. `check-baselines`
- * already fails closed on a real regression; the projections add the refresh
- * half of the loop, not a second gate. Every projection is wrapped so a
- * throw becomes a logged skip.
+ * The projection layer's single call site, run once after the gate chain
+ * passes; owns every per-kind concern. Advisory only — nothing here can fail
+ * a close (`check-baselines` is the gate); a throw becomes a logged skip.
  */
 
 import path from 'node:path';
@@ -33,15 +17,12 @@ import {
   projectMaintainabilityRegressions,
 } from './maintainability.js';
 
-/** Default on-disk baseline locations, mirroring the per-gate defaults. */
 const DEFAULT_BASELINE_PATHS = Object.freeze({
   maintainability: 'baselines/maintainability.json',
   crap: 'baselines/crap.json',
 });
 
 /**
- * Resolve a gate's baseline file to an absolute path.
- *
  * @param {string} kind
  * @param {object} gate resolved `delivery.quality.gates.<kind>` block
  * @param {string} cwd
@@ -56,9 +37,7 @@ function resolveBaselinePath(kind, gate, cwd) {
 }
 
 /**
- * A gate is projected unless it is explicitly disabled. An absent gate
- * block means "framework defaults", which enable it — the same reading
- * `buildDefaultGates` applies.
+ * An absent gate block means defaults, which enable it.
  *
  * @param {object|undefined} gate
  * @returns {boolean}
@@ -68,9 +47,7 @@ function isEnabled(gate) {
 }
 
 /**
- * Run one projection with its formatter, swallowing every failure into a
- * logged skip. Returns the projection result (or `null` when it threw) so
- * callers and tests can inspect what happened without parsing log lines.
+ * `null` when the projection threw.
  *
  * @param {{ kind: string, log: (m: string) => void, run: () => Promise<object>|object, format: (r: object) => string|null }} opts
  * @returns {Promise<object|null>}
@@ -99,9 +76,6 @@ async function runOne({ kind, log, run, format }) {
 }
 
 /**
- * Run the maintainability and CRAP pre-merge projections and log their
- * advisories. Never throws; never affects the close verdict.
- *
  * @param {{
  *   cwd: string,
  *   baseBranch: string,

package/.agents/scripts/lib/close-validation/projections/crap.js

@@ -1,28 +1,11 @@
 // .agents/scripts/lib/close-validation/projections/crap.js
 /**
- * crap.js — pre-merge CRAP ceiling projection helper (Story #4776).
- *
- * The CRAP analogue of `projections/maintainability.js`. Both answer the
- * same operator question before the merge runs: *given what this branch
- * changed, which committed baseline rows would the post-merge tree breach,
- * and what is the exact remedy?*
- *
- * Advisory only. `check-baselines` already fails close-validation closed on
- * a real regression; duplicating that here would double-gate the same
- * defect. What this projection adds is the **refresh** half of the loop —
- * naming the breaching methods and the `npm run crap:update` +
- * `baseline-refresh:` remedy while the operator still has the branch in
- * hand, so a corrected baseline does not rot back into staleness.
- *
- * The helper never throws and never mutates anything. Every failure path
- * resolves to `{ ok: true, breaches: [], skipped: '<reason>' }` so the
- * caller can treat the advisory as best-effort.
- *
- * Post-merge approximation: CRAP needs a coverage join, so — unlike the MI
- * projection, which scores a `git show` blob — the scorer reads the working
- * tree. Close-validation runs inside the Story worktree at the branch tip,
- * which is exactly the content a squash-merge lands, so the approximation is
- * exact whenever the merge applies cleanly.
+ * Advisory pre-merge CRAP projection: names the methods the post-merge tree
+ * would breach and the `crap:update` + `baseline-refresh:` remedy
+ * (`check-baselines` already gates the real regression). Never throws;
+ * failures resolve to `{ ok: true, breaches: [], skipped }`. Scores the
+ * worktree (CRAP needs a coverage join), which at the branch tip is exactly
+ * what a clean squash-merge lands.
  */
 
 import path from 'node:path';
@@ -39,20 +22,13 @@ import { gitSpawn as defaultGitSpawn } from '../../git-utils.js';
 import { SCORABLE_SOURCE_EXT_RE } from '../../source-extensions.js';
 import { MISSING_ARG_REASONS, validateProjectionInputs } from './inputs.js';
 
-/**
- * Default absolute tolerance on a projected CRAP score, shared with
- * `check-crap`'s regression arm: floating-point noise must not register as
- * a breach.
- */
+/** Absorbs floating-point noise. */
 export const DEFAULT_CRAP_TOLERANCE = 0.001;
 
-/** Framework default for the new-method ceiling (`gates.crap.newMethodCeiling`). */
 export const DEFAULT_NEW_METHOD_CEILING = 30;
 
 /**
- * Map the shared predicate's fine-grained `missing-*` reason onto the
- * `missing-args` skipped-reason the sibling MI projection reports, so both
- * projections speak one vocabulary at the advisory boundary.
+ * Collapse `missing-*` to `missing-args`, matching the MI projection.
  *
  * @param {string} reason
  * @returns {string}
@@ -62,17 +38,10 @@ function normaliseSkipReason(reason) {
 }
 
 /**
- * Read the committed CRAP baseline and re-key its rows onto the `file`
- * field `compareCrap` matches on (the on-disk v2 envelope keys on `path`).
- * Returns `[]` when the baseline is absent or unreadable — the caller maps
- * that to the `no-baseline` skip.
- *
- * Deliberately module-local: `projectCrapBreaches`'s `loadBaseline` default
- * is the single production door to it, and tests inject their own loader.
- * Exporting it would add a second entry point nothing in production reaches
- * — which is precisely the orphaning this Story exists to stop.
+ * Re-keys on-disk `path` to the `file` field `compareCrap` matches on;
+ * `[]` when absent or unreadable.
  *
- * @param {string} baselinePath absolute path to `baselines/crap.json`
+ * @param {string} baselinePath
  * @returns {Array<{file: string, method: string, startLine: number, crap: number}>}
  */
 function loadCrapBaselineRows(baselinePath) {
@@ -92,10 +61,8 @@ function loadCrapBaselineRows(baselinePath) {
 }
 
 /**
- * Build the default working-tree CRAP scorer. Returns an async callable
- * `(files) => rows | null`; `null` signals "coverage artifact missing under
- * `requireCoverage`", which the projection reports as the `no-coverage`
- * skip rather than as a clean run.
+ * The scorer resolves `null` when coverage is missing under
+ * `requireCoverage` (a `no-coverage` skip, not a clean run).
  *
  * @param {{
  *   cwd: string,
@@ -132,9 +99,8 @@ export function createCrapScorer({
 }
 
 /**
- * Refresh `origin/<baseBranch>` so the diff range resolves even when close
- * has not reached its own base-sync step. Routed through the shared fetch
- * cache so a story-init fetch in the same run satisfies it for free.
+ * Close may not have base-synced yet; the fetch cache makes this free when
+ * story-init already fetched.
  *
  * @param {string} cwd
  * @param {string} baseBranch
@@ -153,10 +119,6 @@ function refreshBaseRef(cwd, baseBranch, git) {
 }
 
 /**
- * Enumerate the Story branch's changed files, narrowed by the shared
- * scorable-source extension set (`source-extensions.js`) so the projection
- * selects exactly the files the CRAP scanner walks.
- *
  * @param {{ cwd: string, baseBranch: string, storyBranch: string, git: { gitSpawn: typeof defaultGitSpawn } }} opts
  * @returns {{ ok: true, files: string[] } | { ok: false, detail: string }}
  */
@@ -177,13 +139,9 @@ function diffScorableFiles({ cwd, baseBranch, storyBranch, git }) {
 }
 
 /**
- * Project the post-merge CRAP scores for every file changed on the Story
- * branch and return the subset of methods that would breach either their
- * committed baseline row or, for methods with no baseline row, the
- * configured `newMethodCeiling`.
- *
- * Baseline rows are narrowed to the changed-file set before the compare so
- * every untouched file's rows are not spuriously reported as removed.
+ * Breaches are vs the baseline row, or `newMethodCeiling` for new methods.
+ * Baseline rows are narrowed to changed files so untouched rows do not read
+ * as removed.
  *
  * @param {{
  *   cwd: string,
@@ -266,9 +224,6 @@ export async function projectCrapBreaches({
 }
 
 /**
- * Render one breach as an advisory bullet. New-method breaches name the
- * ceiling they cleared; regressions name the baseline row they exceeded.
- *
  * @param {object} b
  * @returns {string}
  */
@@ -283,10 +238,7 @@ function formatBreach(b) {
 }
 
 /**
- * Render the pre-merge CRAP advisory as a human-readable multi-line log
- * block, naming every breaching method and the exact refresh remedy.
- * Returns `null` when there is nothing to surface so callers can `if` past
- * the log call without a string-empty check.
+ * `null` when there is nothing to surface.
  *
  * @param {Awaited<ReturnType<typeof projectCrapBreaches>>} result
  * @returns {string | null}

package/.agents/scripts/lib/close-validation/projections/head-sha.js

@@ -1,21 +1,7 @@
 // .agents/scripts/lib/close-validation/projections/head-sha.js
-/**
- * head-sha.js — resolves the current working tree's HEAD commit SHA.
- *
- * Extracted from close-validation.js (Story #1850) to keep the parent
- * module below the 700-LOC target and to land the helper below CRAP 12
- * in `baselines/crap.json`. The implementation is unchanged — it shells
- * out via the injected git interface, returns `null` on any failure,
- * and never throws.
- */
-
 import { gitSpawn as defaultGitSpawn } from '../../git-utils.js';
 
 /**
- * Normalise a `git rev-parse HEAD` stdout buffer to the trimmed SHA string,
- * or `null` when the output is empty. Split out of `defaultGetHeadSha` so
- * the success-path is a single straight-line statement.
- *
  * @param {string|undefined|null} stdout
  * @returns {string|null}
  */
@@ -25,9 +11,7 @@ function parseHeadSha(stdout) {
 }
 
 /**
- * Resolve the current `git rev-parse HEAD` SHA inside `cwd`. Returns `null`
- * when git is unavailable or the call fails — callers treat that as
- * "evidence skip disabled" so the gate runs as before.
+ * Never throws; `null` disables the evidence skip so the gate runs.
  *
  * @param {string} cwd
  * @param {typeof defaultGitSpawn} [gitSpawn]

package/.agents/scripts/lib/close-validation/projections/inputs.js

@@ -1,17 +1,5 @@
 // .agents/scripts/lib/close-validation/projections/inputs.js
-/**
- * inputs.js — shared input validator for close-validation projection helpers.
- *
- * Used by `projections/maintainability.js` (and any future projection that
- * shares the same `{ cwd, baseBranch, storyBranch, baselinePath }` argument
- * shape) to collapse the inline guard cascade into a single predicate that
- * returns a typed `reason` on failure.
- *
- * Pure function — no I/O, no side effects. Callers inject `loadBaseline`
- * when they need the predicate to also confirm the baseline file is non-
- * empty; omitting `loadBaseline` skips the baseline check (the predicate
- * still verifies the `baselinePath` argument is present).
- */
+/** Shared argument validator for the close-validation projections. */
 
 /**
  * @typedef {Object} ProjectionInputs
@@ -24,9 +12,7 @@
 /**
  * @typedef {Object} ValidationOk
  * @property {true} ok
- * @property {Record<string, number>} [baseline] - When `loadBaseline` is
- *   supplied, the parsed baseline map is forwarded so callers don't have to
- *   re-read the file.
+ * @property {Record<string, number>} [baseline] - present when `loadBaseline` was supplied.
  */
 
 /**
@@ -36,18 +22,7 @@
  */
 
 /**
- * Validate the standard projection-helper argument set.
- *
- * Reason branches (in order):
- *   - `missing-cwd`           — cwd is falsy
- *   - `missing-base-branch`   — baseBranch is falsy
- *   - `missing-story-branch`  — storyBranch is falsy
- *   - `missing-baseline-path` — baselinePath is falsy
- *   - `no-baseline`           — loadBaseline returned null/undefined/empty
- *
- * The fine-grained `missing-*` variants are normalised to the historical
- * `missing-args` reason by `maintainability.js` so the existing public
- * contract of `projectMaintainabilityRegressions` is preserved byte-for-byte.
+ * Pure. Without `loadBaseline` the baseline file itself is not checked.
  *
  * @param {ProjectionInputs} inputs
  * @param {{ loadBaseline?: (path: string) => Record<string, number>|null|undefined }} [opts]
@@ -72,12 +47,7 @@ export function validateProjectionInputs(inputs, opts = {}) {
   return { ok: true };
 }
 
-/**
- * The set of reason values returned by `validateProjectionInputs` that
- * represent "one of the required arguments was missing". Used by
- * projection helpers to normalise to the historical `missing-args`
- * skipped-reason without enumerating each variant at the call site.
- */
+/** Reasons the projections collapse to `missing-args`. */
 export const MISSING_ARG_REASONS = new Set([
   'missing-cwd',
   'missing-base-branch',