mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/git-utils.js

@@ -1,74 +1,31 @@
 /**
- * git-utils.js — Shared Git Shell Utilities
- *
- * Centralizes all Git subprocess invocations for the orchestration
- * engine, eliminating duplicated wrappers across the codebase.
- *
- * Two flavours are provided. Choose based on whether a non-zero git exit
- * code represents a bug (use `gitSync`) or a recoverable runtime state
- * (use `gitSpawn`):
- *
- *   - `gitSync(cwd, ...args)`  — throws on non-zero exit; returns trimmed
- *     stdout. Use when the operation must succeed for the caller to
- *     proceed (e.g. `rev-parse HEAD`, `merge-base --is-ancestor` inside a
- *     critical-path check). A non-zero exit is treated as a bug or a
- *     corrupted repo state, and the throw propagates to the caller's
- *     existing error path.
- *
- *   - `gitSpawn(cwd, ...args)` — never throws; returns a {@link GitResult}
- *     object. Use when the caller needs to inspect or recover from the
- *     non-zero case (e.g. `merge-base --is-ancestor` as a boolean check,
- *     `branch -D` where "no such branch" is acceptable, fetch/push retry
- *     loops where the caller decides whether to retry on stderr content).
- *
- * The two functions are intentional siblings — they share argument shape so
- * either can be substituted at a call site by changing the import. Do not
- * unify into a single `git({ throwOnNonZero })` until the call-site split
- * shows roughly even use of each contract.
+ * git-utils.js — git runners: `gitSync` throws on failure (a bug);
+ * `gitSpawn` returns a {@link GitResult} for recoverable failures.
  */
 
 import { execFileSync, spawnSync } from 'node:child_process';
 import { execFileCapture, spawnCapture } from './child-exec.js';
 
 /**
- * Result of a `gitSpawn` invocation. Field semantics match `child_process.spawnSync`
- * with two normalisations: `status` is coerced to `1` when null (e.g. when
- * the child terminated by signal), and stdout/stderr are trimmed.
+ * `status` is 1 when null (signal); output is trimmed.
  *
  * @typedef {object} GitResult
- * @property {number} status - Process exit code (0 = success).
- * @property {string} stdout - Trimmed stdout.
- * @property {string} stderr - Trimmed stderr.
+ * @property {number} status
+ * @property {string} stdout
+ * @property {string} stderr
  */
 
 let _execFileSync = execFileSync;
 let _spawnSync = spawnSync;
 
 /**
- * Memoized cleaned env shared by every `gitSync` / `gitSpawn` /
- * `createGitInterface` invocation in this process. Built lazily on first
- * use so cold imports pay nothing. Call sites pass the object through to
- * `child_process` only — none mutate `GIT_*` (or any other key) between
- * git calls, so reuse is safe. Tests that mutate `process.env` and need
- * a fresh snapshot must call {@link __resetCleanGitEnv}.
- *
  * @type {NodeJS.ProcessEnv | null}
  */
 let _cleanGitEnv = null;
 
 /**
- * Build a child-process env that drops every `GIT_*` variable inherited from
- * the parent. When this module's helpers run inside a git hook (e.g. husky
- * pre-push) the parent git invocation exports GIT_DIR / GIT_WORK_TREE /
- * GIT_INDEX_FILE / GIT_PREFIX / GIT_COMMON_DIR / etc. Those env vars
- * override the explicit `cwd` we pass, so a `gitSync(tmpdir, 'init')` ends
- * up operating on the parent worktree's `.git` rather than `tmpdir`. Tests
- * that spin up real git fixtures break reproducibly under that shape.
- *
- * Stripping every `GIT_*` is broader than strictly necessary but cheap and
- * impossible to drift out of sync with future git releases. The result is
- * memoized per process (see `_cleanGitEnv`); author/committer identity is
- * restored via per-call `env:` overrides where required.
+ * Memoised env with every `GIT_*` dropped: inside a git hook, the inherited
+ * GIT_DIR / GIT_WORK_TREE override the `cwd` we pass.
  *
  * @returns {NodeJS.ProcessEnv}
  */
@@ -82,26 +39,15 @@ function cleanGitEnv() {
   return _cleanGitEnv;
 }
 
-/**
- * Drop the memoized cleaned env so the next git call rebuilds from
- * `process.env`. Testing-only seam — not part of the stable API.
- */
 export function __resetCleanGitEnv() {
   _cleanGitEnv = null;
 }
 
 /**
- * Override git runners. Testing-only seam — not part of the stable API.
- *
- * Production code must not call this. The double-underscore prefix is the
- * contract: `__setGitRunners` exists so the test suite can inject mock
- * child-process runners without requiring a broader DI refactor of every
- * `gitSync`/`gitSpawn` call site. If more injection points become needed,
- * replace this seam with a proper `createGitRunner({exec, spawn})` factory
- * and thread it through the module graph.
+ * Test-only; prefer {@link createGitInterface}.
  *
- * @param {typeof execFileSync} exec  - Mock for `execFileSync`.
- * @param {typeof spawnSync}    spawn - Mock for `spawnSync`.
+ * @param {typeof execFileSync} exec
+ * @param {typeof spawnSync}    spawn
  */
 export function __setGitRunners(exec, spawn) {
   _execFileSync = exec;
@@ -109,18 +55,10 @@ export function __setGitRunners(exec, spawn) {
 }
 
 /**
- * The **single** throwing git runner. Both the module-level {@link gitSync} and
- * the interface returned by {@link createGitInterface} route through this —
- * they differ only in which `execFileSync` they hand it.
- *
- * Buffer, shell and encoding policy belong to
- * [`child-exec.js`](child-exec.js); this function contributes only the git
- * specifics (argv prefix, cwd, scrubbed env).
- *
  * @param {typeof execFileSync} exec
  * @param {string} cwd
  * @param {string[]} args
- * @returns {string} Trimmed stdout text.
+ * @returns {string}
  */
 function runGitSync(exec, cwd, args) {
   return String(
@@ -134,10 +72,6 @@ function runGitSync(exec, cwd, args) {
 }
 
 /**
- * The **single** non-throwing git runner — the `spawnSync` counterpart of
- * {@link runGitSync}, normalising `status`/stdout/stderr into a
- * {@link GitResult} via the shared exec surface.
- *
  * @param {typeof spawnSync} spawn
  * @param {string} cwd
  * @param {string[]} args
@@ -152,23 +86,17 @@ function runGitSpawn(spawn, cwd, args) {
 }
 
 /**
- * Run a git command synchronously, returning trimmed stdout.
- * Throws an Error if the command exits with a non-zero code.
- *
- * @param {string}   cwd  - Working directory for the git process.
- * @param {...string} args - Git sub-command and arguments.
- * @returns {string} Trimmed stdout text.
+ * @param {string}   cwd
+ * @param {...string} args
+ * @returns {string} Trimmed stdout.
  */
 export function gitSync(cwd, ...args) {
   return runGitSync(_execFileSync, cwd, args);
 }
 
 /**
- * Run a git command synchronously, returning a result object.
- * Never throws — callers must inspect `status` to detect failure.
- *
- * @param {string}   cwd  - Working directory for the git process.
- * @param {...string} args - Git sub-command and arguments.
+ * @param {string}   cwd
+ * @param {...string} args
  * @returns {GitResult}
  */
 export function gitSpawn(cwd, ...args) {
@@ -176,18 +104,13 @@ export function gitSpawn(cwd, ...args) {
 }
 
 /**
- * Build a git interface closed over injected child-process runners. Preferred
- * seam for callers that want explicit injection without touching the
- * module-global `__setGitRunners` state (which is a test-only override that
- * leaks between suites). The returned object has the same shape as this
- * module's namespace exports (`gitSync`, `gitSpawn`, `gitFetchWithRetry`,
- * `gitPullWithRetry`) so it is drop-in as a `ctx.git` replacement.
+ * Same shape as this module's exports, over injected runners (`ctx.git`).
  *
  * @param {object} [deps]
- * @param {typeof execFileSync} [deps.exec]   - Defaults to real `execFileSync`.
- * @param {typeof spawnSync}    [deps.spawn]  - Defaults to real `spawnSync`.
- * @param {(ms: number) => Promise<void>} [deps.sleep] - Retry backoff sleep.
- * @param {number} [deps.jitter] - Jitter factor for retry backoff.
+ * @param {typeof execFileSync} [deps.exec]
+ * @param {typeof spawnSync}    [deps.spawn]
+ * @param {(ms: number) => Promise<void>} [deps.sleep]
+ * @param {number} [deps.jitter]
  */
 export function createGitInterface(deps = {}) {
   const exec = deps.exec ?? execFileSync;
@@ -214,12 +137,7 @@ export function createGitInterface(deps = {}) {
   };
 }
 
-/**
- * Known lock-contention error signatures that occur when two worktrees
- * fetch concurrently against the same repo. Matching any of these is the
- * only condition under which `gitFetchWithRetry` will re-attempt —
- * unrelated fetch failures surface immediately.
- */
+/** Concurrent-worktree lock contention — the only failures retried. */
 const PACKED_REFS_CONTENTION_PATTERNS = [
   /packed-refs\.lock/i,
   /cannot lock ref/i,
@@ -233,8 +151,6 @@ function isPackedRefsContention(stderr) {
 }
 
 /**
- * Real wall-clock sleep — the default backoff delay for both the module-level
- * retry helpers and {@link createGitInterface}.
  * @param {number} ms
  * @returns {Promise<void>}
  */
@@ -243,47 +159,32 @@ function defaultSleep(ms) {
 }
 
 /**
- * Sleep helper for retry backoff. Overridable via `__setSleep` so tests
- * can skip real wall-clock delays without relying on node:test timer mocks.
  * @type {(ms: number) => Promise<void>}
  */
 let _sleep = defaultSleep;
 let _jitterFactor = 0.5;
 
 /**
- * Test-only seam: replace the sleep implementation used by
- * `gitFetchWithRetry` to avoid real backoff in unit tests.
  * @param {(ms: number) => Promise<void>} fn
- * @param {{ jitter?: number }} [opts] - Override jitter factor (default: 0 for mocks).
+ * @param {{ jitter?: number }} [opts]
  */
 export function __setSleep(fn, opts = {}) {
   _sleep = fn;
   _jitterFactor = opts.jitter ?? 0;
 }
 
-/**
- * Backoff schedule for {@link gitWithContentionRetry}: 250ms, 500ms, 1000ms
- * (3 retries → 4 attempts total).
- */
+/** 3 retries → 4 attempts total. */
 const CONTENTION_BACKOFF_MS = Object.freeze([250, 500, 1000]);
 
 /**
- * The **single** bounded retry loop for git commands that can hit packed-refs
- * lock contention. Only contention signatures trigger a retry — non-contention
- * failures surface immediately, and success short-circuits the loop.
- *
- * Deliberately no global lock — a mutex would erase the parallelism the
- * worktree-isolation model is designed to enable. The schedule and the jitter
- * policy live only here, so a backoff tuning change has a single point of
- * application: the module-level `gitFetchWithRetry` / `gitPullWithRetry` pass
- * the `_sleep` / `_jitterFactor` seams, and {@link createGitInterface} passes
- * its injected equivalents.
+ * Bounded retry on lock contention only. Deliberately no global lock — a
+ * mutex would erase the parallelism worktree isolation exists for.
  *
  * @param {{ spawnGit: (cwd: string, ...args: string[]) => GitResult,
  *   sleep: (ms: number) => Promise<void>, jitterFactor: number }} runners
  * @param {string} cwd
- * @param {string[]} argvPrefix - Leading git argv (e.g. `['fetch']`).
- * @param {string[]} args - Trailing arguments (e.g. `['origin']`).
+ * @param {string[]} argvPrefix
+ * @param {string[]} args
  * @returns {Promise<{ status: number, stdout: string, stderr: string, attempts: number }>}
  */
 async function gitWithContentionRetry(
@@ -310,9 +211,7 @@ async function gitWithContentionRetry(
 }
 
 /**
- * The module-level retry runners — the `__setSleep`-overridable seams bound to
- * the module-global {@link gitSpawn}. Read lazily so `__setSleep` and
- * `__setGitRunners` still take effect after import.
+ * Read lazily so `__setSleep` / `__setGitRunners` take effect after import.
  *
  * @returns {{ spawnGit: typeof gitSpawn, sleep: (ms: number) => Promise<void>,
  *   jitterFactor: number }}
@@ -322,11 +221,8 @@ function moduleRetryRunners() {
 }
 
 /**
- * Run `git fetch …` with the bounded packed-refs-contention retry loop
- * (see `gitWithContentionRetry`).
- *
  * @param {string} cwd
- * @param {...string} args - Arguments after `fetch` (e.g. `'origin'`).
+ * @param {...string} args
  * @returns {Promise<{ status: number, stdout: string, stderr: string, attempts: number }>}
  */
 export function gitFetchWithRetry(cwd, ...args) {
@@ -334,12 +230,8 @@ export function gitFetchWithRetry(cwd, ...args) {
 }
 
 /**
- * Run `git pull --rebase …` with the same bounded retry loop as
- * `gitFetchWithRetry`. Packed-refs contention can occur during pulls
- * just as during fetches — particularly in multi-worktree setups.
- *
  * @param {string} cwd
- * @param {...string} args - Arguments after `pull --rebase` (e.g. `'origin', 'main'`).
+ * @param {...string} args
  * @returns {Promise<{ status: number, stdout: string, stderr: string, attempts: number }>}
  */
 export function gitPullWithRetry(cwd, ...args) {
@@ -352,12 +244,8 @@ export function gitPullWithRetry(cwd, ...args) {
 }
 
 /**
- * Sanitize a string into a URL/branch-safe slug.
- * Lowercases, replaces non-alphanumeric characters with hyphens,
- * collapses multiple hyphens, and trims leading/trailing hyphens.
- *
- * @param {string} text - Raw text to slugify.
- * @returns {string} Sanitized slug.
+ * @param {string} text
+ * @returns {string}
  */
 export function slugify(text) {
   return text
@@ -368,8 +256,6 @@ export function slugify(text) {
 }
 
 /**
- * Resolves the canonical branch name for a Story.
- * v5 Standard: story-[STORY_ID]
  * @param {string|number} storyId
  * @returns {string}
  */
@@ -382,19 +268,11 @@ export function getStoryBranch(storyId) {
   return `story-${id}`;
 }
 
-/**
- * Canonical `story-<id>` branch name matcher. Single source of truth for the
- * Story-branch shape — `parseStoryBranch` and `isStoryBranch` both close over
- * this so call sites never re-author the regex inline.
- */
 const STORY_BRANCH_RE = /^story-(\d+)$/;
 
 /**
- * Parse a canonical Story branch name into its numeric Story ID.
- *
- * @param {string} name - Branch name to inspect (e.g. `story-3334`).
- * @returns {number|null} The Story ID when `name` matches `story-<id>`,
- *   otherwise `null`.
+ * @param {string} name
+ * @returns {number|null}
  */
 export function parseStoryBranch(name) {
   if (typeof name !== 'string') return null;
@@ -403,9 +281,7 @@ export function parseStoryBranch(name) {
 }
 
 /**
- * Predicate: is `name` a canonical `story-<id>` branch name?
- *
- * @param {string} name - Branch name to test.
+ * @param {string} name
  * @returns {boolean}
  */
 export function isStoryBranch(name) {

package/.agents/scripts/lib/github/framework-repo.js

@@ -1,58 +1,18 @@
 /**
- * framework-repo.js — the follow-up **ownership routing** SSOT: which
- * repository a finding, a retro proposal, or a CI-gap intake issue is filed
- * in, and what to say when that question has no answer.
- *
- * ## Three buckets, not two
- *
- * A defect surfaced by one repository's CI is not necessarily that
- * repository's to fix. Ownership splits three ways:
- *
- *   - `consumer`  — the repo the run is standing in (`github.owner`/`repo`).
- *   - `framework` — the Mandrel framework itself
- *     (`github.followUpRepos.framework`, defaulted to the mirror constant).
- *   - `platform`  — a shared platform / infrastructure repo that neither of
- *     the other two owns: a shared base config, a runner fleet, a
- *     cross-repo toolchain (`github.followUpRepos.platform`, **no default**
- *     — nothing can guess a shared repo's slug).
- *
- * ## Why there is no `?? currentRepo` fallback
- *
- * The two-bucket predecessor resolved a framework-tagged item with
- * `frameworkRepo ? frameworkRepo : currentRepo`. When the config key was
- * absent that expression filed framework-owned work into the **consumer's**
- * repo while the rendered retro claimed it went to the framework repo — a
- * silent mis-file, recorded in `retro-proposals-graduator.js`'s own file-top
- * comment. The failure was invisible in this repository precisely because
- * consumer === framework here.
- *
- * So an unresolvable bucket is a first-class outcome, never a fallback:
- * `routeOwnership` returns `routable: false` plus the `missingKey` that
- * would fix it, and every caller must decide **out loud** what to do with
- * that — file locally and say so in the body (the CI-gap filer), or defer
- * and surface it where an operator will see it (the graduators). What no
- * caller may do is route it somewhere plausible and stay quiet.
+ * framework-repo.js — ownership routing SSOT across `consumer`, `framework`
+ * and `platform` buckets. Deliberately no `?? currentRepo` fallback: an
+ * unresolvable bucket is `routable: false` + `missingKey`, and the caller must
+ * say out loud what it did instead of silently mis-filing.
  */
 
-/**
- * Canonical framework repository slug, used when the consumer config does
- * not supply `github.followUpRepos.framework`. The `framework` bucket is the
- * one bucket with a knowable default: it is this framework.
- */
 export const DEFAULT_FRAMEWORK_REPO = 'dsj1984/mandrel';
 
-/** The closed ownership-bucket set. */
 export const OWNERSHIP_BUCKETS = Object.freeze([
   'consumer',
   'framework',
   'platform',
 ]);
 
-/**
- * The `.agentrc.json` key behind each bucket, quoted verbatim when a bucket
- * is unroutable so the operator is told which key to set rather than that
- * "routing failed".
- */
 const OWNERSHIP_CONFIG_KEYS = Object.freeze({
   consumer: 'github.owner / github.repo',
   framework: 'github.followUpRepos.framework',
@@ -60,11 +20,6 @@ const OWNERSHIP_CONFIG_KEYS = Object.freeze({
 });
 
 /**
- * Parse an `"<owner>/<repo>"` slug into `{ owner, repo }`, or `null` when the
- * slug is absent, empty, or malformed. A `null` return is the signal an
- * unroutable bucket is built from — never a reason to substitute another
- * repo.
- *
  * @param {string|null|undefined} slug
  * @returns {{ owner: string, repo: string } | null}
  */
@@ -78,9 +33,6 @@ export function parseRepoSlug(slug) {
 }
 
 /**
- * Render a `{ owner, repo }` pair back to its slug, or `null` when the pair
- * is absent/malformed.
- *
  * @param {{ owner?: string, repo?: string }|null|undefined} repo
  * @returns {string|null}
  */
@@ -95,15 +47,7 @@ export function formatRepoSlug(repo) {
 }
 
 /**
- * Resolve every ownership bucket from a resolved `.agentrc` config.
- *
- * `framework` falls back to {@link DEFAULT_FRAMEWORK_REPO}; `platform` has no
- * default and stays `null` when unconfigured; `consumer` is `null` when
- * `github.owner`/`github.repo` are unset. A `null` bucket is an honest
- * "unknown", which {@link routeOwnership} turns into a named, reportable
- * outcome.
- *
- * @param {object} [config] — resolved `.agentrc` config.
+ * @param {object} [config]
  * @returns {{ consumer: ({owner: string, repo: string}|null), framework: ({owner: string, repo: string}|null), platform: ({owner: string, repo: string}|null) }}
  */
 export function resolveOwnershipRepos(config) {
@@ -121,19 +65,12 @@ export function resolveOwnershipRepos(config) {
 }
 
 /**
- * Route one ownership bucket to the repository its work belongs in.
- *
- * Total: an unknown bucket, an absent repos map, and an unconfigured bucket
- * all resolve to `routable: false` with the `missingKey` that would fix it —
- * never to a substituted repository.
+ * Total: never a substituted repo.
  *
  * @param {object} opts
- * @param {string} opts.bucket — one of {@link OWNERSHIP_BUCKETS}.
+ * @param {string} opts.bucket
  * @param {{consumer?: object|null, framework?: object|null, platform?: object|null}} opts.repos
- *   — resolved buckets, from {@link resolveOwnershipRepos} or assembled by a
- *   caller that already holds the repo objects.
- * @param {{owner: string, repo: string}|null} [opts.currentRepo] — the repo
- *   the run is standing in, used only to report `crossRepo`.
+ * @param {{owner: string, repo: string}|null} [opts.currentRepo] — for `crossRepo`.
  * @returns {{ bucket: string, routedRepo: ({owner: string, repo: string}|null), routable: boolean, missingKey: (string|null), crossRepo: boolean }}
  */
 export function routeOwnership({ bucket, repos, currentRepo = null } = {}) {

package/.agents/scripts/lib/github-url.js

@@ -1,21 +1,6 @@
-// .agents/scripts/lib/github-url.js
 /**
- * Shared GitHub URL utilities. Consolidates the `parsePrNumberFromUrl` helper
- * that was triplicated across `finalizer.js`, `watcher.js`, and
- * `code-review.js`, each with a subtly different regex. Story #3649.
- */
-
-/**
- * Extract the PR number from a GitHub PR URL.
- *
- * Accepts any URL whose path contains `/pull/<digits>` — the fragment
- * (`#diff-…`), query string (`?diff=split`), and trailing slash are all
- * ignored. Returns `null` when the URL is not a string, does not contain
- * a `/pull/` segment, or when the parsed integer is ≤ 0.
- *
- * This is the canonical implementation; the inline copies in `finalizer.js`,
- * `watcher.js`, and `code-review.js` have been deleted in favour of this
- * function.
+ * Ignores fragment, query and trailing slash; `null` for no `/pull/` or a
+ * non-positive number.
  *
  * @param {string|null|undefined} prUrl
  * @returns {number|null}

package/.agents/scripts/lib/import-graph.js

@@ -1,19 +1,7 @@
 /**
- * import-graph.js — the shared static-import graph seam (Story #4902).
- *
- * Extracted verbatim from `check-arch-cycles.js`, which owned the only
- * import-graph builder in the repository and kept it private to its own
- * cycle ratchet. A second consumer now needs the same graph for a very
- * different question — `audit-baselines.js` ranks hotspot files by import
- * in-degree — and re-deriving "which module imports which" a second time
- * would guarantee the two answers drift.
- *
- * Note this is a **module** graph, not the task/DAG graph in `lib/Graph.js`;
- * the two are unrelated despite the shared word.
- *
- * The extraction is behaviour-preserving: `check-arch-cycles.js` imports
- * these helpers and re-exports them, so its public surface (and the ratchet's
- * output) is unchanged.
+ * import-graph.js — the shared static-import (module) graph, used by the
+ * cycle ratchet and the hotspot in-degree ranking so both read one answer.
+ * Unrelated to the task DAG in `lib/Graph.js`.
  *
  * @module lib/import-graph
  */
@@ -22,21 +10,15 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 /**
- * Default scan roots making up the project's distributed surface — the
- * directories published to npm via `package.json` `files[]`. Resolving
- * them into one graph (relativized against the repo root) means a cycle
- * crossing two roots is visible to consumers of the graph.
+ * The npm-published roots, resolved into one graph so cross-root cycles show.
  *
  * @type {string[]}
  */
 export const DEFAULT_ROOTS = [path.join('.agents', 'scripts'), 'bin', 'lib'];
 
 /**
- * Recursively collect `.js` files under `rootDir`, skipping
- * `node_modules`. Returns absolute paths, sorted for determinism.
- *
  * @param {string} rootDir
- * @returns {string[]}
+ * @returns {string[]} absolute paths, sorted
  */
 export function collectJsFiles(rootDir) {
   const out = [];
@@ -64,8 +46,6 @@ export function collectJsFiles(rootDir) {
 const IMPORT_RE = /from\s+['"](\.\.?\/[^'"]+\.js)['"]/g;
 
 /**
- * Pure helper: extract relative static-import specifiers from source text.
- *
  * @param {string} source
  * @returns {string[]}
  */
@@ -78,12 +58,9 @@ export function parseRelativeImports(source) {
 }
 
 /**
- * Build a directed import graph over the given files. Node identity is the
- * file path relative to `rootDir`, posix-separated, so the graph (and any
- * cycles found in it) serializes identically across platforms. Edges that
- * resolve outside the scanned file set are dropped.
+ * Posix ids relative to `rootDir` (platform-stable); external edges dropped.
  *
- * @param {string[]} files absolute paths
+ * @param {string[]} files
  * @param {string} rootDir
  * @param {{ readFile?: (p: string) => string }} [opts]
  * @returns {Map<string, string[]>}
@@ -116,12 +93,10 @@ export function buildGraph(files, rootDir, { readFile } = {}) {
 }
 
 /**
- * Build the whole-repository import graph by scanning the roots that exist
- * under `cwd`. Returns `null` when none of the roots is present — the
- * "no resolvable import graph" degradation every consumer must tolerate
- * rather than treating an absent graph as a graph with no edges.
+ * `null` when no root exists — callers must not treat that as an edgeless
+ * graph.
  *
- * @param {string} cwd repository root the ids are relativized against
+ * @param {string} cwd
  * @param {{ roots?: string[] }} [opts]
  * @returns {Map<string, string[]> | null}
  */
@@ -136,9 +111,7 @@ export function resolveRepoGraph(cwd, { roots = DEFAULT_ROOTS } = {}) {
 }
 
 /**
- * Count inbound edges per node. Nodes with no inbound edge are present in
- * the result with a count of 0, so callers never have to distinguish
- * "unknown module" from "module nothing imports".
+ * Every node is present (0 when nothing imports it).
  *
  * @param {Map<string, string[]> | null} graph
  * @returns {Map<string, number>} empty when `graph` is null

package/.agents/scripts/lib/install-cmd-parser.js

@@ -1,14 +1,8 @@
 /**
- * Tokenize + spawn the operator-supplied install command in argv form
- * (shell:true is only used on Windows because well-known package managers
- * ship as `.cmd` shims and Node 18.20+/20.10+/22+ refuses to spawn them
- * with shell:false under CVE-2024-27980). Tokenization removes the
- * single-string injection vector — args are escaped individually even
- * when shell:true is required for binary resolution.
- *
- * Whitespace tokenization (no quote handling) is deliberate: the input
- * contract is a simple `binary arg arg …` form. Operators that need
- * quoted args can pass a `runInstall` override directly.
+ * Spawn the operator's install command in argv form, removing the
+ * single-string injection vector. Shell only on Windows (`.cmd` shims,
+ * CVE-2024-27980). Whitespace tokenization with no quoting is the contract;
+ * quoted args need a `runInstall` override.
  */
 
 import { spawnSync as defaultSpawnSync } from 'node:child_process';
@@ -32,9 +26,6 @@ function parseInstallCmd(installCmd) {
 }
 
 /**
- * Default runInstall implementation. Tokenizes `installCmd`, then spawns
- * synchronously with the correct shell flag per platform.
- *
  * @param {string} installCmd
  * @param {string} cwd
  * @param {{ spawnSync?: typeof defaultSpawnSync }} [deps] — test seam

package/.agents/scripts/lib/json-utils.js

@@ -1,22 +1,9 @@
 /**
- * json-utils.js — shared JSON-shape helpers.
- *
- * Hoisted out of five callers (`lib/baselines/writer.js`,
- * `lib/config/defaults.js`, `lib/signals/schema.js`) which
- * shipped functionally-equivalent copies of these predicates. See Story
- * #2464.
- *
- * The helpers are scoped to JSON-shaped data — numbers, strings, booleans,
- * null, arrays, and plain objects. They do not handle Dates, Maps, Sets,
- * RegExps, or class instances; callers either JSON-roundtrip their inputs
- * or only ever pass JSON-equivalent values (the on-disk baseline writer
- * and the config defaults module both fall in the second bucket).
+ * json-utils.js — predicates for JSON-shaped data only (no Dates, Maps,
+ * Sets, RegExps or class instances).
  */
 
 /**
- * Return true when `v` is a plain object (not null, not an array). Used
- * by readers and aggregators to defensively pre-flight record shapes.
- *
  * @param {unknown} v
  * @returns {boolean}
  */
@@ -25,9 +12,7 @@ export function isObject(v) {
 }
 
 /**
- * Structural deep-equality for JSON-shaped data. Object key order is
- * ignored. Array order is significant. NaN compares unequal (matches
- * `===` semantics; callers must not pass NaN).
+ * Key order ignored, array order significant; NaN compares unequal.
  *
  * @param {unknown} a
  * @param {unknown} b