mandrel 2.60.0 → 2.62.0

package/lib/cli/doctor.js

@@ -1,26 +1,8 @@
 // lib/cli/doctor.js
 /**
- * `mandrel doctor` subcommand.
- *
- * Runs every check from lib/cli/registry.js in registration order,
- * prints a ✔/✘ per-check report with remedies for failures, prints a
- * final summary line, and exits 0 when all checks pass or non-zero when
- * any check fails.
- *
- * Output contract (per Story #3450 AC):
- *   pass  → "✔  <name>   <detail>"
- *   fail  → "✘  <name>   <detail>\n   → <remedy>"
- *   final → "✅  Ready (N/N checks passed)"
- *         | "❌  Not ready (N/N checks failed)"
- *
- * All output goes to process.stdout so it can be captured by tests.
- * Exit code 0 = all pass, 1 = any fail.
- *
- * Injectable seams (used by tests):
- *   - `checks`           — replaces the default registry array
- *   - `write`            — replaces process.stdout.write
- *   - `exit`             — replaces process.exit
- *   - `writeResultCache` — replaces the temp/doctor-result.json writer
+ * `mandrel doctor`: run the registry checks in order, print a ✔/✘ line per
+ * check (with the remedy under a failure) and a summary; exit 1 on any
+ * failure.
  */
 
 import nodeFs from 'node:fs';
@@ -32,13 +14,7 @@ import {
 } from '../../.agents/scripts/lib/doc-tiers.js';
 import { registry } from './registry.js';
 
-// ---------------------------------------------------------------------------
-// Formatting helpers
-// ---------------------------------------------------------------------------
-
 /**
- * Pad or truncate `name` to `width` characters so columns line up neatly.
- *
  * @param {string} name
  * @param {number} width
  * @returns {string}
@@ -47,13 +23,10 @@ function padName(name, width) {
   return name.length >= width ? name : name + ' '.repeat(width - name.length);
 }
 
-// Column width for the check-name field (longest registry name is
-// "agents-materialized" = 19 chars; use 21 for breathing room).
+// Longest check name is 19 chars.
 const NAME_COL = 21;
 
 /**
- * Format a single check result line (or lines when a remedy is present).
- *
  * @param {{ name: string, ok: boolean, detail: string, remedy?: string }} result
  * @returns {string}
  */
@@ -68,8 +41,6 @@ function formatResult({ name, ok, detail, remedy }) {
 }
 
 /**
- * Format the final summary line.
- *
  * @param {number} passed
  * @param {number} total
  * @returns {string}
@@ -83,17 +54,9 @@ function formatSummary(passed, total) {
 }
 
 /**
- * Build the one report-only line describing the always-loaded documentation
- * closure (the `CLAUDE.md` `@`-import graph) — its file count and total size in
- * KB. This is **informational only**: it is never counted toward the pass/fail
- * tally and therefore never changes the doctor exit code (Story #4438). Any
- * failure to resolve the closure degrades to a neutral line rather than
- * throwing, so an unreadable tree never breaks the doctor run.
- *
- * Security (security-baseline § 5 — Data Leakage & Logging): emits only a file
- * count and byte total, never file contents.
- *
- * Exported for testing.
+ * Informational line for the `CLAUDE.md` always-loaded closure (file count,
+ * KB). Never counted toward the verdict; a resolve failure degrades to a
+ * neutral line.
  *
  * @param {{ cwd?: () => string, resolveClosure?: (root: string) => Array<{ path: string, bytes: number }> }} [opts]
  * @returns {string} a single line terminated by `\n`
@@ -116,19 +79,9 @@ export function formatClosureReport({
   return `ℹ  ${label}  ${files.length} file(s), ${kb} KB always-loaded\n`;
 }
 
-// ---------------------------------------------------------------------------
-// Result cache
-// ---------------------------------------------------------------------------
-
 /**
- * Best-effort write of the doctor verdict to `temp/doctor-result.json` under
- * the consumer root so downstream workflows (e.g. the `/mandrel-plan` first-run
- * preflight) can read the last recorded verdict without re-running doctor.
- * `temp/` is the gitignored scratch root, so neither git nor the sync prune
- * pass ever sees the cache. Any write failure is swallowed — the cache is
- * advisory, never a gate.
- *
- * Exported for testing.
+ * Record the verdict in `temp/doctor-result.json` for workflows that read it
+ * without re-running doctor. Advisory: write failures are swallowed.
  *
  * @param {'ready'|'unready'} verdict
  * @param {{ fs?: typeof nodeFs, cwd?: () => string }} [opts]
@@ -146,17 +99,11 @@ export function writeDoctorResultCache(
       `${JSON.stringify({ verdict, checkedAt: new Date().toISOString() }, null, 2)}\n`,
     );
   } catch {
-    // Best-effort only — an unwritable temp/ must never fail the doctor run.
+    // An unwritable temp/ must never fail the doctor run.
   }
 }
 
-// ---------------------------------------------------------------------------
-// Doctor runner (exported for testing)
-// ---------------------------------------------------------------------------
-
 /**
- * Run all checks and emit a formatted report.
- *
  * @param {{
  *   checks?: Array<{ name: string, run(opts?: unknown): { ok: boolean, detail: string, remedy?: string } }>,
  *   write?: (s: string) => void,
@@ -181,8 +128,7 @@ export async function runDoctor({
     write(formatResult({ name: check.name, ...result }));
   }
 
-  // Report-only informational line — NOT counted toward passed/total, so it
-  // never affects the doctor verdict or exit code (Story #4438).
+  // Report-only: not counted toward passed/total.
   write(closureReport());
 
   const total = checks.length;
@@ -195,13 +141,7 @@ export async function runDoctor({
   }
 }
 
-// ---------------------------------------------------------------------------
-// Subcommand entry point (called by bin/mandrel.js)
-// ---------------------------------------------------------------------------
-
 /**
- * Default export consumed by `bin/mandrel.js`.
- *
  * @param {string[]} _argv  Unused — `mandrel doctor` takes no arguments.
  * @returns {Promise<void>}
  */

package/lib/cli/init.js

@@ -1,67 +1,14 @@
 // lib/cli/init.js
 /**
- * `mandrel init` subcommand — one-command cold start (Story #3975).
+ * `mandrel init`: cold start. When `./.agents/` is absent, run
+ * `npm install mandrel --ignore-scripts` then an explicit sync through the
+ * installed bin (one deterministic materialization, no lifecycle scripts);
+ * then ask whether to run `bootstrap.js` now (default yes). `--assume-yes`
+ * skips the prompt; a non-TTY without it stays files-only so GitHub
+ * provisioning never runs unattended.
  *
- * Folds the former `create-mandrel` launcher logic into a subcommand of the
- * single published `mandrel` package. `npx mandrel init` (≡ `npm exec --
- * mandrel init`, or `mandrel init` once installed) takes a project from a
- * blank folder to a configured Mandrel environment in one command:
- *
- *   1. **Install-if-absent.** When `./.agents/` is missing in the cwd, install
- *      the framework deterministically — `npm install mandrel --ignore-scripts`
- *      followed by an explicit sync run against the freshly installed bin
- *      (`node ./node_modules/mandrel/bin/mandrel.js sync`, NOT a bare `mandrel`
- *      on `PATH` — see `SYNC_BIN` below). The `--ignore-scripts` install
- *      skips the package's best-effort `postinstall` sync so the explicit
- *      `sync` is the single, deterministic materialization (review rec D.3 —
- *      no postinstall-then-init double-sync, and no arbitrary install
- *      lifecycle scripts during cold start). When `./.agents/` already exists
- *      (the operator ran `npm install mandrel` first), step 1 is skipped and
- *      `init` goes straight to the prompt — the one subcommand is idempotent
- *      across both the cold-start and post-install entry points.
- *
- *   2. **Yes/no prompt.** Ask whether to begin the interactive setup now
- *      (yes → run `node .agents/scripts/bootstrap.js`, forwarding every
- *      passthrough flag unchanged) or stop at "just the files" (no → print a
- *      re-run hint and exit 0). Yes is the default, so a bare Enter configures
- *      (mirrors the `[Y/n]` convention in bootstrap.js). `--assume-yes` skips
- *      the prompt and configures (the flag is also forwarded to bootstrap for
- *      its own non-interactive run). A non-TTY stdin without `--assume-yes`
- *      defaults to no (files-only) so the side-effecting GitHub provisioning
- *      never runs unattended.
- *
- * ## Cold-start provenance
- *
- * The installed package name is the **hardcoded build-time constant**
- * `PACKAGE_NAME` below — it is NEVER read from argv or the environment. A
- * cold start fetches `mandrel` from npx's temp cache and runs this bin; the
- * package it then installs into the project must be the same `mandrel`, not an
- * attacker-influenced name supplied on the command line. The forwarded
- * passthrough flags reach `bootstrap.js` (the sole bootstrap orchestrator),
- * which owns its own summary + confirm loop and validates its own inputs.
- *
- * ## Injectable seams (used by tests/cli/init.test.js)
- *
- * The plan/decision logic is a pure function (`planInit`) over injected
- * boundaries so the suite is hermetic — no real TTY, npm, or network:
- *
- *   - `argv`     — subcommand args (after `mandrel init`)
- *   - `exists`   — `(path) => boolean`; defaults to an `fs.existsSync` probe
- *                  for `./.agents/` in the cwd
- *   - `runStep`  — `(cmd, args) => { status }`; runs one install/sync/bootstrap
- *                  step. Defaults to a `spawnSync` runner with `stdio: inherit`.
- *   - `confirm`  — `() => boolean | Promise<boolean>`; reads the operator's
- *                  yes/no answer (true = configure now). Defaults to a
- *                  `node:readline` stdin prompt (awaited) with yes as the
- *                  default.
- *   - `stdout`   — `(s) => void`; defaults to `process.stdout.write`.
- *   - `isTTY`    — boolean; defaults to `process.stdin.isTTY`.
- *   - `exit`     — `(code) => void`; defaults to `process.exit`.
- *
- * Security (security-baseline § 5/6): logs only flag/step descriptions and
- * never reads or echoes tokens, credentials, or env values. The package name
- * is a hardcoded constant rather than interpolated input, and the step runner
- * passes argv as an array (no shell-string concatenation of user input).
+ * The installed package is the hardcoded `PACKAGE_NAME`, never argv or env,
+ * so a cold start cannot be steered to another package.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -70,10 +17,7 @@ import path from 'node:path';
 import readline from 'node:readline/promises';
 import { pathToFileURL } from 'node:url';
 
-// Lazily resolved at runtime so cold-start `npx mandrel init` (where
-// `.agents/` is absent) does not try to import from a directory that does not
-// exist yet. The import is performed after bootstrap succeeds and `.agents/`
-// is guaranteed to be materialised.
+// Lazy: `.agents/` does not exist until the cold start has materialized it.
 let _runInitTail = null;
 async function getRunInitTail(projectRoot) {
   if (_runInitTail) return _runInitTail;
@@ -85,39 +29,21 @@ async function getRunInitTail(projectRoot) {
     'onboard',
     'init-tail.js',
   );
-  // pathToFileURL handles Windows drive letters correctly (a raw
-  // `file://C:\…` template treats the drive letter as a URL host — same
-  // fix as commit 2e3d210b in lib/transpile.js).
+  // A raw `file://C:\…` template would read the drive letter as a URL host.
   const mod = await import(pathToFileURL(tailPath).href);
   _runInitTail = mod.runInitTail;
   return _runInitTail;
 }
 
-/**
- * Hardcoded build-time package name. NEVER read from argv or env — cold-start
- * provenance requires the install target to be the same package this bin
- * shipped from. See the module header.
- */
+/** Never read from argv or env (see the module header). */
 const PACKAGE_NAME = 'mandrel';
 
-// The `mandrel sync` and `node .agents/scripts/bootstrap.js` invocations both
-// resolve relative to the consumer's cwd at run time (the materialized
-// `.agents/` lives there), so they are expressed as cwd-relative steps rather
-// than against PROJECT_ROOT (which, under npx, is npx's throwaway cache).
+// Cwd-relative: under npx the package root is npx's throwaway cache.
 const BOOTSTRAP_SCRIPT = path.join('.agents', 'scripts', 'bootstrap.js');
 
-// The `sync` step is dispatched against the **locally installed** Mandrel bin
-// rather than a bare `mandrel` on `PATH`. A bare `spawnSync('mandrel', …)` only
-// resolves while npx keeps its throwaway `.bin` on `PATH`; reached any other
-// way (a documented `npm install mandrel` then `mandrel init`, or a plain
-// `node bin/mandrel.js init`), the freshly installed binary lives at
-// `./node_modules/mandrel/bin/mandrel.js` — off `PATH` — and a bare spawn dies
-// with ENOENT, leaving `.agents/` un-materialized. Spawning `process.execPath`
-// against the package entrypoint resolves identically under npx, under a
-// post-install invocation, and in tests — and, by going through `node`, also
-// sidesteps the win32 `.cmd`-shim concern entirely (no `shell: true` needed for
-// this step). The path is cwd-relative because the package is installed into
-// the consumer's cwd (the same reason BOOTSTRAP_SCRIPT is cwd-relative).
+// Spawned as `node <installed bin>`, not a bare `mandrel`: the bare name only
+// resolves while npx's `.bin` is on PATH (ENOENT after a plain `npm install`),
+// and going through node avoids the win32 `.cmd` shim.
 const SYNC_BIN = path.join('node_modules', PACKAGE_NAME, 'bin', 'mandrel.js');
 
 const PROMPT_TEXT =
@@ -128,12 +54,7 @@ const PROMPT_TEXT =
 
 const FILES_ONLY_HINT = 'Setup any time with: npx mandrel init\n';
 
-// ASCII banner printed once at the very top of `mandrel init`, before any
-// install/sync output streams to the terminal. Paste multi-line ASCII art
-// between the fences below. `String.raw` keeps backslashes literal so the art
-// renders exactly as pasted — the only characters to avoid inside are a
-// literal backtick and the `${` sequence. The leading/trailing blank lines
-// frame the art in the terminal.
+// `String.raw` keeps the art's backslashes literal; avoid backticks and `${`.
 const BANNER = String.raw`
 
    ______  ___             _________           ______
@@ -145,20 +66,11 @@ ____________________________________________________
 
 `;
 
-// On win32, `npm` resolves to a `.cmd` shim that Node refuses to spawn without
-// a shell after the CVE-2024-27980 hardening; mirror update.js and set
-// `shell: true` only there. Off win32, never shell out — array argv stays
-// injection-proof. (The `sync` step no longer hits a `.cmd` shim at all: it is
-// dispatched as `process.execPath` + `SYNC_BIN`, a plain `node` spawn — but the
-// `npm install` step still needs the shim handling, so `NEEDS_SHELL` stays.)
+// Win32 `npm` is a `.cmd` shim Node will not spawn without a shell
+// (CVE-2024-27980); shell nowhere else, so array argv stays injection-proof.
 const NEEDS_SHELL = process.platform === 'win32';
 
 /**
- * Strip the `--assume-yes` flag from a passthrough argv, returning the
- * remaining flags. `--assume-yes` is consumed by `init` to skip the prompt but
- * is ALSO forwarded to bootstrap (see `buildBootstrapArgs`), so this helper
- * exists only to detect its presence, not to drop it from the forward set.
- *
  * @param {string[]} argv
  * @returns {boolean} whether `--assume-yes` is present
  */
@@ -167,9 +79,7 @@ function hasAssumeYes(argv) {
 }
 
 /**
- * Build the forwarded argv for the bootstrap step. Every passthrough flag is
- * forwarded unchanged; `--assume-yes` is appended when chosen but absent so
- * bootstrap runs non-interactively without the operator having typed it.
+ * All flags forwarded unchanged, plus `--assume-yes` when chosen but absent.
  *
  * @param {string[]} argv
  * @param {boolean} assumeYes
@@ -183,13 +93,7 @@ function buildBootstrapArgs(argv, assumeYes) {
 }
 
 /**
- * Decide and execute the cold-start plan over injected boundaries.
- *
- * This is the testable core: it consults `exists` to decide whether to run the
- * install + sync steps, resolves the prompt outcome from `isTTY` / `--assume-yes`
- * / `confirm`, and either runs the bootstrap step or prints the files-only hint.
- * Every effectful boundary is injected so the suite never touches a real TTY,
- * npm, or the network.
+ * The cold-start plan over injected boundaries.
  *
  * @param {{
  *   argv?: string[],
@@ -219,10 +123,6 @@ export async function planInit({
   const steps = [];
 
   /**
-   * Run one step through the injected runner and record it. A non-zero status
-   * short-circuits the plan with that exit code (the runner inherits stdio, so
-   * the failing tool's own output already reached the terminal).
-   *
    * @param {string} cmd
    * @param {string[]} args
    * @returns {number} the step's exit code (0 on success)
@@ -233,10 +133,6 @@ export async function planInit({
     return result?.status ?? 1;
   };
 
-  // --- Step 1: install-if-absent ------------------------------------------
-  // When `./.agents/` is missing, materialize the framework deterministically:
-  // `npm install <pkg> --ignore-scripts` then explicit `mandrel sync`. When it
-  // is present, skip straight to the prompt (idempotent post-install path).
   const agentsPresent = exists('.agents');
   if (!agentsPresent) {
     const installStatus = step('npm', [
@@ -266,13 +162,8 @@ export async function planInit({
 
   const installed = !agentsPresent;
 
-  // --- Step 2: configure-or-files prompt ----------------------------------
   const assumeYes = hasAssumeYes(argv);
 
-  // Decide the outcome: configure (run bootstrap) vs. files-only.
-  // - `--assume-yes` → configure, prompt skipped entirely.
-  // - non-TTY without `--assume-yes` → files-only (never provision unattended).
-  // - TTY → consult the confirm seam for the yes/no answer (yes = configure).
   let proceed;
   if (assumeYes) {
     proceed = true;
@@ -298,11 +189,8 @@ export async function planInit({
       };
     }
 
-    // Bootstrap succeeded — run the onboarding tail: stack detection, docs
-    // scaffolding offer, doctor gate, and /mandrel-plan handoff. A tail that reports
-    // `ok: false` (the doctor gate failed) makes the whole init exit
-    // non-zero; the tail already printed its own remediation message, and the
-    // earlier install/sync/bootstrap phases' results stand as completed.
+    // A tail reporting `ok: false` (doctor gate failed) fails init; it has
+    // already printed its own remediation.
     if (afterBootstrap) {
       const tail = await afterBootstrap(process.cwd());
       if (tail && tail.ok === false) {
@@ -323,14 +211,11 @@ export async function planInit({
     };
   }
 
-  // Declined (files-only): print the re-run hint and exit cleanly.
   stdout(FILES_ONLY_HINT);
   return { installed, ranBootstrap: false, steps, exitCode: 0 };
 }
 
 /**
- * Default `exists` seam — probe for `./.agents/` in the consumer's cwd.
- *
  * @param {string} relPath
  * @returns {boolean}
  */
@@ -339,12 +224,6 @@ function defaultExists(relPath) {
 }
 
 /**
- * Default step runner — spawn the tool synchronously, inheriting stdio so its
- * output streams to the terminal. Sets `shell: true` only on win32 so the
- * `npm.cmd` shim resolves under CVE-2024-27980 hardening. The `sync` and
- * bootstrap steps spawn `process.execPath` (a plain `node`), which needs no
- * shell on any platform.
- *
  * @param {string} cmd
  * @param {string[]} args
  * @returns {{ status: number | null }}
@@ -358,23 +237,10 @@ function defaultRunStep(cmd, args) {
 }
 
 /**
- * Default `confirm` seam — yes/no prompt read via `node:readline` (mirrors the
- * prompt mechanism in `bootstrap.js`). Returns on Enter and never blocks
- * waiting for EOF the way `fs.readFileSync(0)` did — that EOF-blocking read hung
- * `mandrel init` on an interactive TTY. Any input other than an explicit "no"
- * (`n`/`no`, case-insensitive) — including bare Enter — resolves to `true`
- * (configure), matching the `[Y/n]` convention where yes is the default. The
- * prompt text is written by `planInit` via `stdout`, so the question string
- * passed here is empty.
- *
- * `terminal: false` is **load-bearing**, not cosmetic: with terminal mode on
- * (the default when stdout is a TTY) readline emits cursor-control escapes
- * (`\x1b[1G\x1b[0J` — column-1 + erase-to-end-of-screen) when it takes over the
- * line, which **erases the `[Y/n]:` prompt already written via `stdout`** — the
- * operator then sees only the first prompt line and a dead-looking cursor.
- * Disabling terminal mode leaves the pre-written prompt intact and reads the
- * line via the TTY's own cooked-mode echo. `createInterface` is injectable so a
- * test can assert this option is set (regression guard).
+ * Anything but `n`/`no` (including bare Enter) means yes. Reads a line rather
+ * than waiting for EOF, which would hang on a TTY. `terminal: false` is
+ * load-bearing: terminal mode emits erase-line escapes that wipe the
+ * `[Y/n]:` prompt `planInit` already wrote.
  *
  * @param {{ createInterface?: typeof readline.createInterface }} [opts]
  * @returns {Promise<boolean>}
@@ -391,7 +257,6 @@ export async function defaultConfirm({
     const answer = (await rl.question('')).trim().toLowerCase();
     return answer !== 'n' && answer !== 'no';
   } catch {
-    // No readable line (e.g. stdin closed) → default to yes (configure).
     return true;
   } finally {
     rl.close();
@@ -399,8 +264,6 @@ export async function defaultConfirm({
 }
 
 /**
- * Default export consumed by `bin/mandrel.js`.
- *
  * @param {string[]} [argv] - Subcommand arguments (after `mandrel init`).
  * @returns {Promise<void>}
  */
@@ -417,8 +280,6 @@ export default async function run(argv = []) {
     return;
   }
 
-  // Banner is the very first output — before the install + sync steps that
-  // planInit kicks off — so it greets the operator on a cold start.
   process.stdout.write(BANNER);
 
   const result = await planInit({

package/lib/cli/migrate.js

@@ -1,54 +1,8 @@
 // lib/cli/migrate.js
 /**
- * `mandrel migrate` subcommand — the standalone migration runner entry
- * (f-migration-runner, Story #3505, Epic #3437 — Auto-Update & Version
- * Lifecycle).
- *
- * Exposes the version-keyed migration runner from `lib/migrations/index.js` as
- * a standalone command so operators can apply (or preview) on-disk migrations
- * without going through a full `mandrel update` cycle or a package bump. This
- * is the manual escape hatch for re-running a migration that a prior upgrade
- * missed, or for inspecting what a version crossing would do before committing
- * to it.
- *
- * ## CLI surface
- *
- *   mandrel migrate --from <v> --to <v> [--dry-run]
- *
- *   --from <v>   Version the tree is currently on (exclusive lower bound).
- *   --to   <v>   Version the tree is upgrading to (inclusive upper bound).
- *   --dry-run    Report the steps that WOULD run and write nothing.
- *
- * Both `--from` and `--to` are required for a live run; a missing bound is a
- * usage error (non-zero exit). `--from`/`--to` accept either `--from 1.4.0` or
- * `--from=1.4.0` spellings.
- *
- * ## `--dry-run`
- *
- * Resolves the in-range steps from the registry, consults each step's
- * `detect(ctx)` against a throwaway context to decide whether it would apply
- * or be skipped, prints the plan, and returns WITHOUT calling any step's
- * `apply` — nothing on disk changes. The dry-run never mutates the shared
- * context the caller would use for a live run; it probes a fresh `{}` so
- * `detect` side effects (there should be none) cannot leak into a later live
- * pass.
- *
- * ## Injectable seams (used by lib/cli/__tests__/migrate.test.js)
- *
- *   - `argv`           — subcommand args (after `mandrel migrate`)
- *   - `runMigrations`  — version-keyed migration runner (lib/migrations)
- *   - `registry`       — step registry; defaults to the module `migrations`
- *                        array, injected by tests with fixture steps so the
- *                        dry-run plan and the live pass are both exercisable
- *                        without a real contract step existing
- *   - `ctx`            — opaque context threaded to each step's detect/apply
- *   - `write`/`writeErr` — stdout / stderr sinks
- *   - `exit`           — process.exit replacement
- *
- * Security (security-baseline § 5 — Data Leakage & Logging): logs only version
- * strings and step descriptions. No tokens, credentials, or env values are
- * read or logged, and no shell-string interpolation occurs (the runner is a
- * pure in-process call; transport is owned by the steps themselves).
+ * `mandrel migrate --from <v> --to <v> [--dry-run]`: run (or preview) the
+ * version-keyed migrations outside an `update` cycle, e.g. to re-run one a
+ * prior upgrade missed. Both bounds are required.
  */
 
 import {
@@ -58,8 +12,6 @@ import {
 } from '../migrations/index.js';
 
 /**
- * Parse a single `--flag value` / `--flag=value` option out of argv.
- *
  * @param {string[]} argv
  * @param {string} flag  The long flag name including leading dashes (e.g. `--from`).
  * @returns {string | undefined} The option value, or undefined when absent.
@@ -78,9 +30,6 @@ function parseOption(argv, flag) {
 }
 
 /**
- * The envelope shape every `runMigrate` exit returns. Centralised so the four
- * exits cannot drift in which fields they populate.
- *
  * @param {object} fields
  * @returns {object}
  */
@@ -115,10 +64,8 @@ function reportUsageError({ writeErr, exit }) {
 }
 
 /**
- * Report the in-range steps and whether each WOULD apply or be skipped,
- * probing a throwaway context so no step's `apply` runs and nothing on disk
- * changes. The ordering comes from `selectStepsInRange`, the same selector the
- * live run uses, so the preview cannot disagree with what would happen.
+ * Probes `detect` against a throwaway context and never calls `apply`. Uses
+ * the live run's selector, so the preview cannot disagree with it.
  *
  * @param {{
  *   registry: Array<object>,
@@ -172,8 +119,6 @@ function reportApplied({ applied, fromVersion, toVersion, write }) {
 }
 
 /**
- * Run the standalone `mandrel migrate` command.
- *
  * @param {{
  *   argv?: string[],
  *   runMigrations?: typeof defaultRunMigrations,
@@ -235,8 +180,6 @@ export function runMigrate({
     });
   }
 
-  // The runner owns ordering, range filtering, idempotency, and the per-step
-  // `migrated …` log line.
   const { applied, skipped } = runMigrations({
     fromVersion,
     toVersion,
@@ -256,8 +199,6 @@ export function runMigrate({
 }
 
 /**
- * Default export consumed by `bin/mandrel.js`.
- *
  * @param {string[]} argv - Subcommand arguments (after `mandrel migrate`).
  * @returns {Promise<void>}
  */