mandrel 2.60.0 → 2.61.0

package/.agents/scripts/lib/orchestration/single-story-close/phases/auto-merge.js

@@ -1,85 +1,20 @@
 /**
- * phases/auto-merge.js — enable GitHub native auto-merge on the PR.
- *
- * Mirrors the v2 `single-story-close.js` finalize call shape: squash strategy, delete
- * the branch on merge. Non-fatal — returns `{ enabled: false, reason }`
- * on any failure so the caller can fall back to the operator-merges-button
- * path.
- *
- * Story #2990 routed the underlying `gh pr merge` call through the
- * `lib/gh-exec.js` facade (the same shim the `providers/github/`
- * gateways use). The `runner` seam is preserved so existing tests can
- * inject a synchronous fake; the default runner delegates to
- * `gh.pr.merge`, which spawns through the classified, typed-error
- * surface instead of a raw `execFileSync('gh', …)` call.
- *
- * Story #4282 made arming robust when the base branch is checked out by a
- * git worktree. The `--delete-branch` flag makes `gh` shell out to local
- * `git` (including a `git checkout <base>`); from a per-Story worktree cwd
- * that collides with the base branch already checked out by the primary
- * worktree (`fatal: '<base>' is already used by worktree`). We now resolve
- * the arm cwd to the **primary worktree root** (which holds the base
- * branch) via `resolveAutoMergeArmCwd`, so `gh`'s local checkout is a
- * no-op. `--delete-branch` is preserved verbatim, so the PR head branch is
- * still deleted on merge without depending on the repo's auto-delete
- * setting. Resolution is non-fatal — it degrades to the original cwd.
- *
- * Story #4681 made the arm survive a LOCAL-ONLY cleanup failure. Against an
- * already-mergeable PR, `gh pr merge --auto --squash --delete-branch` merges
- * immediately and then shells out to local `git` to drop the head branch.
- * When the per-Story worktree still holds `story-<id>`, that local delete
- * fails (`Cannot delete branch 'story-<id>' used by worktree at …`) and `gh`
- * exits non-zero — even though the REMOTE merge already landed. Reporting
- * that as an arm failure sent close's confirm phase straight to
- * `blockOnUnlanded`, flipping a merged Story to a stale `agent::blocked` that
- * only a hand-run `single-story-confirm-merge.js` could undo. The failure is
- * now classified: a local-cleanup-only signature reports the arm as ENABLED
- * with `localCleanupDeferred: true`, so the confirm phase polls the PR
- * (observes MERGED) and the post-land tail reaps the local ref. Every other
- * non-zero exit — a genuinely refused REMOTE merge — keeps the pre-existing
- * `enabled: false` → blocked behaviour verbatim.
- *
- * Story #4682 restored the direct-merge fallback the v2.0.0 Story-only cutover
- * dropped (originally PR #4480 / Story #4472, in the retired `AutomergeArmer`).
- * GitHub native auto-merge (`gh pr merge --auto`) can only be QUEUED on a repo
- * that has the "Allow auto-merge" setting enabled — which in practice requires
- * branch protection. A repo with NO required checks and NO branch protection
- * (every mandrel-bench sandbox, many real consumer repos) refuses the `--auto`
- * arm: either "auto-merge is not allowed for this repository", or — once the
- * PR has settled to an immediately-mergeable state, which the SECOND delivery
- * into a warm repo reaches faster than the first into a cold one — the
- * `enablePullRequestAutoMerge` "Pull request is in clean status" refusal. The
- * close gates and Story-scope review have already cleared the merge by the
- * time the arm runs, so the safe, must-land-satisfying response is a direct
- * immediate squash-merge (no `--auto`). When the `--auto` failure matches the
- * narrow {@link isAutoMergeUnavailable} signature, `enableAutoMergeWith`
- * retries `gh pr merge --squash --delete-branch` and reports
- * `{ enabled: true, directMerged: true }` on success — so the confirm phase
- * polls the PR, observes MERGED, and lands it instead of blocking a PR that
- * would never merge on its own. Every OTHER `--auto` failure — a genuine
- * conflict, a red required check, an auth fault — matches neither the
- * local-cleanup nor the unavailable signature and keeps blocking verbatim.
+ * phases/auto-merge.js — arm GitHub native auto-merge (squash, delete branch).
+ * Non-fatal: a failure returns `{ enabled: false, reason }`. The arm runs from
+ * the primary worktree so `--delete-branch`'s local `git checkout <base>`
+ * cannot collide with a worktree holding the base.
  */
 
-import { gh as defaultGh } from '../../../gh-exec.js';
+import { gh as defaultGh, describeGhFailure } from '../../../gh-exec.js';
 import { resolveAutoMergeArmCwd } from '../../auto-merge-cwd.js';
 import {
-  advisoryCheckFailedBlocksArm,
+  decideAdvisoryGateBlock,
   deriveRedHeadRuns,
-  resolveAdvisoryGateVerdict,
-  selectBlockingRedRuns,
 } from '../../merge-poll.js';
 
 /**
- * Arm reasons that mean **the operator deliberately owns the merge** — the PR
- * was never armed because it was asked not to be, not because arming failed.
- *
- * The distinction is load-bearing: an un-armed-by-request PR has nothing for
- * close to land, so `resolveWaitForMerge` (`./options.js`) resolves
- * `waitForMerge` to `false` for these reasons and the Story rests at
- * `agent::closing` for the human. Every *other* falsy arm outcome
- * (`pr-number-unparseable`, an `enableAutoMerge` failure) is a genuine fault
- * and still routes through the merge-unlanded block path.
+ * The operator deliberately owns the merge, so close does not wait for it;
+ * every other falsy arm outcome is a genuine fault.
  */
 const OPERATOR_MERGE_ARM_REASONS = Object.freeze([
   'disabled-by-flag',
@@ -95,34 +30,16 @@ export function isOperatorMergeReason(reason) {
 }
 
 /**
- * Signatures of a `gh pr merge --delete-branch` failure whose ONLY casualty
- * is the LOCAL head-branch cleanup that runs *after* the remote merge has
- * already been performed (or auto-merge already armed).
- *
- * Each pattern is emitted by local `git` (or `gh`'s wrapper around it) and
- * names branch DELETION specifically:
- *   - `Cannot delete branch '<name>' used by worktree at …` — `git branch -D`
- *     refusing a ref another worktree has checked out (the Story #4681 report).
- *   - `failed to delete local branch …` — `gh`'s own wrapper wording.
- *
- * Deliberately narrow on two fronts. A genuinely refused REMOTE merge ("Pull
- * request is not mergeable", a required status check, branch protection)
- * matches neither pattern and keeps the existing blocked path. Nor does the
- * bare `fatal: '<base>' is already used by worktree` checkout collision Story
- * #4282 defends against: that one aborts `gh` *before* the branch delete and
- * carries no evidence the merge stands, so it must keep failing the arm.
+ * A `gh pr merge --delete-branch` failure whose only casualty is the LOCAL
+ * head-branch delete after the remote merge/arm already happened. Deliberately
+ * narrow: a refused remote merge, and the `'<base>' is already used by
+ * worktree` checkout collision (which aborts before the merge), must still
+ * fail the arm.
  */
 const LOCAL_CLEANUP_FAILURE =
   /cannot delete branch[^\n]*used by worktree|failed to delete (?:the )?local branch/i;
 
 /**
- * Whether a non-zero `gh pr merge` exit is attributable solely to local
- * branch cleanup, leaving the remote merge/arm itself intact.
- *
- * Module-private on purpose: `enableAutoMergeWith` is the only caller and the
- * only surface worth pinning, so the classification is asserted through it
- * rather than through a test-only export.
- *
  * @param {string|undefined|null} stderr
  * @returns {boolean}
  */
@@ -131,33 +48,10 @@ function isLocalCleanupOnlyFailure(stderr) {
 }
 
 /**
- * Pure: does a `gh pr merge --auto` stderr indicate that GitHub native
- * auto-merge is UNAVAILABLE on this repository / PR — as opposed to a genuine
- * arm failure (a merge conflict, a red required check, an auth fault)?
- *
- * Two distinct refusals both mean "there is no queued auto-merge for this repo,
- * merge it directly instead", and both are safe to retry as an immediate
- * squash-merge:
- *
- *   - **"auto-merge is not allowed for this repository"** — the repo has no
- *     "Allow auto-merge" setting (no branch protection). Constant per repo.
- *   - **"Pull request is in clean status"** — the `enablePullRequestAutoMerge`
- *     GraphQL mutation refuses to queue a merge on a PR that is ALREADY
- *     immediately mergeable with nothing to wait for (no required checks
- *     pending). This is the second-delivery wedge (Story #4682): the first
- *     delivery into a cold sandbox arms while GitHub is still computing the
- *     fresh PR's mergeability (the arm queues, then merges); the second
- *     delivery into the now-warm repo hits an instantly-clean PR, so the arm
- *     is refused here.
- *
- * Only these classes fall through to the direct-merge fallback; everything
- * else (an unmatched non-zero exit) keeps the `enabled: false` → blocked path.
- * Matched case-insensitively.
- *
- * Module-private on purpose (mirroring {@link isLocalCleanupOnlyFailure}):
- * `enableAutoMergeWith` is the only caller, so the marker set is asserted
- * through it rather than through a test-only export the production dead-export
- * ratchet would then flag.
+ * Whether `--auto` was refused because native auto-merge is unavailable —
+ * the repo disallows it, or the PR is already clean with nothing to queue
+ * behind (`enablePullRequestAutoMerge` "clean status"). Both are safe to
+ * retry as a direct squash-merge; any other failure keeps blocking.
  *
  * @param {string|undefined|null} stderr
  * @returns {boolean}
@@ -174,18 +68,8 @@ function isAutoMergeUnavailable(stderr) {
 }
 
 /**
- * Direct (non-`--auto`) squash-merge fallback (Story #4682, restoring PR
- * #4480 / Story #4472). Reached only when the `--auto` arm was refused with
- * the {@link isAutoMergeUnavailable} signature — a repo with no native
- * auto-merge, or an already-clean PR with nothing to queue behind. Omitting
- * `--auto` makes `gh` merge synchronously; the same `--squash --delete-branch`
- * shape and the same `armCwd` re-point are preserved so the trailing local
- * `--delete-branch` housekeeping runs from the primary worktree (Story #4282).
- *
- * A local-cleanup-only grumble on the direct merge (Story #4681) still means
- * the REMOTE merge landed, so it reports `directMerged` with
- * `localCleanupDeferred`. Any other non-zero exit is a genuine failure the
- * caller escalates.
+ * Direct (non-`--auto`) squash-merge, run from the same `armCwd`. A
+ * local-cleanup-only failure still means the remote merge landed.
  *
  * @returns {Promise<{ enabled: boolean, directMerged?: boolean, localCleanupDeferred?: boolean, reason?: string }>}
  */
@@ -231,9 +115,6 @@ export async function enableAutoMergeWith({
   resolveArmCwd = resolveAutoMergeArmCwd,
 }) {
   const exec = runner ?? makeDefaultGhAutoMergeRunner(gh ?? defaultGh);
-  // Re-point the arm at the base-branch (primary) worktree so gh's
-  // `--delete-branch` local `git checkout <base>` cannot collide with the
-  // base branch already checked out by the primary worktree (Story #4282).
   const armCwd = resolveArmCwd(cwd);
   try {
     const result = await exec(
@@ -250,15 +131,10 @@ export async function enableAutoMergeWith({
     if (result.status === 0) return { enabled: true };
     const detail = `gh-exit-${result.status}: ${(result.stderr ?? '').trim().slice(0, 200)}`;
     if (isLocalCleanupOnlyFailure(result.stderr)) {
-      // The remote side stands; only the local head-branch cleanup failed.
-      // Report ENABLED so the confirm phase polls the real PR state instead
-      // of blocking a merge that already landed, and flag the deferred
-      // cleanup for the land tail's `git branch -D` to finish.
+      // The remote side stands; the land tail finishes the local ref reap.
       return { enabled: true, localCleanupDeferred: true, reason: detail };
     }
     if (isAutoMergeUnavailable(result.stderr)) {
-      // No native auto-merge on this repo (or nothing to queue behind an
-      // already-clean PR): merge directly so the PR still lands (Story #4682).
       return directMergeFallback({
         exec,
         prNumber,
@@ -273,20 +149,11 @@ export async function enableAutoMergeWith({
 }
 
 /**
- * Build the default `gh pr merge` runner that adapts the async
- * `lib/gh-exec.js` facade into the synchronous-looking
- * `{ status, stdout, stderr }` envelope `enableAutoMergeWith` consumes.
- *
- * The adapter swallows non-zero exits (mapping the typed `GhExecError`
- * carrier back to its `code` + `stderr`) because auto-merge enablement
- * is intentionally non-fatal — the caller treats failures as "operator
- * merges manually".
+ * Adapt `gh.pr.merge` into the `{ status, stdout, stderr }` envelope,
+ * mapping non-zero exits back to that envelope rather than throwing.
  */
 function makeDefaultGhAutoMergeRunner(gh) {
   return async function defaultGhAutoMergeRunner(args, _opts) {
-    // `args` always starts with `pr merge <prNumber>` — pass everything
-    // after the third element to `gh.pr.merge` as flags so the facade
-    // owns the `gh pr merge <id> …` argv assembly.
     const [, , prIdStr, ...flags] = args;
     try {
       const result = await gh.pr.merge(prIdStr, flags);
@@ -296,13 +163,8 @@ function makeDefaultGhAutoMergeRunner(gh) {
         stderr: result?.stderr ?? '',
       };
     } catch (err) {
-      // Duck-type: any error carrying a numeric `.code` (or `.status`,
-      // which the legacy `execFileSync` shim used) + an optional
-      // `.stderr` is mapped back to the `{ status, stdout, stderr }`
-      // envelope `enableAutoMergeWith` consumes. The typed
-      // `GhExecError` carriers from `lib/gh-exec.js` already fit this
-      // shape; bare `Error`s without a code fall through to the spawn-
-      // error reason in the parent catch.
+      // Any error with a numeric `.code`/`.status` maps to the envelope;
+      // a codeless Error falls through to the caller's spawn-error reason.
       const numericCode =
         typeof err?.code === 'number'
           ? err.code
@@ -328,24 +190,8 @@ function makeDefaultGhAutoMergeRunner(gh) {
 }
 
 /**
- * Evaluate the pre-arm advisory-gate verdict (Story #5096).
- *
- * GitHub native auto-merge is defined to wait on REQUIRED contexts only, so a
- * red ADVISORY quality gate — a coverage, mutation, duplication, a11y or
- * bundle-size ratchet a consumer deliberately left non-required — is merged
- * straight past once the required contexts go green. The arming decision is
- * mandrel's, not GitHub's, so this is where it has to be made.
- *
- * Reads the SAME head-anchored derivation the merge wait uses
- * (`readPrWaitProbe` → `deriveRedHeadRuns`), so a `CANCELLED` superseded-push
- * run or a sibling-invalidated run is never mistaken for a red gate (the
- * #4695 / #4710 trap), and `mergeStateStatus: UNSTABLE` supplies the
- * required-vs-advisory discrimination the rollup itself lacks.
- *
- * **Non-fatal and fail-open in every degraded case.** A probe error, an absent
- * or `UNKNOWN` merge state, or a disabled knob all return "do not block" — the
- * arm proceeds exactly as it did before this Story. Only a positive verdict
- * refuses.
+ * Native auto-merge waits on REQUIRED contexts only, so mandrel must refuse
+ * to arm over a red advisory gate itself.
  *
  * @param {object} args
  * @returns {Promise<{ blocked: boolean, blockingRuns?: Array<object>, reason?: string }>}
@@ -365,38 +211,61 @@ async function readAdvisoryProbe({ prNumber, gh }) {
 }
 
 /**
- * Disarm GitHub native auto-merge on a PR (Story #5096).
- *
- * Lives here, beside the arm, because `lifecycle-lint`'s merge-lockout rule
- * confines every `gh pr merge` invocation to this module: auto-merge
- * enablement — and therefore its reversal — must flow through the Story close
- * path rather than being spelled out wherever a caller happens to need it.
- * The merge wait imports this rather than shelling out itself.
- *
- * Best-effort by contract: the caller blocks the Story either way, and a
- * failed disarm is reported rather than thrown, because the one thing it
- * cannot do is stop GitHub from landing the PR.
+ * A `gh` refusal meaning auto-merge was never armed — the PR is already in the
+ * desired un-armed posture, unlike a genuine disarm failure.
+ */
+const NOT_ARMED = /not enabled|isn't enabled|is not set|no auto-?merge/i;
+
+/**
+ * Lives here because `lifecycle-lint` confines `gh pr merge` to this module.
+ * Never throws.
  *
- * @returns {Promise<boolean>} whether the disarm actually took.
+ * @param {{ prNumber?: number|string, prRef?: string, gh?: object,
+ *   progress?: (tag: string, msg: string) => void }} args `prRef` wins over
+ *   `prNumber` when both are given.
+ * @returns {Promise<{ disarmed: boolean, alreadyUnarmed: boolean, detail: string }>}
  */
-export async function disarmAutoMerge({ prNumber, gh, progress }) {
+export async function disarmAutoMerge({ prNumber, prRef, gh, progress }) {
+  const ref = String(prRef ?? prNumber);
   try {
-    await (gh ?? defaultGh).pr.merge(String(prNumber), ['--disable-auto']);
+    await (gh ?? defaultGh).pr.merge(ref, ['--disable-auto']);
     progress?.(
       'CONFIRM',
-      `🔓 Auto-merge DISARMED on PR #${prNumber} — the PR stays open and hand-mergeable.`,
+      `🔓 Auto-merge DISARMED on PR #${ref} — the PR stays open and hand-mergeable.`,
     );
-    return true;
+    return { disarmed: true, alreadyUnarmed: false, detail: 'disarmed' };
   } catch (err) {
-    progress?.(
-      'CONFIRM',
-      `⚠️ Could not disarm auto-merge on PR #${prNumber} (${err?.message ?? err}) — ` +
-        'GitHub may still land it when the required checks pass. Disarm by hand.',
-    );
-    return false;
+    const outcome = classifyDisarmFailure(describeGhFailure(err));
+    warnIfStillArmed({ outcome, ref, progress });
+    return outcome;
   }
 }
 
+/**
+ * @param {string} detail The operator-legible `gh` failure line.
+ * @returns {{ disarmed: boolean, alreadyUnarmed: boolean, detail: string }}
+ */
+function classifyDisarmFailure(detail) {
+  const alreadyUnarmed = NOT_ARMED.test(detail);
+  return {
+    disarmed: alreadyUnarmed,
+    alreadyUnarmed,
+    detail: alreadyUnarmed
+      ? `auto-merge was not armed: ${detail.slice(0, 160)}`
+      : detail.slice(0, 200),
+  };
+}
+
+function warnIfStillArmed({ outcome, ref, progress }) {
+  if (outcome.disarmed) return;
+  progress?.(
+    'CONFIRM',
+    `⚠️ Could not disarm auto-merge on PR #${ref} (${outcome.detail}) — ` +
+      'GitHub may still land it when the required checks pass. Disarm by hand.',
+  );
+}
+
+/** Fail-open: a probe error or disabled knob never blocks the arm. */
 async function evaluateAdvisoryGate({
   prNumber,
   gh,
@@ -423,31 +292,23 @@ async function evaluateAdvisoryGate({
     );
     return { blocked: false };
   }
-  if (!advisoryCheckFailedBlocksArm(probe, advisoryAllowlist)) {
-    return { blocked: false };
-  }
-  const blockingRuns = selectBlockingRedRuns(
-    probe.redHeadRuns,
+  // Same evaluator as the merge wait's mid-wait gate, so the verdicts cannot drift.
+  const verdict = decideAdvisoryGateBlock({
+    probe,
+    blockOnAdvisoryFailure,
     advisoryAllowlist,
-  );
-  // Story #5266 — the class travels with the reason. This pre-arm gate
-  // classifies on the text the ROLLUP carried (a legacy StatusContext's
-  // `description`); the merge wait, which owns the common case, additionally
-  // reads the check-run output. Either way a run whose failure cannot be read
-  // as "never finished" keeps the `advisory-gate-red` verdict.
-  const verdict = resolveAdvisoryGateVerdict({ blockingRuns });
+  });
+  if (!verdict) return { blocked: false };
   return {
     blocked: true,
-    blockingRuns,
+    blockingRuns: verdict.blockingRuns,
     blockClass: verdict.blockClass,
     reason: verdict.reason,
   };
 }
 
 /**
- * Dispatch auto-merge enablement based on `--no-auto-merge`, an
- * unparseable PR number, or a `gh` failure. Returns the structured
- * `{ autoMergeEnabled, autoMergeReason }` pair the result envelope needs.
+ * Dispatch auto-merge enablement.
  *
  * @param {{
  *   cwd: string,
@@ -459,10 +320,8 @@ async function evaluateAdvisoryGate({
  *   progress: (tag: string, msg: string) => void,
  * }} args
  * @returns {Promise<{ autoMergeEnabled: boolean, autoMergeReason: string|null, localCleanupDeferred?: boolean, directMerged?: boolean }>}
- *   `localCleanupDeferred` is true when the arm stands but `gh`'s local
- *   head-branch delete failed (Story #4681) — the land tail owns the reap.
- *   `directMerged` is true when native auto-merge was unavailable and the PR
- *   was landed by a direct squash-merge instead (Story #4682).
+ *   `localCleanupDeferred`: the arm stands but the land tail owns the local
+ *   ref reap. `directMerged`: landed by direct squash-merge instead.
  */
 export async function runAutoMergePhase({
   cwd,
@@ -480,13 +339,6 @@ export async function runAutoMergePhase({
     progress('PR', '⏭  Auto-merge disabled (--no-auto-merge).');
     return { autoMergeEnabled: false, autoMergeReason: 'disabled-by-flag' };
   }
-  // `delivery.ci.autoMerge: "strict"` opts standalone Stories out of
-  // auto-merge (parallel to the Epic path's strict predicate): the PR opens
-  // and waits for an operator merge instead of arming native auto-merge.
-  // The default `"trust-ci"` keeps arming on green required CI — GitHub's
-  // native `--auto` is the required-check gate, so no client-side predicate
-  // is needed here (unlike the Epic path, which gates on local
-  // audit/review/retro signals a standalone Story does not produce).
   if (autoMergePolicy === 'strict') {
     progress(
       'PR',
@@ -507,10 +359,8 @@ export async function runAutoMergePhase({
       autoMergeReason: 'pr-number-unparseable',
     };
   }
-  // Story #5096 — refuse to arm over a genuinely red ADVISORY check. This
-  // gate covers the narrow case where the gate is ALREADY red at close time
-  // (a re-close, or a gate carried over from an earlier push); the merge
-  // wait owns the common case, where the gate reddens after arming.
+  // Covers a gate ALREADY red at close time; the merge wait owns one that
+  // reddens after arming.
   const advisory = await evaluateAdvisoryGate({
     prNumber,
     gh,
@@ -537,10 +387,6 @@ export async function runAutoMergePhase({
   const result = await enableAutoMergeWith({ cwd, prNumber, gh });
   if (result.enabled) {
     if (result.directMerged) {
-      // No native auto-merge on this repo — the PR was merged directly
-      // instead of queued (Story #4682). The confirm phase polls the PR,
-      // observes MERGED, and runs the land tail; `localCleanupDeferred`
-      // still defers a local-ref reap when gh's `--delete-branch` grumbled.
       progress(
         'PR',
         `✅ Native auto-merge unavailable on PR #${prNumber} — direct squash-merge landed it` +
@@ -556,8 +402,6 @@ export async function runAutoMergePhase({
       };
     }
     if (result.localCleanupDeferred) {
-      // Warning, never a block (Story #4681): the merge/arm stands and the
-      // land tail reaps the local ref once the worktree releases it.
       progress(
         'PR',
         `⚠️ Auto-merge armed on PR #${prNumber}, but gh's LOCAL branch cleanup failed ` +

package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js

@@ -1,25 +1,8 @@
 /**
- * phases/base-sync.js — pre-push base-sync phase for `single-story-close`.
- *
- * Story #2580: sync the Story branch from `origin/<baseBranch>` before
- * push so the PR opens with the latest base commits already integrated.
- * Defends against the parallel-`/single-story-deliver` race where one
- * Story's auto-merge bumps `main` while sibling Stories are mid-flight —
- * without the sync, the lagging PRs open "behind base" and stall against
- * the `up-to-date branch` protection rule.
- *
- * The sync runs INSIDE the worktree (where the Story branch is checked
- * out); falls back to the main checkout when the worktree is absent.
- * On a merge conflict the Story is transitioned to `agent::blocked` via
- * `handleSyncFailure` and the caller throws — the operator resolves in
- * the worktree and re-runs.
- *
- * Story #5267: a sync that lands tracked content also spends the worker's
- * pre-push credit, because that credit is keyed on the tree. The phase says
- * so out loud — see `buildStampInvalidatedWarning` — instead of leaving
- * close's second full suite looking like a bug. Story #5278 splits the claim
- * in two: gate evidence is spent by any tracked path, the capture stamp only
- * by one under `crap.targetDirs`.
+ * phases/base-sync.js — sync the Story branch from `origin/<baseBranch>`
+ * before push, so a PR does not open behind a base a sibling's merge just
+ * moved. Runs in the worktree (else the main checkout); a failure blocks the
+ * Story and throws.
  */
 
 import { getQuality } from '../../../config/quality.js';
@@ -35,11 +18,7 @@ import {
 } from '../../ticketing.js';
 
 /**
- * Orchestrate the pre-push base-sync step: run `syncBranchFromBase`
- * inside the worktree (or main checkout when no worktree exists). On
- * failure, post a friction comment, flip the Story to `agent::blocked`,
- * and throw so the caller fails non-zero. The `--skip-sync` flag is
- * handled by the caller; this function assumes the sync is desired.
+ * `--skip-sync` is the caller's concern.
  *
  * @param {{
  *   cwd: string,
@@ -109,10 +88,7 @@ export async function runBaseSyncPhase({
 }
 
 /**
- * The CRAP scoring scope, or `[]` when it cannot be resolved. A `[]` makes
- * the warning below fall back to naming the capture stamp unconditionally —
- * the pre-#5278 wording — because an unresolvable scope is no evidence that
- * the stamp survived.
+ * The CRAP scoring scope, or `[]` when unresolvable.
  *
  * @param {typeof resolveConfig} resolveConfigImpl
  * @param {string} cwd
@@ -126,37 +102,13 @@ function resolveCrapTargetDirs(resolveConfigImpl, cwd) {
   }
 }
 
-/**
- * How many changed paths the warning names before it stops listing.
- * Enough to recognise the change set; short enough that the warning still
- * reads as a warning rather than as a diff.
- */
 const WARNED_PATH_LIMIT = 12;
 
 /**
- * The loud "your credit is spent" warning, or `[]` when the sync changed
- * nothing (Story #5267, narrowed by #5278).
- *
- * The worker banks two kinds of credit before the push: gate evidence keyed
- * on the tree (lint, typecheck) and one full-suite capture stamp keyed on the
- * content of `crap.targetDirs`. This sync runs after that, and the two are
- * spent on different conditions — which is why #5267's single blanket
- * sentence was wrong half the time:
- *
- *   - **Gate evidence** is spent by any tracked path at all, because the tree
- *     hash it is keyed on moves with the first byte.
- *   - **The capture stamp** is spent only when a merged path lands under
- *     `crap.targetDirs`. A sync that brings in docs, workflows or CI config
- *     leaves it perfectly valid, and announcing it as spent taught operators
- *     to expect a second full suite that close was never going to run.
- *
- * Quiet by construction on the outcome that cannot spend either: a
- * `noop-already-current` sync never touched the tree. A content-changing
- * fast-forward DOES warn — it moves the tree exactly as a merge commit does,
- * and staying quiet there would be a lie of omission.
- *
- * Pure. Module-private: the phase is the seam tests drive it through
- * (`injectedSync` + a `progress` spy), so it needs no export of its own.
+ * Warn that the sync spent pre-push credit, or `[]` when it changed nothing.
+ * Gate evidence is keyed on the tree, so any tracked path spends it; the
+ * full-suite capture stamp is spent only by a path under `crap.targetDirs`.
+ * A content-changing fast-forward warns just as a merge does.
  *
  * @param {{ baseBranch: string, result: { kind?: string, changedPaths?: string[] }, targetDirs?: string[] }} args
  * @returns {string[]} Progress lines, in order. Empty when nothing changed.
@@ -167,8 +119,7 @@ function buildStampInvalidatedWarning({ baseBranch, result, targetDirs }) {
     : [];
   if (changed.length === 0) return [];
   const dirs = Array.isArray(targetDirs) ? targetDirs : [];
-  // An unresolvable scope (`[]`) cannot prove the stamp survived, so it fails
-  // closed to the unconditional wording.
+  // An unresolvable scope cannot prove the stamp survived: fail closed.
   const scored =
     dirs.length === 0 ? changed : filterFilesUnderTargets(changed, dirs);
   const shown = changed.slice(0, WARNED_PATH_LIMIT);
@@ -191,8 +142,7 @@ function buildStampInvalidatedWarning({ baseBranch, result, targetDirs }) {
 }
 
 /**
- * Post a `friction` structured comment summarising a base-sync failure
- * and transition the Story to `agent::blocked`. Exported for testing.
+ * Post a `friction` comment and block the Story; both best-effort.
  *
  * @param {{
  *   provider: object,
@@ -224,10 +174,8 @@ export async function handleSyncFailure({
     result,
   });
 
-  // Post the structured comment first so the operator's recovery
-  // surface lands even if the label flip fails. Both are best-effort:
-  // we never want a notification-side failure to mask the real reason
-  // close threw.
+  // Comment first so the recovery surface lands even if the flip fails; a
+  // notification failure must never mask why close threw.
   try {
     await upsertStructuredComment(provider, storyId, 'friction', body);
     progress('SYNC', `📝 Posted friction comment on #${storyId}.`);
@@ -237,9 +185,7 @@ export async function handleSyncFailure({
     );
   }
 
-  // Story #4539 — the canonical mutator, not a direct label write: a bare
-  // `provider.updateTicket` skips the Projects v2 column sync (Story
-  // #2548) and strands the board on the Story's prior status.
+  // The canonical mutator: a bare label write skips the Projects v2 sync.
   try {
     await transitionTicketState(provider, storyId, STATE_LABELS.BLOCKED, {});
     progress('SYNC', `🚧 Flipped Story #${storyId} → ${AGENT_LABELS.BLOCKED}.`);
@@ -251,17 +197,9 @@ export async function handleSyncFailure({
 }
 
 /**
- * Build the markdown body posted on a base-sync failure. Pure; exported
- * for tests so the operator-recoverable surface stays reviewable.
- *
- * Story #4891 — `baseConfirmed` gates the merge-the-base recovery block, and
- * defaults to `false` so it fails closed. Telling the operator to run
- * `git merge origin/<baseBranch>` is actively harmful when `<baseBranch>` is
- * not the base the Story was seeded from: it permanently contaminates the
- * branch and its PR diff with an unrelated base. Close confirms the base
- * against the run's init receipt before that advice is emitted; when
- * it could not (receipt absent, unreadable, or unpinned), the operator is
- * told to establish the real base first instead.
+ * `baseConfirmed` (default false, fail-closed) gates the merge-the-base
+ * advice: merging a base the Story was not seeded from contaminates the
+ * branch and PR diff, so an unconfirmed base gets "establish it first".
  *
  * @param {{ storyId: number, storyBranch: string, baseBranch: string, baseConfirmed?: boolean, syncCwd: string, result: { kind: string, conflictFiles?: string[], stderr?: string } }} args
  * @returns {string}