mandrel 2.60.0 → 2.62.0

package/.agents/scripts/bootstrap.js

@@ -1,55 +1,8 @@
 #!/usr/bin/env node
 /**
- * bootstrap.js — single-command consumer setup for Mandrel.
- *
- * The sole bootstrap orchestrator (Story #3690 collapsed the temporary
- * bootstrap-new.js fork into this file). Key behaviours:
- *   - No config profiles — `.agentrc.json` always seeds from the bundled
- *     `.agents/starter-agentrc.json` starter reference.
- *   - Runs even when the directory is NOT a git repo yet (preflight detects
- *     git state instead of failing on it).
- *   - Adds a Projects V2 permission check to preflight (warns rather than
- *     failing when classic token scopes cannot be read, e.g. fine-grained
- *     PATs).
- *   - Uses a plain summary + confirm loop (interactive runs can go back and
- *     re-answer) instead of a phased-approval manifest.
- *   - Provisions the missing pieces of a cold start: initializes the local
- *     git repo (with a first commit) when absent, creates the GitHub repo
- *     (linking + pushing the local tree), and creates the Projects V2 board
- *     from a typed name — capturing its number for the rest of the run.
- *
- * Usage:
- *   node .agents/scripts/bootstrap.js [flags]
- *
- * Flags:
- *   --owner <name>            GitHub owner (default: parsed from origin remote)
- *   --repo <name>             GitHub repo  (default: parsed from origin remote)
- *   --visibility <v>          Visibility for a newly created repo:
- *                             private | public | internal (default: private)
- *   --operator-handle <name>  GitHub handle for github.operatorHandle
- *   --base-branch <name>      Base branch (default: origin/HEAD or 'main')
- *   --project-number <n>      Projects V2 number/name (optional)
- *   --assume-yes              Accept every default + approve GitHub-admin
- *                             mutations. A non-TTY run requires this (or
- *                             --approve-github-admin) — there is no operator
- *                             to confirm the summary.
- *   --approve-github-admin    Consent to the irreversible GitHub-admin phase
- *                             (labels, Projects V2, branch protection, merge
- *                             methods) without accepting every other default.
- *   --skip-github             Skip the GitHub-side bootstrap entirely
- *   --with-quality            Opt-in: install local quality gates (pre-commit
- *                             hook + quality:preview/watch scripts). Off by
- *                             default — prompted y/N.
- *   --dry-run                 Collect info and print the plan; change nothing
- *   --with-project-board      Opt-in: provision the Projects V2 Status field
- *                             and custom fields. Off by default — the project
- *                             board object is still created when a project
- *                             name is supplied, but decoration is skipped.
- *   --with-issue-forms        Opt-in: generate .github/ISSUE_TEMPLATE/story.yml.
- *                             Off by default.
- *   --reap-conflicting-workflows  Delete Projects V2 built-in workflows that
- *                             race against the orchestrator (destructive)
- *   --help                    Print this help
+ * bootstrap.js — single-command consumer setup for Mandrel (flags: see HELP).
+ * Works on a folder that is not yet a git repo, and provisions the missing
+ * pieces of a cold start: local repo, GitHub repo, Projects V2 board.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -58,7 +11,6 @@ import path from 'node:path';
 import readline from 'node:readline/promises';
 import { fileURLToPath } from 'node:url';
 
-// Reused bootstrap library helpers (unchanged).
 import {
   buildManualInstructions,
   COMMIT_SUBJECT,
@@ -118,27 +70,14 @@ Flags:
   --help                    Print this help
 `;
 
-// ---------------------------------------------------------------------------
-// Small helpers
-// ---------------------------------------------------------------------------
-
-/** Strip an `owner/` prefix off a repo slug, leaving the bare repo name. */
 function bareRepoName(slug) {
   const slash = slug.indexOf('/');
   return slash === -1 ? slug : slug.slice(slash + 1);
 }
 
 /**
- * Normalize an operator handle to the bare login the starter template expects.
- *
- * The starter `.agentrc.json` carries `"operatorHandle": "@[USERNAME]"` and the
- * seed step substitutes `[USERNAME]` with this answer — so the answer MUST be
- * the bare handle (no leading `@`), or the seeded value becomes `@@foo`. The
- * interactive validator already rejects a leading `@`, but the
- * `--operator-handle @x` flag and `GH_OPERATOR_HANDLE=@x` env paths skip that
- * validator (Story #3700). Stripping a single leading `@` here closes that gap
- * for every resolution path. Idempotent: a bare handle is returned unchanged,
- * so a re-run never re-strips or re-accumulates.
+ * Strip one leading `@`: the starter template's `@[USERNAME]` would otherwise
+ * seed `@@foo`, and the flag/env paths bypass the interactive validator.
  *
  * @param {string|undefined|null} handle
  * @returns {string|undefined|null} the input with a single leading `@` removed
@@ -148,7 +87,6 @@ export function normalizeHandleAnswer(handle) {
   return handle.replace(/^@/, '');
 }
 
-/** Run a list-producing fn, returning [] on any throw. */
 function safeList(fn) {
   try {
     return fn() ?? [];
@@ -171,11 +109,7 @@ export function resolveOwnerForPicker(defaults, flags, env = process.env) {
   return null;
 }
 
-/**
- * Ask a yes/no question. `defaultAnswer` controls the default when the
- * operator presses Enter without typing (true = Y/n, false = y/N). In
- * non-interactive mode the default is returned immediately.
- */
+/** Yes/no prompt; non-interactive returns `defaultAnswer`. */
 async function confirmYesNo(message, interactive, defaultAnswer = true) {
   if (!interactive) return defaultAnswer;
   const rl = readline.createInterface({
@@ -194,12 +128,7 @@ async function confirmYesNo(message, interactive, defaultAnswer = true) {
   }
 }
 
-/**
- * Run a git command in `cwd`. Returns the normalized
- * `{ ok, status, stdout, stderr, error }` shape (mirroring the bootstrap
- * preflight/gh-list runners) so callers branch on `ok` without juggling
- * spawnSync internals.
- */
+/** Run git in `cwd` → `{ ok, status, stdout, stderr, error }`. */
 function runGit(args, cwd) {
   const result = spawnSync('git', args, { cwd, encoding: 'utf8' });
   return {
@@ -211,11 +140,7 @@ function runGit(args, cwd) {
   };
 }
 
-/**
- * Surface a `gh`/exec failure with the same detail the GitHub bootstrap
- * step prints — message plus the real gh stderr/stdout/args carried on a
- * `GhExecError` — so a bare "gh exited with code 1" is actually diagnosable.
- */
+/** Log a `GhExecError` with its gh stderr/stdout/args so it is diagnosable. */
 function logGhError(label, err) {
   Logger.error(`[Bootstrap] ${label} failed: ${err.message}`);
   if (err.stderr)
@@ -228,11 +153,8 @@ function logGhError(label, err) {
 }
 
 /**
- * Per-command git identity args. The first commit fails when neither a repo-
- * nor global-level `user.name`/`user.email` is configured, which is common on
- * a freshly provisioned machine. When either is missing we supply a
- * non-persistent identity via `-c` (derived from the operator handle) so the
- * commit succeeds without mutating the operator's git config.
+ * A non-persistent `-c` identity when `user.name`/`user.email` is unset (fresh
+ * machine), so the commit succeeds without mutating the operator's config.
  */
 function gitIdentityArgs(cwd, answers) {
   const haveName = runGit(['config', 'user.name'], cwd).ok;
@@ -248,19 +170,15 @@ function gitIdentityArgs(cwd, answers) {
 }
 
 /**
- * Initialize the local git repo when one is not already present, and ensure
- * at least one commit exists so `gh repo create --source=. --push` has
- * something to push. Idempotent: a repo that already resolves `HEAD` is left
- * untouched. Returns `{ ok, initialized, committed }` (or `{ ok:false, error }`
- * on failure).
+ * Idempotently init the repo and ensure a commit exists for
+ * `gh repo create --push`.
  */
 function ensureGitInitialized(state) {
   const cwd = state.projectRoot;
   const branch = state.answers.baseBranch || 'main';
   let initialized = false;
   if (!state.gitInitialized) {
-    // `git init -b <branch>` (git ≥ 2.28) sets the initial branch directly;
-    // fall back to a plain init + symbolic-ref for older git.
+    // `init -b` needs git ≥ 2.28; fall back to init + symbolic-ref.
     let init = runGit(['init', '-b', branch], cwd);
     if (!init.ok) {
       init = runGit(['init'], cwd);
@@ -275,18 +193,8 @@ function ensureGitInitialized(state) {
     );
   }
 
-  // A push needs a commit; create one only when HEAD does not resolve yet.
-  //
-  // SECURITY (Story #3894): do NOT `git add -A` here. `.gitignore` seeding
-  // (`ensureGitignore`) runs two phases later in the pipeline, so at this
-  // point a cold-start folder may still contain secret-bearing files
-  // (`.env`, `.mcp.json`). Staging the whole tree before any gitignore
-  // exists — followed immediately by `gh repo create --push` — would push
-  // those secrets to a brand-new (often public) remote with no per-file
-  // consent, violating `security-baseline.md` § Secrets Management. The
-  // push only needs a commit to *exist*, so we create an empty one; the
-  // operator's own first content commit lands after the gitignore phase has
-  // already excluded the secret-bearing paths.
+  // SECURITY: the commit is EMPTY, never `git add -A` — `.gitignore` is seeded
+  // later, so staging now would push `.env` / `.mcp.json` to the new remote.
   let committed = false;
   if (!runGit(['rev-parse', '--verify', 'HEAD'], cwd).ok) {
     const commit = runGit(
@@ -309,14 +217,9 @@ function ensureGitInitialized(state) {
 }
 
 /**
- * Wire the local `origin` remote to owner/repo when it is missing, so the
- * GitHub bootstrap — which infers the target repo from the local remote —
- * can run. This is the companion to `createGithubRepo`: that path wires
- * `origin` itself via `--remote origin`, but a repo that already exists (or
- * a re-run after a partial failure) leaves the local folder unlinked. Only
- * acts when the repo actually exists on GitHub; pushes the base branch to
- * set upstream, downgrading a rejected push to a warning since the bootstrap
- * only needs the remote to resolve (content sync is the operator's to settle).
+ * Wire a missing `origin` to an existing GitHub repo (the GitHub bootstrap
+ * infers its target from it). A rejected push only warns: the remote just
+ * needs to resolve.
  */
 async function ensureGitRemote(state, execImpl = exec) {
   const cwd = state.projectRoot;
@@ -345,12 +248,8 @@ async function ensureGitRemote(state, execImpl = exec) {
 }
 
 /**
- * Authoritatively check whether `owner/repo` exists, via `gh repo view`.
- * Returns false on a not-found (so the repo can be created), true when it
- * resolves, and true on any other error (auth/network/etc.) so a transient
- * failure never triggers a spurious create attempt. Used instead of an
- * `is it in the repo-list?` heuristic, which mis-fires for a brand-new
- * account whose `gh repo list` is empty.
+ * `gh repo view` probe: false only on not-found, so a transient error never
+ * triggers a spurious create. (A repo-list check mis-fires on empty accounts.)
  */
 async function repoExists(owner, repo, execImpl = exec) {
   try {
@@ -364,14 +263,7 @@ async function repoExists(owner, repo, execImpl = exec) {
   }
 }
 
-/**
- * Link the repo to the Projects V2 board (`gh project link`) so issues and
- * PRs from the repo surface on the project. Runs whenever both a numeric
- * project number and a repo are resolved — a freshly created project or an
- * existing one picked from the list. Non-fatal and re-run-safe: an
- * already-linked repo or a transient hiccup is downgraded to a warning so it
- * never fails the bootstrap.
- */
+/** `gh project link` the repo to the board; non-fatal and re-run-safe. */
 async function ensureProjectLinked(state, execImpl = exec) {
   const { owner, repo } = state.answers;
   const pn = String(state.answers.projectNumber ?? '');
@@ -397,11 +289,7 @@ export const REPO_VISIBILITIES = Object.freeze([
   'internal',
 ]);
 
-/**
- * Resolve the new-repo visibility from `--visibility` (default `private`).
- * Case-insensitive. Returns `null` for an unrecognized value so the caller
- * can reject it with a clear message instead of silently defaulting.
- */
+/** `--visibility` (default `private`); `null` for an unknown value. */
 export function resolveRepoVisibility(flags = {}) {
   const raw = flags.visibility;
   if (typeof raw !== 'string' || raw.length === 0) return 'private';
@@ -409,14 +297,7 @@ export function resolveRepoVisibility(flags = {}) {
   return REPO_VISIBILITIES.includes(value) ? value : null;
 }
 
-/**
- * Create the GitHub repo from the resolved owner/repo. `--source` links the
- * existing local repo, `--remote origin` wires the remote, and `--push`
- * uploads the current branch — so the local tree and the new remote stay in
- * lockstep and Step 1's auto-detection works on a re-run. Visibility comes
- * from `--visibility` (default private). Throws GhExecError on failure
- * (surfaced by the caller).
- */
+/** Create, link as `origin`, and push the repo. Throws GhExecError. */
 async function createGithubRepo(state, execImpl = exec) {
   const { owner, repo } = state.answers;
   const slug = `${owner}/${repo}`;
@@ -440,13 +321,8 @@ async function createGithubRepo(state, execImpl = exec) {
 }
 
 /**
- * Find an existing Projects V2 board owned by `owner` whose title matches
- * `title` exactly (case-insensitive, trimmed), returning its numeric id or
- * `null` when none matches. Lists through the injected `execImpl` seam (the
- * same `gh project list --owner X --format json` shape `gh-list` parses) so
- * the dedupe is unit-testable without spawning a real `gh`. Any non-zero
- * exit, spawn error, or unparseable payload degrades to `null` (no match) so
- * a transient list failure never blocks creation.
+ * The number of the owner's board titled `title` (case-insensitive), or
+ * `null` — including on any list failure, which must not block creation.
  *
  * @param {string} owner
  * @param {string} title
@@ -486,14 +362,8 @@ async function findExistingProjectNumber(owner, title, execImpl) {
 }
 
 /**
- * Resolve the typed Projects V2 name into a numeric id and rewrite
- * `state.answers.projectNumber` so the downstream persist + GitHub bootstrap
- * steps treat it as an existing project (and never create a duplicate). Before
- * creating, it **dedupes against the owner's existing project titles**: if a
- * board with the same title already exists, that board is adopted instead of
- * running `gh project create` — so a re-run that re-types the same name never
- * spawns a second same-titled board (Story #3896 / review Finding B.3). Throws
- * on create failure or when gh returns no number.
+ * Resolve the typed board name to a number (adopting a same-titled board so a
+ * re-run never duplicates it) and write it onto `answers.projectNumber`.
  */
 async function createGithubProject(state, execImpl = exec) {
   const { owner } = state.answers;
@@ -506,8 +376,7 @@ async function createGithubProject(state, execImpl = exec) {
     );
     return existing;
   }
-  // `gh project create` uses `--format json` (not `--json`), so exec returns
-  // the raw `{ stdout }` envelope — parse the number ourselves.
+  // `--format json` (not `--json`): exec returns raw stdout to parse.
   const res = await execImpl({
     args: [
       'project',
@@ -536,32 +405,16 @@ async function createGithubProject(state, execImpl = exec) {
   return number;
 }
 
-// ---------------------------------------------------------------------------
-// Question list (Step 3).
-// ---------------------------------------------------------------------------
-
-/**
- * Build the Step 3 question list. `silentAccept` keys (owner/repo/baseBranch/
- * operatorHandle) are git-inferred and accepted without prompting unless an
- * override is supplied. The `operatorHandle` and `projectNumber` defaults
- * track the repo owner / repo name respectively (see post-processing in
- * `collectAndConfirm`).
- */
+/** The Step 3 question list. */
 export function buildQuestions(defaults, flags, env = process.env, lists = {}) {
   const owner = resolveOwnerForPicker(defaults, flags, env);
-  // Pre-fetched lists (shared with the summary display) are a fast path used
-  // only when populated. They're empty when the owner is unknown up front
-  // (a folder with no git remote), so the pickers fall back to a live fetch
-  // keyed off the owner the operator just typed (`answers.owner`).
+  // Pre-fetched lists are empty when the owner was unknown up front, so the
+  // pickers fall back to a live fetch keyed off the typed `answers.owner`.
   const reposList = lists.reposList;
   const projectsList = lists.projectsList;
   const pickerOwner = (answers) => answers?.owner || owner;
-  // `owner` / `repo` are GitHub-side answers. When `--skip-github` suppresses
-  // the entire GitHub bootstrap, they are not required — this lets a
-  // non-interactive `--assume-yes --skip-github` run materialize and configure
-  // a fresh non-git directory (no inferable remote) without hard-failing on
-  // `missing required answers: owner, repo`. With GitHub bootstrap active they
-  // remain required (the target repo must be resolvable).
+  // owner/repo are optional under --skip-github, so a remote-less folder can
+  // still be configured non-interactively.
   const skipGithub = Boolean(flags?.['skip-github']);
   return [
     {
@@ -580,7 +433,6 @@ export function buildQuestions(defaults, flags, env = process.env, lists = {}) {
       env: 'GH_OPERATOR_HANDLE',
       message:
         'GitHub username/handle without preceding@ (default: same as owner)',
-      // Default tracks the repo owner; resolved post-collect if left blank.
       default: defaults.owner,
       required: false,
       validate: (v) =>
@@ -624,11 +476,7 @@ export function buildQuestions(defaults, flags, env = process.env, lists = {}) {
       message: 'New GitHub Project V2 name',
       pickerMessage:
         'GitHub Project V2 name  - Select existing or press ENTER to create',
-      // Prefer the already-stored numeric project number (an
-      // already-provisioned project on a re-run) so `--assume-yes` resolves a
-      // numeric answer that `detectCreation` treats as existing — never a
-      // duplicate board (Story #3896). Falls back to the repo name only on a
-      // genuine first run where nothing is stored yet.
+      // A stored number first, so a re-run never reads as a new board.
       default: defaults.projectNumber || defaults.repo,
       required: false,
       picker: {
@@ -640,8 +488,7 @@ export function buildQuestions(defaults, flags, env = process.env, lists = {}) {
           return o ? listProjects({ owner: o }) : [];
         },
       },
-      // Accept blank (skip), an existing project number, or a new project
-      // name (letters/digits/space/._-).
+      // Blank (skip), an existing number, or a new project name.
       validate: (v) =>
         v.length === 0 || /^\d+$/.test(v) || /^[A-Za-z0-9 ._-]+$/.test(v)
           ? null
@@ -682,10 +529,6 @@ export function resolveSilentAccept(defaults, flags, env = process.env) {
   return out;
 }
 
-// ---------------------------------------------------------------------------
-// GitHub-side bootstrap (Step 6) — same wiring as bootstrap.js.
-// ---------------------------------------------------------------------------
-
 async function runGithubBootstrap(answers, opts) {
   const { runBootstrap, preflightGh, preflightRuntimeDeps } = await import(
     './agents-bootstrap-github.js'
@@ -695,10 +538,8 @@ async function runGithubBootstrap(answers, opts) {
   const { resolveConfig, validateOrchestrationConfig } = await import(
     './lib/config-resolver.js'
   );
-  // `resolveConfig` reads github.projectNumber from .agentrc.json, which the
-  // persistProjectNumber step writes BEFORE this runs — so the provider reuses
-  // the existing project instead of creating a new one (Bug: gave #8, created
-  // #12 because the number never reached the provider config).
+  // persistProjectNumber has already written the number, so the provider
+  // reuses the board instead of creating another.
   const config = resolveConfig();
   validateOrchestrationConfig(config);
   return runBootstrap(config, {
@@ -706,15 +547,9 @@ async function runGithubBootstrap(answers, opts) {
     github: config.github,
     assumeYes: opts.assumeYes,
     baseBranch: answers.baseBranch,
-    // Real consent signal threaded from `parseAndValidate` (Story #3897):
-    // interactive operator confirmation, `--assume-yes`, or
-    // `--approve-github-admin`. Default-deny at the boundary gate when absent.
+    // Default-deny at the boundary gate (see parseAndValidate).
     githubAdminApproved: opts.githubAdminApproved === true,
-    // Opt-in: provision Status field + custom fields on the project board.
-    // Default off — prompted y/N during collect/confirm or via --with-project-board.
     withProjectBoard: opts.withProjectBoard === true,
-    // Opt-in: delete the Projects V2 built-in workflows that race against the
-    // orchestrator's ColumnSync (e.g. "Pull request merged"). Off by default.
     reapConflictingWorkflows: Boolean(opts.reapConflictingWorkflows),
   });
 }
@@ -727,13 +562,8 @@ function githubSubMutationsSucceeded(gh) {
 }
 
 /**
- * Phase groups whose mutations actually landed, for the install ledger.
- *
- * Every project-side group runs on every install (Story #3690 replaced the
- * consent-first phased-approval install with a plain summary+confirm loop),
- * so the only variable is whether the irreversible GitHub-admin mutations
- * landed. Story #5007 collapsed the set-threading this used to carry down to
- * that one boolean.
+ * Phase groups that landed, for the install ledger. Every project-side group
+ * always runs; only GitHub-admin is variable.
  *
  * @param {object|undefined} report — the live execution report.
  * @returns {Set<string>}
@@ -748,29 +578,11 @@ function resolveAppliedGroups(report) {
   return applied;
 }
 
-// ---------------------------------------------------------------------------
-// Pipeline phases
-// ---------------------------------------------------------------------------
-
 /**
- * Step 1 — Parse argv, handle `--help`, and enforce the non-TTY contract.
- *
- * Consent contract (Story #3897). A non-TTY run has no operator to confirm
- * the summary loop in `collectAndConfirm`, so the irreversible GitHub-admin
- * mutations cannot ride on a real confirmation — they need an explicit
- * up-front signal. The gate therefore requires **either** `--assume-yes`
- * **or** `--approve-github-admin` on any non-TTY run (matching the
- * `--help` text), and computes `githubAdminApproved` once for the whole run:
- *
- *   - **interactive (TTY)** → consent is the operator's `Is this correct?`
- *     confirmation in `collectAndConfirm`, so the run is approved.
- *   - **non-TTY** → consent is `--assume-yes` or `--approve-github-admin`;
- *     without one of those the run halts before any mutation.
- *
- * `githubAdminApproved` flows down to `runGithubBootstrap`, which forwards it
- * to the boundary gate in `agents-bootstrap-github.js#runBootstrap`. That
- * gate is default-deny, so a non-approved value makes the GitHub-admin phase
- * a verified no-op instead of a silent mutation.
+ * Step 1 — parse argv and compute GitHub-admin consent once: an interactive
+ * run consents via the summary confirmation; a non-TTY run MUST pass
+ * `--assume-yes` or `--approve-github-admin` or halts before any mutation.
+ * The downstream gate in `runBootstrap` is default-deny.
  */
 export function parseAndValidate(argv, opts = {}) {
   const stdout = opts.stdout ?? process.stdout;
@@ -783,12 +595,6 @@ export function parseAndValidate(argv, opts = {}) {
   const interactive = Boolean(stdin.isTTY) && !flags['assume-yes'];
   const assumeYes = Boolean(flags['assume-yes']);
   const approveGithubAdmin = Boolean(flags['approve-github-admin']);
-  // A non-TTY run cannot collect operator consent interactively, so it MUST
-  // carry an explicit consent signal. This restores parity with the --help
-  // text, which has always claimed --assume-yes is required for non-TTY runs.
-  // (owner/repo are resolved from flags/env/git-remote downstream — a consent
-  // signal alone is sufficient to advance, exactly as the pre-Story #3897
-  // `--assume-yes` path did.)
   if (!interactive && !assumeYes && !approveGithubAdmin) {
     Logger.error(
       '[Bootstrap] non-TTY run requires --assume-yes or --approve-github-admin ' +
@@ -796,8 +602,6 @@ export function parseAndValidate(argv, opts = {}) {
     );
     return { ok: false, exit: 1 };
   }
-  // Real GitHub-admin consent: an interactive run confirms it in
-  // `collectAndConfirm`; a non-TTY run signals it via flag (above).
   const githubAdminApproved = interactive || assumeYes || approveGithubAdmin;
   if (resolveRepoVisibility(flags) === null) {
     Logger.error(
@@ -812,10 +616,7 @@ export function parseAndValidate(argv, opts = {}) {
   };
 }
 
-/**
- * Step 1b — Resolve paths, infer defaults from git, and echo the detected
- * values back to the operator (the "share found values" requirement).
- */
+/** Step 1b — resolve paths, infer defaults from git, and echo them. */
 export function prepareContext(state, opts = {}) {
   const scriptUrl = opts.scriptUrl ?? import.meta.url;
   const here = path.dirname(fileURLToPath(scriptUrl));
@@ -837,11 +638,7 @@ export function prepareContext(state, opts = {}) {
   };
 }
 
-/**
- * Step 2 — Preflight. Work-tree check is informational (does not fail the
- * gate); adds the Projects V2 permission check. Prints a pass/fail line for
- * every check.
- */
+/** Step 2 — preflight; the work-tree check is informational only. */
 export async function runPreflightPhase(state, opts = {}) {
   const run = opts.run ?? runPreflight;
   const skipGithub = Boolean(state.flags['skip-github']);
@@ -853,10 +650,7 @@ export async function runPreflightPhase(state, opts = {}) {
 
   for (const check of result.checks) {
     if (check.ok) {
-      // A non-fatal informational check (it carries `gitInitialized`) shows a
-      // glyph reflecting the real state rather than its always-true gate pass:
-      // ✓ when the git repo exists, ✗ when it does not (bootstrap initialises
-      // it in a later phase regardless — the ✗ never aborts the run).
+      // The informational git check shows the real state; its ✗ never aborts.
       const glyph =
         typeof check.gitInitialized === 'boolean' && !check.gitInitialized
           ? '✗'
@@ -876,18 +670,12 @@ export async function runPreflightPhase(state, opts = {}) {
     return { ok: false, exit: 1 };
   }
 
-  // The git-repo state is already reported by the (non-fatal) "Local git
-  // initialized" check above — both derive from the same
-  // `git rev-parse --is-inside-work-tree` probe — so there is no separate
-  // "git initialized" line here (it would duplicate, and contradict, that
-  // check). The boolean is still threaded through the payload for later phases.
   return {
     ok: true,
     payload: { preflight: result, gitInitialized: result.gitInitialized },
   };
 }
 
-/** Render the resolved answers as a human-readable summary block. */
 function renderAnswerSummary(
   answers,
   creation,
@@ -912,14 +700,8 @@ function renderAnswerSummary(
 }
 
 /**
- * Determine whether the answers ask for resources that do not exist yet.
- * The repo is "new" when `gh repo view owner/repo` reports it does not
- * exist — an authoritative per-repo probe rather than an "is it in the
- * repo-list?" check, which mis-fired for a brand-new account whose
- * `gh repo list` is empty (it then assumed the repo already existed and
- * skipped creation). A non-numeric project answer (a typed name, not a
- * picked number) is "new". When GitHub is skipped there is nothing to
- * create, so detection is bypassed.
+ * Which answers name resources that do not exist yet: a repo `repoExists`
+ * denies, or a non-numeric (typed) project answer.
  */
 async function detectCreation(answers, skipGithub) {
   const creation = { newRepo: false, newProject: false };
@@ -935,10 +717,8 @@ async function detectCreation(answers, skipGithub) {
 }
 
 /**
- * Resolve the Projects V2 answer into a `{ name, number }` pair for the
- * summary. The picker stores only the numeric value, so for an existing
- * project (numeric answer) we look the name up in the owner's project list.
- * A typed answer (non-numeric) is a new project name with no number yet.
+ * `{ name, number }` for the summary; the picker stores only the number, so
+ * an existing project's name is looked up.
  */
 function resolveProjectDisplay(answers, skipGithub, projectsList) {
   const pn = answers.projectNumber;
@@ -956,23 +736,17 @@ function resolveProjectDisplay(answers, skipGithub, projectsList) {
     }
     return { name, number: pn };
   }
-  // Typed name → new project; number is assigned at creation time.
   return { name: pn, number: '(new)' };
 }
 
 /**
- * Steps 3 + 4 — Collect answers, show a summary, and confirm. Interactive
- * runs that answer "no" loop back and re-ask. Non-interactive runs
- * auto-accept. Then collect creation approval when a new repo/project was
- * requested.
+ * Steps 3 + 4 — collect answers and loop until the summary is confirmed, then
+ * get creation approval and the opt-ins.
  */
 export async function collectAndConfirm(state) {
   const skipGithub = Boolean(state.flags['skip-github']);
   const owner = resolveOwnerForPicker(state.defaults, state.flags);
-  // Fetch the owner's repos + projects ONCE and reuse for the pickers and
-  // the summary display — so the resolved project name never depends on a
-  // second (flaky) `gh` call. (Repo existence for the creation check is a
-  // separate, authoritative `gh repo view` probe in `detectCreation`.)
+  // Fetched once for pickers and summary, so the name never needs a second call.
   const reposList =
     !skipGithub && owner
       ? safeList(() => listRepos({ owner }).map(bareRepoName))
@@ -981,7 +755,6 @@ export async function collectAndConfirm(state) {
     !skipGithub && owner ? safeList(() => listProjects({ owner })) : [];
 
   let silentAccept = state.silentAccept;
-  // Loop until the operator confirms the summary (or we auto-accept).
   for (;;) {
     const { answers, missing } = await collectAnswers({
       questions: buildQuestions(state.defaults, state.flags, process.env, {
@@ -1002,12 +775,7 @@ export async function collectAndConfirm(state) {
       );
       return { ok: false, exit: 1 };
     }
-    // Defaults that track another answer: handle ⇐ owner, project ⇐ repo.
     if (!answers.operatorHandle) answers.operatorHandle = answers.owner;
-    // Strip a single leading `@` so the starter template's `@[USERNAME]`
-    // substitution yields `@foo`, not `@@foo` (Story #3700). The flag/env
-    // paths bypass the interactive validator that already rejects a leading
-    // `@`, so normalize uniformly here.
     answers.operatorHandle = normalizeHandleAnswer(answers.operatorHandle);
 
     const creation = await detectCreation(answers, skipGithub);
@@ -1024,12 +792,10 @@ export async function collectAndConfirm(state) {
     const correct = await confirmYesNo('Is this correct?', state.interactive);
     if (!correct) {
       Logger.info('[Bootstrap] Okay — let’s try again.');
-      // Re-prompt everything on the next pass (drop silent-accept).
       silentAccept = [];
       continue;
     }
 
-    // In --dry-run we only collect/confirm info, so never ask to create.
     if (!state.flags['dry-run'] && (creation.newRepo || creation.newProject)) {
       const approved = await confirmYesNo(
         'Create the new GitHub repo/project listed above?',
@@ -1043,8 +809,7 @@ export async function collectAndConfirm(state) {
       }
     }
 
-    // Opt-in: board decoration (Status field, custom fields). Default off.
-    // Dry-run halts immediately after this step — resolve without prompting.
+    // Opt-ins default off; dry-run resolves them without prompting.
     let withProjectBoard = Boolean(state.flags['with-project-board']);
     if (!state.flags['dry-run'] && !withProjectBoard) {
       withProjectBoard = await confirmYesNo(
@@ -1054,7 +819,6 @@ export async function collectAndConfirm(state) {
       );
     }
 
-    // Opt-in: GitHub Issue Form templates. Default off.
     let withIssueForms = Boolean(state.flags['with-issue-forms']);
     if (!state.flags['dry-run'] && !withIssueForms) {
       withIssueForms = await confirmYesNo(
@@ -1064,7 +828,6 @@ export async function collectAndConfirm(state) {
       );
     }
 
-    // Opt-in: local quality gates. Default off.
     let withQuality = Boolean(state.flags['with-quality']);
     if (!state.flags['dry-run'] && !withQuality) {
       withQuality = await confirmYesNo(
@@ -1087,12 +850,6 @@ export async function collectAndConfirm(state) {
   }
 }
 
-/**
- * --dry-run gate — print the resolved answers and the full mutation plan,
- * then halt BEFORE any file write, GitHub change, or label creation. Runs
- * after collect/confirm so the operator sees exactly what would happen.
- */
-/** Render the dry-run plan as a per-section layout (no mutations happen). */
 function renderDryRunPlan(state) {
   const a = state.answers ?? {};
   const c = state.creation ?? {};
@@ -1118,6 +875,7 @@ function renderDryRunPlan(state) {
   ].join('\n');
 }
 
+/** --dry-run gate: print the plan and halt before any mutation. */
 export function dryRunPlan(state) {
   if (!state.flags['dry-run']) return { ok: true, payload: {} };
   Logger.info(
@@ -1128,34 +886,14 @@ export function dryRunPlan(state) {
 }
 
 /**
- * Step 5 — Provision the missing pieces of a cold start, in dependency order:
- *
- *   1. Local git — `git init` + an initial commit when the folder is not a
- *      repo yet (so the repo create below has something to push).
- *   2. GitHub repo — `gh repo create --source --remote --push` when the repo
- *      does not exist for the owner; otherwise wire the `origin` remote to the
- *      existing repo when the local folder is not yet linked. Either way the
- *      GitHub bootstrap can resolve the target from the local remote.
- *   3. GitHub Project V2 — `gh project create` from the typed name when the
- *      project answer is a name rather than an existing number; the assigned
- *      number is written back onto `state.answers.projectNumber`.
- *   4. Link — `gh project link` ties the repo to the project board so its
- *      issues/PRs surface there (non-fatal; safe to re-run).
- *
- * Every action is idempotent and guarded by the detection done in
- * `collectAndConfirm`, so a re-run on an already-provisioned project is a
- * no-op. `--skip-github` suppresses the GitHub mutations but still runs the
- * local git init. `--dry-run` never reaches this step (it halts earlier).
- *
- * `deps.exec` injects the `gh-exec` seam so the GitHub-touching branches
- * (`gh repo create`, `gh project create`, `gh project link`) are unit-testable
- * without spawning a real `gh`; it defaults to the module's `exec`.
+ * Step 5 — provision a cold start in dependency order: local git, GitHub repo
+ * (or `origin` wiring), Projects V2 board, repo↔board link. Every step is
+ * idempotent; `--skip-github` still runs the local git init.
  */
 export async function provisionResources(state, deps = {}) {
   const execImpl = deps.exec ?? exec;
   const skipGithub = Boolean(state.flags['skip-github']);
 
-  // 1. Local git — initialize + first commit when missing (idempotent).
   const git = ensureGitInitialized(state);
   if (!git.ok) {
     Logger.error(`[Bootstrap] git initialization failed: ${git.error}`);
@@ -1175,10 +913,6 @@ export async function provisionResources(state, deps = {}) {
     return { ok: true, payload: {} };
   }
 
-  // 2. GitHub repo — create + link + push when it does not exist yet;
-  //    otherwise ensure the local `origin` remote points at the existing repo
-  //    so the GitHub bootstrap can resolve the target (idempotent re-runs and
-  //    pre-created repos would otherwise leave the folder unlinked).
   if (newRepo) {
     try {
       await createGithubRepo(state, execImpl);
@@ -1190,12 +924,9 @@ export async function provisionResources(state, deps = {}) {
     await ensureGitRemote(state, execImpl);
   }
 
-  // 3. GitHub Project V2 — create from the typed name; capture its number so
-  //    the persist + GitHub bootstrap steps reuse it instead of duplicating.
   if (newProject) {
     try {
       await createGithubProject(state, execImpl);
-      // It now exists with a real number; downstream treats it as existing.
       state.creation.newProject = false;
     } catch (err) {
       logGhError('project create', err);
@@ -1207,19 +938,12 @@ export async function provisionResources(state, deps = {}) {
     Logger.info('[Bootstrap] No new GitHub resources needed.');
   }
 
-  // 4. Link the repo to the project board so issues/PRs surface on it
-  //    (idempotent + non-fatal; runs for both freshly created and existing
-  //    repo/project pairs).
   await ensureProjectLinked(state, execImpl);
 
   return { ok: true, payload: {} };
 }
 
-/**
- * Step 6a — Project-side bootstrap. Every project-side phase runs; the
- * install ledger decides afterwards which phase groups actually landed
- * ({@link resolveAppliedGroups}).
- */
+/** Step 6a — project-side bootstrap (every phase runs). */
 export async function executeBootstrap(state) {
   Logger.info(
     `[Bootstrap] Starting project bootstrap at ${state.projectRoot} (owner=${state.answers.owner} repo=${state.answers.repo} base=${state.answers.baseBranch})`,
@@ -1235,13 +959,9 @@ export async function executeBootstrap(state) {
 }
 
 /**
- * Step 6 (between project + GitHub) — Persist the chosen Projects V2 number
- * into .agentrc.json's github block so it is the stored source of truth that
- * resolveConfig (and the orchestrator) read back. Runs AFTER the project-side
- * bootstrap has ensured .agentrc.json exists and BEFORE the GitHub bootstrap,
- * so the provider reuses the existing project instead of creating a new one.
- * Merges into an existing file (ensureAgentrc never overwrites one). Stored as
- * an integer per the schema; a blank/new-project answer stores nothing.
+ * Persist the numeric project number into `.agentrc.json` — after the
+ * project-side bootstrap creates the file, before the GitHub bootstrap reads
+ * it, so the provider reuses the board.
  */
 export function persistProjectNumber(state) {
   const pn = String(state.answers.projectNumber ?? '');
@@ -1259,10 +979,7 @@ export function persistProjectNumber(state) {
     return { ok: true, payload: {} };
   }
   config.github = config.github ?? {};
-  // Minimal-write contract (Story #3700): only re-serialize `.agentrc.json`
-  // when the stored number actually changes. When the value is already present
-  // and equal, leave the file byte-for-byte untouched — a re-run must not churn
-  // the consumer's hand-formatting or whitespace.
+  // Unchanged → leave the file byte-for-byte (keep the consumer's formatting).
   if (config.github.projectNumber === Number(pn)) {
     return { ok: true, payload: {} };
   }
@@ -1288,8 +1005,6 @@ export async function executeGithubBootstrap(state) {
       ),
     });
   } catch (err) {
-    // GhExecError carries the real gh stderr/stdout/exit code — surface it so
-    // a generic "gh exited with code 1" is actually diagnosable.
     logGhError('GitHub bootstrap', err);
     state.report.github = { error: err.message };
   }
@@ -1304,10 +1019,6 @@ export function recordLedger(state) {
     skipGithub: Boolean(state.flags['skip-github']),
     withQuality: state.withQuality === true,
   };
-  // The manifest always carries the unconditional ide-wiring / repo-config
-  // entries and `appliedGroups` always contains those groups, so the filter
-  // never empties. (Story #5007 removed the phased-approval gate that was the
-  // only way to reach an empty set.)
   const entries = buildMutationManifest(manifestCtx).filter((e) =>
     appliedGroups.has(e.phaseGroup),
   );
@@ -1315,9 +1026,8 @@ export function recordLedger(state) {
     entries,
     approvedGroups: appliedGroups,
     answers: state.answers,
-    // The live execution report lets the ledger record `already-present` vs
-    // `seeded` per entry, so uninstall never deletes a pre-existing
-    // `.agentrc.json` the install merely left in place (Story #3895).
+    // Records `already-present` vs `seeded`, so uninstall never deletes a
+    // pre-existing `.agentrc.json`.
     report: state.report,
   });
   const result = writeInstallLedger(state.projectRoot, record);
@@ -1326,32 +1036,11 @@ export function recordLedger(state) {
 }
 
 /**
- * Step 7 — Offer to commit + push the bootstrap wiring (Story #3899).
- *
- * Story delivery runs in git worktrees that check out **tracked files only**,
- * so an uncommitted `.agents/` tree means every Story sub-agent breaks. This
- * step closes that "worked in my checkout, broke in delivery" trap by offering
- * the commit + push at the end of the run.
- *
- * Ordering: this phase runs LAST in the pipeline, after `executeBootstrap`
- * (which seeds the secret-safe `.gitignore`) and `recordLedger`. The stage
- * step also uses an explicit allowlist and refuses to stage `.env` /
- * `.mcp.json` / `.agentrc.local.json` regardless of `.gitignore` state, so the
- * commit never carries a secret even before the gitignore-ordering Story
- * (#3894) lands.
- *
- * Behaviour:
- *   - `--dry-run` → no-op (the dry-run gate already halted earlier; this is a
- *     belt-and-braces guard for direct calls).
- *   - Interactive + accept → stage the allowlist, commit with a conventional
- *     subject, push the base branch.
- *   - Interactive + decline → print the exact manual commands; no git mutation.
- *   - Non-interactive (`--assume-yes` / no TTY) → the defined safe path is to
- *     print the manual commands and make NO git mutation, so a CI run never
- *     surprises the operator with a push it did not ask for.
- *
- * `deps.runGit` injects the git seam and `deps.confirm` the yes/no prompt seam
- * for unit testing; both default to the module's implementations.
+ * Step 7 — offer to commit + push the wiring: delivery worktrees check out
+ * tracked files only, so an uncommitted `.agents/` breaks every Story. Runs
+ * last, after `.gitignore` is seeded; staging is an allowlist that refuses
+ * secret files regardless. Non-interactive runs only print the commands —
+ * never an unasked-for push.
  */
 export async function offerCommitPush(state, deps = {}) {
   if (state.flags['dry-run']) return { ok: true, payload: {} };
@@ -1365,8 +1054,6 @@ export async function offerCommitPush(state, deps = {}) {
     baseBranch: branch,
   });
 
-  // Non-interactive (--assume-yes / no TTY): never push unprompted. Print the
-  // exact commands and leave the working tree untouched.
   if (!state.interactive) {
     Logger.info(`\n[Bootstrap] ${instructions}`);
     return { ok: true, payload: { commitPush: { action: 'instructed' } } };
@@ -1392,7 +1079,7 @@ export async function offerCommitPush(state, deps = {}) {
     cwd,
   );
   if (!commit.ok) {
-    // A "nothing to commit" exit is benign — the wiring is already committed.
+    // Benign when the wiring is already committed.
     Logger.warn(
       `[Bootstrap] git commit did not create a commit (already committed?): ${commit.stderr || commit.stdout}`,
     );
@@ -1411,7 +1098,6 @@ export async function offerCommitPush(state, deps = {}) {
   return { ok: true, payload: { commitPush: { action: 'committed-pushed' } } };
 }
 
-/** Pipeline driver — threads accumulated state through each phase. */
 export async function runPipeline(phases) {
   let state = {};
   for (const phase of phases) {
@@ -1423,9 +1109,6 @@ export async function runPipeline(phases) {
 }
 
 export async function main(argv = process.argv.slice(2), deps = {}) {
-  // `deps.phases` lets tests inject a substitute pipeline so the
-  // post-pipeline GitHub-failure detection can be exercised
-  // deterministically without spawning `gh` (Story #3898).
   const phases = deps.phases ?? [
     () => parseAndValidate(argv),
     (s) => prepareContext(s),
@@ -1442,12 +1125,8 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
   const result = await runPipeline(phases);
   if (!result.ok) return result.exit;
 
-  // GitHub-side bootstrap failures are non-fatal to the pipeline (so the
-  // ledger still records the project-side mutations that already landed —
-  // the failure is surfaced, not silently rolled back), but they MUST NOT
-  // exit 0. `executeGithubBootstrap` records `report.github.error` instead
-  // of throwing; detect it here and exit non-zero with a distinct final
-  // status line so `mandrel init` and CI see the failure (Story #3898).
+  // A GitHub failure is non-fatal to the pipeline (the ledger still records
+  // what landed) but MUST NOT exit 0.
   const githubError = result.state?.report?.github?.error;
   if (githubError) {
     Logger.error(