mandrel 2.60.0 → 2.61.0

package/.agents/scripts/lib/bootstrap/workflow-audit.js

@@ -1,66 +1,21 @@
 /**
- * bootstrap/workflow-audit — audit the GitHub Projects v2 built-in
- * workflows for the project board, classifying each enabled workflow
- * against an allowlist (Story #2845).
+ * Audit the board's Projects v2 built-in workflows. `ColumnSync` owns the
+ * Status column; built-ins that also write it land after the orchestrator
+ * and leave closed Stories stuck `In Progress`.
  *
- * Motivation:
- *   The orchestrator's `ColumnSync` writes the Status column at every
- *   `transitionTicketState` call and documents "I own Status" at
- *   [`column-sync.js:21-27`]. GitHub Projects v2 ships several built-in
- *   workflows that *also* write the Status column as side-effects of
- *   issue / PR events. When both are enabled, the bot frequently gets
- *   the last write on `agent::done` transitions (PR merged ~2 minutes
- *   after the orchestrator's flip), leaving closed Stories stuck at
- *   `In Progress` on the board even though the issue is closed and
- *   labeled `agent::done`. Reproduced on Story #2813.
- *
- * Surface:
- *   - {@link CONFLICTING_WORKFLOWS} / {@link COMPATIBLE_WORKFLOWS} —
- *     frozen allowlists keyed by GitHub's built-in workflow `name`
- *     field.
- *   - {@link auditProjectWorkflows} — pure-ish (one GraphQL read) that
- *     classifies the project's currently-enabled workflows and returns
- *     a structured envelope.
- *   - {@link reapConflictingWorkflows} — opt-in destructive helper
- *     that issues `deleteProjectV2Workflow` for every entry in the
- *     audit's `conflicting` set. Fails fast on the first mutation
- *     error (no partial-reap state).
- *
- * GraphQL surface note:
- *   `ProjectV2Workflow` exposes `enabled` as `NON_NULL` but **read-only**
- *   — GraphQL ships no `updateProjectV2Workflow` mutation at the time
- *   of this Story. The only programmatic action is
- *   `deleteProjectV2Workflow`, which is irreversible from the API
- *   (the operator must re-create deleted built-ins from the GitHub UI).
- *   If GitHub later adds a toggle mutation, swap delete for toggle in
- *   {@link reapConflictingWorkflows}.
+ * GraphQL exposes `enabled` read-only, so the only remedy is the irreversible
+ * `deleteProjectV2Workflow`; swap to a toggle if GitHub ever adds one.
  */
 
 import { resolveProjectMeta } from '../orchestration/project-meta-resolver.js';
 
-/**
- * Workflows that **must not** be enabled when the orchestrator owns
- * the Status column. Each entry writes Status as a side-effect of an
- * event the orchestrator already handles (close, PR merge, PR link),
- * and the bot's write typically arrives *after* the orchestrator's
- * — clobbering the intended terminal state.
- *
- * Names match GitHub's built-in `ProjectV2Workflow.name` literals.
- */
+/** Built-ins whose Status writes clobber the orchestrator's; `ProjectV2Workflow.name` literals. */
 export const CONFLICTING_WORKFLOWS = Object.freeze([
   'Pull request merged',
   'Pull request linked to issue',
 ]);
 
-/**
- * Workflows that are safe to leave on. Either they don't touch the
- * Status column, or they touch it in a way the orchestrator's writes
- * agree with (`Item closed` sets Status to `Done`, which matches
- * `agent::done`).
- *
- * Surfaced informationally in the audit envelope so operators can see
- * what was inspected without re-querying.
- */
+/** Built-ins that leave Status alone or agree with the orchestrator. */
 export const COMPATIBLE_WORKFLOWS = Object.freeze([
   'Item closed',
   'Item added to project',
@@ -91,10 +46,6 @@ const DELETE_WORKFLOW_MUTATION = `
   }`;
 
 /**
- * Classify a single workflow row against the allowlists.
- *
- * Pure helper — exported for test pinning.
- *
  * @param {{ name: string, enabled: boolean }} workflow
  * @returns {'conflicting'|'compatible'|'unknown'|'disabled-conflicting'|'disabled-other'}
  */
@@ -111,10 +62,6 @@ export function classifyWorkflow(workflow) {
 }
 
 /**
- * Query the project's built-in workflows and classify each one. Returns
- * a structured envelope the bootstrap step can render and the reap
- * helper can act on.
- *
  * @param {{
  *   provider: { graphql: Function },
  *   projectId: string,
@@ -163,15 +110,8 @@ export async function auditProjectWorkflows(args) {
 }
 
 /**
- * Delete every workflow in the audit's `conflicting` set. Fails fast on
- * the first mutation error — leaves the remaining workflows untouched
- * rather than producing a partially-reaped board, because the operator
- * cannot easily tell which workflows were deleted versus which were
- * preserved when looking at the post-failure board state.
- *
- * Returns the per-workflow outcome so callers can log a deterministic
- * summary even on partial success (the failure path will throw, but the
- * happy path returns the full ordered list for printing).
+ * Delete every conflicting workflow; fails fast, naming what was already
+ * deleted, since the board alone cannot tell the operator.
  *
  * @param {{
  *   provider: { graphql: Function },
@@ -209,18 +149,8 @@ export async function reapConflictingWorkflows(args) {
 }
 
 /**
- * Resolve a Project v2 node id from a project number. Used by the
- * bootstrap CLI to convert the resolver's `projectNumber` into the node
- * id required by {@link auditProjectWorkflows}.
- *
- * Walks the shared owner-type ladder — `organization(login:$owner)` →
- * `user(login:$owner)` → `viewer` — via {@link resolveProjectMeta}, so an
- * **org-owned** board resolves here the same way it does for `ColumnSync`
- * (Story #4237). The owner login is read from `provider.projectOwner`
- * (explicit board owner) and falls back to `provider.owner` (the repo
- * owner) so org boards resolve even when no separate `projectOwner` is
- * configured. Returns `null` when no owner scope can see the project
- * (e.g. missing scope) so the caller can degrade gracefully.
+ * Walks the shared org → user → viewer ladder so org-owned boards resolve as
+ * they do for `ColumnSync`. `null` when no owner scope sees the project.
  *
  * @param {{
  *   provider: { graphql: Function, owner?: string|null, projectOwner?: string|null },
@@ -254,9 +184,6 @@ export async function resolveProjectIdByNumber(args) {
 }
 
 /**
- * Render a human-readable summary line for the audit. Pure — exported
- * so the bootstrap CLI and tests share the same formatting.
- *
  * @param {Awaited<ReturnType<typeof auditProjectWorkflows>>} audit
  * @returns {string}
  */

package/.agents/scripts/lib/branch-name-guard.js

@@ -1,27 +1,8 @@
 /**
- * branch-name-guard.js — Canonical branch-name safety assertion.
- *
- * Single source of truth for "is this string safe to forward to a `git`
- * subprocess as a branch name?". Consolidates the duplicated assertion
- * logic that previously lived in `git-branch-lifecycle.js` and
- * `git-branch-cleanup.js`, so the two sites cannot drift apart.
- *
- * The default check is the **union** of every assertion either previous
- * site performed:
- *   - reject `null` / `undefined` / non-string values
- *   - reject empty string
- *   - reject any character outside `[a-zA-Z0-9._\-/]` (catches whitespace,
- *     shell metacharacters, glob characters, etc.)
- *   - reject leading `-` (would otherwise be parsed as a CLI flag by git,
- *     even though the regex character class allows hyphens elsewhere)
- *
- * Callers performing destructive operations (`branch -D`, `push --delete`)
- * can opt into the protected-branch deny list by passing `{ protected: true }`,
- * which additionally rejects `main`, `master`, `HEAD`, and any name
- * starting with `refs/`.
- *
- * All exports are pure: they read no config, spawn no subprocesses, and
- * make no network calls.
+ * The one check that a string is safe to pass to `git` as a branch name:
+ * a non-empty string of `[a-zA-Z0-9._\-/]` with no leading `-` (git would
+ * read it as a flag). Destructive callers pass `{ protected: true }` to also
+ * reject `main`, `master`, `HEAD` and `refs/*`. Pure.
  */
 
 import { isSafeBranchComponent } from './dependency-parser.js';

package/.agents/scripts/lib/changed-files.js

@@ -1,27 +1,10 @@
 import { createGitInterface } from './git-utils.js';
 
 /**
- * Resolve the ONE git ref a step of the pre-push chain computes its
- * changed-file set against — the whole rule, stated once (Story #5365).
- *
- * **A ref the caller named wins; `crap.incrementalCoverage.baseRef` is the
- * default for a caller that named none, and `main` the default for neither.**
- * `.husky/pre-push` captures coverage at `--ref origin/main` and then previews
- * CRAP at `--changed-since origin/main`, and the preview only reads its own
- * tree when the artifact under it was captured over the same change set.
- * Letting the configured value outrank the named ref meant a consumer that set
- * `baseRef` captured one scope while the preview scored another — precisely
- * the stale-artifact read the capture-before-preview ordering (Story #5356)
- * closed. This repository sets no `baseRef`, so that divergence was invisible
- * locally and only a consumer who configured one would have paid for it.
- *
- * Callers that name no ref — the close-validation gate, whose argv carries no
- * `--ref` — still get the configured value, so the key keeps the meaning it
- * was added with.
- *
- * Every step that derives that change set calls this: both `coverage-capture`
- * paths and the preview's CRAP baseline join. A new consumer routes through it
- * rather than reading `baseRef` itself.
+ * The single rule for the ref a pre-push step diffs against: a named ref
+ * wins, then `crap.incrementalCoverage.baseRef`, then `main`. The named ref
+ * must win so coverage capture and the CRAP preview score the same change
+ * set. Every consumer routes through here rather than reading `baseRef`.
  *
  * @param {{ crap: object, ref: string | null | undefined }} opts
  * @returns {string}
@@ -31,19 +14,7 @@ export function resolveChangedFilesRef({ crap, ref }) {
 }
 
 /**
- * Parse the stdout from `git diff --name-only` into a normalized file list.
- * Trims whitespace, drops blank lines, and converts backslash separators to
- * forward slashes so set-membership checks line up with the paths produced by
- * `scanAndScore` and `calculateAll` on Windows checkouts.
- *
- * Pure; no I/O.
- *
- * Module-private since Story #4944. It was exported for
- * `diff-scope-cli.js#resolveDiffScopeFiles`, which the duplication-CLI
- * migration deleted; the three remaining callers all live in this file, so
- * exporting it now would ship a seam only the tests reach. Its behaviour is
- * covered through `diffNameOnly`, which returns this function's output
- * verbatim.
+ * Forward-slash separators so set membership matches scorer paths on Windows.
  *
  * @param {string | null | undefined} stdout
  * @returns {string[]}
@@ -58,30 +29,16 @@ function parseNameOnlyStdout(stdout) {
 }
 
 /**
- * Low-level helper: run `git diff --name-only <range>` and return the
- * forward-slash-normalised file list. Throws on non-zero git exit so callers
- * that must fail-closed can propagate the error; callers that prefer
- * best-effort behaviour wrap this in a try/catch.
- *
- * Accepts either a pre-built `range` string **or** `baseRef`+`headRef`
- * (assembled into `<baseRef>...<headRef>` when `threeDot` is true, or
- * `<baseRef>..<headRef>` otherwise). When both `range` and
- * `baseRef`/`headRef` are supplied, `range` takes precedence.
- *
- * The `gitSpawn` injection matches the signature used by `createGitInterface`:
- * `(cwd: string, ...gitArgs: string[]) => { status: number, stdout: string, stderr: string }`.
- * Production callers omit it (the default uses `createGitInterface({})`);
- * tests pass a stub.
+ * `git diff --name-only`; `range` wins over `baseRef`/`headRef`.
  *
  * @param {object} params
- * @param {string} [params.range]         Pre-built range string (e.g. `"epic/3599...story-3636"`).
- * @param {string} [params.baseRef]       Left-hand ref — used when `range` is absent.
- * @param {string} [params.headRef='HEAD'] Right-hand ref — used when `range` is absent.
- * @param {boolean} [params.threeDot=true] Use three-dot (`...`) merge-base semantics
- *   when `range` is absent. Set to `false` for a two-dot direct diff.
+ * @param {string} [params.range]
+ * @param {string} [params.baseRef]
+ * @param {string} [params.headRef='HEAD']
+ * @param {boolean} [params.threeDot=true] Merge-base (`...`) semantics.
  * @param {string} [params.cwd=process.cwd()]
  * @param {((cwd: string, ...args: string[]) => { status: number, stdout: string, stderr: string }) | null} [params.gitSpawn]
- * @returns {string[]} Forward-slash-normalised repo-relative paths.
+ * @returns {string[]}
  * @throws {Error} When git exits non-zero.
  */
 export function diffNameOnly({
@@ -106,35 +63,16 @@ export function diffNameOnly({
 }
 
 /**
- * Resolve the list of files changed since `ref` relative to the current HEAD.
- *
- * Used by `check-crap.js` and `check-maintainability.js` to implement the
- * `--changed-since <ref>` diff-scoped mode — the quality gates limit both
- * scoring and comparison to this file set so the pre-push / PR CI feedback
- * loop stays fast on large consumer repos.
- *
- * Semantics:
- *   - Runs `git diff --name-only <ref>...HEAD` so the comparison is against
- *     the merge-base (three-dot range). This matches how GitHub computes the
- *     "files changed" view for a PR and deliberately excludes anything that
- *     was merged into the base branch after the PR branched off.
- *   - Returns relative paths with forward-slash separators so set-membership
- *     checks line up with the normalized paths produced by `scanAndScore` and
- *     `calculateAll` on Windows checkouts.
- *   - A non-zero git exit is surfaced as a thrown Error — `--changed-since`
- *     must **never** silently degrade to "no regressions found"; that is the
- *     entire reason the CLIs fail closed on a bad ref.
+ * Files changed on `ref...HEAD` (merge-base, like a PR's "files changed").
+ * Throws on a bad ref: `--changed-since` must never degrade to "no
+ * regressions found".
  *
  * @param {object} [params]
- * @param {string} [params.ref='main']         The ref to diff against.
- * @param {string} [params.cwd=process.cwd()]  Repo working directory.
- * @param {ReturnType<typeof createGitInterface>} [params.git] Injected git
- *   interface — production callers omit this; tests pass a mock.
- * @returns {string[]} Relative, forward-slash-normalized file paths. Order is
- *   whatever `git diff --name-only` produces (stable per invocation).
- * @throws {Error} When git exits non-zero (unresolvable ref, corrupt repo,
- *   etc.). The error message names the ref so the operator can react without
- *   re-reading the CLI flags.
+ * @param {string} [params.ref='main']
+ * @param {string} [params.cwd=process.cwd()]
+ * @param {ReturnType<typeof createGitInterface>} [params.git]
+ * @returns {string[]}
+ * @throws {Error} When git exits non-zero.
  */
 export function getChangedFiles({
   ref = 'main',
@@ -152,43 +90,17 @@ export function getChangedFiles({
   return parseNameOnlyStdout(res.stdout);
 }
 
-/**
- * A full-length hex object id, as `git rev-parse` prints it. Used to reject
- * anything that is not a resolved commit — a stubbed git interface in a test
- * answers every `gitSpawn` with the same canned stdout, and a file list must
- * never be mistaken for a merge head.
- */
+/** A full object id; rejects canned stub output posing as a merge head. */
 const OBJECT_ID_RE = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
 
 /**
- * Resolve the commit an in-progress merge is merging **in**, or `null` when no
- * merge is in progress.
- *
- * Story #5131. `git diff --cached` with no commit argument diffs the index
- * against `HEAD`, and during a merge `HEAD` is still the pre-merge tip — so a
- * base-sync merge commit (`git merge --no-edit origin/<base>`, which
- * `single-story-close`'s base-sync phase tells the operator to run by hand)
- * put every file the base branch had landed into the staged scope. The
- * pre-commit MI/CRAP gate then blocked the resolution commit for deltas
- * belonging to already-landed, already-gated work, with no remedy: the preview
- * is a delta against the baseline, not a baseline comparison, so no baseline
- * refresh could silence it.
- *
- * Two details are load-bearing:
+ * The commit an in-progress merge is merging in, or `null`. During a merge
+ * `HEAD` is the pre-merge tip, so a plain `--cached` diff would pull the base
+ * branch's landed work into the staged scope.
  *
- *   - **Ask git, never the filesystem.** `.git` is a *file*, not a directory,
- *     in the linked worktrees this repo delivers from, so an
- *     `existsSync('.git/MERGE_HEAD')` probe would be silently inert exactly
- *     where deliveries happen. `rev-parse --verify` resolves the ref through
- *     git's own worktree-aware lookup.
- *   - **`--verify` fails closed on an octopus merge.** It refuses a
- *     `MERGE_HEAD` naming more than one head, which lands here as `null` — the
- *     pre-#5131 behaviour. Narrowing the scope wrongly would hide a real
- *     regression; widening it only restores the status quo.
- *
- * Never throws: a merge is either detectable or it is not, and an
- * undetectable one must degrade to the plain cached diff rather than fail the
- * gate.
+ * Ask git, never the filesystem: in a linked worktree `.git` is a file. An
+ * octopus `MERGE_HEAD` fails `--verify` and yields `null` (wider scope is
+ * safe; wrongly narrower would hide a regression). Never throws.
  *
  * @param {object} [params]
  * @param {string} [params.cwd=process.cwd()]
@@ -209,10 +121,6 @@ export function resolveMergeHead({ cwd = process.cwd(), git } = {}) {
 }
 
 /**
- * Read the index file list against an explicit base, shared by
- * `getStagedFiles` and `resolvePreviewScope` so the merge head is resolved
- * once per scope resolution rather than once per caller.
- *
  * @param {object} params
  * @param {string} params.cwd
  * @param {ReturnType<typeof createGitInterface>} params.git
@@ -231,21 +139,9 @@ function stagedFilesAgainst({ cwd, git, mergeHead }) {
 }
 
 /**
- * Resolve paths in the index (staged for commit). Used by `quality-preview
- * --staged` so pre-commit gates score only the commit payload, not unstaged
- * working-tree edits.
- *
- * Semantics:
- *   - Runs `git diff --name-only --cached`, which diffs the index against
- *     `HEAD`.
- *   - **During a merge**, diffs the index against `MERGE_HEAD` instead
- *     (Story #5131), so the scope is the merging branch's own contribution
- *     plus its conflict resolutions — not the base branch's incoming work.
- *     `git merge-base HEAD MERGE_HEAD` would *not* do: diffing the index
- *     against the fork point re-admits everything the base branch landed since
- *     it, which is the whole defect.
- *   - Returns forward-slash-normalized repo-relative paths.
- *   - Non-zero git exit throws — staged mode must not silently widen scope.
+ * Staged paths. During a merge the index is diffed against `MERGE_HEAD`, not
+ * the merge-base (which would re-admit everything the base landed since the
+ * fork). Throws on git failure rather than widen scope.
  *
  * @param {object} [params]
  * @param {string} [params.cwd=process.cwd()]
@@ -262,16 +158,8 @@ export function getStagedFiles({ cwd = process.cwd(), git } = {}) {
 }
 
 /**
- * Resolve the file set for quality-preview runners.
- *
- * When `staged` is true, only index paths are returned and `changedSinceRef`
- * is ignored. Otherwise a `changedSinceRef` limits to that three-dot diff;
- * when both are absent the caller runs in full-repo mode (`scopeSet: null`).
- *
- * In `staged` scope, `diffRef` carries the in-progress merge head when there
- * is one (Story #5131) and `null` otherwise, so a caller can tell the operator
- * *why* the scope narrowed. `scope` stays `'staged'` either way — the merge is
- * a property of the base the index is read against, not a different mode.
+ * `staged` wins over `changedSinceRef`; neither means full scope. In staged
+ * scope `diffRef` is the merge head, if any.
  *
  * @param {object} [params]
  * @param {boolean} [params.staged=false]

package/.agents/scripts/lib/checks/core-bare-clean.js

@@ -1,32 +1,12 @@
 /**
- * core-bare-clean — refuse-and-print blocker check.
- *
- * Asserts that `git config core.bare` on the main checkout is NOT set
- * to `true`. This guards the old failure mode where an `npm test` path
- * mis-set `core.bare=true` on the main checkout, after which
- * `single-story-close.js`'s post-rebase `git checkout` aborted with
- * `fatal: this operation must be run in a work tree`. `cleanGitEnv`
- * already lands the live fix; this check is the regression guard.
- *
- * Severity is `blocker` because single-story-close cannot recover on its own
- * — the operator must run `git config --unset core.bare` (or rely on
- * `cleanGitEnv` to do it before the rebase). The check is
- * refuse-and-print: the `fixCommand` is the literal unset, and the
- * operator runs it deliberately. We do not auto-fix because mutating
- * the parent repo's git config from a check is exactly the
- * "no commits to integration branches" cousin of the autoCorrect
- * disallowed list — config writes outside the local worktree boundary.
- *
- * Detection reads `state.git.coreBare`, the string returned by
- * `git config --get core.bare` (or `null` when unset). The check fires
- * when the string is the literal `'true'`.
+ * Blocks on `core.bare=true` in the main checkout, which aborts close's
+ * post-rebase checkout (`cleanGitEnv` is the live fix; this is the regression
+ * guard). Refuse-and-print: a check must not write config outside its worktree.
  */
 export default {
   id: 'core-bare-clean',
   severity: 'blocker',
-  // 'npm-test' keeps the test-wrapper preflight's refusal claim true: a
-  // poisoned shared config is caught before a suite (or N concurrent
-  // /mandrel-deliver workers) inherits it, not only at close/retro time (#4580).
+  // 'npm-test' catches a poisoned shared config before a suite inherits it.
   scope: ['story-close', 'retro', 'npm-test'],
   autoCorrect: 'refuse-and-print',
   detect(state) {

package/.agents/scripts/lib/checks/index.js

@@ -1,49 +1,8 @@
 /**
- * checks/index.js — Discovery-based registry + runner for self-healing checks.
- *
- * This module is the single entry point for every consumer surface that
- * runs checks (preflight guards at `single-story-close.js` and
- * `mandrel-update-preflight.js`, the
- * `npm test` wrapper, the `diagnose.js` CLI viewer, and the retro hook in
- * `retro-runner.js`). Each surface calls `runChecks({ scope, autoFix, state })`
- * with its own scope and gets back `{ findings, fixed }`.
- *
- * Registry shape (each sibling module exports):
- *
- *   {
- *     id: string,
- *     severity: 'blocker' | 'warning' | 'info',
- *     scope: string[],                              // may include 'retro'
- *     autoCorrect: 'auto' | 'refuse-and-print',
- *     detect(state): Promise<Finding | null>,
- *     fix?(state): Promise<{ ok: boolean, message: string }>,
- *   }
- *
- * Invariants enforced here (defense-in-depth — see README for the full
- * contract):
- *
- *   1. `scope === 'retro'` is read-only. `runChecks({ scope: 'retro',
- *      autoFix: true })` throws `'retro scope is read-only: autoFix must
- *      be false'` before any check runs. The retro-runner relies on this
- *      to keep retro stateless even if a future call site flips the flag.
- *
- *   2. `autoCorrect: 'refuse-and-print'` is hard-refusal. The runner will
- *      NEVER invoke a check's `fix()` unless `autoCorrect === 'auto'`,
- *      even if the check author later adds a `fix` body. This is what
- *      makes new fix implementations harmless until their author also
- *      opts in.
- *
- *   3. Phase split: `detect()` invocations fan out concurrently via
- *      `Promise.all` (Story #2463 — preflight subprocess batching), while
- *      `fix()` invocations remain strictly serial. `detect()` is
- *      read-only against the frozen `assembleState` object, so concurrent
- *      reads cannot race it; `fix()` may mutate the worktree, so its
- *      ordering is preserved by walking the registry-ordered findings
- *      array sequentially.
- *
- * Discovery happens once per process via `loadRegistry()`. The result is
- * cached; `clearRegistryCache()` is exported for tests that want to
- * exercise a different fixture directory.
+ * Discovery-based registry and runner for self-healing checks; every surface
+ * calls `runChecks({ scope, autoFix, state })`. Invariants: `retro` scope is
+ * read-only; `fix()` runs only when `autoCorrect === 'auto'`; `detect()` fans
+ * out concurrently, `fix()` stays serial.
  */
 
 import { readdirSync, statSync } from 'node:fs';
@@ -85,40 +44,24 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 /**
- * Module-local registry cache. Keyed by the absolute directory it was
- * loaded from so tests with fixture directories don't poison the cache
- * for the real `lib/checks/` directory.
+ * Keyed by absolute directory so fixture registries never poison the real one.
  *
  * @type {Map<string, Check[]>}
  */
 const registryCache = new Map();
 
-/**
- * Module names that are part of the runner infrastructure, not checks.
- * `loadRegistry()` filters these out of the readdir scan.
- *
- * @type {Set<string>}
- */
+/** @type {Set<string>} */
 const NON_CHECK_FILES = new Set(['index.js', 'state.js']);
 
-/**
- * Clear the registry cache. Tests call this between cases that load from
- * a fixture directory so a fresh registry is observed.
- */
 export function clearRegistryCache() {
   registryCache.clear();
 }
 
 /**
- * Load all check modules in a directory. Defaults to the directory this
- * module lives in (`lib/checks/`). Synchronously enumerates `.js` files,
- * filters out the runner infrastructure (`index.js`, `state.js`), and
- * dynamically imports each remaining file. Each module must default-export
- * a check object (see contract above).
+ * Import every check module in `dir`; each must default-export a {@link Check}.
  *
  * @param {object} [opts]
- * @param {string} [opts.dir]  Override directory — used by tests to load
- *   from a fixture directory.
+ * @param {string} [opts.dir]
  * @returns {Promise<Check[]>}
  */
 export async function loadRegistry({ dir = __dirname } = {}) {
@@ -130,10 +73,7 @@ export async function loadRegistry({ dir = __dirname } = {}) {
   try {
     entries = readdirSync(absDir);
   } catch {
-    // No directory → empty registry. The runner is still callable; it just
-    // returns `{ findings: [], fixed: [] }` for every scope. This is the
-    // shape the diagnose viewer expects when invoked on a fresh checkout
-    // before any check modules have been authored.
+    // No directory → empty registry, not an error.
     registryCache.set(absDir, []);
     return [];
   }
@@ -162,9 +102,6 @@ export async function loadRegistry({ dir = __dirname } = {}) {
 }
 
 /**
- * Look up a single check by id from the default registry. Returns
- * `undefined` if no check has that id.
- *
  * @param {string} id
  * @param {object} [opts]
  * @param {string} [opts.dir]
@@ -176,19 +113,12 @@ export async function getCheck(id, opts) {
 }
 
 /**
- * Run all checks matching `scope` against `state`. The retro-readonly and
- * refuse-and-print invariants are enforced here, not in the check
- * modules — see the JSDoc on the file for the rationale.
- *
  * @param {object} opts
- * @param {string} [opts.scope]      Surface scope, e.g. 'story-close',
- *   'story-close', 'npm-test', 'retro', 'diagnose'. When omitted, every check runs.
- * @param {boolean} [opts.autoFix=false]  Invoke `fix()` for checks with
- *   `autoCorrect: 'auto'`. Forbidden when `scope === 'retro'`.
- * @param {object} opts.state        Probed state from `assembleState()`.
- * @param {object} [opts.registry]   Pre-loaded registry — bypasses
- *   `loadRegistry()`. Used by tests with fixture checks.
- * @param {string} [opts.dir]        Fixture directory for `loadRegistry`.
+ * @param {string} [opts.scope]      Omitted runs every check.
+ * @param {boolean} [opts.autoFix=false]  Forbidden when `scope === 'retro'`.
+ * @param {object} opts.state        From `assembleState()`.
+ * @param {object} [opts.registry]   Pre-loaded registry.
+ * @param {string} [opts.dir]
  * @returns {Promise<{ findings: Finding[], fixed: Array<Finding & { fixResult: FixResult }> }>}
  */
 export async function runChecks({
@@ -206,12 +136,8 @@ export async function runChecks({
     ? checks.filter((c) => Array.isArray(c.scope) && c.scope.includes(scope))
     : checks;
 
-  // Phase 1 (read-only fan-out, Story #2463): run every `detect()` in
-  // parallel via Promise.all. `state` is the frozen object returned by
-  // `assembleState()`, so concurrent reads are race-free. Promise.all
-  // preserves input order in its resolved array, so the
-  // findings-by-registry-order contract that downstream consumers rely on
-  // is upheld even though the detects themselves overlap in flight.
+  // `state` is frozen, so concurrent detects are race-free; Promise.all keeps
+  // registry order.
   const detected = await Promise.all(
     filtered.map((check) => Promise.resolve(check.detect(state))),
   );
@@ -221,16 +147,12 @@ export async function runChecks({
   /** @type {Array<Finding & { fixResult: FixResult }>} */
   const fixed = [];
 
-  // Phase 2 (mutation-bearing serial pass): walk the registry-ordered
-  // detection results and apply fix() one at a time. fix() may mutate the
-  // worktree (delete branches, rewrite refs), so running it concurrently
-  // would race those mutations and scramble logs.
+  // fix() mutates the worktree, so it runs serially.
   for (let i = 0; i < filtered.length; i += 1) {
     const check = filtered[i];
     const finding = detected[i];
     if (!finding) continue;
-    // Invariant #2: refuse-and-print is hard-refusal — never invoke fix(),
-    // regardless of whether the author defined one. The flag is the gate.
+    // refuse-and-print never runs fix(), even if one is defined.
     if (
       autoFix &&
       check.autoCorrect === 'auto' &&
@@ -241,8 +163,6 @@ export async function runChecks({
         fixed.push({ ...finding, fixResult: result });
         continue;
       }
-      // fix() ran and failed → surface the finding as unfixed so the
-      // operator sees both the original problem AND the failure detail.
       findings.push({
         ...finding,
         detail: [
@@ -260,9 +180,6 @@ export async function runChecks({
 }
 
 /**
- * Shape-validate a check module. Used by `loadRegistry()` to fail fast on
- * malformed modules rather than crashing later inside `runChecks()`.
- *
  * @param {unknown} candidate
  * @returns {candidate is Check}
  */