mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/bootstrap/project-bootstrap.js

@@ -1,14 +1,7 @@
 /**
- * bootstrap/project-bootstrap — deterministic project bootstrap steps.
- *
- * Each exported `ensure*` function is one step of the bootstrap. Every step
- * is idempotent and additive — re-running on an already-bootstrapped clone
- * produces zero file mutations and zero network I/O.
- *
- * Injectable seams: every function that performs filesystem I/O or spawns a
- * child process accepts an optional `fsImpl` / `spawnImpl` default-param so
- * unit tests can stub I/O without touching the real filesystem. The seam
- * contract is defined in `.agents/rules/test-seams.md`.
+ * Deterministic project bootstrap steps. Every step is idempotent and
+ * additive: a re-run on a bootstrapped clone mutates nothing and does no
+ * network I/O.
  */
 
 import { spawnSync as defaultSpawnSync } from 'node:child_process';
@@ -25,36 +18,19 @@ import { applyQualityBootstrap } from './quality-bootstrap.js';
 
 export const SYNC_COMMAND = 'node .agents/scripts/sync-claude-commands.js';
 
-// Epic #4478 (M7-B). The role-scoped agent projection runs in every place the
-// command projection does — `sync:agents` script, `prepare`, and the bootstrap
-// `sync` phase (`runSyncCommands`) — so `.claude/agents/*.md` materializes for
-// hosts that read it, exactly as `.claude/commands/*.md` does.
+// The agent projection runs everywhere the command projection does.
 export const SYNC_AGENTS_COMMAND = 'node .agents/scripts/sync-claude-agents.js';
 
 export const BOOTSTRAP_COMMAND = 'node .agents/scripts/bootstrap.js';
 
-/**
- * Marker that identifies the framework's system-prompt import inside a
- * consumer `CLAUDE.md`. The wiring step keys idempotence off this exact
- * import path so a re-run never duplicates the import line.
- */
+/** `CLAUDE.md` wiring keys idempotence off this exact import path. */
 export const SYSTEM_PROMPT_IMPORT = '@.agents/instructions.md';
 
-/**
- * Import block appended to an existing `CLAUDE.md` that lacks the import.
- * Mirrors the root `CLAUDE.md` shape (a `## System Prompt` heading above
- * the import) so the consumer file reads the same as this repo's own.
- */
 export const SYSTEM_PROMPT_BLOCK = `## System Prompt
 
 ${SYSTEM_PROMPT_IMPORT}
 `;
 
-/**
- * Full `CLAUDE.md` body written when the consumer has no `CLAUDE.md` at
- * all. A bare title plus the import block is enough for Claude Code to
- * hydrate the framework system prompt on cold start.
- */
 export const SYSTEM_PROMPT_CLAUDE_MD = `# Agent Protocols
 
 ${SYSTEM_PROMPT_BLOCK}`;
@@ -70,21 +46,12 @@ export const GITIGNORE_BLOCKS = Object.freeze({
     block:
       '\n# Project-scoped MCP config carries secrets — keep out of git.\n.mcp.json\n',
   },
-  // Story #3894: `.env` holds real secrets (`mandrel init` instructs operators
-  // to put `GITHUB_TOKEN` here). It MUST be ignored by default so a cold-start
-  // provision never stages/pushes it. The pattern matches a bare `.env` (with
-  // an optional trailing slash) but deliberately NOT `.env.example`, the
-  // committed placeholder that `security-baseline.md` § Secrets Management
-  // exempts.
+  // Matches bare `.env` but NOT the committed `.env.example` placeholder.
   env: {
     pattern: /^\s*\.env\/?\s*$/m,
     block:
       '\n# Secrets live in .env (e.g. GITHUB_TOKEN) — never commit it. Only .env.example (placeholders) is checked in.\n.env\n',
   },
-  // Story #3894: the install ledger is a per-clone install record, not a
-  // checked-in source artifact. `install-ledger.js` documents that the
-  // bootstrap `.gitignore` step ignores it — key the entry off the exact
-  // `LEDGER_RELATIVE_PATH` constant so the doc and code never drift again.
   installLedger: {
     pattern: new RegExp(
       `^\\s*${LEDGER_RELATIVE_PATH.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`,
@@ -95,9 +62,6 @@ export const GITIGNORE_BLOCKS = Object.freeze({
 });
 
 /**
- * Read a JSON file if it exists; return null when missing. Accepts an
- * injectable `fsImpl` so callers can stub filesystem access in tests.
- *
  * @param {string} p
  * @param {typeof fs} [fsImpl]
  * @returns {object|null}
@@ -108,10 +72,6 @@ function readJsonIfExists(p, fsImpl = fs) {
 }
 
 /**
- * Write a pretty-printed JSON file, creating parent directories as needed.
- * Accepts an injectable `fsImpl` so callers can stub filesystem access in
- * tests.
- *
  * @param {string} p
  * @param {object} obj
  * @param {typeof fs} [fsImpl]
@@ -122,28 +82,13 @@ function writeJson(p, obj, fsImpl = fs) {
 }
 
 /**
- * The minimum Node.js patch version mandrel requires.
- *
- * Rationale: `22.22.1` is the Node 22 LTS patch that ships with the
- * `node:sqlite` built-in (`--experimental-sqlite` removed from flag
- * requirement in 22.5.0, but the module stabilised at 22.22.1 per the
- * Node 22 LTS changelog). Pinning to this patch prevents silent failures on
- * older 22.x installs that lack the built-in. CI exercises `node-version: 22`
- * which resolves to the latest 22.x (always ≥ 22.22.1 in the current GHA
- * environment), so CI validates the contract without exercising the exact
- * patch floor — the floor is enforced at install time, not in CI.
- *
- * Single source of truth: `registry.js` and any other consumer MUST import
- * this constant rather than duplicating it.
- *
- * Matches `package.json` `engines.node` (`>=22.22.1 <25`).
+ * Node floor SSOT (`node:sqlite` stabilised at 22.22.1); import it, never
+ * duplicate. Matches `package.json` `engines.node` (`>=22.22.1 <25`).
  */
 export const REQUIRED_NODE_FLOOR = '22.22.1';
 export const REQUIRED_NODE_CEILING_MAJOR = 25;
 
 /**
- * Return true when `version` satisfies `>=22.22.1 <25` (same as `engines`).
- *
  * @param {string} version
  * @returns {boolean}
  */
@@ -161,10 +106,6 @@ export function satisfiesNodeEngine(version) {
 }
 
 /**
- * Step 1 — Verify Node satisfies `engines.node`. Returns `{ ok, version,
- * required }` so the CLI can report the detected version regardless of
- * whether the check passed.
- *
  * @param {string} [version=process.versions.node]
  */
 export function checkNodeVersion(version = process.versions.node) {
@@ -176,12 +117,7 @@ export function checkNodeVersion(version = process.versions.node) {
 }
 
 /**
- * Detect the package manager based on lockfile presence. Defaults to
- * `npm` when no lock is found (including the `null` case from the shared
- * helper where no Node manifest exists at all).
- *
- * Delegates to the shared `detectPackageManager` helper
- * (Story #4048 B3 — one implementation per concept).
+ * Lockfile-based; defaults to `npm`.
  *
  * @param {string} projectRoot
  * @param {typeof fs} [fsImpl]
@@ -192,12 +128,8 @@ export function detectPackageManager(projectRoot, fsImpl = fs) {
 }
 
 /**
- * Step 2a/2b/2c — Ensure `package.json` exists and carries the
- * `sync:commands` + `prepare` + `bootstrap` scripts. The consumer manifest
- * is never mutated with framework runtime dependencies: those arrive
- * transitively via the `mandrel` package, so bootstrap leaves the
- * `dependencies` block untouched (Story #3466). Returns the per-key outcome
- * the caller can render.
+ * Ensure `package.json` carries the sync/prepare/bootstrap scripts. Never
+ * touches `dependencies` — framework deps arrive transitively via `mandrel`.
  *
  * @param {object} ctx
  * @param {typeof fs} [ctx.fsImpl]
@@ -237,9 +169,7 @@ export function ensurePackageJson(ctx) {
     pkg.scripts.prepare = `${SYNC_COMMAND} && ${SYNC_AGENTS_COMMAND}`;
     outcomes.scriptsPrepare = 'added';
   } else {
-    // Append each projection independently so an existing prepare that already
-    // carries the command sync still gains the agent sync on the next bootstrap
-    // (and both are idempotent — a prepare carrying both is left untouched).
+    // Append each projection independently so a partial prepare gains the other.
     let next = prepare;
     if (!next.includes('sync-claude-commands.js')) {
       next = `${next} && ${SYNC_COMMAND}`;
@@ -252,9 +182,7 @@ export function ensurePackageJson(ctx) {
       outcomes.scriptsPrepare = 'appended';
     }
   }
-  // Expose a discoverable `npm run bootstrap` alias for the framework
-  // setup command. An operator-defined `bootstrap` script always wins —
-  // we only seed the default when the key is absent.
+  // An operator-defined `bootstrap` script always wins.
   if (!pkg.scripts.bootstrap) {
     pkg.scripts.bootstrap = BOOTSTRAP_COMMAND;
     outcomes.scriptsBootstrap = 'added';
@@ -270,11 +198,7 @@ export function ensurePackageJson(ctx) {
 }
 
 /**
- * Step 2d — Install dependencies when the framework's sentinel module is
- * unresolvable. Bootstrap no longer seeds framework deps into the consumer
- * manifest (Story #3466) — they arrive transitively via `mandrel`
- * — so the install is triggered purely by an empty/stale `node_modules`.
- * Returns `{ ran, manager, skipped, reason }`.
+ * Install dependencies when the sentinel module (`ajv`) is unresolvable.
  *
  * @param {object} ctx
  * @param {typeof fs} [ctx.fsImpl]
@@ -310,15 +234,8 @@ export function ensureDependenciesInstalled(ctx) {
 }
 
 /**
- * Step 2.5a — Seed `.agentrc.json` when missing.
- *
- * Seeds from the bundled `starter-agentrc.json` reference, applying the
- * operator-identity placeholder substitution (`[OWNER]` / `[REPO]` /
- * `[USERNAME]`) and the `baseBranch` override. (Story #3690 removed the
- * named config-profile seeding path — the starter reference is the single
- * seed source.)
- *
- * An existing `.agentrc.json` is never overwritten — operator wins.
+ * Seed a missing `.agentrc.json` from `starter-agentrc.json` with identity
+ * placeholders filled. Never overwrites an existing file.
  *
  * @param {object} ctx
  * @param {typeof fs} [ctx.fsImpl]
@@ -342,9 +259,7 @@ export function ensureAgentrc(ctx) {
     .replace(/\[OWNER\]/g, ctx.answers.owner)
     .replace(/\[REPO\]/g, ctx.answers.repo)
     .replace(/\[USERNAME\]/g, ctx.answers.operatorHandle ?? ctx.answers.owner);
-  // The starter pins baseBranch to "main"; if the operator chose a
-  // different default, update the seeded copy so the per-clone config
-  // matches the live remote HEAD.
+  // The starter pins baseBranch to "main".
   if (ctx.answers.baseBranch && ctx.answers.baseBranch !== 'main') {
     body = body.replace(
       /"baseBranch":\s*"main"/,
@@ -356,8 +271,7 @@ export function ensureAgentrc(ctx) {
 }
 
 /**
- * Step 2.5b — Validate `.agentrc.json` against the framework's AJV schema.
- * Returns `{ ok, errors }`. Caller decides whether to abort.
+ * Validate `.agentrc.json` against the AJV schema; the caller decides whether to abort.
  *
  * @param {object} ctx
  * @param {typeof fs} [ctx.fsImpl]
@@ -373,8 +287,7 @@ export async function validateAgentrc(ctx) {
   if (!fsImpl.existsSync(schemaModule)) {
     return { ok: false, errors: ['config-settings-schema.js not found'] };
   }
-  // pathToFileURL handles Windows drive letters and percent-encoding
-  // correctly (same fix as commit 2e3d210b in lib/transpile.js).
+  // pathToFileURL handles Windows drive letters and percent-encoding.
   const mod = await import(pathToFileURL(schemaModule).href);
   const validate = mod.getAgentrcValidator();
   const data = readJsonIfExists(
@@ -386,24 +299,8 @@ export async function validateAgentrc(ctx) {
   return { ok: !!ok, errors: ok ? [] : (validate.errors ?? []) };
 }
 
-// Story #4527/#4530: the UserPromptSubmit sync-hook wiring
-// (ensureClaudeSettings, formerly Step 3) was removed. It spawned
-// `mandrel sync-commands` on every prompt to keep `.claude/commands/` in
-// sync with `.agents/workflows/` — a rewrite racing the harness's own read
-// of that same directory while expanding a slash command, and a directory
-// that cannot change mid-session in the first place, so the hook reported
-// `0 file(s) synced` on effectively every invocation. The real sync points
-// already cover every case: `prepare` on install, `mandrel sync` /
-// `mandrel update` on upgrade, and doctor's `commands-in-sync` check for
-// hand-edits. `lib/cli/uninstall.js#revertClaudeSettings` still removes the
-// hook from a consumer who already has it installed from a prior version.
-
 /**
- * Step 4 + Step 8 — Ensure `.gitignore` carries every {@link GITIGNORE_BLOCKS}
- * entry (`.claude/commands/`, `.mcp.json`, `.env`, and the per-clone install
- * ledger). Each block is marker-keyed off a presence pattern, so a re-run is a
- * zero-mutation no-op and never appends a duplicate block. Returns a per-block
- * outcome (`added` | `already-present`).
+ * Append each missing {@link GITIGNORE_BLOCKS} entry, keyed off its presence pattern.
  *
  * @param {object} ctx
  * @param {typeof fs} [ctx.fsImpl]
@@ -431,17 +328,7 @@ export function ensureGitignore(ctx) {
 }
 
 /**
- * Materialize the generated GitHub Issue Forms
- * (`.github/ISSUE_TEMPLATE/story.yml`) into the consumer
- * project (Story #4227). Derived from the Story-body SSOT so a human-filed
- * ticket round-trips through `story-body.parse()`. Idempotent and additive,
- * mirroring `ensureGitignore`: byte-identical forms are `unchanged`,
- * operator-edited forms are preserved (`custom-skip`).
- *
- * Returns the per-form action envelope keyed by ticket type.
- *
- * Internal — consumed only by the `issueForms` entry in
- * {@link BOOTSTRAP_PHASES} below.
+ * Materialize the generated Issue Forms; returns per-form actions keyed by ticket type.
  *
  * @param {object} ctx
  * @param {string} ctx.projectRoot
@@ -456,11 +343,7 @@ function ensureIssueFormsPhase(ctx) {
 }
 
 /**
- * Step 5 — Run the sync script. Step 6 (parity) is enforced by the
- * sync script itself (it removes stale entries and writes from the
- * single source of truth), so a successful exit equals parity.
- *
- * Returns `{ ok, stdout }`.
+ * Run the command and agent projections; the sync itself enforces parity.
  *
  * @param {object} ctx
  * @param {typeof defaultSpawnSync} [ctx.spawnImpl]
@@ -471,9 +354,6 @@ export function runSyncCommands(ctx) {
     ctx.agentRoot ?? path.join(ctx.projectRoot, '.agents'),
     'scripts',
   );
-  // Both projections run here (Epic #4478, M7-B): the command tree AND the
-  // role-scoped agent tree, so `mandrel sync` / the postinstall path
-  // materializes `.claude/agents/*.md` alongside `.claude/commands/*.md`.
   const projections = [
     { label: 'sync-claude-commands.js', script: 'sync-claude-commands.js' },
     { label: 'sync-claude-agents.js', script: 'sync-claude-agents.js' },
@@ -503,19 +383,8 @@ export function runSyncCommands(ctx) {
 }
 
 /**
- * Step 6 — Parity check between `.agents/workflows/*.md` and the generated
- * flat command tree `.claude/commands/*.md`. Step 5's sync already enforces
- * this; this is a belt-and-braces verification that the command projection
- * covers every top-level workflow.
- *
- * A workflow whose frontmatter carries `command: false` is deliberately NOT
- * projected to a command — `sync-claude-commands.js` skips it via the same
- * `isCommandExcluded` predicate used here. Such a workflow must therefore be
- * excluded from the expected-command set, or this check would demand a
- * command the sync is contracted never to emit (e.g. the `audit-lighthouse` /
- * `audit-security` lenses, which are run by the audit suite, not as slash
- * commands). Keeping the two surfaces on one predicate is what stops them
- * drifting.
+ * Verify `.claude/commands/*.md` matches the projectable workflows. Shares
+ * `isCommandExcluded` with the sync so `command: false` workflows never drift.
  *
  * @param {object} ctx
  * @param {typeof fs} [ctx.fsImpl]
@@ -535,9 +404,6 @@ export function checkParity(ctx) {
           .map((e) => e.name.replace(/\.md$/, ''))
           .sort()
       : [];
-  // Expected commands = projectable workflows only. A `command: false`
-  // workflow is contracted out of the command tree, so it is not "missing" a
-  // command — it declined one.
   const projectable = (name) =>
     !isCommandExcluded(
       fsImpl.readFileSync(path.join(workflowsDir, `${name}.md`), 'utf8'),
@@ -554,22 +420,8 @@ export function checkParity(ctx) {
 }
 
 /**
- * Step 8.5 — Wire the framework system prompt into a consumer `CLAUDE.md`.
- *
- * Claude Code hydrates its always-loaded context from a project-root
- * `CLAUDE.md`; without the `@.agents/instructions.md` import the framework
- * system prompt never loads on cold start. This step makes that wiring
- * automatic and idempotent:
- *
- *   - No `CLAUDE.md` at all → write a minimal one carrying the import.
- *   - `CLAUDE.md` exists but lacks the import → append the import block.
- *   - `CLAUDE.md` already imports it → no-op (no duplicate import line).
- *
- * Idempotence is keyed off the literal `SYSTEM_PROMPT_IMPORT` path, so a
- * re-run on an already-wired file is a guaranteed zero-mutation no-op.
- *
- * Returns `{ action, path }` where `action` is one of `created`,
- * `appended`, or `already-present`.
+ * Ensure `CLAUDE.md` imports the system prompt — without it the framework
+ * never loads on cold start. Creates, appends, or no-ops.
  *
  * @param {object} ctx
  * @param {typeof fs} [ctx.fsImpl]
@@ -595,9 +447,7 @@ export function ensureSystemPromptWiring(ctx) {
 }
 
 /**
- * Step 9 — Windows git-perf hints (warn-only). On non-Windows this is a
- * silent no-op. On Windows the check probes three settings and reports
- * which are missing; it never mutates global git config.
+ * Windows git-perf hints, warn-only; never mutates global git config.
  *
  * @param {object} ctx
  * @param {typeof fs} [ctx.fsImpl]
@@ -628,34 +478,13 @@ export function checkWindowsGitPerf(ctx) {
   };
 }
 
-// ---------------------------------------------------------------------------
-// BOOTSTRAP_PHASES (Story #2459 / Task #2473)
-//
-// The previous `applyProjectBootstrap` was an 11-step inline pipeline with
-// three fatal-abort branches (`nodeCheck`, `validation`, `parity`). Each
-// phase is now a declarative `{ name, run, isFatal?, formatError? }`
-// entry. The single-pass driver `runPhases` reads the array, calls each
-// `run(ctx, report)`, accumulates the result onto `report[phase.name]`,
-// and routes fatal phases through `throwIfFatal` so the abort message
-// remains operator-visible.
-//
-// `applyProjectBootstrap` collapses to two lines: instantiate an empty
-// report, hand it to `runPhases`, return it.
-// ---------------------------------------------------------------------------
-
 /**
  * @typedef {object} BootstrapPhase
- * @property {string} name       — key used to land the result on the report.
+ * @property {string} name       — report key.
  * @property {(ctx: object, report: object) => any|Promise<any>} run
- *                                 — executes the phase. May read prior
- *                                   phases via `report.<name>`.
- * @property {boolean} [isFatal]  — when `true`, the driver passes the
- *                                   result through `formatError`; if the
- *                                   formatter returns a non-empty string,
- *                                   the driver throws with that message.
+ *                                 — may read prior phases via `report.<name>`.
+ * @property {boolean} [isFatal]  — throw when `formatError` returns a message.
  * @property {(result: any) => string|null} [formatError]
- *                                 — produces the error message when the
- *                                   phase result indicates a fatal abort.
  */
 
 const fatalNodeCheck = (result) =>
@@ -680,17 +509,8 @@ const fatalParity = (result) =>
       }; orphan commands: ${result.orphanCommand.join(', ') || '(none)'}`;
 
 /**
- * Pipeline definition — the order, the helpers, and the fatal-abort
- * branches. Exported so tests can assert phase ordering, the fatal flag,
- * and the report-shape parity guarantee without driving the whole
- * bootstrap.
- *
- * Each project-side mutation phase carries a `phaseGroup` matching one of
- * the {@link PHASE_GROUPS}. Since Story #5007 that string is pure
- * ledger/uninstall metadata — every phase runs on every install, and the
- * ledger decides after the fact which groups actually landed. Phases with no
- * `phaseGroup` (the Node-version precondition and the dependency install)
- * are always-run infrastructure.
+ * Ordered bootstrap pipeline. `phaseGroup` is ledger/uninstall metadata only
+ * — every phase runs on every install.
  */
 export const BOOTSTRAP_PHASES = Object.freeze([
   {
@@ -765,12 +585,6 @@ export const BOOTSTRAP_PHASES = Object.freeze([
 ]);
 
 /**
- * Throw with the formatted message when the phase is marked fatal and
- * the result indicates an abort. Pure helper so the driver stays a
- * single-branch loop.
- *
- * Exported for tests.
- *
  * @param {BootstrapPhase} phase
  * @param {any} result
  */
@@ -781,13 +595,6 @@ export function throwIfFatal(phase, result) {
 }
 
 /**
- * Iterate `phases` in order; await each phase's `run(ctx, report)`, land
- * the result on `report[phase.name]`, then route fatal phases through
- * `throwIfFatal`. Returns the accumulated report.
- *
- * Exported for tests so phase ordering and fatal behaviour can be
- * asserted without spawning a full bootstrap.
- *
  * @param {ReadonlyArray<BootstrapPhase>} phases
  * @param {object} ctx
  * @returns {Promise<object>}
@@ -803,14 +610,6 @@ export async function runPhases(phases, ctx) {
 }
 
 /**
- * Compose every step in order. Each returned key is the outcome of one
- * step so the CLI can render a structured summary.
- *
- * Story #5007 removed the no-write `ctx.preview` branch: it had zero
- * production callers (bootstrap's own `--dry-run` renders a hand-rolled text
- * plan instead) and it survived only to serve the consent-first install
- * screen Story #3690 replaced with a plain summary+confirm loop.
- *
  * @param {object} ctx
  * @param {string} ctx.projectRoot
  * @param {string} [ctx.agentRoot]
@@ -820,8 +619,8 @@ export async function runPhases(phases, ctx) {
  * @param {boolean} [ctx.skipGithub]
  * @param {boolean} [ctx.skipInstall]
  * @param {boolean} [ctx.quiet]
- * @param {typeof fs} [ctx.fsImpl]       — injectable filesystem seam (test-seams.md).
- * @param {typeof defaultSpawnSync} [ctx.spawnImpl] — injectable spawn seam (test-seams.md).
+ * @param {typeof fs} [ctx.fsImpl]
+ * @param {typeof defaultSpawnSync} [ctx.spawnImpl]
  * @returns {Promise<object>}
  */
 export async function applyProjectBootstrap(ctx) {