mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/bootstrap/issue-forms-template.js

@@ -1,47 +1,8 @@
 /**
- * bootstrap/issue-forms-template — Story #4227 (framework-gap)
- *
- * Generates the GitHub **Story Issue Form**
- * (`.github/ISSUE_TEMPLATE/story.yml`) derived from the canonical Story-body SSOT
- * (`lib/story-body/story-body.js`). The forms exist so a human filing a
- * Story in the GitHub web UI produces a body that round-trips through
- * the same `story-body.parse()` agents rely on — closing the
- * human↔agent ticket-shape gap.
- *
- * ## Why generated, not hand-authored
- *
- * Hand-authoring the forms would let the field headings drift from what
- * `parse()` expects. Instead the form field set is derived from a single
- * `HUMAN_INTENT_FIELDS` table here, and each field's heading is the exact
- * section name the parser maps (`goal` → `## Goal`, etc.). The CI
- * conformance lint (`lint-issue-body.js`) runs the real `parse()` against
- * human-opened issues so the form and the parser cannot silently drift.
- *
- * ## Form fields ⊆ body schema
- *
- * The forms expose only the human **intent subset** — `goal`, `changes`,
- * `acceptance`, `verify`, `references`. Machine-managed sections (the
- * `<!-- meta: … -->` block, the frozen dispatch manifest, `agent::*`
- * transitions) are deliberately absent; the runtime fills those. The
- * relationship is "form fields ⊆ body schema," not "form == body."
- *
- * ## GitHub serialization contract (the lossy seam)
- *
- * GitHub Issue Forms render every `textarea`/`input` field as:
- *
- * ```text
- * ### {label}
- *
- * {value}
- * ```
- *
- * i.e. the field label becomes a level-3 heading (`###`), not the level-2
- * (`##`) the canonical serializer emits. `story-body.parse()` accepts both
- * heading levels (Story #4227 widened its heading regex), so a body
- * assembled from form output round-trips. This is the single point where
- * the form shape and the canonical serializer differ, and it is covered by
- * the round-trip test that feeds simulated GitHub output back through
- * `parse()`.
+ * Generates the Story Issue Form from the Story-body SSOT so a human-filed
+ * body round-trips through `story-body.parse()`. Fields are only the human
+ * intent subset; the runtime fills machine-managed sections. GitHub renders
+ * labels as `###` headings, not `##` — `parse()` accepts both levels.
  *
  * @module bootstrap/issue-forms-template
  */
@@ -49,29 +10,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-/**
- * Directory (relative to a project root) GitHub reads issue forms from.
- * Internal — the per-form path constants below are the exported surface.
- */
 const ISSUE_TEMPLATE_RELATIVE_DIR = '.github/ISSUE_TEMPLATE';
 
-/**
- * Relative path of the generated Story form, surfaced as a constant so tests
- * and the bootstrap caller assert the canonical write target without
- * re-deriving it.
- */
 export const STORY_FORM_RELATIVE_PATH = `${ISSUE_TEMPLATE_RELATIVE_DIR}/story.yml`;
 
 /**
- * The human **intent subset** of the Story-body schema, in canonical
- * `parse()` section order. Each entry drives one form field. `heading` is
- * the exact section name `story-body.parse()` maps (case-insensitive); the
- * generated YAML uses it verbatim as the field `label` so GitHub's
- * `### {label}` render produces a heading the parser recognises.
- *
- * Machine-managed body fields (`wide`, `reason_to_exist`, `depends_on`
- * meta) are intentionally absent — the runtime fills those. `depends_on` is exposed as a free-text input
- * that serializes to the `blocked by #N` footer `parse()` already reads.
+ * Intent fields in `parse()` section order. `heading` must be the exact
+ * section name `parse()` maps, since GitHub renders the label as the heading.
  *
  * @type {Array<{
  *   id: string,
@@ -143,11 +88,7 @@ export const HUMAN_INTENT_FIELDS = [
 ];
 
 /**
- * Escape a string for safe embedding inside a double-quoted YAML scalar.
- * The generated YAML only ever quotes single-line scalars (labels,
- * descriptions, placeholders), so we escape backslashes, double quotes,
- * and collapse embedded newlines into the literal `\n` placeholder GitHub
- * renders verbatim in the form preview.
+ * Double-quoted single-line YAML scalar; newlines become literal `\n`.
  *
  * @param {string} value
  * @returns {string}
@@ -161,10 +102,6 @@ function yamlQuote(value) {
 }
 
 /**
- * Render a single Issue-Form field block (a `textarea` or `input`) from a
- * {@link HUMAN_INTENT_FIELDS} descriptor. Indented to sit under the
- * top-level `body:` sequence.
- *
  * @param {(typeof HUMAN_INTENT_FIELDS)[number]} field
  * @returns {string}
  */
@@ -182,10 +119,7 @@ function renderFieldBlock(field) {
 }
 
 /**
- * Render the shared `depends_on` input. Its value serializes (by the
- * conformance lint / body assembler) into the `blocked by #N` footer lines
- * `parse()` already extracts, so it stays out of the heading-mapped field
- * set above.
+ * `depends_on` serializes to `blocked by` footer lines, not a heading.
  *
  * @returns {string}
  */
@@ -204,17 +138,11 @@ function renderDependsOnBlock() {
 
 /**
  * @typedef {object} IssueFormOptions
- * @property {string} [entryStateLabel='agent::review-spec'] - Lifecycle
- *   entry-state label auto-applied alongside the `type::*` label so
- *   human-filed tickets land in the same lane as agent-created ones.
- * @property {string} [projectName] - Optional repo/project name woven into
- *   the form description. Purely cosmetic.
+ * @property {string} [entryStateLabel='agent::review-spec'] - Puts human-filed
+ *   tickets in the same lane as agent-created ones.
+ * @property {string} [projectName] - Cosmetic.
  */
 
-/**
- * Shared header banner stamped on every generated form so the provenance
- * (and the "regenerate, don't hand-edit" rule) travels with the file.
- */
 const GENERATED_BANNER =
   '# Generated by agents-bootstrap-github (Story #4227) from the Story-body SSOT\n' +
   '# (.agents/scripts/lib/story-body/story-body.js). Do NOT hand-edit the\n' +
@@ -223,12 +151,7 @@ const GENERATED_BANNER =
   '# (lint-issue-body.js) is the drift guard between this form and the parser.';
 
 /**
- * Render the GitHub Issue Form YAML for Stories. Epics are no longer a
- * ticket type in the label taxonomy, so the generated human-entry surface
- * is story-only.
- *
- * The output is deterministic so the round-trip + idempotency tests assert
- * on its exact shape.
+ * Deterministic Story form YAML.
  *
  * @param {'story'} ticketType
  * @param {IssueFormOptions} [opts]
@@ -268,12 +191,7 @@ ${renderDependsOnBlock()}
 }
 
 /**
- * Assemble a canonical Story-body markdown string from the per-field values
- * a GitHub Issue Form yields (keyed by field `id`). This is the inverse of
- * the form: it reconstructs what GitHub *would* serialize, using the
- * canonical `## {Heading}` form so the result feeds straight into
- * `story-body.parse()`. The conformance lint and the round-trip test use it
- * to prove the form → parser contract without a live GitHub call.
+ * Inverse of the form: canonical `## {Heading}` body from field values.
  *
  * @param {Record<string, string>} values - Field id → raw textarea/input value.
  * @returns {string} Canonical markdown body.
@@ -302,21 +220,11 @@ export function assembleBodyFromFormValues(values = {}) {
   return body;
 }
 
-/**
- * Relative path of the issue-body conformance workflow — the drift guard
- * that runs `story-body.parse()` against human-opened tickets.
- */
+/** The drift guard between the form and `story-body.parse()`. */
 export const CONFORMANCE_WORKFLOW_RELATIVE_PATH =
   '.github/workflows/issue-body-conformance.yml';
 
 /**
- * Render the CI workflow that runs the issue-body conformance lint
- * (`lint-issue-body.js`) on opened/edited `type::story` issues. This is
- * the mechanism that prevents the generated form and
- * `story-body.parse()` from silently drifting (Story #4227 acceptance).
- * Deterministic so the bootstrap test asserts its exact shape. Internal —
- * exposed to consumers only through {@link ensureIssueForms}.
- *
  * @returns {string}
  */
 function renderConformanceWorkflow() {
@@ -364,22 +272,13 @@ jobs:
 }
 
 /**
- * Write (or refresh) the Story issue form into a project checkout. Idempotent at
- * the byte level:
- *
- * - file absent → `created`
- * - byte-identical → `unchanged`
- * - operator-edited (differs from the rendered template) → `custom-skip`
- *   (the existing file is preserved; `rendered` is returned so the caller
- *   can offer a diff)
- *
- * Network-free; safe under tests with a tmp `projectRoot`.
+ * Write the form and its conformance workflow; an operator-edited file is
+ * preserved (`custom-skip`).
  *
  * @param {object} args
  * @param {string} args.projectRoot
  * @param {IssueFormOptions} [args.options]
- * @param {boolean} [args.write=true] - When `false`, compute the would-be
- *   actions without touching disk (dry-run).
+ * @param {boolean} [args.write=true] - `false` is a dry run.
  * @returns {{ forms: Array<{ type: 'story'|'conformance-workflow',
  *             action: 'created'|'unchanged'|'custom-skip',
  *             path: string, rendered: string }> }}
@@ -389,9 +288,6 @@ export function ensureIssueForms(args) {
   const options = args.options ?? {};
   const write = args.write !== false;
 
-  // Each target pairs a type key with the rendered body. The conformance
-  // workflow is materialized alongside the form because it is the form's
-  // drift guard — they ship as one unit.
   const targets = [
     {
       type: 'story',

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

@@ -1,33 +1,7 @@
 /**
- * bootstrap/manifest — single mutation-manifest source for the install
- * ledger (Story #3521, Feature #3515, Epic #3438).
- *
- * `buildMutationManifest(ctx)` enumerates every mutation the bootstrap
- * pipeline can perform as a flat, declarative array. Each entry carries five
- * fields:
- *
- *   - `phaseGroup` — one of the four groups (`ide-wiring`, `repo-config`,
- *     `github-admin`, `quality-gates`).
- *   - `target`     — the file path or remote resource the mutation touches.
- *   - `action`     — the verb describing the mutation (`create`, `merge`,
- *     `update`, `run`, `configure`).
- *   - `detail`     — a one-line operator-facing description of the change.
- *   - `reversible` — whether the operator can trivially undo the change
- *     (e.g. delete a created file) vs. a remote-admin mutation that is not
- *     a simple local revert.
- *
- * Story #3690 replaced the consent-first phased-approval install screen with
- * a plain summary+confirm loop, and Story #5007 removed the vestigial
- * machinery it left behind (the no-write `previewMutationManifest` renderer
- * and the `approvedGroups` set-threading). What survives is load-bearing:
- * `recordLedger` filters these entries into the install ledger, and
- * `mandrel uninstall` walks them — the `phaseGroup` string is the ledger's
- * grouping key, not an approval gate.
- *
- * The manifest describes *intended* mutations deterministically from the
- * project root; it does not read or mutate any file. Whether a given
- * mutation is a no-op on a particular clone (the file already carries the
- * wiring) is decided at execution time by the idempotent `ensure*` steps.
+ * Declarative manifest of every mutation bootstrap can perform, filtered into
+ * the install ledger and walked by `mandrel uninstall`. Describes intent only;
+ * whether a mutation is a no-op is decided by the idempotent `ensure*` steps.
  *
  * @module bootstrap/manifest
  */
@@ -35,9 +9,7 @@
 import path from 'node:path';
 
 /**
- * The four phase groups. Ledger/uninstall metadata only (Story #5007): every
- * manifest entry MUST carry exactly one of these values so the install ledger
- * can group and the uninstaller can select what a run actually landed.
+ * Ledger/uninstall grouping key, not an approval gate; every entry carries one.
  *
  * @type {Readonly<{ IDE_WIRING: 'ide-wiring', REPO_CONFIG: 'repo-config',
  *   GITHUB_ADMIN: 'github-admin', QUALITY_GATES: 'quality-gates' }>}
@@ -49,22 +21,12 @@ export const PHASE_GROUPS = Object.freeze({
   QUALITY_GATES: 'quality-gates',
 });
 
-/**
- * Frozen set of valid `phaseGroup` values, for validation and the
- * acceptance check. Derived from `PHASE_GROUPS` so the two never drift.
- *
- * @type {ReadonlySet<string>}
- */
+/** @type {ReadonlySet<string>} */
 export const PHASE_GROUP_VALUES = Object.freeze(
   new Set(Object.values(PHASE_GROUPS)),
 );
 
-/**
- * The five required fields on every manifest entry. Exported so tests and
- * downstream renderers can assert entry shape without re-declaring the list.
- *
- * @type {readonly string[]}
- */
+/** @type {readonly string[]} */
 export const MANIFEST_ENTRY_FIELDS = Object.freeze([
   'phaseGroup',
   'target',
@@ -76,33 +38,20 @@ export const MANIFEST_ENTRY_FIELDS = Object.freeze([
 /**
  * @typedef {object} MutationManifestEntry
  * @property {'ide-wiring'|'repo-config'|'github-admin'|'quality-gates'} phaseGroup
- *   — the independently-approvable group this mutation belongs to.
- * @property {string} target  — file path (relative to project root) or a
- *   remote-resource identifier the mutation touches.
- * @property {string} action  — verb describing the mutation.
+ * @property {string} target  — project-root-relative path or remote resource.
+ * @property {string} action
  * @property {string} detail  — one-line operator-facing description.
- * @property {boolean} reversible — true when the operator can trivially
- *   undo the change locally; false for remote-admin mutations.
+ * @property {boolean} reversible — false for remote-admin mutations.
  */
 
 /**
- * Build the consent-first mutation manifest for a project root.
- *
- * Returns a flat array of {@link MutationManifestEntry} objects covering
- * every mutation the bootstrap pipeline performs, partitioned across the
- * four {@link PHASE_GROUPS}. File targets are project-root-relative
- * forward-slash POSIX paths so the preview renders identically on every
- * platform; remote targets are scoped to the resolved `owner/repo` slug.
- *
- * The `github-admin` group is omitted when `ctx.skipGithub` is set, and the
- * `quality-gates` group is included only when `ctx.withQuality` is true, so
- * the preview reflects the same flags the executing pipeline honours.
+ * File targets are POSIX paths so output is platform-identical; the group
+ * set honours the same flags the executing pipeline does.
  *
  * @param {object} [ctx]
- * @param {{ owner?: string, repo?: string }} [ctx.answers] — scopes the
- *   `github-admin` targets to the `owner/repo` slug.
- * @param {boolean} [ctx.skipGithub] — omit the `github-admin` group.
- * @param {boolean} [ctx.withQuality] — include the `quality-gates` group.
+ * @param {{ owner?: string, repo?: string }} [ctx.answers]
+ * @param {boolean} [ctx.skipGithub]
+ * @param {boolean} [ctx.withQuality]
  * @returns {MutationManifestEntry[]}
  */
 export function buildMutationManifest(ctx = {}) {
@@ -110,15 +59,6 @@ export function buildMutationManifest(ctx = {}) {
 
   const entries = [];
 
-  // --- ide-wiring -------------------------------------------------------
-  // Claude Code / IDE integration: the system-prompt import, the generated
-  // flat command surface, and the .gitignore entry that keeps the
-  // generated tree out of git. (Story #4527/#4530: the UserPromptSubmit
-  // per-prompt re-sync hook entry was removed alongside the hook itself —
-  // it raced the harness's own read of the same directory and reported
-  // "0 file(s) synced" on effectively every invocation; the real sync
-  // points — `prepare`, `mandrel sync`/`update`, doctor's
-  // `commands-in-sync` — already cover every case.)
   entries.push(
     {
       phaseGroup: PHASE_GROUPS.IDE_WIRING,
@@ -146,10 +86,7 @@ export function buildMutationManifest(ctx = {}) {
     },
   );
 
-  // --- repo-config ------------------------------------------------------
-  // Local repository configuration files the bootstrap seeds or extends.
-  // Also includes git-init, which is the most irreversible local mutation
-  // the bootstrap performs (B1 — uninstall ledger must record it).
+  // git-init is the most irreversible local mutation; the ledger must record it.
   entries.push(
     {
       phaseGroup: PHASE_GROUPS.REPO_CONFIG,
@@ -185,9 +122,6 @@ export function buildMutationManifest(ctx = {}) {
     },
   );
 
-  // --- quality-gates ----------------------------------------------------
-  // Stabilized quality-gate surface (husky pre-commit, quality npm
-  // scripts, .agentrc quality defaults). Included only when opted in.
   if (ctx.withQuality) {
     entries.push(
       {
@@ -216,9 +150,6 @@ export function buildMutationManifest(ctx = {}) {
     );
   }
 
-  // --- github-admin -----------------------------------------------------
-  // Remote GitHub configuration. These are NOT trivially reversible local
-  // edits — they mutate remote repo/org admin state.
   if (!ctx.skipGithub) {
     const repoSlug =
       ctx.answers?.owner && ctx.answers?.repo
@@ -226,8 +157,6 @@ export function buildMutationManifest(ctx = {}) {
         : 'the GitHub repository';
     entries.push(
       {
-        // B1: GitHub repo creation is the most irreversible remote mutation —
-        // record it so the uninstall ledger always lists it.
         phaseGroup: PHASE_GROUPS.GITHUB_ADMIN,
         target: `${repoSlug} (repo)`,
         action: 'create',

package/.agents/scripts/lib/bootstrap/merge-methods.js

@@ -1,29 +1,7 @@
 /**
- * bootstrap/merge-methods — Epic #1235 Story 5
- *
- * Promotes the framework's hands-off-pipeline merge stance to the
- * consumer repo:
- *   - allow_squash_merge: true   — single commit per PR; clean history.
- *   - allow_rebase_merge: false  — no rebase-merge (status checks would
- *                                  need to be re-run per commit).
- *   - allow_merge_commit: false  — no merge commits cluttering the
- *                                  default branch.
- *   - allow_auto_merge: true     — required for the auto-merge label
- *                                  feature Story 1 delivered.
- *   - delete_branch_on_merge: true — head branches are throwaway.
- *
- * Behaviour rules
- * ---------------
- * No drift (live settings already match the target): no-op, returns
- * `{ status: 'unchanged' }`.
- *
- * Drift (any field differs from the target stance): when a `hitlConfirm`
- * gate is supplied, the proposed payload routes through it — on approval
- * the PATCH is issued; on decline the module returns
- * `{ status: 'skipped', reason: 'hitl-declined' }` without writing (a loud
- * decline, never silent). When NO gate is supplied (non-TTY, no operator
- * present — Story #4045 A4), the framework stance is default-applied with
- * an explicit log line.
+ * Applies the framework merge stance (squash-only, auto-merge on, delete head
+ * branches). On drift, a supplied `hitlConfirm` gate decides; with no gate
+ * (non-TTY) the stance is applied with an explicit log line.
  */
 
 export const TARGET_MERGE_METHODS = Object.freeze({
@@ -34,11 +12,7 @@ export const TARGET_MERGE_METHODS = Object.freeze({
   delete_branch_on_merge: true,
 });
 
-/**
- * Compute the drift between `current` (sparse) and the merged
- * (defaults+settings) target. Returns null when nothing diverges so the
- * caller can short-circuit before prompting HITL.
- */
+/** `null` when nothing diverges. */
 export function diffMergeMethods(current, target) {
   const diff = {};
   for (const key of Object.keys(target)) {
@@ -66,7 +40,6 @@ export async function applyMergeMethods({
   hitlConfirm,
   log = () => {},
 }) {
-  // Merge methods live under `github.mergeMethods`.
   const override = settings?.github?.mergeMethods ?? {};
   const target = { ...TARGET_MERGE_METHODS, ...override };
 
@@ -102,8 +75,6 @@ export async function applyMergeMethods({
       return { status: 'skipped', reason: 'hitl-declined', diff };
     }
   } else {
-    // Non-TTY: no operator present to confirm. Default-apply the framework
-    // stance and log explicitly so the consequence is never silent.
     log(
       '[Bootstrap] Merge methods: non-TTY — applying framework stance automatically ' +
         '(allow_squash_merge, allow_auto_merge, delete_branch_on_merge). ' +

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

@@ -1,23 +1,6 @@
 /**
- * bootstrap/preflight — unified prerequisite preflight (Story #3375).
- *
- * Aggregates the cold-start prerequisite checks into a single
- * fail-before-mutate gate that `bootstrap.js` runs as the FIRST pipeline
- * phase, ahead of any project-side or GitHub-side mutation:
- *
- *   - Node version  — reuses `checkNodeVersion` from `project-bootstrap.js`.
- *   - git available — `git --version` resolves on PATH.
- *   - inside-work-tree — `git rev-parse --is-inside-work-tree` is true.
- *   - gh CLI + auth — reuses `preflightGh` from `gh-preflight.js`; skipped
- *     entirely when `skipGithub` is true.
- *
- * `runPreflight({ skipGithub })` returns `{ ok, checks }` where `ok` is
- * false when any check failed. Every failing check carries a `remedy`
- * string so the CLI can print actionable next steps before halting.
- *
- * The runner seams (`nodeCheck`, `gitRunner`, `gh`) default to the real
- * implementations and are injectable so the unit test can drive every
- * branch without spawning real child processes.
+ * Fail-before-mutate prerequisite gate run before any bootstrap mutation.
+ * Every failing check carries a `remedy`.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -32,10 +15,6 @@ const NODE_REMEDY = (result) =>
   `Node ${result.version} is below required ${result.required}. Upgrade Node (https://nodejs.org/) and re-run this command.`;
 
 /**
- * Default git runner: synchronously execs `git <args>` and returns the
- * normalized `{ status, stdout, stderr, error }` shape. Extracted so the
- * preflight tests can inject a stub without spawning a real child process.
- *
  * @param {string[]} args
  * @returns {{ status: number|null, stdout: string, stderr: string,
  *             error?: NodeJS.ErrnoException }}
@@ -51,9 +30,6 @@ function defaultGitRunner(args) {
 }
 
 /**
- * Probe Node version via the injected `nodeCheck` seam (defaults to
- * `checkNodeVersion`). Returns a check record.
- *
  * @param {() => { ok: boolean, version: string, required: string }} nodeCheck
  * @returns {{ name: string, ok: boolean, remedy?: string }}
  */
@@ -64,8 +40,6 @@ function checkNode(nodeCheck) {
 }
 
 /**
- * Probe `git --version` for availability on PATH.
- *
  * @param {(args: string[]) => { status: number|null, stdout: string,
  *   stderr: string, error?: NodeJS.ErrnoException }} gitRunner
  * @returns {{ name: string, ok: boolean, remedy?: string }}
@@ -89,9 +63,6 @@ function checkGitAvailable(gitRunner) {
 }
 
 /**
- * Probe `git rev-parse --is-inside-work-tree` to confirm the command is
- * running inside a git work tree.
- *
  * @param {(args: string[]) => { status: number|null, stdout: string,
  *   stderr: string, error?: NodeJS.ErrnoException }} gitRunner
  * @returns {{ name: string, ok: boolean, remedy?: string }}
@@ -109,10 +80,6 @@ function checkInsideWorkTree(gitRunner) {
 }
 
 /**
- * Probe the `gh` CLI + auth via the injected `gh` seam (defaults to
- * `preflightGh`). Maps the typed errors `preflightGh` throws into a
- * single failing check carrying the error message as the remedy.
- *
  * @param {(opts?: object) => Promise<{ version: string }>} gh
  * @returns {Promise<{ name: string, ok: boolean, remedy?: string }>}
  */
@@ -126,28 +93,17 @@ async function checkGh(gh) {
 }
 
 /**
- * Run every prerequisite check and aggregate them into a single result.
- *
  * @param {object} [opts]
- * @param {boolean} [opts.skipGithub=false] — when true, skip the `gh` CLI
- *   + auth check (the Node and git checks always run).
- * @param {boolean} [opts.requireWorkTree=true] — when true (the default,
- *   used by `bootstrap.js`), being outside a git work tree FAILS the gate.
- *   When false (`bootstrap-new.js`), the work-tree probe is informational:
- *   it never fails the gate and its result is reported via the returned
- *   `gitInitialized` flag so later steps can fill in the missing git state.
- * @param {boolean} [opts.checkProjectScope=false] — when true (and
- *   `skipGithub` is false), also verify the `gh` token carries the
- *   `project` scope needed to read/modify GitHub Projects V2.
+ * @param {boolean} [opts.skipGithub=false]
+ * @param {boolean} [opts.requireWorkTree=true] — false makes the work-tree
+ *   probe informational (reported via `gitInitialized`); git is initialised later.
+ * @param {boolean} [opts.checkProjectScope=false]
  * @param {() => { ok: boolean, version: string, required: string }}
- *   [opts.nodeCheck] — Node-version seam (defaults to `checkNodeVersion`).
- * @param {(args: string[]) => object} [opts.gitRunner] — git runner seam
- *   (defaults to a real `spawnSync('git', …)`).
- * @param {(opts?: object) => Promise<{ version: string }>} [opts.gh] —
- *   `gh` preflight seam (defaults to `preflightGh`).
+ *   [opts.nodeCheck]
+ * @param {(args: string[]) => object} [opts.gitRunner]
+ * @param {(opts?: object) => Promise<{ version: string }>} [opts.gh]
  * @param {() => Promise<{ name: string, ok: boolean, remedy?: string }>}
- *   [opts.projectScope] — project-scope seam (defaults to
- *   `checkProjectScopes`).
+ *   [opts.projectScope]
  * @returns {Promise<{ ok: boolean, gitInitialized: boolean,
  *   checks: Array<{ name: string, ok: boolean, remedy?: string }> }>}
  */
@@ -164,8 +120,7 @@ export async function runPreflight(opts = {}) {
 
   const gitAvailable = checkGitAvailable(gitRunner);
   checks.push(gitAvailable);
-  // The inside-work-tree probe only makes sense when git itself resolved;
-  // if git is missing the rev-parse error is redundant noise.
+  // Without git, the work-tree probe is redundant noise.
   let gitInitialized = false;
   if (gitAvailable.ok) {
     const workTree = checkInsideWorkTree(gitRunner);
@@ -173,11 +128,7 @@ export async function runPreflight(opts = {}) {
     if (requireWorkTree) {
       checks.push(workTree);
     } else {
-      // Non-fatal detection: record whether we are inside a git repo but
-      // never fail the gate on it — bootstrap initialises git in a later
-      // phase. `ok` stays true so the gate passes; the rendered glyph is
-      // driven off `gitInitialized` (✓ when a repo exists, ✗ when not) so the
-      // operator sees the real state without the run aborting.
+      // `ok` stays true; the rendered glyph reads `gitInitialized`.
       checks.push({
         name: 'Local git initialized',
         ok: true,