mandrel 2.60.0 → 2.62.0

package/lib/cli/registry.js

@@ -1,26 +1,11 @@
 // lib/cli/registry.js
 /**
- * Doctor check + remedy registry for `mandrel doctor`.
- *
- * Exports an ordered array of check objects each shaped `{ name, run() }`.
- * `run()` returns `{ ok, detail, remedy? }` — `remedy` is present and
- * non-empty whenever `ok` is false, and on an `advisory` check that passes
- * while still having something actionable to say (`test-credit-path`), which
- * repeats it in `detail` because that is the field the doctor prints for a
- * passing check. The registry is the single source of truth for which checks
- * the doctor command runs and in what order.
- *
- * Checks run sequentially in the doctor runner (not in parallel) because
- * some checks are meaningless without a prerequisite having passed first
- * (e.g. `gh-auth` requires `gh-available`).
- *
- * Design goals
- * - Every check is injectable via optional seam parameters so tests can
- *   drive every branch without spawning real child processes.
- * - The `github-token` check never echoes the token value in `detail` or
- *   `remedy` (security baseline §5 — Secrets Management).
- * - Node built-ins only; no third-party imports so the module loads inside
- *   the preflight guard before any third-party package is present.
+ * Ordered `mandrel doctor` check registry: each entry is `{ name, run() }`,
+ * `run()` returning `{ ok, detail, remedy? }` (`remedy` present whenever
+ * `ok` is false). Checks run sequentially because some presuppose an earlier
+ * one (`gh-auth` needs `gh-available`). Node built-ins only, so the module
+ * loads inside the preflight guard before third-party packages exist; no
+ * check ever echoes a token value.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -54,13 +39,7 @@ import {
   satisfiesPinSpec,
 } from './version-helpers.js';
 
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
 /**
- * Synchronously spawn a binary and return `{ status, stdout, stderr, error }`.
- *
  * @param {string} cmd
  * @param {string[]} args
  * @returns {{ status: number|null, stdout: string, stderr: string, error?: NodeJS.ErrnoException }}
@@ -75,9 +54,7 @@ function spawn(cmd, args, opts = {}) {
   };
 }
 
-// ---------------------------------------------------------------------------
 // check: node-version
-// ---------------------------------------------------------------------------
 
 /**
  * @param {{ nodeVersion?: string }} [opts]
@@ -94,9 +71,7 @@ function runNodeVersion({ nodeVersion = process.versions.node } = {}) {
   };
 }
 
-// ---------------------------------------------------------------------------
 // check: git-available
-// ---------------------------------------------------------------------------
 
 /**
  * @param {{ runner?: (cmd: string, args: string[]) => { status: number|null, stdout: string, stderr: string, error?: NodeJS.ErrnoException } }} [opts]
@@ -115,9 +90,7 @@ function runGitAvailable({ runner = spawn } = {}) {
   return { ok: true, detail: r.stdout.trim().split('\n')[0] };
 }
 
-// ---------------------------------------------------------------------------
 // check: gh-available
-// ---------------------------------------------------------------------------
 
 /**
  * @param {{ runner?: (cmd: string, args: string[]) => { status: number|null, stdout: string, stderr: string, error?: NodeJS.ErrnoException } }} [opts]
@@ -136,21 +109,12 @@ function runGhAvailable({ runner = spawn } = {}) {
   return { ok: true, detail: r.stdout.trim().split('\n')[0] };
 }
 
-// ---------------------------------------------------------------------------
 // check: github-token
-// ---------------------------------------------------------------------------
 
 /**
- * Verify a GitHub token is resolvable the way the runtime resolves it.
- *
- * Parity with `.agents/scripts/providers/github/auth.js#resolveToken`: a
- * token counts as present when either `GITHUB_TOKEN` / `GH_TOKEN` is set in
- * the environment **or** `gh auth token` returns a value. The `mandrel` CLI
- * does not load `.env`, so the previous env-only check false-blocked
- * operators who authenticate solely via `gh auth login` (Finding A.4) —
- * the runtime never needed `GITHUB_TOKEN` in that case because it falls back
- * to the `gh` CLI. Never echoes the token value in `detail` or `remedy`
- * (security baseline §5 — Secrets Management).
+ * Resolve a token the way `providers/github/auth.js#resolveToken` does: env
+ * `GITHUB_TOKEN`/`GH_TOKEN`, else `gh auth token`. The CLI does not load
+ * `.env`, so an env-only check would false-block `gh auth login` users.
  *
  * @param {{ env?: Record<string,string|undefined>,
  *   runner?: (cmd: string, args: string[]) => {
@@ -176,25 +140,14 @@ function runGithubToken({ env = process.env, runner = spawn } = {}) {
   };
 }
 
-// ---------------------------------------------------------------------------
 // check: gh-auth
-// ---------------------------------------------------------------------------
 
 /**
- * Verify the GitHub CLI can authenticate.
- *
- * `gh auth status` performs **live token validation** (it probes the API for
- * the active token). A GitHub Actions installation token — and some
- * fine-grained tokens — cannot pass that probe (`GET /user` returns 403
- * "Resource not accessible by integration") even though the token works for
- * every git/API operation mandrel actually performs. The non-interactive
- * runtime never consults `gh auth status`: it resolves auth via the env token
- * or `gh auth token` (`.agents/scripts/providers/github/auth.js#resolveToken`,
- * mirrored by the `github-token` check above). So when `gh auth status` fails
- * but a token is present in the environment, degrade to **warn-and-skip**
- * (ok=true) rather than false-blocking the ready verdict — the same
- * warn-and-skip resolution #3915 applied to the project-scope preflight.
- * A genuine "no token anywhere and not logged in" condition still fails.
+ * `gh auth status` live-validates the token, which an Actions installation
+ * token (and some fine-grained tokens) cannot pass even though they work for
+ * everything mandrel does. The runtime never consults it, so a failing status
+ * with an env token present is warn-and-skip (ok); only "no token and not
+ * logged in" fails.
  *
  * @param {{ runner?: (cmd: string, args: string[]) => { status: number|null, stdout: string, stderr: string, error?: NodeJS.ErrnoException }, env?: Record<string,string|undefined> }} [opts]
  * @returns {{ ok: boolean, detail: string, remedy?: string }}
@@ -224,49 +177,23 @@ function runGhAuth({ runner = spawn, env = process.env } = {}) {
         'Run `gh auth login` (choose GitHub.com → HTTPS → login with a web browser), then re-run.',
     };
   }
-  // Extract "Logged in to github.com as <handle>" from stdout or stderr.
   const output = (r.stdout + r.stderr).trim();
   const match = /Logged in to \S+ as (\S+)/i.exec(output);
   const detail = match ? `logged in as ${match[1]}` : 'logged in';
   return { ok: true, detail };
 }
 
-// ---------------------------------------------------------------------------
 // check: commands-in-sync
-// ---------------------------------------------------------------------------
 
 /**
- * Dry-run the sync-claude-commands logic: compare the union of the two
- * projection sources — `.agents/workflows/*.md` (the installed payload) and
- * `.agents/local/workflows/*.md` (consumer-authored, prune-exempt, projected
- * since 1.75.0 / #4244) — to the generated flat command tree
- * `.claude/commands/*.md` destinations and report parity (the projection is
- * a flat `/<name>` command surface; the #3576 plugin projection was
- * reverted). A dest command backed only by a local workflow is in sync, not
- * stale (#4721).
+ * Parity of `.claude/commands/*.md` against the union of `.agents/workflows/`
+ * and `.agents/local/workflows/`. A basename is expected iff at least one
+ * source copy is not `command: false`, mirroring the sync script's
+ * payload-wins shadowing; an unreadable source counts as projected.
  *
- * Union semantics mirror the sync script's payload-wins shadowing (`byRel`):
- * a basename projects iff at least one source's copy is non-excluded — an
- * excluded payload copy never enters `byRel`, so it does not shadow a
- * projectable local copy. Filtering each source dir independently and
- * unioning the surviving basenames reproduces that exactly.
- *
- * Resolution anchor (Story #3588): the root defaults to `process.cwd()` —
- * the consumer project directory where `mandrel sync` materializes both
- * `.agents/` and the command tree — mirroring the `agents-materialized`
- * and `agents-drift` checks. It MUST NOT fall back to `resolveProjectRoot()`:
- * that walks up from this module's own location and lands on the *package*
- * directory in an npm-installed consumer
- * (`node_modules/mandrel/`), where the generated command tree never
- * exists — yielding a permanent `N not synced` false positive whose
- * `npm run sync:commands` remedy can never clear it.
- *
- * Injectable seams (used by tests so no real filesystem is touched):
- * - `cwd()` replaces `process.cwd` so tests can pin the consumer root.
- * - `readDir` replaces `fs.readdirSync`.
- * - `readFile` replaces `fs.readFileSync` (frontmatter `command: false`
- *   projection opt-out, #4482 — an unreadable source is treated as
- *   projected, matching the sync script's fail-loud read).
+ * The root defaults to `process.cwd()`, never `resolveProjectRoot()` — that
+ * lands on `node_modules/mandrel/` in an installed consumer, where the
+ * command tree never exists, producing a permanent false "not synced".
  *
  * @param {{ projectRoot?: string, cwd?: () => string, readDir?: (dir: string) => string[], readFile?: (file: string) => string | null }} [opts]
  * @returns {{ ok: boolean, detail: string, remedy?: string }}
@@ -299,12 +226,7 @@ function runCommandsInSync({ projectRoot, cwd, readDir, readFile } = {}) {
   ];
   const destDir = path.join(root, '.claude', 'commands');
 
-  // Only top-level .md files are synced (helpers/ subdirectory excluded by
-  // the sync script — they are path-included modules, not slash commands).
-  // Workflows whose frontmatter carries `command: false` (#4482) opt out of
-  // projection and must not count toward the expected command set. An absent
-  // local dir degrades to [] via the listDir catch, so payload-only
-  // consumers are unchanged.
+  // Top-level .md only (helpers/ are included modules, not commands).
   const expected = new Set();
   for (const srcDir of srcDirs) {
     for (const f of listDir(srcDir)) {
@@ -338,14 +260,10 @@ function runCommandsInSync({ projectRoot, cwd, readDir, readFile } = {}) {
   };
 }
 
-// ---------------------------------------------------------------------------
 // check: agents-in-sync
-// ---------------------------------------------------------------------------
 
 /**
- * Best-effort raw JSON read — no AJV, no merge validation. Absent, unreadable,
- * or malformed files degrade to `null` so a config problem never crashes a
- * doctor check; the caller applies framework defaults on `null`.
+ * Raw JSON read; any failure degrades to `null`.
  *
  * @param {string} absPath
  * @param {typeof fs} fsImpl
@@ -360,20 +278,10 @@ function readJsonSafe(absPath, fsImpl) {
 }
 
 /**
- * Resolve `delivery.routing.roleScopedAgents` (default `true`) for
- * `agents-in-sync`'s fatal/advisory branch below, WITHOUT importing the full
- * `resolveConfig()` chain — that chain pulls in AJV (`config-schema.js`),
- * which would violate this module's own "Node built-ins only" contract (see
- * the module doc: registry.js must load inside the preflight guard, before
- * any third-party package is guaranteed present).
- *
- * Reads `.agentrc.json` and `.agentrc.local.json` directly and shallow-merges
- * only the `delivery.routing` block (local wins per-key) — narrower than the
- * resolver's full deep-merge, but sufficient for this one boolean, and it
- * still honours a local override rather than silently ignoring it. Delegates
- * the actual default/coercion to `getDeliveryRouting` (`config/delivery-
- * routing.js`), which has zero imports of its own and is already the single
- * source of truth for this default elsewhere in the framework.
+ * Resolve `delivery.routing.roleScopedAgents` without `resolveConfig()`,
+ * which pulls in AJV and would break the built-ins-only contract. Shallow-
+ * merges only `delivery.routing` from `.agentrc.json` and
+ * `.agentrc.local.json` (local wins).
  *
  * @param {string} projectRoot
  * @param {typeof fs} fsImpl
@@ -397,44 +305,11 @@ function resolveRoleScopedAgentsFlag(projectRoot, fsImpl) {
 }
 
 /**
- * Dry-run the sync-claude-agents logic: compare `.agents/agents/*.md` sources
- * to the generated `.claude/agents/*.md` role-agent tree and report parity.
- * Exact sibling of `commands-in-sync` for the role-agent surface (#4478); the
- * agent tree is a flat projection with no `loops/` namespace and no
- * frontmatter projection opt-out.
- *
- * Resolution anchor: the root defaults to `process.cwd()` — the consumer
- * project directory where `mandrel sync` materializes both `.agents/` and the
- * agent tree — mirroring `commands-in-sync`. It MUST NOT fall back to
- * `resolveProjectRoot()`: that walks up from this module's own location and
- * lands on the *package* directory in an npm-installed consumer, where the
- * generated agent tree never exists.
- *
- * A repo with no `.agents/agents/` sources and no `.claude/agents/` tree is a
- * clean no-op (0 sources, 0 dests → "up to date").
- *
- * **Tightened from advisory to fatal (Story #4530, M7-B).** Prior to this
- * Story, a **never materialized** agent tree (sources present, `.claude/
- * agents/` empty) was reported as advisory — "inert", because no workflow
- * spawned the role agents yet. M7-B has landed: `helpers/deliver-story` Step
- * 1a dispatches `subagent_type: acceptance-critic` on the **default** path
- * (`roleScopedAgents` defaults `true`). An unmaterialized tree under that
- * default is no longer a benign scaffolding gap — it is the acceptance
- * ceremony's fresh-context critic silently failing to spawn and falling back
- * to a weaker inline critic, with doctor reporting green throughout. This
- * check now fails in exactly that case. When `roleScopedAgents` is `false`
- * (the operator kill-switch), an unmaterialized tree is expected — the check
- * stays advisory. Once the tree HAS been materialized, drift (a source
- * missing from the dest, or a stale dest file) fails the check exactly like
- * `commands-in-sync`, unconditionally, exactly as before this Story.
- *
- * Injectable seams (used by tests so no real filesystem is touched):
- * - `cwd()` replaces `process.cwd` so tests can pin the consumer root.
- * - `readDir` replaces `fs.readdirSync`.
- * - `fsImpl` replaces the `node:fs` surface used for the `.agentrc.json` /
- *   `.agentrc.local.json` reads.
- * - `roleScopedAgents` overrides the resolved flag directly, bypassing the
- *   config reads entirely.
+ * Parity of `.claude/agents/*.md` against `.agents/agents/*.md` (root anchored
+ * at `process.cwd()` as in `commands-in-sync`). A never-materialized tree is
+ * fatal while `roleScopedAgents` is on — the acceptance critic would silently
+ * fail to spawn and fall back to a weaker inline critic — and advisory when it
+ * is off. Drift in a materialized tree always fails.
  *
  * @param {{
  *   projectRoot?: string,
@@ -483,7 +358,6 @@ function runAgentsInSync({
         ? roleScopedAgents
         : resolveRoleScopedAgentsFlag(root, fsImpl);
     if (!resolvedFlag) {
-      // Kill-switch off: an unmaterialized tree is expected, not a defect.
       return {
         ok: true,
         detail: `${sources.length} agent def(s) not materialized (roleScopedAgents is disabled)`,
@@ -517,18 +391,12 @@ function runAgentsInSync({
   };
 }
 
-// ---------------------------------------------------------------------------
 // check: runtime-deps
-// ---------------------------------------------------------------------------
 
 /**
- * The verdict when every required package is present.
- *
- * Presence is not the whole contract: `.agents/` resolves from the consumer's
- * node_modules, so a declared range cannot enforce which `@babel/parser` major
- * the complexity kernel actually gets, and the wrong major fails scoring
- * mid-scan with an opaque plugin-list error. Reporting it here puts it where a
- * consumer is already looking for what to fix.
+ * Presence is not enough: a declared range cannot pin which `@babel/parser`
+ * major the consumer's node_modules supplies, and the wrong one fails
+ * scoring mid-scan with an opaque error — so report it here.
  *
  * @param {() => string|null} parserMajorError
  * @returns {{ ok: boolean, detail: string, remedy?: string }}
@@ -546,24 +414,9 @@ function allPresentVerdict(parserMajorError) {
 }
 
 /**
- * Verify that the framework's required runtime dependencies are resolvable
- * from the project's node_modules.
- *
- * `projectRoot` defaults to `process.cwd()` (the consumer project root) so
- * the manifest path and the require-resolution context mirror the context in
- * which the framework scripts actually run (Story #4046 A2). Using
- * `resolveProjectRoot()` (the package root inside `node_modules/mandrel/`)
- * breaks the check under pnpm isolated-mode layouts where the consumer's
- * node_modules are hoisted above `node_modules/mandrel/` and are invisible
- * from the package root's resolver.
- *
- * Injectable seams:
- * - `resolve(dep)` — replaces the real `require.resolve`; throws when a dep
- *   is missing.
- * - `manifestRequired` — array of required package names, skips the
- *   filesystem read of `runtime-deps.json`.
- * - `parserMajorError()` — replaces the resolved-parser-major probe, so the
- *   unsupported-major report is assertable without installing one.
+ * Are the runtime deps resolvable from the consumer root? Anchored at
+ * `process.cwd()`, not the package root: under pnpm isolated mode the
+ * consumer's node_modules are invisible from `node_modules/mandrel/`.
  *
  * @param {{ projectRoot?: string, resolve?: (dep: string) => string, manifestRequired?: string[] }} [opts]
  * @returns {{ ok: boolean, detail: string, remedy?: string }}
@@ -574,10 +427,6 @@ function runRuntimeDeps({
   manifestRequired,
   parserMajorError = describeParserMajorError,
 } = {}) {
-  // Anchor at process.cwd() (the consumer root), not resolveProjectRoot() (the
-  // package root). Under pnpm isolated-mode the consumer's node_modules are not
-  // visible from inside node_modules/mandrel/, so the old anchor produced false
-  // "missing" reports on a clean install (Story #4046 A2).
   const root = projectRoot ?? process.cwd();
 
   let required = manifestRequired;
@@ -598,17 +447,8 @@ function runRuntimeDeps({
 
   const missing = [];
 
-  // Anchor resolution to the consumer project root so it mirrors the context
-  // in which the framework scripts run (they free-ride on the consumer's
-  // node_modules). Under pnpm isolated-mode the consumer's node_modules are
-  // not reachable from inside node_modules/mandrel/; anchoring at process.cwd()
-  // finds them correctly.
-  //
-  // `isResolvable` is shared with the framework-side preflight rather than
-  // reimplemented here: it probes the bare specifier AND `<name>/package.json`,
-  // because a dependency with no `main` and no `exports` cannot be resolved by
-  // name at all. Probing only the bare name reports such a package missing
-  // while it sits installed, and this check gates `mandrel doctor`.
+  // `isResolvable` also probes `<name>/package.json`: a dep with no `main`
+  // and no `exports` cannot be resolved by bare name yet is installed.
   const resolve =
     resolveSeam ?? createRequire(path.join(root, 'package.json')).resolve;
   for (const dep of required) {
@@ -630,30 +470,12 @@ function runRuntimeDeps({
   };
 }
 
-// ---------------------------------------------------------------------------
 // check: agents-materialized
-// ---------------------------------------------------------------------------
 
 /**
- * Verify that the `.agents/` payload has been materialized into the consumer
- * project (`./.agents/instructions.md` exists). When it is absent but the
- * `mandrel` package *is* installed in node_modules, the project is in
- * the "postinstall-skipped" state — the package was installed with scripts
- * disabled (e.g. `npm ci --ignore-scripts`, a sandboxed CI, or a package
- * manager that skips lifecycle scripts), so the materializer never ran. The
- * remedy is to run `mandrel sync` (lib/cli/sync.js) by hand.
- *
- * Resolution anchors:
- * - `./.agents/instructions.md` is resolved against `cwd` (the consumer
- *   project root), matching where `mandrel sync` writes the materialized tree.
- * - `mandrel` is resolved from `cwd` so we detect *their* install, not
- *   a copy hoisted next to this CLI module — mirroring sync.js's resolver.
- *
- * Injectable seams (used by tests so no real filesystem or package is needed):
- * - `cwd()` — replaces `process.cwd`.
- * - `existsSync(p)` — replaces `fs.existsSync`.
- * - `resolvePackage(fromDir)` — replaces `mandrel` resolution; throws
- *   when the package is not installed.
+ * Is `./.agents/instructions.md` present? Absent with the package installed
+ * means postinstall was skipped (`--ignore-scripts`, sandboxed CI). Both
+ * lookups anchor at the consumer's cwd.
  *
  * @param {{
  *   cwd?: () => string,
@@ -704,31 +526,11 @@ function runAgentsMaterialized({ cwd, existsSync, resolvePackage } = {}) {
   };
 }
 
-// ---------------------------------------------------------------------------
 // check: agents-drift
-// ---------------------------------------------------------------------------
-
-// defaultResolvePackageRoot and listPayloadFiles (re-exported as `listFiles`
-// from sync.js) are imported from `lib/cli/sync.js` at the top of this file
-// (Story #4048 B3 — no mirror copies).
 
 /**
- * Decide whether a single materialized payload file has drifted from its
- * package-payload source.
- *
- * Size short-circuit (Story #4193): when the injected `fsImpl` exposes
- * `statSync`, a `statSync(src).size !== statSync(dest).size` mismatch is
- * sufficient proof of drift, so it returns `true` on two `stat` syscalls
- * **without reading either file's contents** — the overwhelmingly common
- * drift shape after a stale `sync` is a size change. Equal sizes do not
- * guarantee equal content, so an equal-size pair falls through to the
- * `readFileSync` + `Buffer.equals` byte comparison. The short-circuit is
- * opt-in on `statSync` being present; a seam that omits it (e.g. a legacy
- * test double) transparently uses the byte-read path, preserving the prior
- * behaviour exactly.
- *
- * Security: returns only a boolean — it never surfaces file contents to the
- * caller (security baseline §5 — Data Leakage & Logging).
+ * A size mismatch proves drift without reading contents; equal sizes fall
+ * through to a byte compare. `statSync` is optional on the seam.
  *
  * @param {string} src - absolute path to the package-payload file
  * @param {string} dest - absolute path to the materialized file
@@ -746,28 +548,9 @@ function payloadFileDrifted(src, dest, fsImpl) {
 }
 
 /**
- * Compare the consumer's materialized `./.agents/<f>` bytes against the
- * installed package payload (`node_modules/mandrel/.agents/<f>`),
- * excluding the `.agents/local/` zone. Reports the first drifted (or
- * missing) materialized file so the operator can re-sync or move local edits
- * into `.agents/local/`.
- *
- * Security: logs only paths and counts — file contents are read for a byte
- * comparison but never placed into `detail` or `remedy` (security baseline
- * §5 — Data Leakage & Logging). The comparison is short-circuiting and never
- * accumulates file contents.
- *
- * Performance: per-file drift is decided by `payloadFileDrifted`, which gates
- * the byte read behind a cheap `statSync` size comparison (Story #4193) so a
- * size-changed file — the common drift shape after a stale `sync` — reports
- * without reading either file's contents.
- *
- * Injectable seams (used by tests so no real filesystem or package is needed):
- * - `cwd()` — replaces `process.cwd`.
- * - `fsImpl` — replaces the `node:fs` surface (`existsSync`, `readdirSync`,
- *   `readFileSync`, and optionally `statSync` for the size short-circuit).
- * - `resolvePackageRoot(fromDir)` — replaces `mandrel` resolution;
- *   throws when the package is not installed.
+ * Compare materialized `./.agents/` bytes to the installed package payload
+ * (excluding `.agents/local/`) and report the first missing or drifted file.
+ * Only paths and counts are reported, never contents.
  *
  * @param {{
  *   cwd?: () => string,
@@ -785,9 +568,7 @@ export function runAgentsDrift({ cwd, fsImpl = fs, resolvePackageRoot } = {}) {
   try {
     packageRoot = resolveRoot(projectRoot);
   } catch {
-    // Without the package installed there is no baseline to compare against;
-    // agents-materialized owns the "not installed" remedy, so this check is
-    // a no-op success rather than a false drift signal.
+    // agents-materialized owns the "not installed" remedy.
     return {
       ok: true,
       detail: 'mandrel not installed — drift skipped',
@@ -804,7 +585,6 @@ export function runAgentsDrift({ cwd, fsImpl = fs, resolvePackageRoot } = {}) {
 
   const destRoot = path.join(projectRoot, '.agents');
   if (!fsImpl.existsSync(destRoot)) {
-    // Nothing materialized yet — agents-materialized owns that remedy.
     return { ok: true, detail: './.agents/ not materialized — drift skipped' };
   }
 
@@ -844,66 +624,18 @@ export function runAgentsDrift({ cwd, fsImpl = fs, resolvePackageRoot } = {}) {
   };
 }
 
-// ---------------------------------------------------------------------------
 // check: pin-current
-// ---------------------------------------------------------------------------
 
 /**
- * Fatal doctor check (Story #4525 / #4530): is the version actually
- * resolvable in `node_modules` **consistent with** the consumer's declared
- * `mandrel` dependency range (`package.json`)?
- *
- * This is a **different** signal from `agents-drift` (are the materialized
- * `.agents/` file *contents* byte-identical to the installed payload) and
- * from `version-current` below (is a *newer* version *published*). Neither
- * of those catches the shape of bug #4525 reported: a `package.json` pin
- * that has fallen out of agreement with what `node_modules` actually
- * resolves to — e.g. an out-of-band symlink, or `npm install mandrel@latest
- * --no-save` — which `mandrel doctor` graded as fully green before this
- * check existed, because the only version `defaultCurrentVersion` ever read
- * WAS the inflated `node_modules` one.
- *
- * **Range-aware.** The declared pin is a *range*, not an equality, so the
- * question this check asks is satisfaction, not identity. A consumer who
- * declares `^2.1.0` and runs a routine `npm update` gets 2.4.0 in
- * `node_modules` with `package.json` untouched — that is npm behaving
- * exactly as documented, and under this project's `always-bump-minor`
- * release cadence it is the *normal* steady state, not a defect. Grading it
- * fatal (as this check originally did, comparing only the pin's base
- * version) made `mandrel doctor` cry wolf on healthy installs.
- *
- * The graded contract:
- * - installed **satisfies** the declared range and equals its base version
- *   → pass, quietly.
- * - installed **satisfies** the declared range but is newer than its base
- *   (`^2.1.0` + 2.4.0) → pass with an **advisory** `detail`. Re-pinning via
- *   `mandrel update` is tidier, but nothing is broken. This mirrors how
- *   `version-current` stays non-fatal: `ok: true` with the advisory carried
- *   in `detail` (the registry's `advisory: true` flag documents an entry
- *   whose `run()` *never* fails, which is not true of this check).
- * - installed does **not** satisfy the declared range (`^2.1.0` + 3.0.0, or
- *   an exact `2.1.0` pin + 2.4.0) → **fail**. The declared dependency does
- *   not describe the code that is running.
- * - installed is **behind** the pin's base version (`^2.4.0` + 2.1.0) →
- *   **fail**, and note that `<` the base never satisfies any of the ranges
- *   `resolveConsumerPinSpec` yields, so this is a sub-case of the above
- *   given a distinct, more actionable message.
- *
- * Skips cleanly (not a failure) when there is no resolvable pin at all — no
- * `package.json`, no `mandrel` entry in `dependencies`/`devDependencies`, or
- * a non-semver specifier (`workspace:`, `git+`, `latest`, a comparator
- * range) — via {@link resolveConsumerPinSpec}'s own `null` contract. This
- * is also how mandrel's own repo (no self-dependency) and workspace/npx
- * consumers degrade to a clean pass rather than a false failure.
- *
- * Injectable seams (used by tests so no real filesystem or package is
- * needed):
- * - `cwd()` — replaces `process.cwd`, anchoring both the pin read and the
- *   `node_modules` resolution at the same consumer root (mirrors
- *   `agents-drift` / `agents-in-sync`).
- * - `fsImpl` — replaces the `node:fs` surface.
- * - `resolvePackageRoot(fromDir)` — replaces `mandrel` resolution; throws
- *   when the package is not installed.
+ * Fatal: does the installed `mandrel` satisfy the consumer's declared range?
+ * Distinct from `agents-drift` (file contents) and `version-current` (newer
+ * published). Graded by range satisfaction, not identity, because `^2.1.0` +
+ * 2.4.0 after `npm update` is the normal steady state:
+ * - satisfies and equals the base → pass;
+ * - satisfies but newer than the base → pass, advisory in `detail`;
+ * - behind the base → fail (distinct message);
+ * - otherwise outside the range → fail.
+ * No resolvable semver pin (absent, `workspace:`, `git+`, `latest`, …) skips.
  *
  * @param {{
  *   cwd?: () => string,
@@ -929,8 +661,6 @@ export function runPinCurrent({ cwd, fsImpl = fs, resolvePackageRoot } = {}) {
   try {
     installedRoot = resolveRoot(projectRoot);
   } catch {
-    // No baseline to compare the pin against; agents-materialized /
-    // runtime-deps own the "not installed" remedy.
     return {
       ok: true,
       detail: 'mandrel not installed — pin check skipped',
@@ -971,10 +701,7 @@ export function runPinCurrent({ cwd, fsImpl = fs, resolvePackageRoot } = {}) {
   }
 
   if (compareSemver(installed, spec.version) > 0) {
-    // In range, just newer than the declared base — the ordinary result of an
-    // `npm update` under a caret/tilde pin. Healthy, so `ok: true`; the
-    // advisory rides in `detail` (the doctor runner only prints `remedy` for
-    // failures).
+    // The doctor prints only `detail` for a pass, so the advisory rides there.
     return {
       ok: true,
       detail: `v${installed} satisfies the ${declared} pin but is newer than it — run \`mandrel update\` to re-pin (advisory)`,
@@ -987,19 +714,9 @@ export function runPinCurrent({ cwd, fsImpl = fs, resolvePackageRoot } = {}) {
   };
 }
 
-// ---------------------------------------------------------------------------
 // check: version-current
-// ---------------------------------------------------------------------------
-
-// parseVersion and compareVersions are imported from `lib/cli/version-helpers.js`
-// at the top of this file (Story #4048 B3 — no mirror copies). `compareSemver`
-// is the registry-local alias for the imported `compareVersions`.
 
 /**
- * Resolve the installed `mandrel` version from this package's own
- * `package.json`. This module lives at `<root>/lib/cli/registry.js`, so the
- * manifest is two directories up. Mirrors `lib/cli/update.js#defaultCurrentVersion`.
- *
  * @param {typeof fs} fsImpl
  * @returns {string}
  */
@@ -1010,17 +727,12 @@ function defaultInstalledVersion(fsImpl) {
   return String(parsed.version);
 }
 
-/**
- * Default cache filename — mirrors `version-check.js#DEFAULT_CACHE_FILENAME`.
- */
+/** Mirrors `version-check.js#DEFAULT_CACHE_FILENAME`. */
 const DEFAULT_VERSION_CACHE_FILENAME = 'version-check.json';
 
 /**
- * Default cache path: `<consumerRoot>/temp/version-check.json`, anchored at
- * `process.cwd()` (the consumer project root) so the cache file survives
- * npm/pnpm reinstalls that may replace `node_modules/` entirely (Story #4046
- * A2). Mirrors `commands-in-sync` / `agents-materialized` / `agents-drift`
- * which all anchor at `process.cwd()`.
+ * Anchored at the consumer root so the cache survives reinstalls that
+ * replace `node_modules/`.
  *
  * @returns {string}
  */
@@ -1029,32 +741,8 @@ function defaultVersionCachePath() {
 }
 
 /**
- * Cache-only stale-version advisory (Story #3507, Epic #3437 — f-notify-stale).
- *
- * Reads the daily freshness cache written by `lib/cli/version-check.js` and
- * reports whether a newer version than the installed one is already known
- * locally. This check is **cache-only**: it NEVER issues a network request
- * (it calls `readCache`, not `isStale`, so the network `runner` seam is never
- * reached) — the daily refresh is owned by `version-check.js`, invoked
- * elsewhere on the normal command path.
- *
- * **Non-fatal advisory contract.** A stale install is informational, not a
- * readiness failure, so this check ALWAYS returns `ok: true` and therefore can
- * never flip `mandrel doctor`'s exit code or block CI. When a newer version is
- * cached, the advisory is surfaced through `detail` ("a newer version is
- * available") and an actionable `remedy` (`mandrel update`); when the cache is
- * absent, malformed, or already current, the check reports the up-to-date /
- * unknown state with no remedy. The registry entry carries `advisory: true` so
- * downstream renderers can label it as informational.
- *
- * Security (security-baseline § 5 — Data Leakage & Logging): emits only version
- * strings; never reads or echoes tokens, credentials, or raw cache bytes beyond
- * the two version fields `readCache` already validates.
- *
- * Injectable seams (used by tests so no real filesystem is touched):
- * - `cachePath`        — absolute path to the freshness cache JSON.
- * - `installedVersion` — the currently installed version string.
- * - `fsImpl`           — `node:fs` surface forwarded to `readCache`.
+ * Cache-only stale-version advisory: reads the freshness cache and never hits
+ * the network. Always `ok: true`, so it can never fail doctor or CI.
  *
  * @param {{
  *   cachePath?: string,
@@ -1071,7 +759,6 @@ function runVersionCurrent({ cachePath, installedVersion, fsImpl = fs } = {}) {
     try {
       current = defaultInstalledVersion(fsImpl);
     } catch {
-      // Without a readable manifest we cannot compare; stay non-fatal.
       return {
         ok: true,
         detail: 'installed version unknown — advisory skipped',
@@ -1081,7 +768,6 @@ function runVersionCurrent({ cachePath, installedVersion, fsImpl = fs } = {}) {
 
   const cached = readCache({ cachePath: resolvedPath, fs: fsImpl });
   if (!cached) {
-    // Missing / malformed cache → nothing to advise on yet. Non-fatal.
     return {
       ok: true,
       detail: `v${current} (no cached freshness check yet)`,
@@ -1099,35 +785,20 @@ function runVersionCurrent({ cachePath, installedVersion, fsImpl = fs } = {}) {
   return { ok: true, detail: `v${current} is up to date` };
 }
 
-// ---------------------------------------------------------------------------
-// Registry
-// ---------------------------------------------------------------------------
+// check: merge-driver
 
 /**
- * Is this clone's `baselines/*.json` merge driver actually registered?
- *
- * The two halves of that registration live in different places on purpose.
- * `.gitattributes` is tracked, so the "use the driver" half ships with the
- * repo; the driver COMMAND is per-clone `git config`, because git will not
- * execute a command chosen by whoever wrote the repository. A fresh clone
- * therefore has the first half and not the second — and git reports nothing
- * at all, it just quietly falls back to text-merging baselines, which is the
- * behaviour the driver exists to replace.
- *
- * Silent degradation is why this is a doctor check rather than a one-time
- * install step. It is scoped to repos that opted in: when `.gitattributes`
- * does not declare the driver, the check passes as skipped, so a consumer
- * who never installed the quality surface is not told to fix something they
- * did not ask for.
+ * Is this clone's `baselines/*.json` merge driver registered? `.gitattributes`
+ * ships with the repo but the driver command is per-clone `git config`, and a
+ * missing one silently falls back to a text merge. Skipped when
+ * `.gitattributes` does not declare the driver.
  *
  * @param {{cwd?: () => string, fsImpl?: typeof fs, runner?: typeof spawn}} [opts]
  * @returns {{ ok: boolean, detail: string, remedy?: string }}
  */
 export function runMergeDriver({ cwd, fsImpl = fs, runner = spawn } = {}) {
   const projectRoot = (cwd ?? (() => process.cwd()))();
-  // Both git calls run from `projectRoot`: the config key is per-clone, and
-  // reading it from wherever `mandrel doctor` was typed answers about a
-  // different repository (or none).
+  // Git runs from projectRoot: the config key is per-clone.
   const { declared, command } = probeBaselineMergeDriver({
     projectRoot,
     fsImpl,
@@ -1151,27 +822,11 @@ export function runMergeDriver({ cwd, fsImpl = fs, runner = spawn } = {}) {
 }
 
 /**
- * Does the configured driver command actually RUN? (Story #5277)
- *
- * A set-but-broken key is the failure mode a presence check cannot see, and it
- * is the common one: the command names an absolute node binary, and an nvm or
- * volta version bump moves that binary out from under it months after the
- * driver was installed. Git's behaviour then is the same silence a missing key
- * produces — the driver exits non-zero, git leaves the file conflicted, and the
- * operator reads it as "baselines conflict again" rather than as a broken
- * registration. So the check executes what git would execute.
- *
- * `--help` is the probe because the driver's real invocation mutates `%A` in
- * place; the shipped CLI answers `--help` with exit 0 and touches nothing.
- *
- * The command is tokenised, never handed to a shell
- * ({@link parseBaselineMergeDriverCommand}) — it is a config value, and running
- * it through `shell: true` would make any write to that key arbitrary command
- * execution (security-baseline § Output & Rendering).
- *
- * The probe runs from `projectRoot`, because the command's script path is
- * relative to the worktree root — which is where git invokes a merge driver
- * from, and is not necessarily where `mandrel doctor` was typed.
+ * Execute the configured driver with `--help` (the real invocation mutates
+ * `%A`): a set-but-broken command — typically an absolute node path moved by
+ * an nvm/volta bump — fails as silently as an unset key. The command is
+ * tokenised, never shell-run, since a config value must not become arbitrary
+ * command execution. Runs from projectRoot, where git invokes drivers.
  *
  * @param {string} command
  * @param {typeof spawn} runner
@@ -1199,32 +854,20 @@ function probeConfiguredDriver(command, runner, projectRoot) {
   };
 }
 
-// ---------------------------------------------------------------------------
 // check: test-credit-path
-// ---------------------------------------------------------------------------
 
-/**
- * The runner whose own green full run deposits the close `test` credit as a
- * side effect (`.agents/scripts/run-tests.js` → `lib/test-run-credit.js`).
- */
+/** The runner whose green full run deposits the close `test` credit itself. */
 const MANDREL_TEST_RUNNER = 'run-tests.js';
 
-/**
- * The deposit that works whatever `npm test` resolves to: it spawns the
- * project's own suite and stamps the result, so it is honest by construction.
- */
+/** Deposits the credit whatever `npm test` resolves to. */
 const TEST_CREDIT_DEPOSIT_COMMAND =
   'node .agents/scripts/evidence-gate.js --standalone --scope-id <storyId> --gate test --worktree <workCwd> -- npm test';
 
-/** Remedy shared by every shape that does not earn the credit on its own. */
 const TEST_CREDIT_REMEDY = `run the suite through the depositor instead of bare \`npm test\`: ${TEST_CREDIT_DEPOSIT_COMMAND}`;
 
 /**
- * The project's `test` script — what `npm test` runs, and therefore what the
- * close `test` gate spawns. Deliberately read from `package.json` rather than
- * `project.commands.test`: the close gate's argv is the literal `npm test`, so
- * the npm script is the command whose shape decides whether a bare run
- * deposits anything.
+ * Read from `package.json`, not `project.commands.test`: the close gate's argv
+ * is the literal `npm test`.
  *
  * @param {string} projectRoot
  * @param {typeof fs.readFileSync} readFileImpl
@@ -1243,20 +886,10 @@ function readProjectTestScript(projectRoot, readFileImpl) {
 }
 
 /**
- * Report whether this project's test command reaches mandrel's own runner,
- * and therefore whether a bare `npm test` deposits the close `test` credit
- * by itself (Story #5324).
- *
- * **Always `ok: true`.** A project on `vitest`, `jest` or any other runner is
- * a supported setup, not a broken install — the only thing it lacks is the
- * runner-side bonus deposit, and the remedy command covers it. So the check
- * informs rather than gates, and (unlike every other entry here) carries its
- * `remedy` alongside a passing verdict; the same guidance also rides in
- * `detail`, which is the field the doctor prints for a passing check.
- *
- * The runner is detected by name, never by executing anything: a script that
- * reaches `run-tests.js` indirectly reads as "own runner", which errs toward
- * naming the deposit command — correct on either shape.
+ * Does a bare `npm test` reach mandrel's runner and so deposit the close
+ * `test` credit? Always `ok: true` — another runner is supported, it just
+ * needs the explicit depositor — so the remedy rides a passing verdict and is
+ * repeated in `detail`. Detected by name only, never executed.
  *
  * @param {{ projectRoot?: string, readFile?: typeof fs.readFileSync }} [opts]
  * @returns {{ ok: boolean, detail: string, remedy?: string }}
@@ -1283,14 +916,7 @@ function runTestCreditPath({ projectRoot, readFile = fs.readFileSync } = {}) {
   };
 }
 
-/**
- * Ordered array of doctor checks. Each entry follows the
- * `{ name: string, run(opts?): { ok: boolean, detail: string, remedy?: string } }` contract.
- * The doctor runner iterates this array sequentially.
- *
- * The `run` functions return plain objects (not Promises) — the doctor runner
- * may call them with `await` but they do not need to be async.
- */
+/** `advisory: true` marks a check whose `run()` never fails. */
 export const registry = [
   {
     name: 'node-version',
@@ -1338,24 +964,15 @@ export const registry = [
   },
   {
     name: 'pin-current',
-    // Fatal, unlike version-current below (Story #4525/#4530): a pin/install
-    // disagreement means the declared dependency does not describe the code
-    // that is running.
     run: (opts) => runPinCurrent(opts),
   },
   {
     name: 'version-current',
-    // Non-fatal: surfaces a cache-only stale-version advisory. `run()` always
-    // returns ok:true, so it never blocks `mandrel doctor`'s exit code or CI.
     advisory: true,
     run: (opts) => runVersionCurrent(opts),
   },
   {
     name: 'test-credit-path',
-    // Non-fatal: `run()` always returns ok:true. A project on its own test
-    // runner is a supported setup that simply has to deposit the close
-    // `test` credit explicitly, so this reports a condition rather than
-    // failing the install (Story #5324).
     advisory: true,
     run: (opts) => runTestCreditPath(opts),
   },