mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/bootstrap/prompt.js

@@ -1,22 +1,6 @@
 /**
- * bootstrap/prompt — interactive prompt + CLI flag helpers for bootstrap.js.
- *
- * Uses Node's built-in `readline/promises` so the bootstrap stays
- * dependency-free. Provides:
- *
- *   - `parseFlags(argv)`            — minimal arg parser for the flags the
- *                                     bootstrap CLI accepts.
- *   - `inferDefaults(projectRoot)`  — derives default values for owner /
- *                                     repo / baseBranch / operatorHandle
- *                                     from the project's git remote and
- *                                     config (no network calls).
- *   - `collectAnswers({ flags, defaults, interactive })` — resolves every
- *                                     required value, prompting only for
- *                                     values not supplied via flag.
- *
- * In non-TTY contexts the helper refuses to prompt and returns the
- * accumulated answers; callers must decide whether the remaining required
- * fields are satisfied via flags/env.
+ * Dependency-free prompt and CLI-flag helpers for bootstrap.js. Never prompts
+ * in non-TTY contexts; callers decide whether missing fields are fatal.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -24,10 +8,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline/promises';
 
-/**
- * Flags the bootstrap CLI accepts. Keep this list in sync with the
- * `--help` text in bootstrap.js.
- */
+/** Keep in sync with the `--help` text in bootstrap.js. */
 const KNOWN_FLAGS = Object.freeze({
   string: [
     'owner',
@@ -49,10 +30,7 @@ const KNOWN_FLAGS = Object.freeze({
 });
 
 /**
- * Parse a minimal `--flag value` / `--flag=value` / `--boolean` argv.
- *
- * Unknown long flags become string flags (last-write-wins) so callers can
- * forward through to nested scripts without losing data.
+ * Unknown long flags become string flags so they can be forwarded.
  *
  * @param {string[]} argv
  * @returns {Record<string, string|boolean>}
@@ -85,10 +63,6 @@ export function parseFlags(argv) {
 }
 
 /**
- * Parse `owner/repo` out of a git remote URL. Supports HTTPS, SSH, and
- * `git@host:owner/repo.git` forms. Returns `null` when the URL is empty
- * or not recognisable.
- *
  * @param {string} url
  * @returns {{ owner: string, repo: string } | null}
  */
@@ -114,16 +88,8 @@ function runGit(args, cwd) {
 }
 
 /**
- * Read the already-stored `github.projectNumber` from an existing
- * `.agentrc.json` in `projectRoot`, returned as a numeric string (the shape
- * the `projectNumber` question default expects). Returns `null` when the
- * file is missing, unparseable, or carries no integer project number.
- *
- * This is the authoritative default for an already-provisioned project on a
- * bootstrap re-run: surfacing the stored number (rather than the repo name)
- * means an `--assume-yes` re-run resolves a numeric answer, which
- * `detectCreation` classifies as an *existing* project — so no duplicate
- * board is created (Story #3896 / review Finding B.3).
+ * Stored `github.projectNumber` as a numeric string. A re-run must default to
+ * it so `detectCreation` sees an existing project and no duplicate board is made.
  *
  * @param {string} projectRoot
  * @returns {string|null}
@@ -147,9 +113,7 @@ export function inferStoredProjectNumber(projectRoot) {
 }
 
 /**
- * Derive defaults for the interactive prompts from the project's git
- * config. No network calls — only inspects the local remote/config and the
- * stored `.agentrc.json` (for the already-provisioned project number).
+ * Prompt defaults from local git state and `.agentrc.json`; no network calls.
  *
  * @param {string} projectRoot
  * @returns {{ owner: string|null, repo: string|null, baseBranch: string,
@@ -175,41 +139,22 @@ export function inferDefaults(projectRoot) {
   };
 }
 
-// ---------------------------------------------------------------------------
-// Resolver chain (Story #2459 / Task #2470)
-//
-// `collectAnswers` used to be a 60-line for-loop with seven `continue`
-// branches — flag, env, silent-accept, interactive (with re-ask), assume-yes,
-// missing-required. The branches all had the same shape: "try to produce a
-// value; if you have one, record it and move on". Each branch is now a
-// dedicated `resolveFrom*` helper that returns one of three outcomes:
-//
-//   { kind: 'value',   value }  — accepted this answer; stop trying resolvers.
-//   { kind: 'missing' }         — required-but-empty; record on `missing[]`.
-//   { kind: 'skip' }            — this resolver doesn't apply; try the next.
-//
-// `collectAnswers` becomes a two-level loop: for each question, walk the
-// `RESOLVERS` array in priority order. Each resolver is testable in
-// isolation and measures CC < 8 independently.
-// ---------------------------------------------------------------------------
+// Resolvers return `{ kind: 'value', value }` (stop), `{ kind: 'missing' }`
+// (required-but-empty) or `{ kind: 'skip' }` (try the next resolver).
 
 /**
  * @typedef {object} ResolverContext
- * @property {object} q                — The question definition.
+ * @property {object} q
  * @property {Record<string, string|boolean>} flags
  * @property {NodeJS.ProcessEnv} env
- * @property {Set<string>} silentSet   — Keys whose default should be
- *                                       accepted without prompting.
+ * @property {Set<string>} silentSet   — Keys whose default is accepted unprompted.
  * @property {boolean} interactive
  * @property {boolean} assumeYes
- * @property {() => Promise<readline.Interface>} getRl — Lazy readline factory
- *                                       that returns the same instance across
- *                                       calls within one collectAnswers run.
+ * @property {() => Promise<readline.Interface>} getRl — Lazy, one instance per run.
  * @property {NodeJS.WritableStream} output
  */
 
 /**
- * Resolver 1 — CLI flag wins outright.
  * @param {ResolverContext} ctx
  * @returns {{ kind: 'value'|'skip', value?: string }}
  */
@@ -222,7 +167,6 @@ export function resolveFromFlag(ctx) {
 }
 
 /**
- * Resolver 2 — env var override.
  * @param {ResolverContext} ctx
  * @returns {{ kind: 'value'|'skip', value?: string }}
  */
@@ -237,8 +181,6 @@ export function resolveFromEnv(ctx) {
 }
 
 /**
- * Resolver 3 — silent-accept default (key was inferred from local git state
- * and no operator override was supplied).
  * @param {ResolverContext} ctx
  * @returns {{ kind: 'value'|'skip', value?: string }}
  */
@@ -250,28 +192,9 @@ export function resolveFromSilent(ctx) {
 }
 
 /**
- * Resolver — interactive numbered-menu picker. Sits between
- * `resolveFromSilent` and `resolveInteractive` so an operator who declined
- * the silent default still gets a live menu of real choices (e.g. their
- * GitHub repos / projects) before falling back to free-text entry.
- *
- * The question opts in by carrying an optional `picker: { list }` field,
- * where `list(answers)` is a function returning an array of string choices
- * (commonly a `gh-list` provider). It receives the answers resolved so far,
- * so a later question can list against an earlier answer — e.g. the repo /
- * project pickers fetching the just-entered owner's repos/projects, which is
- * the only owner available when the folder has no git remote to infer from.
- * The resolver returns `kind: 'skip'` — falling through to manual entry via
- * `resolveInteractive` — in three cases:
- *
- *   1. not interactive (`ctx.interactive` is false),
- *   2. the question has no `picker` (or no callable `picker.list`),
- *   3. the provider returns an empty list (no choices to render).
- *
- * Otherwise it renders a numbered menu, reads a selection via `ctx.getRl()`,
- * and returns the chosen value. A blank line or an out-of-range / unparseable
- * selection also falls through to manual entry (`kind: 'skip'`) rather than
- * looping, keeping the resolver single-shot and predictable.
+ * Numbered-menu picker for questions carrying `picker.list(answers)`, which
+ * sees earlier answers (e.g. the owner just entered). Single-shot: no choices
+ * or a blank/invalid selection falls through to manual entry.
  *
  * @param {ResolverContext} ctx
  * @returns {Promise<{ kind: 'value'|'skip', value?: string }>}
@@ -286,10 +209,6 @@ export async function resolveFromPicker(ctx) {
 
   const normalized = choices.map(normalizePickerChoice);
   const rl = await ctx.getRl();
-  // The picker header uses `pickerMessage` when set, so a question can show
-  // list-oriented guidance here (e.g. "Select existing or press ENTER to create
-  // new one") while the manual-entry fall-through prompt (`askOnce`) uses the
-  // shorter `message` (e.g. "New GitHub repo name"). Falls back to `message`.
   ctx.output.write(`${ctx.q.pickerMessage ?? ctx.q.message}:\n`);
   normalized.forEach((choice, index) => {
     ctx.output.write(`  ${index + 1}) ${choice.label}\n`);
@@ -318,11 +237,6 @@ export async function resolveFromPicker(ctx) {
 }
 
 /**
- * Normalize a picker choice into a `{ label, value }` pair. A bare string
- * choice uses the same text for both; an object choice carries an explicit
- * `label` shown in the menu and `value` returned on selection. Exported for
- * unit testing.
- *
  * @param {string | { label?: string, value?: string }} choice
  * @returns {{ label: string, value: string }}
  */
@@ -337,9 +251,7 @@ export function normalizePickerChoice(choice) {
 }
 
 /**
- * Prompt once with the question's default label, applying the default when
- * the operator pressed Enter on an empty line. Pure I/O; exported so
- * `resolveInteractive` can be unit-tested with a mocked readline.
+ * An empty line takes the default.
  *
  * @param {readline.Interface} rl
  * @param {object} q
@@ -354,8 +266,7 @@ async function askOnce(rl, q) {
 }
 
 /**
- * Resolver 4 — interactive prompt. Asks once; if `q.validate` rejects, the
- * helper re-asks once more before declaring the answer missing.
+ * Re-asks once on a validation failure before declaring the answer missing.
  *
  * @param {ResolverContext} ctx
  * @returns {Promise<{ kind: 'value'|'missing'|'skip', value?: string }>}
@@ -376,10 +287,6 @@ export async function resolveInteractive(ctx) {
 }
 
 /**
- * Resolver 5 — non-interactive `--assume-yes` fallback. Accepts the
- * question's default verbatim; emits `missing` for required questions that
- * lack a default.
- *
  * @param {ResolverContext} ctx
  * @returns {{ kind: 'value'|'missing'|'skip', value?: string }}
  */
@@ -390,10 +297,7 @@ export function resolveAssumeYes(ctx) {
   return { kind: 'skip' };
 }
 
-/**
- * Priority-ordered list of resolvers. Each is tried in turn until one
- * returns a non-`skip` outcome. Exported for testing.
- */
+/** Priority order; the first non-`skip` outcome wins. */
 export const RESOLVERS = Object.freeze([
   resolveFromFlag,
   resolveFromEnv,
@@ -404,15 +308,7 @@ export const RESOLVERS = Object.freeze([
 ]);
 
 /**
- * Walk the question list and resolve a value for each. Each question is
- * routed through the `RESOLVERS` chain in priority order; the first
- * resolver to return `{ kind: 'value' }` wins, `{ kind: 'missing' }` adds
- * the key to `missing[]`, and `{ kind: 'skip' }` continues the chain. If
- * every resolver skips a *required* question, the key is recorded as
- * missing so callers can decide whether to abort.
- *
- * Returns `{ answers, missing }` so the CLI can decide whether to abort
- * (non-TTY with missing required fields and no `--assume-yes`).
+ * Resolve each question through `RESOLVERS`; the CLI decides whether `missing` aborts.
  *
  * @param {object} args
  * @param {Array<{ key: string, flag: string, env?: string, message: string,
@@ -421,8 +317,7 @@ export const RESOLVERS = Object.freeze([
  * @param {Record<string, string|boolean>} args.flags
  * @param {boolean} args.interactive
  * @param {boolean} args.assumeYes
- * @param {Iterable<string>} [args.silentAccept] Keys whose `q.default`
- *   should be accepted without prompting (when no flag/env overrides).
+ * @param {Iterable<string>} [args.silentAccept]
  * @param {NodeJS.ReadableStream} [args.input=process.stdin]
  * @param {NodeJS.WritableStream} [args.output=process.stdout]
  * @returns {Promise<{ answers: Record<string, string>, missing: string[] }>}
@@ -456,9 +351,7 @@ export async function collectAnswers(args) {
         assumeYes,
         getRl,
         output,
-        // Answers resolved so far (questions run in order), so a later
-        // question's picker can key off an earlier answer — e.g. the repo /
-        // project pickers listing against the owner just entered.
+        // Resolved so far, so a later picker can key off an earlier answer.
         answers,
       };
       let outcome = { kind: 'skip' };
@@ -474,7 +367,6 @@ export async function collectAnswers(args) {
         missing.push(q.key);
         continue;
       }
-      // Every resolver skipped — record as missing only if required.
       if (q.required) missing.push(q.key);
     }
   } finally {

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

@@ -1,35 +1,7 @@
 /**
- * bootstrap/quality-bootstrap — Story #1401 (Epic #1386)
- *
- * Idempotent installer for the stabilized-quality-gates surface area on a
- * project clone. Performs five additive actions, each safe to re-run:
- *
- *   1. Copies the `code-quality-guardrails.md` helper into the project's
- *      `.agents/workflows/helpers/` (no-op when the helper is already present).
- *   2. Installs `.husky/pre-commit` carrying the `quality:preview` invocation
- *      that the framework ships, preserving any custom hook lines already in
- *      place. When a custom (non-framework) `pre-commit` exists, it is left
- *      untouched and the caller is told to merge in the snippet manually.
- *   3. Adds `quality:preview` and `quality:watch` npm scripts when missing.
- *      Existing scripts are preserved.
- *   4. Seeds `delivery.quality.codingGuardrails` and
- *      `delivery.quality.autoRefresh` defaults in `.agentrc.json` when
- *      the keys are absent. Existing values are preserved.
- *   5. Registers the `baselines/*.json` merge driver (Story #5215) — the
- *      `.gitattributes` line plus this clone's `merge.mandrel-baseline.driver`
- *      config, so concurrent baseline refreshes merge by row identity instead
- *      of conflicting on the `generatedAt` stamp.
- *   6. Prunes a committed pre-v2 `baselines/epic/` tree (Story #5007). The
- *      v2 model is Story-only — nothing writes, reads, or reaps per-Epic
- *      ratchet snapshots — so an upgrading consumer is left carrying a
- *      committed directory no gate consults. Absent on every repo that never
- *      ran a pre-v2 install, which is the overwhelmingly common case.
- *
- * Returns a structured summary so the bootstrap and update workflows can
- * surface exactly which actions ran and which were no-ops.
- *
- * Exports are pure-ish (filesystem effects only via the supplied paths) so
- * the test suite can drive the helper against a tmp directory.
+ * Idempotent, additive installer for the quality-gates surface: guardrails
+ * helper, pre-commit hook, npm scripts, config defaults, baseline merge
+ * driver, and pruning the retired `baselines/epic/` tree.
  *
  * @module bootstrap/quality-bootstrap
  */
@@ -41,11 +13,7 @@ import { getAgentrcDefaults, lookupPath } from '../config/defaults.js';
 import { deepEqual } from '../json-utils.js';
 import { ensureBaselineMergeDriver } from './baseline-merge-driver.js';
 
-/**
- * The exact pre-commit body the framework ships. Kept as a single string so
- * the hook-installer can detect a verbatim framework hook (overwrite-safe)
- * vs a custom hook (preserve and warn).
- */
+/** The framework's own pre-commit body. */
 const FRAMEWORK_PRE_COMMIT = `node scripts/check-version-sync.js
 npx lint-staged
 # Story #1395 / Epic #1386: catch MI/CRAP drift at git-commit time so the
@@ -56,13 +24,7 @@ npx lint-staged
 node .agents/scripts/quality-preview.js --changed-since HEAD --staged
 `;
 
-/**
- * Minimal pre-commit body for downstream projects that do not carry the
- * framework's `check-version-sync.js` script. Drops that line and the
- * `lint-staged` invocation (downstream may or may not have lint-staged
- * configured); keeps the quality-preview line which is the load-bearing
- * Epic #1386 addition.
- */
+/** Consumer pre-commit: only the load-bearing quality-preview line. */
 export const DOWNSTREAM_PRE_COMMIT = `# Stabilized quality gates (Epic #1386 / Story #1401):
 # catch MI/CRAP drift at git-commit time so the agent refactors before the
 # diff is closed. quality:preview wraps both gates with --changed-since HEAD
@@ -71,43 +33,25 @@ export const DOWNSTREAM_PRE_COMMIT = `# Stabilized quality gates (Epic #1386 / S
 node .agents/scripts/quality-preview.js --changed-since HEAD --staged
 `;
 
-/**
- * Marker substring used to detect a framework-installed quality-preview line
- * inside a pre-commit hook regardless of which body variant is in use.
- */
+/** Detects an installed quality-preview line in either body variant. */
 export const PRE_COMMIT_MARKER =
   'node .agents/scripts/quality-preview.js --changed-since HEAD --staged';
 
 /**
- * Default values seeded into `delivery.quality.{codingGuardrails,autoRefresh}`
- * when the keys are absent. Mirrors `.agents/docs/agentrc-reference.json` — keep in
- * sync when those numbers move.
+ * Mirrors `.agents/docs/agentrc-reference.json`. Other `autoRefresh` knobs are
+ * fixed constants; seeding them would write an invalid config.
  */
 const QUALITY_CONFIG_DEFAULTS = Object.freeze({
-  codingGuardrails: Object.freeze({
-    cyclomaticFlag: 8,
-    requireSiblingTest: false,
-  }),
-  autoRefresh: Object.freeze({
-    enabled: true,
-    crapJumpCap: 5,
-    scope: 'diff',
-  }),
+  autoRefresh: Object.freeze({ enabled: true }),
 });
 
-/**
- * NPM scripts seeded by the bootstrap. Existing values are preserved.
- */
 export const QUALITY_NPM_SCRIPTS = Object.freeze({
   'quality:preview':
     'node .agents/scripts/quality-preview.js --changed-since HEAD',
   'quality:watch': 'node .agents/scripts/quality-watch.js',
 });
 
-/**
- * Read JSON from a path, returning `null` when the file does not exist.
- * Surfaces parse errors so callers can fail loudly on a corrupt config.
- */
+/** `null` when absent; parse errors propagate so a corrupt config fails loudly. */
 function readJsonIfExists(p) {
   if (!fs.existsSync(p)) return null;
   const raw = fs.readFileSync(p, 'utf8');
@@ -120,16 +64,9 @@ function writeJson(p, obj) {
 }
 
 /**
- * Step 1 — Ensure the code-quality-guardrails helper is present under
- * `.agents/workflows/helpers/`. When the helper already exists we report
- * `already-present`. Otherwise the helper is copied from the framework source
- * if available, or skipped with a `missing-source` outcome the caller can
- * surface.
- *
  * @param {object} ctx
  * @param {string} ctx.projectRoot
- * @param {string} [ctx.frameworkRoot] - Path to the framework checkout
- *   (defaults to `<projectRoot>/.agents`). Tests pass an explicit path.
+ * @param {string} [ctx.frameworkRoot] - Defaults to `<projectRoot>/.agents`.
  */
 export function ensureGuardrailsHelper(ctx) {
   const projectRoot = ctx.projectRoot;
@@ -159,16 +96,8 @@ export function ensureGuardrailsHelper(ctx) {
 }
 
 /**
- * Step 2 — Install the `.husky/pre-commit` hook. Decision tree:
- *
- *   - No `.husky/pre-commit` file → write the requested body, action `created`.
- *   - File exists and already contains the quality-preview marker → no-op,
- *     action `already-present`.
- *   - File exists, does NOT contain the marker, and matches the framework
- *     body byte-for-byte → safe overwrite, action `updated`.
- *   - File exists, custom content → leave untouched and emit
- *     `custom-hook-skip` so the workflow can print the operator notice with
- *     the recommended snippet to merge in.
+ * Create the hook when absent; an existing hook without the marker is never
+ * overwritten — `custom-hook-skip` hands the operator the snippet to merge.
  *
  * @param {object} ctx
  * @param {string} ctx.projectRoot
@@ -209,14 +138,7 @@ export function ensurePreCommitHook(ctx) {
   };
 }
 
-/**
- * Step 3 — Register the `quality:preview` and `quality:watch` npm scripts
- * in the project's `package.json`. Existing values are preserved
- * unconditionally; this helper only adds missing keys.
- *
- * Returns the per-script outcome so the workflow can surface which scripts
- * were added vs already present.
- */
+/** Add missing quality npm scripts; existing values always win. */
 export function ensureQualityNpmScripts(ctx) {
   const pkgPath = path.join(ctx.projectRoot, 'package.json');
   const pkg = readJsonIfExists(pkgPath);
@@ -244,24 +166,13 @@ export function ensureQualityNpmScripts(ctx) {
 }
 
 /**
- * Deep-merge the requested defaults into an object, only setting keys that
- * are absent AND whose intended value diverges from the framework default
- * at that dotted path. The runtime layers `getAgentrcDefaults()`
- * underneath the project config at read time, so a key whose intended
- * value equals the framework default would be written redundantly — and
- * would then be flagged `[REDUNDANT]` by the sync-agentrc helper on the
- * next /mandrel-update. Default-aware seeding keeps the two helpers from
- * contradicting each other.
- *
- * Returns `{ merged, addedKeys[] }` so the caller can report exactly
- * which keys were seeded. Pure-default writes are reported under
- * `skippedKeys[]` so callers can surface why the seed was a no-op.
+ * Set only keys that are absent AND differ from the framework default — a
+ * default-equal write would be flagged `[REDUNDANT]` by sync-agentrc.
+ * Default-equal keys are reported in `skippedKeys`.
  *
  * @param {object} target
- * @param {object} defaults — the values the caller would seed if
- *   default-blindness were the policy.
- * @param {object} frameworkDefaults — the framework's resolved defaults
- *   at the seed root. Compared to each intended write.
+ * @param {object} defaults
+ * @param {object} frameworkDefaults — resolved defaults at the seed root.
  * @param {string} prefix — dotted path under construction.
  */
 function mergeMissingKeys(
@@ -309,13 +220,8 @@ function mergeMissingKeys(
 }
 
 /**
- * Step 4 — Seed the `delivery.quality.codingGuardrails` and
- * `delivery.quality.autoRefresh` defaults into `.agentrc.json`. Only
- * missing keys are added; existing values are preserved unconditionally
- * (including operator overrides that diverge from the framework defaults).
- *
- * When `.agentrc.json` does not exist the action is `missing-config` and
- * nothing is written — the project must complete its base bootstrap first.
+ * Seed missing quality defaults into `.agentrc.json`; writes nothing when the
+ * file is absent (base bootstrap must run first).
  */
 export function ensureQualityConfigDefaults(ctx) {
   const cfgPath = path.join(ctx.projectRoot, '.agentrc.json');
@@ -344,9 +250,7 @@ export function ensureQualityConfigDefaults(ctx) {
   if (addedKeys.length > 0) {
     writeJson(cfgPath, cfg);
   } else {
-    // No-op path — undo the scaffolding we inserted so the on-disk file
-    // and the in-memory snapshot agree (defensive; nothing reads cfg
-    // after this).
+    // Undo the scaffolding so memory matches disk.
     if (!hadQuality) delete cfg.delivery.quality;
     if (!hadDelivery) delete cfg.delivery;
   }
@@ -358,31 +262,17 @@ export function ensureQualityConfigDefaults(ctx) {
   };
 }
 
-/**
- * Repo-root-relative path of the retired committed per-Epic snapshot tree.
- * Module-private: exporting it would add a production-dead row to the
- * dead-exports ratchet for a two-word constant.
- */
+/** Private: exporting it would add a dead-exports row. */
 const LEGACY_EPIC_BASELINES_RELPATH = 'baselines/epic';
 
 /**
- * Step 5 — Prune a committed pre-v2 `baselines/epic/` tree (Story #5007).
- *
- * Story #1396 committed per-Epic ratchet snapshots under
- * `baselines/epic/<id>/`. The v2 Story-only model retired epics along with
- * every reader of those snapshots, and `check-baselines.js` resolves
- * baselines by fixed filename rather than by directory glob — so the tree is
- * inert, and the only remaining value in the retired layout migration was
- * getting it out of version control.
- *
- * `git rm -r --ignore-unmatch` stages the removal when the path is tracked
- * and is a safe no-op when it is not (fresh clone / untracked leftovers);
- * the on-disk residue is then removed so a re-run reports `absent`. The
- * caller commits the resulting working-tree delta.
+ * Remove the inert per-Epic snapshot tree no reader consults. `git rm
+ * --ignore-unmatch` stages it when tracked and no-ops otherwise; the caller
+ * commits the delta.
  *
  * @param {object} ctx
  * @param {string} ctx.projectRoot
- * @param {typeof defaultSpawnSync} [ctx.spawnImpl] — injectable spawn seam.
+ * @param {typeof defaultSpawnSync} [ctx.spawnImpl]
  * @returns {{ action: 'absent'|'pruned', path: string, gitStatus?: number|null }}
  */
 export function pruneLegacyEpicBaselines(ctx) {
@@ -411,10 +301,6 @@ export function pruneLegacyEpicBaselines(ctx) {
 }
 
 /**
- * Run all six steps in order. Composable wrapper used by the bootstrap
- * and update workflows. Each step's outcome is returned under its own key
- * so callers can render a per-action summary.
- *
  * @param {object} ctx
  * @param {string} ctx.projectRoot
  * @param {string} [ctx.frameworkRoot]

package/.agents/scripts/lib/bootstrap/summary.js

@@ -1,11 +1,4 @@
-/**
- * bootstrap/summary — Bootstrap result formatting + summary printing
- *
- * Pure formatting helpers (`format*Summary`) and the `printSummary`
- * presenter extracted from `agents-bootstrap-github.js` (Story #3349).
- * These render the `runBootstrap` result envelope into operator-facing
- * lines; they hold no provider coupling and no orchestration logic.
- */
+/** Renders the `runBootstrap` result envelope into operator-facing lines. */
 
 import { Logger } from '../Logger.js';