mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/ITicketingProvider.js

@@ -1,28 +1,14 @@
 /**
- * ITicketingProvider — Abstract Ticketing Provider Interface
- *
- * All ticketing interactions in the v5 Story-centric orchestration are mediated
- * through this interface. Concrete implementations (e.g., `providers/github.js`)
- * extend this class and override every method.
- *
- * Unoverridden methods throw `Error('Not implemented: <method>')` to enforce
- * the contract at runtime rather than silently returning `undefined`.
- *
- * @see docs/architecture.md — Provider Abstraction Layer
- * @see docs/v5-implementation-plan.md Sprint 1A
+ * Abstract ticketing provider. Implementations (e.g. `providers/github.js`)
+ * override every method; unoverridden ones throw rather than return
+ * `undefined`.
  */
 
 export class ITicketingProvider {
-  // ---------------------------------------------------------------------------
-  // Read Operations
-  // ---------------------------------------------------------------------------
+  // Reads
 
   /**
-   * Fetch the Epic issue with its body — the single planning document
-   * (ideation sections plus the folded Tech Spec / Acceptance Table
-   * managed sections, Story #4324).
-   *
-   * @param {number} epicId - GitHub Issue number of the Epic.
+   * @param {number} epicId
    * @returns {Promise<{
    *   id: number,
    *   title: string,
@@ -34,10 +20,8 @@ export class ITicketingProvider {
     throw new Error('Not implemented: getEpic');
   }
   /**
-   * Fetch all child tickets for an Epic, optionally filtered by labels or state.
-   *
-   * @param {number} epicId - GitHub Issue number of the Epic.
-   * @param {{ label?: string, state?: string }} [filters={}] - Filter criteria.
+   * @param {number} epicId
+   * @param {{ label?: string, state?: string }} [filters={}]
    * @returns {Promise<Array<{
    *   id: number,
    *   title: string,
@@ -50,9 +34,7 @@ export class ITicketingProvider {
   }
 
   /**
-   * Fetch all immediate sub-tickets of a given parent ticket.
-   *
-   * @param {number} parentId - GitHub Issue number of the parent.
+   * @param {number} parentId
    * @returns {Promise<Array<{
    *   id: number,
    *   title: string,
@@ -65,9 +47,7 @@ export class ITicketingProvider {
   }
 
   /**
-   * Retrieve a single ticket with full metadata.
-   *
-   * @param {number} ticketId - GitHub Issue number.
+   * @param {number} ticketId
    * @returns {Promise<{
    *   id: number,
    *   title: string,
@@ -82,41 +62,19 @@ export class ITicketingProvider {
   }
 
   /**
-   * Pre-populate the provider's per-instance ticket cache with a batch of
-   * already-hydrated tickets so subsequent `getTicket(id)` calls can be
-   * served from cache instead of issuing a REST round-trip.
-   *
-   * Default no-op: providers without a cache (e.g. the manual adapter or
-   * test stubs) need not override. Call sites can therefore invoke
-   * `provider.primeTicketCache(tickets)` unconditionally without an
-   * `instanceof` / `typeof === 'function'` capability check.
+   * Seed the ticket cache so later `getTicket` calls skip a round-trip. A
+   * no-op by default, so callers need no capability check.
    *
    * @param {Array<{ id: number }>} _tickets
    * @returns {void}
    */
-  primeTicketCache(_tickets) {
-    // Intentional no-op. Concrete providers that maintain a cache override.
-  }
+  primeTicketCache(_tickets) {}
 
   /**
-   * List every ticket carrying `labels`, in the **mapped** ticket shape.
-   *
-   * This is the declared read for a label scan, and the only one callers
-   * should reach for. Implementations MUST map every issue the way every
-   * other read on this interface does — in particular `id` is the **issue
-   * number**, not the backend's internal database id.
-   *
-   * That single rule is the whole reason the method exists. The raw REST
-   * payload names the issue number `number` and the database id `id`, so a
-   * consumer handed either shape wrote `number ?? id` and appeared to cope —
-   * while silently addressing issues by database id on the mapped shape,
-   * because there `id` is already the number and the fallback never fires.
-   * A declared shape removes the choice rather than documenting it.
-   *
-   * `state` selects `open` (default), `closed` or `all`. Implementations MUST
-   * honour it: a caller asking for `all` is asking a question — "did this
-   * child reopen?" — that an open-only listing answers wrongly rather than
-   * partially.
+   * List tickets carrying `labels` in the mapped shape: `id` MUST be the issue
+   * number, never the backend database id (a raw-vs-mapped `number ?? id`
+   * fallback silently addresses the wrong issue). `state` (default `open`)
+   * MUST be honoured.
    *
    * @param {{ state?: 'open'|'closed'|'all', labels?: string }} [_opts]
    * @returns {Promise<Array<{
@@ -134,19 +92,9 @@ export class ITicketingProvider {
   }
 
   /**
-   * Read a parent's native sub-issue children as issue numbers.
-   *
-   * Takes **both** identifiers because they address different things: the
-   * backend's child edge is keyed by the parent's opaque node id, while
-   * `number` exists only so a degraded read can name the parent it failed on.
-   * Passing the number where the node id belongs is not a type error — it is
-   * a successful call about the wrong issue — which is why the parameter
-   * order is fixed here rather than left to each call site.
-   *
-   * Implementations MUST return `[]` rather than throw when the sub-issue
-   * feature is unavailable on the backend: absence of the feature is not a
-   * failed read, and callers union this with a body checklist that still
-   * answers the question.
+   * Native sub-issue children as issue numbers. The edge is keyed by node id;
+   * passing the number there succeeds about the wrong issue. MUST return `[]`
+   * when the backend lacks the feature (callers union a body checklist).
    *
    * @param {string} _nodeId Opaque node id of the parent.
    * @param {number} _number Parent's issue number, for diagnostics only.
@@ -157,30 +105,19 @@ export class ITicketingProvider {
   }
 
   /**
-   * Resolve a ticket's container parent in **one** call.
+   * Resolve a container parent in one call. Returns `null` (never throws) when
+   * there is no parent or the backend cannot answer, so a degraded lookup
+   * never fails a lifecycle edge.
    *
-   * Exists so a child→parent lookup is a read, not a search. Without it the
-   * only way to find a container was to list every candidate parent and read
-   * each one's children — O(containers) requests to answer what the backend
-   * knows directly.
-   *
-   * Returns `null` when the ticket has no parent, and `null` rather than
-   * throwing when the backend cannot answer. Callers treat a null as "no
-   * parent resolved *here*" and may fall back to a body-declared link; an
-   * exception would turn a degraded lookup into a failed lifecycle edge.
-   *
-   * @param {number} _number Issue number whose parent to resolve.
-   * @returns {Promise<object|null>} Mapped parent ticket, or null.
+   * @param {number} _number
+   * @returns {Promise<object|null>}
    */
   async getParentIssue(_number) {
     throw new Error('Not implemented: getParentIssue');
   }
 
   /**
-   * Return the dependency graph edges for a ticket.
-   * Parses `blocked by #NNN` patterns from the ticket body.
-   *
-   * @param {number} ticketId - GitHub Issue number.
+   * @param {number} ticketId
    * @returns {Promise<{
    *   blocks: number[],
    *   blockedBy: number[]
@@ -191,28 +128,22 @@ export class ITicketingProvider {
   }
 
   /**
-   * Fetch all comments for a specific ticket.
-   *
-   * @param {number} ticketId - GitHub Issue number.
-   * @returns {Promise<object[]>} Array of comment objects.
+   * @param {number} ticketId
+   * @returns {Promise<object[]>}
    */
   async getTicketComments(_ticketId) {
     throw new Error('Not implemented: getTicketComments');
   }
 
-  // ---------------------------------------------------------------------------
-  // Write Operations
-  // ---------------------------------------------------------------------------
+  // Writes
 
   /**
-   * Mutate labels, body (tasklist checkboxes), and assignees on a ticket.
-   *
-   * @param {number} ticketId - GitHub Issue number.
+   * @param {number} ticketId
    * @param {{
    *   labels?: { add?: string[], remove?: string[] },
    *   body?: string,
    *   assignees?: string[]
-   * }} mutations - The mutations to apply.
+   * }} mutations
    * @returns {Promise<void>}
    */
   async updateTicket(_ticketId, _mutations) {
@@ -220,13 +151,11 @@ export class ITicketingProvider {
   }
 
   /**
-   * Append a structured comment to a ticket.
-   *
-   * @param {number} ticketId - GitHub Issue number.
+   * @param {number} ticketId
    * @param {{
    *   body: string,
    *   type: 'progress'|'friction'|'notification'
-   * }} payload - The comment content and classification.
+   * }} payload
    * @returns {Promise<{ commentId: number }>}
    */
   async postComment(_ticketId, _payload) {
@@ -234,8 +163,7 @@ export class ITicketingProvider {
   }
 
   /**
-   * Delete an issue comment by its numeric id.
-   * Implementations SHOULD treat "not found" as a no-op.
+   * SHOULD treat "not found" as a no-op.
    *
    * @param {number} _commentId
    * @returns {Promise<void>}
@@ -244,13 +172,9 @@ export class ITicketingProvider {
     throw new Error('Not implemented: deleteComment');
   }
 
-  // ---------------------------------------------------------------------------
-  // Setup Operations (used by bootstrap)
-  // ---------------------------------------------------------------------------
+  // Setup (bootstrap)
 
   /**
-   * Idempotent label creation. Skips labels that already exist.
-   *
    * @param {Array<{ name: string, color: string, description: string }>} labelDefs
    * @returns {Promise<{ created: string[], skipped: string[] }>}
    */
@@ -259,11 +183,8 @@ export class ITicketingProvider {
   }
 
   /**
-   * List the repository's whole label vocabulary.
-   *
-   * Implementations MUST paginate rather than take a fixed page cap: a cap is
-   * silent truncation, and a caller deciding what to delete from a truncated
-   * view is the exact failure Story #5189 exists to stop reproducing.
+   * MUST paginate: a page cap silently truncates, and callers decide
+   * deletions from this list.
    *
    * @returns {Promise<Array<{ name: string, color: string|null, description: string|null }>>}
    */
@@ -272,11 +193,8 @@ export class ITicketingProvider {
   }
 
   /**
-   * Delete one label by name.
-   *
-   * A label that is already gone MUST resolve as a successful no-op
-   * (`{ deleted: false, reason: 'not-found' }`) rather than throwing, so a
-   * re-run of any sweep built on this port is idempotent.
+   * An absent label MUST resolve `{ deleted: false, reason: 'not-found' }`,
+   * never throw, so sweeps are idempotent.
    *
    * @param {string} _name
    * @returns {Promise<{ deleted: boolean, reason: string|null }>}
@@ -286,8 +204,7 @@ export class ITicketingProvider {
   }
 
   /**
-   * Idempotent custom field creation on the Project board.
-   * Only applicable when `projectNumber` is configured.
+   * Idempotent; only applicable when `projectNumber` is configured.
    *
    * @param {Array<{
    *   name: string,
@@ -301,21 +218,17 @@ export class ITicketingProvider {
   }
 
   /**
-   * Execute a GraphQL query/mutation against the ticketing backend.
-   * @param {string} _query - GraphQL query/mutation string.
+   * @param {string} _query
    * @param {object} [_variables={}]
    * @param {object} [_opts={}]
-   * @returns {Promise<object>} The `data` portion of the response.
+   * @returns {Promise<object>} The response's `data`.
    */
   async graphql(_query, _variables = {}, _opts = {}) {
     throw new Error('Not implemented: graphql');
   }
 
   /**
-   * Inspect the branch-protection state of a branch. Returns
-   * `{ enabled: false }` when no protection rule exists (HTTP 404), and
-   * `{ enabled: true, raw }` when one does. Implementations may return a
-   * richer shape; the only contract consumers rely on is the boolean.
+   * `{ enabled: false }` on 404; consumers rely only on the boolean.
    *
    * @param {string} _branch
    * @returns {Promise<{ enabled: boolean, raw?: object }>}
@@ -325,15 +238,9 @@ export class ITicketingProvider {
   }
 
   /**
-   * Create or additively-merge a branch-protection rule on `_branch`. The
-   * `contexts` array names required status-check contexts; existing
-   * contexts are preserved (additive merge). When no rule exists one is
-   * created with sensible defaults and just the supplied contexts.
-   *
-   * Returns a summary `{ created, added, existing }` describing the diff
-   * the bootstrap orchestrator surfaces to the operator. Implementations
-   * MAY ignore other branch-protection knobs (PR review counts, signed
-   * commits, etc.) so operator-tuned settings survive re-runs.
+   * Additively merge required status-check `contexts` (creating the rule if
+   * absent). Other protection knobs are left alone so operator tuning
+   * survives re-runs.
    *
    * @param {string} _branch
    * @param {{ contexts: string[], strict?: boolean }} _opts
@@ -344,9 +251,7 @@ export class ITicketingProvider {
   }
 
   /**
-   * Read the repo's merge-method allowlist + auto-merge / delete-branch
-   * flags. Returns a sparse object containing only the fields the upstream
-   * API exposes (consumers should treat missing keys as "unknown").
+   * Sparse: a missing key means "unknown".
    *
    * @returns {Promise<Partial<{
    *   allow_squash_merge: boolean,
@@ -361,8 +266,7 @@ export class ITicketingProvider {
   }
 
   /**
-   * PATCH the repo with the supplied merge-method settings. Body is sparse —
-   * only the supplied fields are sent / touched.
+   * Sparse PATCH: only supplied fields are touched.
    *
    * @param {Partial<{
    *   allow_squash_merge: boolean,

package/.agents/scripts/lib/Logger.js

@@ -1,52 +1,24 @@
 /**
- * Logger conventions (see `docs/patterns.md` → "Error Handling Convention"):
- *
- *   - `debug`:  verbose trace; only emitted when the logger level is `verbose`.
- *   - `info`:   normal progress.
- *   - `warn`:   recoverable issue the operator should notice.
- *   - `error`:  non-fatal failure; caller continues. Use when `throw` would
- *               be too loud (e.g. best-effort cleanup paths).
- *   - `fatal`:  unrecoverable; exits the process. Use only at CLI
- *               boundaries, never inside library code.
- *
- * Level is resolved **lazily on every emit** from `AGENT_LOG_LEVEL` (or a
- * `setLevel` override). Resolving per emit — rather than once at module
- * load — lets tests exercise every level branch in-process via `setLevel`
- * or a live `AGENT_LOG_LEVEL` flip, without spawning a child process per
- * level (Story #3329):
- *
- *   - `silent`   → only `fatal` emits.
- *   - `info`     → default. Emits `info` and above; suppresses `debug`.
- *   - `verbose`  → emits everything (including `debug`).
+ * `error` is non-fatal (the caller continues); `fatal` exits and belongs only
+ * at CLI boundaries. The level (`silent` = fatal only, `info` default,
+ * `verbose` adds debug) is resolved from `AGENT_LOG_LEVEL` on every emit, not
+ * at load, so tests can flip it in-process.
  */
 /**
- * Recognized log levels, lowest-noise first. Anything outside this set
- * resolves to `info`.
+ * Anything else resolves to `info`.
  *
  * @type {ReadonlySet<string>}
  */
 const VALID_LEVELS = Object.freeze(new Set(['silent', 'info', 'verbose']));
 
 /**
- * Process-wide level override. `null` means "no explicit override — read
- * `AGENT_LOG_LEVEL` from the environment on each resolve". `setLevel`
- * pins this so tests (and embedders) can exercise every level branch
- * in-process without spawning a child whose module-load reads a different
- * env var. `setLevel(null)` clears the pin and restores env-driven
- * resolution.
+ * `null` means read `AGENT_LOG_LEVEL` on each resolve.
  *
  * @type {string|null}
  */
 let levelOverride = null;
 
 /**
- * Resolve the active log level lazily. Honors an explicit `setLevel`
- * override first, otherwise reads `AGENT_LOG_LEVEL` from the environment
- * on every call. Resolving per emit (rather than once at module load)
- * means a test can flip `AGENT_LOG_LEVEL` — or call `setLevel` — and see
- * the level branches react in-process, without a child process per level
- * (Story #3329).
- *
  * @returns {'silent'|'info'|'verbose'}
  */
 export function resolveLevel() {
@@ -59,11 +31,8 @@ export function resolveLevel() {
 }
 
 /**
- * Pin the process-wide log level, bypassing `AGENT_LOG_LEVEL`. Pass a
- * recognized level (`silent` / `info` / `verbose`) to force it,
- * or `null` to clear the pin and restore env-driven resolution. An
- * unrecognized non-null value throws so callers cannot silently pin a
- * level that resolves to `info`.
+ * Pin the level (`null` clears it). An unrecognized value throws rather than
+ * silently pinning `info`.
  *
  * @param {('silent'|'info'|'verbose')|null} level
  * @returns {void}
@@ -89,24 +58,12 @@ function infoEnabled() {
   return resolveLevel() === 'info' || debugEnabled();
 }
 
-// Mutable sinks for `info` (defaults to stdout via console.log) and the
-// stdout branch of `createProgress` (defaults to console.log). `warn` already
-// uses console.warn which Node routes to stderr, but we expose a sink for it
-// too so a single `routeAllOutputToStderr()` call gives a uniform guarantee
-// to callers that "no Logger output lands on stdout" (Story #2278).
+// Swappable so `routeAllOutputToStderr()` can guarantee nothing hits stdout.
 let infoSink = (msg) => console.log(msg);
 let warnSink = (msg) => console.warn(msg);
 let progressStdoutSink = (msg) => console.log(msg);
 
-/**
- * Flip every Logger output that can land on stdout (`info`, `warn`, and the
- * stdout branch of `createProgress`) to stderr for the lifetime of the
- * process. Idempotent. Use when stdout is reserved for a structured payload
- * — for example the JSON envelope emitted by
- * `plan-context.js`, where any interleaved
- * `[Orchestrator] ℹ️ …` log line corrupts the captured file
- * (Story #2278).
- */
+/** For processes whose stdout is a structured payload. Idempotent. */
 export function routeAllOutputToStderr() {
   infoSink = (msg) => console.error(msg);
   warnSink = (msg) => console.error(msg);
@@ -114,11 +71,7 @@ export function routeAllOutputToStderr() {
 }
 
 export const Logger = {
-  /**
-   * The currently-resolved level. A getter (not a frozen snapshot) so it
-   * reflects `setLevel` overrides and live `AGENT_LOG_LEVEL` changes —
-   * reading `Logger.level` always returns what the next emit will use.
-   */
+  /** A getter, so it always reports what the next emit will use. */
   get level() {
     return resolveLevel();
   },
@@ -155,16 +108,8 @@ export const Logger = {
 };
 
 /**
- * Frozen no-op logger shaped like the public `Logger` surface (minus `fatal`,
- * which must never be silenced — silencing process-exit is a footgun). Use
- * this as the default-argument value when a function accepts an optional
- * logger; consumers that don't pass one get a uniform shape without each
- * call site re-declaring its own inline literal.
- *
- * Deliberately omits `fatal` so that any code path tempted to call
- * `logger.fatal(...)` against the no-op fails loudly rather than silently
- * skipping a process-exit that would otherwise have surfaced an
- * unrecoverable error.
+ * Default for an optional logger. Omits `fatal` deliberately: a silenced
+ * process-exit would hide an unrecoverable error, so calling it throws.
  */
 export const NOOP_LOGGER = Object.freeze({
   silent: true,
@@ -174,14 +119,7 @@ export const NOOP_LOGGER = Object.freeze({
   error() {},
 });
 
-/**
- * Frozen logger that routes every level to **stderr**. Use this when a
- * caller's stdout is a structured payload (e.g. the authoring-context JSON
- * envelope from `plan-context.js`) and any
- * progress/telemetry log must not interleave with the payload. Mirrors the
- * `{ info, warn, error, debug }` shape that the orchestration helpers
- * accept via optional `logger` arguments.
- */
+/** Every level to stderr, for callers whose stdout is a structured payload. */
 export const STDERR_LOGGER = Object.freeze({
   debug: (message) => console.error(message),
   info: (message) => console.error(message),

package/.agents/scripts/lib/audit-baselines/engine.js

@@ -1,16 +1,7 @@
 /**
- * engine.js — assemble the `/audit-baselines` evidence envelope
- * (Story #4902).
- *
- * Strictly read-only and strictly offline: it reads committed baselines, the
- * resolved config, git history, the static import graph, and any friction
- * ledger it finds. It never writes under `baselines/`, never refreshes a
- * baseline, and never runs a test, coverage, or mutation suite — the whole
- * point is that a baseline review costs a file read, not a CI run.
- *
- * Findings are evidence, not a verdict: assembling the envelope is success,
- * however alarming its contents, so the CLI exits 0 whenever it got this far.
- * Judgment belongs to the lens that reads the envelope.
+ * Assembles the `/audit-baselines` evidence envelope. Read-only and offline:
+ * never writes baselines or runs a suite — a review costs a file read, not a
+ * CI run. Evidence, not a verdict: assembling it is success (exit 0).
  *
  * @module lib/audit-baselines/engine
  */
@@ -31,19 +22,16 @@ import {
   readFriction,
 } from './weights.js';
 
-/** Envelope `kind` discriminator; matches the shipped schema's const. */
+/** Matches the shipped schema's const. */
 const ENVELOPE_KIND = 'audit-baselines-envelope';
 
-/** Envelope schema version — bumped on any breaking shape change. */
+/** Bump on any breaking shape change. */
 const ENVELOPE_SCHEMA_VERSION = '1';
 
-/** Cap on emitted hotspot clusters, independent of the per-gate `topN`. */
 export const DEFAULT_HOTSPOT_LIMIT = 50;
 
 /**
- * Resolve the repository config without letting a broken `.agentrc.json`
- * abort the run — an unreadable config still leaves the baseline files
- * themselves readable at their default paths.
+ * A broken `.agentrc.json` must not abort: default baseline paths still read.
  *
  * @param {string} cwd
  * @returns {{ quality: object, configError: string | null }}
@@ -57,11 +45,8 @@ function resolveQualityBlock(cwd) {
 }
 
 /**
- * Absolute temp root the friction ledger is searched under, anchored to the
- * **analysed** repository rather than the process cwd. `resolvedTempRoot()`
- * anchors to whichever checkout the current process sits in, which is the
- * right answer for a writer and the wrong one here: an engine pointed at
- * another repo with `--cwd` must read that repo's ledger, not this one's.
+ * Anchored to the analysed repo (`--cwd`), not the process's checkout as
+ * `resolvedTempRoot()` would be.
  *
  * @param {string} cwd
  * @returns {string}
@@ -71,17 +56,13 @@ function tempRootFor(cwd) {
   try {
     relative = tempRootFrom(resolveConfig({ cwd }));
   } catch {
-    // Unreadable config — the framework default root is still worth probing.
+    // Unreadable config: probe the default root.
   }
   if (path.isAbsolute(relative)) return relative;
   return path.join(mainCheckoutRoot(cwd) ?? cwd, relative);
 }
 
 /**
- * Run the engine and return the envelope object. Pure with respect to the
- * filesystem apart from the reads named in the module docstring — writing
- * the result is the caller's job.
- *
  * @param {{
  *   cwd: string,
  *   topN?: number,
@@ -138,11 +119,10 @@ export function runEngine({
 }
 
 /**
- * Condense an envelope into the pure-JSON stdout summary. Small enough to
- * read in a terminal, and never carrying a row set.
+ * Terminal-sized stdout summary; never carries a row set.
  *
  * @param {object} envelope
- * @param {string} outPath absolute path the full envelope was written to
+ * @param {string} outPath
  * @returns {object}
  */
 export function summarize(envelope, outPath) {

package/.agents/scripts/lib/audit-baselines/gate-surface.js

@@ -1,11 +1,5 @@
 /**
- * gate-surface.js — walk both halves of the baseline surface (Story #4902).
- *
- * The closed `delivery.quality.gates` kinds and the out-of-band ratchet
- * baselines are one surface, and an engine that walks only the first silently
- * drops the second. This module owns that walk and the file universe an
- * `ignoreGlobs` entry is checked against; [`surface-entry.js`](surface-entry.js)
- * turns each kind into its health report.
+ * Walks both halves of the baseline surface (gates and ratchets).
  *
  * @module lib/audit-baselines/gate-surface
  */
@@ -16,9 +10,7 @@ import { listFilesUnder, readJsonFile } from './read.js';
 import { surfaceEntryFor } from './surface-entry.js';
 
 /**
- * Every `targetDirs` entry declared by any gate, deduplicated. This is the
- * file universe an `ignoreGlobs` entry is checked against — a glob that
- * matches nothing inside the dirs its own gate scans is dead weight.
+ * The file universe `ignoreGlobs` are checked against.
  *
  * @param {object | null | undefined} quality
  * @returns {string[]}
@@ -34,15 +26,9 @@ function declaredTargetDirs(quality) {
 }
 
 /**
- * Walk both halves of the gate surface — the closed `delivery.quality.gates`
- * kinds and the out-of-band ratchet baselines — and report each instrument's
- * health.
- *
  * @param {{ cwd: string, quality: object, now?: Date, run?: Function }} args
- *   `run` overrides the git spawn; `staleness.js` owns the real default.
  * @returns {{ entries: object[], baselines: Map<string, object|null> }}
- *   `baselines` carries each parsed envelope forward so the hotspot, trend,
- *   and headroom sections never re-read a 650KB file off disk.
+ *   `baselines` is carried forward so later sections never re-read from disk.
  */
 export function buildGateSurface({ cwd, quality, now = new Date(), run }) {
   const files = declaredTargetDirs(quality).flatMap((dir) =>