mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/onboard/init-tail.js

@@ -1,23 +1,8 @@
 /**
- * init-tail.js — post-bootstrap onboarding tail for `mandrel init`.
- *
- * Called by `mandrel init` after `bootstrap.js` completes successfully on
- * the "configure now" path. Sequences the three phases that walk an operator
- * from a freshly bootstrapped project to a ready-to-plan workspace:
- *
- *   Phase 1 — Offer to scaffold missing docsContextFiles (scaffold-docs.js).
- *   Phase 2 — Run `mandrel doctor` as a readiness gate.
- *   Phase 3 — Print the /mandrel-plan handoff next-step text.
- *
- * The whole tail is idempotent: re-running after an already-onboarded project
- * re-checks and re-offers scaffolding without duplicating stubs (the scaffolder
- * only writes genuinely absent files) and without modifying anything (doctor is
- * read-only).
- *
- * Injectable seams: `runDoctor`, `stdout`, `confirmScaffold`, and `isTTY`
- * allow the unit suite to drive every branch without real I/O.
- *
- * Story #4045 (refs #4045).
+ * init-tail.js — `mandrel init`'s post-bootstrap tail: offer to scaffold
+ * missing docsContextFiles, gate on `mandrel doctor`, then print the
+ * `/mandrel-plan` handoff. Idempotent: the scaffolder writes only absent
+ * files and doctor is read-only.
  */
 
 import { spawnSync as defaultSpawnSync } from 'node:child_process';
@@ -26,26 +11,14 @@ import readline from 'node:readline/promises';
 
 import { STUB_MARKER, scaffoldDocs } from './scaffold-docs.js';
 
-// ---------------------------------------------------------------------------
-// Phase text constants
-// ---------------------------------------------------------------------------
-
 /**
- * Text printed at the end of the init tail to hand the operator off to /mandrel-plan.
- *
  * @type {string}
  */
 export const PLAN_HANDOFF_TEXT =
   '\n✅  Mandrel is ready. Start your first project:\n\n' +
   '    /mandrel-plan --seed "<one-line description of what you want to build>"\n';
 
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
 /**
- * Format a list of missing docs as a human-readable report (no prompt).
- *
  * @param {string[]} missing
  * @returns {string}
  */
@@ -63,23 +36,9 @@ function formatMissingList(missing) {
 const SCAFFOLD_PROMPT = '\nCreate placeholders? [y/N]: ';
 
 /**
- * Async y/N read from stdin via `node:readline` (mirrors the prompt mechanism
- * in `bootstrap.js`). Returns on Enter and never blocks waiting for EOF the way
- * `fs.readFileSync(0)` did — that EOF-blocking read hung `mandrel init` on an
- * interactive TTY. No is the default (`[y/N]`): only an explicit `y`/`yes`
- * resolves to `true` (create the placeholders). A bare Enter or any other input
- * declines, matching the same default-off policy as `--with-issue-forms`. A
- * read error resolves to `false` so a genuine I/O failure never writes
- * unattended. The prompt text is written by the caller via `stdout`, so the
- * question string passed here is empty.
- *
- * `terminal: false` is **load-bearing**: with terminal mode on (the default
- * when stdout is a TTY) readline emits cursor-control escapes
- * (`\x1b[1G\x1b[0J`) that erase the `Create placeholders? [y/N]:` prompt already
- * written via the caller's `stdout`, leaving the operator staring at a blank,
- * dead-looking line. Disabling terminal mode preserves the pre-written prompt
- * and reads the line via the TTY's cooked-mode echo. `createInterface` is
- * injectable so a test can assert this option is set (regression guard).
+ * y/N (default No; a read error declines). Readline, because a blocking
+ * `fs.readFileSync(0)` hangs on a TTY. `terminal: false` is load-bearing:
+ * terminal mode's cursor escapes erase the caller's pre-written prompt.
  *
  * @param {{ createInterface?: typeof readline.createInterface }} [opts]
  * @returns {Promise<boolean>}
@@ -102,24 +61,13 @@ export async function readConfirm({
   }
 }
 
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
 /**
- * Run the post-bootstrap init tail.
- *
  * @param {object} [opts]
- * @param {string} [opts.root] - Project root (defaults to `process.cwd()`).
- * @param {(msg: string) => void} [opts.stdout] - Output sink (defaults to
- *   `process.stdout.write` bound to `process.stdout`).
- * @param {() => boolean} [opts.confirmScaffold] - Read the operator's y/N
- *   answer for the scaffold offer. Returns `true` to scaffold. In non-TTY
- *   contexts defaults to `false` (no write without operator confirmation).
+ * @param {string} [opts.root]
+ * @param {(msg: string) => void} [opts.stdout]
+ * @param {() => boolean} [opts.confirmScaffold]
  * @param {(extraArgs?: string[]) => { status: number|null }} [opts.runDoctor]
- *   - Run `mandrel doctor`; injectable for tests.
- * @param {boolean} [opts.isTTY] - Whether stdin is a TTY (defaults to
- *   `Boolean(process.stdin.isTTY)`).
+ * @param {boolean} [opts.isTTY]
  * @returns {Promise<{
  *   scaffoldResult: object,
  *   doctorStatus: number,
@@ -136,14 +84,11 @@ export async function runInitTail({
   const projectRoot = root ?? process.cwd();
   const tty = isTTY ?? Boolean(process.stdin.isTTY);
 
-  // When confirmScaffold is explicitly injected (e.g. from tests), always use
-  // it. When using the default, auto-decline on non-TTY so the scaffolder
-  // never writes unattended.
+  // An injected confirm is always consulted; the default auto-declines off a
+  // TTY so the scaffolder never writes unattended.
   const usingDefaultConfirm = confirmScaffold == null;
   const confirmFn = confirmScaffold ?? readConfirm;
 
-  // Default doctor runner — spawns `mandrel doctor` via the locally installed
-  // bin; inherits stdio so the report streams to the terminal.
   const mandrelBin = path.join(
     projectRoot,
     'node_modules',
@@ -159,7 +104,6 @@ export async function runInitTail({
 
   const doctorFn = runDoctor ?? defaultRunDoctor;
 
-  // --- Phase 1: Offer to scaffold missing docsContextFiles -----------------
   const preview = scaffoldDocs({ root: projectRoot, write: false });
   let scaffoldResult = preview;
 
@@ -167,9 +111,6 @@ export async function runInitTail({
     stdout('\n[Final Checks] All docsContextFiles are present.\n');
   } else {
     stdout(formatMissingList(preview.missing));
-    // On non-TTY without an injected confirm, auto-decline so the scaffolder
-    // never writes unattended. On TTY (or with an injected confirm seam), show
-    // the prompt and consult the confirm function.
     const canPrompt = tty || !usingDefaultConfirm;
     if (canPrompt) stdout(SCAFFOLD_PROMPT);
     const accepted = canPrompt ? await confirmFn() : false;
@@ -187,7 +128,6 @@ export async function runInitTail({
     }
   }
 
-  // --- Phase 2: Readiness gate (mandrel doctor) ----------------------------
   stdout('\n[Final Checks] Final installation summary via mandrel doctor…\n');
   const doctorResult = doctorFn();
   const doctorStatus = doctorResult?.status ?? 1;
@@ -200,7 +140,6 @@ export async function runInitTail({
     return { scaffoldResult, doctorStatus, ok: false };
   }
 
-  // --- Phase 3: Handoff to /mandrel-plan -------------------------------------------
   stdout(PLAN_HANDOFF_TEXT);
   return { scaffoldResult, doctorStatus, ok: true };
 }

package/.agents/scripts/lib/onboard/scaffold-docs.js

@@ -1,15 +1,8 @@
 /**
- * Guided-onboard doc scaffolder (Epic #3438 Story #3519).
- *
- * Detects which of the project's configured `project.docsContextFiles` are
- * absent under the resolved docs root, and — on acceptance — scaffolds a stub
- * for each missing file. Stubs are seeded from a dedicated template under
- * `.agents/templates/docs/<name>` when one ships; otherwise a generic
- * placeholder stub is written so the mandatory-read never resolves to a
- * missing file.
- *
- * The detection pass is side-effect free: callers can preview the missing set
- * (`scaffoldDocs({ write: false })`) before deciding whether to scaffold.
+ * Guided-onboard doc scaffolder: find the configured
+ * `project.docsContextFiles` missing under the docs root and, when `write`,
+ * stub each one (from `.agents/templates/docs/<name>` when shipped, else a
+ * generic placeholder). `write: false` is a side-effect-free preview.
  *
  * @module lib/onboard/scaffold-docs
  */
@@ -25,18 +18,14 @@ const AGENT_ROOT = path.resolve(__dirname, '../../..');
 const DOCS_TEMPLATE_DIR = path.join(AGENT_ROOT, 'templates', 'docs');
 
 /**
- * Deterministic marker written into every scaffolded stub. The `/mandrel-plan`
- * first-run preflight (and any tooling that wants to detect unedited stubs)
- * keys off this exact string — do not change it without a hard cutover.
+ * Marker in every stub; the `/mandrel-plan` first-run preflight detects
+ * unedited stubs by this exact string — changing it is a hard cutover.
  *
  * @type {string}
  */
 export const STUB_MARKER = '<!-- MANDREL:STUB -->';
 
 /**
- * Build the generic placeholder stub for a docsContextFile that has no
- * dedicated template. Derives a human-readable title from the filename.
- *
  * @param {string} fileName - e.g. `data-dictionary.md`
  * @returns {string}
  */
@@ -57,11 +46,6 @@ function genericStub(fileName) {
 }
 
 /**
- * Read the dedicated template body for a docsContextFile, or fall back to the
- * generic stub when no template ships for that name. Either path prepends the
- * {@link STUB_MARKER} so the `/mandrel-plan` first-run preflight can detect un-edited
- * stubs regardless of whether a dedicated template was used.
- *
  * @param {string} fileName
  * @param {import('node:fs')} fsImpl
  * @returns {string}
@@ -70,25 +54,19 @@ function stubContentFor(fileName, fsImpl) {
   const templatePath = path.join(DOCS_TEMPLATE_DIR, fileName);
   if (fsImpl.existsSync(templatePath)) {
     const body = fsImpl.readFileSync(templatePath, 'utf8');
-    // Prepend the marker only when absent (idempotent; the template files
-    // themselves are kept marker-free so they read cleanly as documentation).
+    // Templates stay marker-free so they read cleanly as documentation.
     return body.startsWith(STUB_MARKER) ? body : `${STUB_MARKER}\n${body}`;
   }
   return genericStub(fileName);
 }
 
 /**
- * Detect missing docsContextFiles and, on acceptance, scaffold stubs.
- *
  * @param {object} [opts]
  * @param {string} [opts.root] - Project root to resolve config + docs root
- *   against. Defaults to the resolver's `PROJECT_ROOT`.
- * @param {string[]} [opts.docsContextFiles] - Override the configured list
- *   (primarily for tests). Falls back to `project.docsContextFiles`.
- * @param {string} [opts.docsRoot] - Override the resolved docs-root directory
- *   name (relative to `root`). Falls back to `project.paths.docsRoot`.
- * @param {boolean} [opts.write=true] - When `false`, only detect (no files are
- *   created). When `true` (acceptance), scaffold each missing file.
+ *   against.
+ * @param {string[]} [opts.docsContextFiles] - Override the configured list.
+ * @param {string} [opts.docsRoot] - Override the docs-root directory name.
+ * @param {boolean} [opts.write=true] - `false` only detects.
  * @param {import('node:fs')} [opts.fs] - Injectable fs implementation.
  * @returns {{
  *   docsRoot: string,
@@ -126,7 +104,6 @@ export function scaffoldDocs(opts = {}) {
     fsImpl.mkdirSync(docsRootAbs, { recursive: true });
     for (const fileName of missing) {
       const target = path.join(docsRootAbs, fileName);
-      // Guard against nested paths whose parent dir is absent.
       fsImpl.mkdirSync(path.dirname(target), { recursive: true });
       fsImpl.writeFileSync(target, stubContentFor(fileName, fsImpl), 'utf8');
       created.push(fileName);

package/.agents/scripts/lib/orchestration/acceptance-eval-decision.js

@@ -1,57 +1,8 @@
 /**
- * Acceptance self-eval decision core (Story #3819).
- *
- * Pure reducer that turns one round's critic verdict plus the resolved
- * round cap into the loop's next action. The CLI wrapper
- * (`acceptance-eval.js`) owns the file reads, schema validation, signal
- * emission, and ticket transitions; this module owns the *decision* so it
- * can be unit-tested in isolation.
- *
- * ## Round derivation (Story #4019)
- *
- * The round number is **derived from the signals ledger**, not from the
- * critic's self-reported `verdict.round`: every prior round appended one
- * `acceptance-eval` signal to the Story's `signals.ndjson`, so the
- * current round is `count(prior signals) + 1`. This survives a subagent
- * restart (the ledger is on disk) and removes the critic's scratch value
- * from the cap enforcement path — a critic that always reports `round: 1`
- * can no longer defeat the bounded-loop guarantee.
- *
- * ## Reading a verdict is not a round (Story #4874)
- *
- * Counting signals made *observation* costly: re-running the gate over an
- * already-scored verdict — a resumed sub-agent re-reading its own verdict,
- * an operator re-checking why the loop said `redraft` — appended another
- * signal and advanced the derived round, so a `redraft` could escalate to
- * `block` with no work in between. Every appended signal therefore carries
- * a `details.verdictFingerprint` content-addressing the verdict it scored,
- * and {@link resolveAcceptanceEvalRound} replays the round already recorded
- * for that fingerprint instead of minting a new one. A replay is observably
- * free: the round does not advance and no signal is appended. New work
- * produces different verdict content, hence a new fingerprint, hence a
- * genuine round.
- *
- * ## The three terminal actions
- *
- *   - `proceed`  — every criterion is `met`. The Story may flip to
- *                  `closing`.
- *   - `redraft`  — at least one criterion is `partial`/`unmet` AND the
- *                  current round is below the cap. The agent reworks the
- *                  flagged criteria and re-runs the eval pass.
- *   - `block`    — at least one criterion is `partial`/`unmet` AND the
- *                  current round has reached (or somehow exceeded) the cap.
- *                  The Story escalates to `agent::blocked`; it never
- *                  silently proceeds to close.
- *
- * ## The cap
- *
- * `maxRounds` arrives normalized by `lib/config/acceptance-eval.js` as a
- * non-negative integer (Story #5313: `0` means "score once, no redraft").
- * This reducer maps that onto an effective cap of scored rounds: a cap of
- * `0`, a negative value or a non-integer is coerced to 1, so there is no
- * input — config or verdict — that yields an unbounded `redraft` chain.
- * When `round >= effectiveCap` and criteria remain unmet, the only
- * possible action is `block`.
+ * Acceptance-eval decision core: verdict + cap → `proceed`, `redraft`, or
+ * `block` (unmet at cap; never a silent close). The round comes from the
+ * signals ledger, never the critic's own `round`, so a critic cannot defeat
+ * the cap; re-scoring an identical verdict replays its round.
  */
 
 import { createHash } from 'node:crypto';
@@ -59,21 +10,13 @@ import { readFileSync } from 'node:fs';
 
 import { runArtifactPath, signalsFile } from '../config/temp-paths.js';
 
-/** Epic-level signals stream basename (mirrors signals-writer). */
 const EPIC_SIGNALS_BASENAME = 'signals.ndjson';
 
-/**
- * Verdicts that clear a criterion. Anything else (`partial`, `unmet`, or
- * an unrecognised value) is treated as not-yet-met and triggers rework.
- *
- * @type {ReadonlySet<string>}
- */
+/** @type {ReadonlySet<string>} */
 const MET_VERDICTS = Object.freeze(new Set(['met']));
 
 /**
- * Coerce a candidate cap to a positive integer ≥ 1. This is the
- * last-line guard against an open loop: any degraded cap falls back to a
- * single round rather than an unbounded one.
+ * Integer ≥ 1 — the last guard against an unbounded redraft loop.
  *
  * @param {unknown} value
  * @returns {number}
@@ -86,10 +29,6 @@ function effectiveCap(value) {
 }
 
 /**
- * Partition a verdict's criteria into met and not-met buckets, preserving
- * order and capturing the evidence for the not-met items (used to compose
- * the blocker comment and the per-criterion signal).
- *
  * @param {Array<{ index?: number, criterion?: string, verdict?: string, evidence?: string }>} criteria
  * @returns {{
  *   metCount: number,
@@ -117,19 +56,10 @@ function partitionCriteria(criteria) {
 }
 
 /**
- * Decide the next loop action from a single round's verdict.
- *
  * @param {object} args
- * @param {{ criteria?: Array<object> }} args.verdict
- *   A verdict already validated against the acceptance-eval-verdict schema.
- *   Its `round` field, when present, is ignored — the round is supplied by
- *   the caller (derived from the signals ledger; Story #4019).
+ * @param {{ criteria?: Array<object> }} args.verdict Its own `round` is ignored.
  * @param {number} args.maxRounds
- *   The resolved (already-clamped) redraft ceiling from
- *   `getAcceptanceEval(config).maxRounds`.
- * @param {number} [args.round]
- *   The current round number, derived via `resolveAcceptanceEvalRound`.
- *   Defaults to 1 when absent or invalid.
+ * @param {number} [args.round] From `resolveAcceptanceEvalRound`.
  * @returns {{
  *   decision: 'proceed' | 'redraft' | 'block',
  *   round: number,
@@ -169,18 +99,14 @@ export function decideAcceptanceEval({ verdict, maxRounds, round: roundIn }) {
 }
 
 /**
- * Build the per-criterion acceptance-eval signal payload for the retro /
- * feedback substrate. Carries which acceptance items needed rework and the
- * round count so `/mandrel-plan` Phase 0 feedback fetch and the retro can
- * surface acceptance churn. PII-free by construction — it carries only
- * acceptance-item indices, verdicts, and the terminal decision.
+ * PII-free by construction: indices, verdicts and the decision only.
  *
  * @param {object} args
  * @param {number} args.storyId
  * @param {number | null} args.epicId
  * @param {ReturnType<typeof decideAcceptanceEval>} args.outcome
  * @param {string} [args.phase]
- * @returns {object} The signal record (sans `ts`, which the caller stamps).
+ * @returns {object} The record without `ts` (the caller stamps it).
  */
 export function buildAcceptanceEvalSignal({
   storyId,
@@ -194,18 +120,12 @@ export function buildAcceptanceEvalSignal({
     kind: 'acceptance-eval',
     epicId: epicId ?? null,
     storyId: storyId ?? null,
-    // Epic #4475 (M4-B): single-delivery acceptance critics score an AC
-    // *cluster*, not a Story. `clusterId` scopes the per-cluster round count
-    // on the epic-level signals stream; omitted (null) for the per-Story path.
     ...(typeof clusterId === 'string' && clusterId.length > 0
       ? { clusterId }
       : {}),
     phase,
     emitter: { tool: 'acceptance-eval.js' },
     details: {
-      // Content address of the verdict this signal scored. The replay guard
-      // in `resolveAcceptanceEvalRound` matches on it, so a re-read of an
-      // already-scored verdict reuses its round instead of minting one.
       ...(typeof verdictFingerprint === 'string' &&
       verdictFingerprint.length > 0
         ? { verdictFingerprint }
@@ -225,27 +145,19 @@ export function buildAcceptanceEvalSignal({
 }
 
 /**
- * Read the `acceptance-eval` records already appended to the Story's (or AC
- * cluster's) `signals.ndjson`, in append order — the prior rounds
- * {@link resolveAcceptanceEvalRound} counts from (Story #4019).
- *
- * The read is restart-safe: the ledger lives on disk, so a subagent that
- * dies mid-loop and restarts still observes every prior round. A missing or
- * unreadable ledger degrades to "no prior rounds" and malformed lines are
- * skipped — observability corruption never wedges the gate.
+ * Prior rounds' records, oldest first. A missing ledger or malformed line
+ * never wedges the gate. `clusterId` counts per AC cluster on the epic-level
+ * stream.
  *
  * @param {object} args
- * @param {number|null} args.epicId   Parent Epic ID, or `null` for a
- *   standalone Story (routes to `<tempRoot>/standalone/stories/...`).
+ * @param {number|null} args.epicId
  * @param {number} args.storyId
- * @param {string|null} [args.clusterId] AC-cluster id (Epic #4475 M4-B).
- * @param {object} [args.config]      Resolved config (tempRoot resolution).
- * @param {(p: string) => string} [args.readFile]  Injectable reader (tests).
+ * @param {string|null} [args.clusterId]
+ * @param {object} [args.config]
+ * @param {(p: string) => string} [args.readFile]
  * @param {(eid: number|null, sid: number, config?: object) => string} [args.signalsPathResolver]
- *   Injectable path resolver (tests). Defaults to `signalsFile`.
  * @param {(eid: number, config?: object) => string} [args.epicSignalsPathResolver]
- *   Injectable epic-stream path resolver (tests).
- * @returns {object[]} The matching records, oldest first.
+ * @returns {object[]}
  */
 function readPriorAcceptanceEvalRecords({
   epicId,
@@ -257,10 +169,6 @@ function readPriorAcceptanceEvalRecords({
   epicSignalsPathResolver = (eid, cfg) =>
     runArtifactPath(eid, EPIC_SIGNALS_BASENAME, cfg),
 }) {
-  // Epic #4475 (M4-B): single-delivery critics score AC clusters, not
-  // Stories. When `clusterId` is supplied the round is counted per cluster
-  // off the epic-level signals stream; otherwise the per-Story path
-  // (unchanged) counts by `storyId` off the Story's stream.
   const clusterMode =
     typeof clusterId === 'string' &&
     clusterId.length > 0 &&
@@ -272,7 +180,6 @@ function readPriorAcceptanceEvalRecords({
       ? readFile(epicSignalsPathResolver(epicId, config))
       : readFile(signalsPathResolver(epicId ?? null, storyId, config));
   } catch (_err) {
-    // No ledger yet → no prior rounds.
     return [];
   }
 
@@ -284,7 +191,7 @@ function readPriorAcceptanceEvalRecords({
     try {
       record = JSON.parse(trimmed);
     } catch (_err) {
-      continue; // Malformed line — skip, never throw.
+      continue;
     }
     if (!record || typeof record !== 'object') continue;
     if (record.kind !== 'acceptance-eval') continue;
@@ -299,19 +206,11 @@ function readPriorAcceptanceEvalRecords({
 }
 
 /**
- * Content-address a verdict so re-scoring the same verdict is recognisable
- * as a re-read rather than a new round (Story #4874).
- *
- * The fingerprint covers exactly what the decision depends on — the ordered
- * per-criterion `index` / `criterion` / `verdict` / `evidence` tuples — and
- * deliberately nothing else: the verdict's self-reported `round`, its
- * timestamp, and any authoring scratch must not make an unchanged
- * evaluation look like a new one. Conversely, real rework changes at least
- * one criterion's verdict or its evidence, so a genuine re-evaluation
- * always fingerprints differently.
+ * Hashes only what the decision depends on, so an unchanged evaluation
+ * fingerprints the same and real rework does not.
  *
  * @param {{ criteria?: Array<object> }} verdict
- * @returns {string} 16 hex chars of a SHA-256 over the canonical form.
+ * @returns {string}
  */
 export function computeVerdictFingerprint(verdict) {
   const criteria = Array.isArray(verdict?.criteria) ? verdict.criteria : [];
@@ -328,23 +227,10 @@ export function computeVerdictFingerprint(verdict) {
 }
 
 /**
- * Resolve the round a verdict should be scored under, distinguishing a
- * genuine evaluation from a re-read of an already-scored verdict
- * (Story #4874). A genuine round is `prior-signal count + 1`, so the first
- * run reports round 1 and each completed round advances it by one.
- *
- * When the ledger already carries an `acceptance-eval` signal whose
- * `details.verdictFingerprint` matches, this invocation is a **replay**: it
- * reports that signal's round and tells the caller not to append a second
- * one, so reading is observably free and cannot escalate a `redraft` into a
- * `block`. Otherwise it is a genuine round and the counter advances exactly
- * as the pre-#4874 count-based derivation always did.
- *
- * Signals written before this field existed carry no fingerprint; they can
- * never match, so legacy ledgers keep their count-based behaviour.
+ * A matching recorded fingerprint is a replay of that round (the caller must
+ * not append); otherwise `prior count + 1`.
  *
- * @param {object} args — {@link readPriorAcceptanceEvalRecords}'s arguments
- *   plus:
+ * @param {object} args — {@link readPriorAcceptanceEvalRecords}'s args, plus:
  * @param {string} args.verdictFingerprint
  * @returns {{ round: number, replay: boolean }}
  */

package/.agents/scripts/lib/orchestration/auto-merge-cwd.js

@@ -1,56 +1,17 @@
 /**
- * auto-merge-cwd.js — resolve a worktree-collision-safe cwd for arming
- * GitHub native auto-merge (Story #4282).
- *
- * Root cause this module exists to defeat:
- *   Arming auto-merge runs, in effect,
- *   `gh pr merge <pr> --auto --squash --delete-branch`. The
- *   `--delete-branch` flag makes `gh` shell out to local `git` to leave
- *   and delete the PR head branch — including a `git checkout <base>` to
- *   switch the working tree off the head branch. When the arm runs from a
- *   per-Story worktree cwd (checked out on the head branch `story-<id>`)
- *   while the base branch (`main`) is already occupied by the primary
- *   worktree, `gh`'s internal `git checkout <base>` collides:
- *
- *     fatal: '<base>' is already used by worktree at '<primary>'
- *
- *   The arm fails (non-fatally), defeating the unattended auto-merge
- *   contract — the operator must re-run the merge manually from a clean cwd.
- *
- * Fix (advisory direction #1 from the Story — "ensure the cwd is already
- * on the base branch so gh's `git checkout <base>` is a no-op"):
- *   Re-point the arm at the **primary worktree root** — the working tree
- *   that holds the base branch — discovered via `git worktree list
- *   --porcelain`. From the primary worktree, `gh`'s `--delete-branch`
- *   cleanup never has to `git checkout <base>` (it is already there), so
- *   the collision cannot occur. `--delete-branch` is preserved verbatim,
- *   so the PR head branch is still removed on merge with no dependency on
- *   the consumer's repo-level "auto-delete head branches" toggle.
- *
- * Non-fatal by construction: any failure to resolve the primary worktree
- * (not a git repo, `git` missing, single-worktree layout, parse failure)
- * degrades to returning the original `cwd` unchanged. Worst case is the
- * pre-fix behaviour; this helper never throws and never blocks arming.
+ * auto-merge-cwd.js — pick a cwd for arming auto-merge that cannot hit the
+ * worktree collision. `gh pr merge --delete-branch` runs `git checkout <base>`;
+ * from a Story worktree that fails because the primary worktree already holds
+ * the base branch. Arming from the primary worktree makes that checkout a
+ * no-op while keeping `--delete-branch`. Any resolution failure returns the
+ * original `cwd`; never throws.
  */
 
 import { gitSpawn as defaultGitSpawn } from '../git-utils.js';
 
 /**
- * Parse `git worktree list --porcelain` output into structured records.
- *
- * The porcelain format emits one stanza per worktree, blank-line
- * separated, e.g.:
- *
- *   worktree /abs/path/to/primary
- *   HEAD <sha>
- *   branch refs/heads/main
- *
- *   worktree /abs/path/to/.worktrees/story-4282
- *   HEAD <sha>
- *   branch refs/heads/story-4282
- *
- * A linked worktree with a detached HEAD emits `detached` instead of a
- * `branch` line. Pure — exported for tests.
+ * Parse `git worktree list --porcelain` stanzas; a detached worktree has
+ * `branch: null`.
  *
  * @param {string} stdout
  * @returns {Array<{ path: string, branch: string|null }>}
@@ -70,21 +31,14 @@ export function parseWorktreeList(stdout) {
         .trim()
         .replace(/^refs\/heads\//, '');
     }
-    // `HEAD <sha>`, `detached`, `bare`, `locked`, `prunable` lines carry
-    // no field we need; ignored.
   }
   if (current) records.push(current);
   return records;
 }
 
 /**
- * Pick the primary worktree from a parsed worktree list. The primary
- * worktree is the first stanza `git worktree list` emits — it is the
- * original (non-linked) working tree and, during delivery, the one that
- * holds the base branch. Returns its absolute path, or `null` when the
- * list is empty / unparseable.
- *
- * Pure — exported for tests.
+ * The first stanza is the primary (non-linked) worktree, which holds the base
+ * branch during delivery.
  *
  * @param {Array<{ path: string, branch: string|null }>} records
  * @returns {string|null}
@@ -98,14 +52,7 @@ export function pickPrimaryWorktreePath(records) {
 }
 
 /**
- * Resolve a worktree-collision-safe cwd for arming auto-merge.
- *
- * Returns the primary worktree root (which holds the base branch) when it
- * can be discovered AND it differs from `cwd`; otherwise returns `cwd`
- * unchanged. Never throws.
- *
- * @param {string} cwd — the cwd the caller would otherwise arm from
- *   (often a per-Story worktree on the head branch).
+ * @param {string} cwd — the cwd the caller would otherwise arm from.
  * @param {{ gitSpawn?: typeof import('../git-utils.js').gitSpawn }} [deps]
  * @returns {string} a cwd safe to run `gh pr merge --delete-branch` from.
  */
@@ -121,8 +68,6 @@ export function resolveAutoMergeArmCwd(
     if (!primary) return cwd;
     return primary;
   } catch {
-    // Any unexpected failure (git missing, non-repo cwd, etc.) degrades
-    // to the original cwd — arming stays best-effort.
     return cwd;
   }
 }