mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/bootstrap/commit-push.js

@@ -1,26 +1,8 @@
 /**
- * bootstrap/commit-push — end-of-bootstrap "commit + push the wiring" offer
- * (Story #3899, Finding A.6).
- *
- * After a successful bootstrap the consumer's working tree carries the
- * framework wiring (`.agents/` tree, `.agentrc.json`, `CLAUDE.md`,
- * `.claude/settings.json`, `.gitignore`, `package.json`, `.husky/`). Nothing
- * told the operator to commit and push it — yet Story delivery runs in git
- * worktrees that check out **tracked files only**, so an uncommitted
- * `.agents/` means no scripts exist inside any worktree and every Story
- * sub-agent breaks. This module offers that commit + push at the end of the
- * run, and prints the exact manual commands when the offer is declined or the
- * run is non-interactive.
- *
- * Security: the stage step uses an explicit **allowlist** of bootstrap-written
- * paths (`git add -- <path>`), never `git add -A`, and explicitly refuses to
- * stage known secret files (`.env`, `.mcp.json`, `.agentrc.local.json`). This
- * keeps the commit safe regardless of whether the secret-safe `.gitignore`
- * Story (#3894) has landed — secrets are never staged even when un-ignored.
- *
- * Every git-touching helper takes an injectable `runGit` seam so the logic is
- * unit-testable without spawning a real `git`. The seam contract mirrors
- * `bootstrap.js#runGit`: `({ ok, status, stdout, stderr })`.
+ * End-of-bootstrap offer to commit and push the wiring: worktrees check out
+ * tracked files only, so an uncommitted `.agents/` breaks every Story. Stages
+ * an explicit allowlist (never `git add -A`) and refuses secret files even
+ * when they are not gitignored.
  *
  * @module bootstrap/commit-push
  */
@@ -29,11 +11,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 /**
- * The bootstrap-written, version-controllable paths the commit offer stages.
- * Project-root-relative POSIX paths. Mirrors the file targets the bootstrap
- * pipeline writes (see `manifest.js` + `project-bootstrap.js`) plus the
- * materialized `.agents/` tree and `.husky/` quality hook. `.claude/commands/`
- * is intentionally absent — it is generated and gitignored.
+ * Mirrors what the bootstrap writes; `.claude/commands/` is generated and
+ * gitignored, so it is absent.
  *
  * @type {readonly string[]}
  */
@@ -49,10 +28,7 @@ export const BOOTSTRAP_COMMIT_PATHS = Object.freeze([
 ]);
 
 /**
- * Paths that MUST NEVER be staged by the commit offer, even when they are not
- * (yet) gitignored. These carry secrets or per-operator local overrides. This
- * is the defense-in-depth that lets the offer run safely before the
- * secret-safe `.gitignore` Story (#3894) lands.
+ * Secrets and per-operator overrides: never staged, even when not gitignored.
  *
  * @type {ReadonlySet<string>}
  */
@@ -67,21 +43,14 @@ export const NEVER_STAGE_PATHS = Object.freeze(
 );
 
 /**
- * The conventional commit subject the offer uses for the wiring commit.
- *
  * @type {string}
  */
 export const COMMIT_SUBJECT = 'chore: wire up Mandrel agent framework';
 
 /**
- * Resolve the subset of {@link BOOTSTRAP_COMMIT_PATHS} that actually exist on
- * disk and are not in {@link NEVER_STAGE_PATHS}. Pure (filesystem read only):
- * the secret-exclusion is applied here so a never-stage path is dropped before
- * it ever reaches `git add`.
- *
  * @param {string} projectRoot
  * @param {typeof fs} [fsImpl]
- * @returns {string[]} project-root-relative paths safe to stage
+ * @returns {string[]} existing, secret-free paths safe to stage
  */
 export function resolveStagePaths(projectRoot, fsImpl = fs) {
   return BOOTSTRAP_COMMIT_PATHS.filter((rel) => {
@@ -91,16 +60,13 @@ export function resolveStagePaths(projectRoot, fsImpl = fs) {
 }
 
 /**
- * Build the exact manual commands the operator should run to commit and push
- * the wiring themselves. Printed when the offer is declined or the run is
- * non-interactive (`--assume-yes`). The `git add` line stages the resolved
- * allowlist only — never `git add -A` — so copy-pasting it cannot stage a
- * secret file.
+ * Manual commands for a declined or non-interactive offer; the `git add` line
+ * names the allowlist so copy-pasting it cannot stage a secret.
  *
  * @param {object} args
- * @param {string[]} args.stagePaths — resolved, secret-free paths to stage.
+ * @param {string[]} args.stagePaths
  * @param {string} args.baseBranch
- * @returns {string} a multi-line, copy-pasteable command block
+ * @returns {string}
  */
 export function buildManualInstructions({ stagePaths, baseBranch }) {
   const addArgs = stagePaths.length > 0 ? stagePaths.join(' ') : '.';
@@ -118,10 +84,6 @@ export function buildManualInstructions({ stagePaths, baseBranch }) {
 }
 
 /**
- * Stage the resolved allowlist via `git add -- <paths>`. No-op (returns
- * `{ ok: true, staged: [] }`) when nothing resolves. Returns the git result on
- * failure so the caller can surface it.
- *
  * @param {object} args
  * @param {string} args.projectRoot
  * @param {(args: string[], cwd: string) => { ok: boolean, status?: number,

package/.agents/scripts/lib/bootstrap/gh-preflight.js

@@ -1,13 +1,4 @@
-/**
- * bootstrap/gh-preflight — `gh` CLI + runtime-dependency preflight
- *
- * Provider-agnostic preflight helpers extracted from
- * `agents-bootstrap-github.js` (Story #3349). Holds the version-comparison
- * arithmetic (`parseGhVersion` / `compareSemver`), the `gh` CLI probe
- * (`preflightGh`), and the runtime-dependency probe (`preflightRuntimeDeps`).
- * Keeping these free of any provider coupling lets the bootstrap orchestrator
- * stay focused on sequencing.
- */
+/** Provider-agnostic `gh` CLI and runtime-dependency preflight. */
 
 import { spawnSync } from 'node:child_process';
 import {
@@ -17,12 +8,7 @@ import {
   MissingRuntimeDepsError,
 } from '../errors/index.js';
 
-/**
- * Minimum `gh` version the bootstrap supports. Set conservatively per
- * Tech Spec #1350 ("Risks & Mitigations → `gh` version skew"): older
- * releases miss flags the eventual `gh-exec` shim relies on. Bumping this
- * is a deliberate, operator-visible change — keep it tracked here.
- */
+/** Older releases miss flags the `gh` shim relies on; bumping is operator-visible. */
 export const MIN_GH_VERSION = '2.40.0';
 
 const GH_INSTALL_HINT =
@@ -34,34 +20,20 @@ const GH_PROJECT_SCOPE_NOTE =
 const GH_SCOPES_UNREADABLE_NOTE =
   'token scopes not reported by `gh auth status` (fine-grained PAT?) — skipping the classic project-scope assertion. If Projects V2 provisioning later fails, grant the Projects permission (fine-grained) or run `gh auth refresh -s project` (classic).';
 
-/**
- * Framework runtime deps the consumer must have installed in
- * `node_modules/` before this script reaches the dynamic
- * `config-resolver` import. `ajv` is the sentinel — if it cannot
- * resolve, the framework runtime dependencies are not installed.
- */
+/** `ajv` is the sentinel for installed framework runtime deps. */
 const REQUIRED_RUNTIME_DEPS = Object.freeze(['ajv']);
 
 const RUNTIME_DEPS_HINT =
   'Run `mandrel init` (for a fresh project) or `npm install mandrel` (for an existing one) to install the framework runtime dependencies, then re-run this command.';
 
 /**
- * Default runner: synchronously execs `gh <args>` and returns
- * `{ status, stdout, stderr, error }`. Extracted so the preflight tests
- * can inject a stub without spawning a real child process. Forerunner of
- * the `lib/gh-exec.js` shim described in Tech Spec #1350; once that
- * lands, this helper deletes and the preflight calls `gh.exec(...)`.
+ * Raw `spawnSync`, not the `gh-exec` facade: these probes decide whether the
+ * facade (which assumes an authenticated `gh`) is usable at all.
  *
  * @param {string[]} args
  * @returns {{ status: number|null, stdout: string, stderr: string,
  *             error?: NodeJS.ErrnoException }}
  */
-// Story #2990: this preflight runner intentionally stays on raw
-// `spawnSync('gh', …)` (not the `lib/gh-exec.js` facade) because it
-// runs *before* auth is resolved — `gh --version` and `gh auth status`
-// are the very probes that decide whether the facade can be used at
-// all. Routing through the provider layer would create a circular
-// dependency: the facade assumes a working, authenticated `gh`.
 function defaultGhRunner(args) {
   const result = spawnSync('gh', args, { encoding: 'utf8' });
   return {
@@ -73,10 +45,6 @@ function defaultGhRunner(args) {
 }
 
 /**
- * Parse the first `MAJOR.MINOR.PATCH` triple out of `gh --version` stdout.
- * Returns `null` when the shape is unrecognized so callers can decide
- * whether to surface an error or proceed.
- *
  * @param {string} stdout
  * @returns {string|null}
  */
@@ -86,9 +54,7 @@ export function parseGhVersion(stdout) {
 }
 
 /**
- * Numeric comparison of two `MAJOR.MINOR.PATCH` strings.
- * Returns negative if `a < b`, positive if `a > b`, zero if equal.
- * Missing segments are treated as `0`. Non-numeric segments compare as 0.
+ * Missing or non-numeric segments compare as 0.
  *
  * @param {string} a
  * @param {string} b
@@ -109,23 +75,7 @@ export function compareSemver(a, b) {
 }
 
 /**
- * Preflight the `gh` CLI before any provider call. Three failure modes,
- * each surfaced as a typed error so callers (CLI `main`, future
- * orchestrators, tests) can `instanceof`-match without parsing strings:
- *
- *   - {@link GhNotInstalledError} — `gh` not on PATH (ENOENT) or the
- *     `--version` invocation reported a non-zero exit suggesting the
- *     binary is missing/broken.
- *   - {@link GhVersionError} — `gh` is present but older than
- *     {@link MIN_GH_VERSION}; carries `{ found, required }` for the
- *     CLI to render an upgrade hint.
- *   - {@link GhAuthError} — `gh auth status` exited non-zero, meaning
- *     no host is logged in.
- *
- * On success returns `{ version }` so the caller can log the resolved
- * version. The `runner` seam defaults to a real `spawnSync('gh', …)`;
- * tests inject a stub returning the canonical
- * `{ status, stdout, stderr, error }` shape.
+ * Throws a typed `GhNotInstalledError`, `GhVersionError` or `GhAuthError`.
  *
  * @param {{ runner?: (args: string[]) => {
  *   status: number|null, stdout: string, stderr: string,
@@ -142,9 +92,7 @@ export async function preflightGh(opts = {}) {
 }
 
 /**
- * Resolve the installed `gh` version via `gh --version`, throwing
- * {@link GhNotInstalledError} for every "not installed correctly" shape
- * (ENOENT, non-zero exit, unparseable output).
+ * Every "not installed correctly" shape throws {@link GhNotInstalledError}.
  *
  * @param {(args: string[]) => object} runner
  * @returns {string}
@@ -157,8 +105,6 @@ function resolveGhVersion(runner) {
     );
   }
   if (versionResult.status !== 0) {
-    // Non-ENOENT failure of `gh --version` is treated as "not installed
-    // correctly" — same remediation, same exit semantics.
     const stderrSnippet = (versionResult.stderr || '').trim().slice(0, 200);
     throw new GhNotInstalledError(
       `gh --version failed (exit ${versionResult.status}): ${stderrSnippet}. ${GH_INSTALL_HINT}`,
@@ -174,9 +120,6 @@ function resolveGhVersion(runner) {
 }
 
 /**
- * Enforce the {@link MIN_GH_VERSION} floor, throwing {@link GhVersionError}
- * with `{ found, required }` when the installed version is older.
- *
  * @param {string} version
  */
 function assertGhVersionFloor(version) {
@@ -189,16 +132,12 @@ function assertGhVersionFloor(version) {
 }
 
 /**
- * Assert `gh auth status` reports a logged-in host, throwing
- * {@link GhAuthError} (or {@link GhNotInstalledError} on a PATH race).
- *
  * @param {(args: string[]) => object} runner
  */
 function assertGhAuth(runner) {
   const authResult = runner(['auth', 'status']);
   if (authResult.error?.code === 'ENOENT') {
-    // Defensive — `gh --version` already passed, so ENOENT here would be a
-    // PATH race. Treat the same as not-installed.
+    // PATH race after `--version` passed.
     throw new GhNotInstalledError(
       `gh CLI disappeared between version and auth check. ${GH_INSTALL_HINT}`,
     );
@@ -211,23 +150,9 @@ function assertGhAuth(runner) {
 }
 
 /**
- * Check that the authenticated `gh` token carries the `project` scope, which
- * the bootstrap needs to read and modify GitHub Projects V2. Parses the
- * `Token scopes:` line from `gh auth status` (some gh versions print it to
- * stderr, others to stdout — we scan both) and looks for a `project` scope.
- *
- * Returns a check record `{ name, ok, remedy?, detail? }` rather than
- * throwing, so the preflight aggregator can surface it alongside the other
- * checks. An unreadable scopes line — the normal case for fine-grained PATs
- * and for `gh` builds that omit it — PASSES with a warning `detail` (Story
- * #3690). A present-but-`project`-less scopes line — the normal case for a
- * vanilla `gh auth login` token — also PASSES with a warning `detail`
- * (Story #3893, Finding A.5): the bootstrap's runtime `resolveProject`
- * already degrades to warn-and-skip-board for exactly this condition, so
- * failing the preflight closed was stricter than the code it guards and
- * created a guaranteed first-run → browser → re-run loop. The check never
- * fails the gate on the project scope; the warning `detail` carries the
- * `gh auth refresh -s project` remediation for operators who want boards.
+ * Check the token's `project` scope (the `Token scopes:` line may be on
+ * stdout or stderr). Never fails: an unreadable or `project`-less line passes
+ * with a warning `detail`, matching `resolveProject`'s skip-the-board path.
  *
  * @param {{ runner?: (args: string[]) => {
  *   status: number|null, stdout: string, stderr: string,
@@ -244,9 +169,6 @@ export async function checkProjectScopes(opts = {}) {
 }
 
 /**
- * Map a (possibly absent) `Token scopes:` match onto the check record.
- * Pure — exported only through {@link checkProjectScopes}.
- *
  * @param {RegExpExecArray|null} scopeLine
  * @returns {{ name: string, ok: boolean, remedy?: string, detail?: string }}
  */
@@ -269,17 +191,8 @@ function classifyProjectScopes(scopeLine) {
 }
 
 /**
- * Preflight the framework's runtime dependencies before dynamic-importing
- * `config-resolver.js` (which transitively pulls in `ajv` via
- * `config-settings-schema.js`). A consumer who has not installed the
- * framework runtime deps will not have `ajv` available, and the raw
- * `ERR_MODULE_NOT_FOUND` from the dynamic import is opaque. This
- * preflight converts that into a {@link MissingRuntimeDepsError} that
- * names the missing packages and points the operator at the correct
- * remediation (`mandrel init` / `npm install mandrel`).
- *
- * The `resolver` seam lets tests inject a stub without touching the real
- * module graph; production uses `import.meta.resolve(specifier)`.
+ * Turn the opaque `ERR_MODULE_NOT_FOUND` of the later `config-resolver`
+ * import into a {@link MissingRuntimeDepsError} naming the remedy.
  *
  * @param {{ resolver?: (specifier: string) => string | Promise<string> }} [opts]
  * @returns {Promise<void>}

package/.agents/scripts/lib/bootstrap/hitl-confirm.js

@@ -1,26 +1,8 @@
 /**
- * bootstrap/hitl-confirm — Epic #1235 Story 5; consent-first opt-in (#3526)
- *
- * Renders a structured diff to stdout and prompts the operator y/N when
- * stdout is a TTY. When not a TTY (CI, sub-agent, redirected pipe), the
- * gate returns `false` and logs the canonical abort message to stderr —
- * silent-apply is a non-feature. The `opts.assume` override lets tests
- * and automation pin the answer deterministically:
- *
- *   - `opts.assume === 'yes'` → returns true, skips the prompt entirely.
- *   - `opts.assume === 'no'`  → returns false, skips the prompt.
- *
- * The default render is intentionally simple: a single-line summary
- * followed by a JSON dump of `{ current, proposed }`. Callers that want
- * a richer view (per-field colour, contextual unified diff) can wrap
- * `confirm` and render their own preamble before calling.
- *
- * Consent-first install (Story #3526): the GitHub-admin phase group — the
- * irreversible remote mutations (labels, Projects V2, branch protection,
- * merge methods) — is gated by an explicit opt-in, not merely a TTY. A
- * non-TTY run that has not opted in records every group as declined, so the
- * abort hint names BOTH the dedicated `--approve-github-admin` flag (consent
- * to just the remote mutations) and `--assume-yes` (accept every group).
+ * y/N confirm of a `{ current, proposed }` diff. Without a TTY it returns
+ * `false` and logs the abort hint — never a silent apply. `opts.assume` pins
+ * the answer. Irreversible GitHub-admin mutations need an explicit opt-in,
+ * so the hint names both `--approve-github-admin` and `--assume-yes`.
  */
 
 import { createInterface } from 'node:readline';
@@ -39,9 +21,7 @@ const ABORT_MESSAGE =
  *   stdout?: NodeJS.WritableStream,
  *   stderr?: NodeJS.WritableStream,
  *   isTTY?: boolean,
- * }} [opts] - Overrides for tests / automation. `isTTY` defaults to
- *   `process.stdout.isTTY`. `stdin`/`stdout`/`stderr` default to the
- *   respective `process.*` streams.
+ * }} [opts]
  * @returns {Promise<boolean>} - true ⇒ apply, false ⇒ abort.
  */
 export async function confirm({ summary, current, proposed }, opts = {}) {
@@ -58,9 +38,6 @@ export async function confirm({ summary, current, proposed }, opts = {}) {
     return false;
   }
 
-  // Render the diff. Single-line summary, then a JSON block so the
-  // operator can pipe the prompt to a logger and still recover the
-  // structured shape.
   stdout.write(`\nHITL confirm: ${summary}\n`);
   stdout.write(
     `  current:  ${JSON.stringify(current ?? null, null, 2)
@@ -84,6 +61,4 @@ export async function confirm({ summary, current, proposed }, opts = {}) {
   }
 }
 
-// Re-export the abort message so tests can assert against the single
-// source of truth.
 export { ABORT_MESSAGE };

package/.agents/scripts/lib/bootstrap/install-ledger.js

@@ -1,21 +1,7 @@
 /**
- * bootstrap/install-ledger — durable record of what an install applied, for
- * a future `mandrel uninstall` to consume (Story #3524, Feature #3515,
- * Epic #3438).
- *
- * A successful bootstrap run writes a ledger to
- * `<projectRoot>/.agents/.install-manifest.json` enumerating exactly the
- * mutation-manifest entries that were APPROVED and applied (the approved
- * subset of `buildMutationManifest`, never the full manifest). The ledger is
- * the single artifact `mandrel uninstall` will later read to know which
- * reversible mutations to undo and which irreversible (GitHub-admin) ones to
- * surface for manual rollback.
- *
- * The ledger is gitignored (`.agents/.install-manifest.json` is added to the
- * consumer `.gitignore` by the bootstrap) because it is a per-clone install
- * record, not a checked-in source artifact.
- *
- * This module performs filesystem writes but no network I/O.
+ * Per-clone (gitignored) record of the manifest entries an install actually
+ * applied — never the full manifest — which `mandrel uninstall` reads to undo
+ * reversible mutations and surface irreversible ones.
  *
  * @module bootstrap/install-ledger
  */
@@ -24,39 +10,24 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 /**
- * Path of the install ledger, relative to the project root. The bootstrap's
- * `.gitignore` step keys its ignore entry off this exact POSIX path.
+ * The `.gitignore` step keys off this exact POSIX path.
  *
  * @type {string}
  */
 export const LEDGER_RELATIVE_PATH = '.agents/.install-manifest.json';
 
 /**
- * Current ledger schema version. A future `mandrel uninstall` reads this to
- * detect a ledger it cannot interpret (hard-cutover contract — no read-side
- * tolerance branch, just a clean refusal).
- *
- * v2 (Story #3895): each entry now carries `executedAction` — the *live*
- * outcome of the bootstrap phase that produced it (e.g. `seeded` vs
- * `already-present` for `.agentrc.json`). Uninstall keys destructive reversal
- * off this so a pre-existing, operator-authored file the install merely left
- * in place (`already-present`) is never deleted.
+ * Uninstall refuses a version it cannot interpret. Entries carry
+ * `executedAction` so an operator-authored file the install left in place
+ * (`already-present`) is never deleted.
  *
  * @type {number}
  */
 export const LEDGER_SCHEMA_VERSION = 2;
 
 /**
- * Map a mutation-manifest `target` (POSIX-relative path) to the bootstrap
- * **phase name** whose execution outcome describes that target. Only targets
- * whose reversal is destructive enough to need the live outcome are mapped;
- * everything else is reversed content-aware and needs no execution hint.
- *
- * The `.agentrc.json` `create` entry is produced by the `agentrc` phase
- * (`ensureAgentrc`), which returns `{ action: 'seeded' }` when it wrote the
- * file from the starter and `{ action: 'already-present' }` when an
- * operator-authored file was left untouched. Recording that distinction lets
- * uninstall skip deleting a file the install did not create (Story #3895).
+ * Target → the phase whose live outcome governs its reversal; only targets
+ * whose reversal is destructive are mapped.
  *
  * @type {Readonly<Record<string, string>>}
  */
@@ -65,16 +36,8 @@ const TARGET_TO_PHASE = Object.freeze({
 });
 
 /**
- * Resolve the live executed action for a manifest entry from the bootstrap
- * report, when one is available. Pure — derives entirely from the entry +
- * report. Returns `undefined` when the target has no mapped phase, the report
- * is absent, or the phase produced no `action` (so older callers/tests that
- * omit the report degrade to "no hint" rather than throwing).
- *
- * The `.agentrc.json` quality-gates `merge` entry shares the same target as
- * the repo-config `create` entry but is keyed by phase, not target — both
- * manifest entries resolve to the same `agentrc` outcome, which is correct:
- * reversal dedupes them to a single `revertAgentrc` call anyway.
+ * `undefined` means no hint. Both `.agentrc.json` entries resolve to the same
+ * `agentrc` outcome, which is correct: reversal dedupes them.
  *
  * @param {{ target: string }} entry
  * @param {Record<string, { action?: string }>} [report]
@@ -89,8 +52,6 @@ function resolveExecutedAction(entry, report) {
 }
 
 /**
- * Resolve the absolute ledger path for a project root.
- *
  * @param {string} projectRoot
  * @returns {string}
  */
@@ -99,24 +60,14 @@ export function ledgerPath(projectRoot) {
 }
 
 /**
- * Build the ledger record from the approved manifest entries. Pure helper —
- * no I/O — so the shape is unit-testable in isolation. The `appliedAt`
- * timestamp is injectable for deterministic tests.
- *
  * @param {object} args
  * @param {import('./manifest.js').MutationManifestEntry[]} args.entries
- *   — the subset of the mutation manifest that was applied.
- * @param {string[]} args.approvedGroups — the phase groups whose mutations
- *   landed (sorted for stable output). Field name predates Story #5007's
- *   removal of the phased-approval gate; the ledger record shape is a
- *   consumer contract read back by `mandrel uninstall`, so it is unchanged.
+ *   — the applied subset.
+ * @param {string[]} args.approvedGroups — groups that landed. The name is a
+ *   consumer contract read by `mandrel uninstall`; do not rename.
  * @param {{ owner?: string, repo?: string }} [args.answers]
- * @param {string} [args.appliedAt] — ISO-8601 timestamp (default: now).
- * @param {Record<string, { action?: string }>} [args.report] — the live
- *   bootstrap execution report (phase name → outcome). When present, each
- *   entry whose target maps to a phase records that phase's `action` as
- *   `executedAction` so uninstall can distinguish `seeded` from
- *   `already-present` (Story #3895).
+ * @param {string} [args.appliedAt] — ISO-8601 (default: now).
+ * @param {Record<string, { action?: string }>} [args.report] — phase → outcome.
  * @returns {{ schemaVersion: number, appliedAt: string,
  *   repo: string|null, approvedGroups: string[],
  *   entries: Array<import('./manifest.js').MutationManifestEntry
@@ -145,10 +96,7 @@ export function buildLedgerRecord(args) {
 }
 
 /**
- * Write the install ledger to `<projectRoot>/.agents/.install-manifest.json`,
- * creating the `.agents/` directory if needed. The file is overwritten on
- * each successful install so the ledger always reflects the most recent run
- * (a re-install with a different approval set replaces, never appends).
+ * Overwrites: the ledger always reflects the most recent install.
  *
  * @param {string} projectRoot
  * @param {ReturnType<typeof buildLedgerRecord>} record
@@ -162,10 +110,6 @@ export function writeInstallLedger(projectRoot, record) {
 }
 
 /**
- * Read and parse the install ledger. Returns `null` when no ledger exists
- * (never installed, or the ledger was removed). A future `mandrel uninstall`
- * is the primary consumer.
- *
  * @param {string} projectRoot
  * @returns {ReturnType<typeof buildLedgerRecord>|null}
  */