mandrel 2.60.0 → 2.62.0

package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-gate-steps.js

@@ -1,33 +1,9 @@
 /**
- * phases/pre-gate-steps.js — the self-heal steps the standalone close runs on
- * the Story branch *before* the check-only gate chain scores it.
- *
- * Two steps live here, and they share one contract that is the reason they
- * share a module: each may author a commit on `story-<id>`, each must run
- * ahead of the gates so its commit is part of what the gates score and part of
- * the branch's own PR, and **neither may ever fail the close**. Downstream
- * there is always an authoritative gate — `biome ci` for formatting,
- * `check-baselines` for the ratchet — so a failure here is a missed
- * opportunity to self-heal, never a verdict.
- *
- *   1. **Scoped format-autofix** (Story #4250) — run the formatter over the
- *      `baseBranch...storyBranch` diff and fold any rewrite into a
- *      `fix(story-close):` commit, so benign JSON/YAML drift that lint-staged
- *      does not glob never reaches the check-only format gate.
- *   2. **Upward baseline write-back** (Story #5224) — persist the
- *      maintainability rows this branch improved on files it touched, as a
- *      `baseline-refresh:` commit, so the committed baseline stops falling
- *      behind the tree in the upward direction.
- *   3. **Context-budget write-back** (Story #5313) — persist the lower
- *      documentation-tier totals this branch measured, so a trimmed tier's
- *      gain locks in without `check-context-budget.js` ever going red on it.
- *
- * Extracted from `close-validation.js` when the second step landed. The phase
- * module's job is the gate chain, the evidence keyspace and the gate-log sink;
- * carrying two multi-branch best-effort wrappers inline alongside that was the
- * mass that made it the file it was. Both collaborators stay injectable — the
- * parent CLI's cache-busted bindings must win in tests that mock the upstream
- * module URLs — and are threaded through from the phase unchanged.
+ * phases/pre-gate-steps.js — self-heal steps run on the Story branch before
+ * the gates: scoped format-autofix, the upward maintainability baseline
+ * write-back, and the context-budget write-back. Each may commit on
+ * `story-<id>` (so the gates score it) and none may ever fail the close — an
+ * authoritative gate for each runs right after.
  */
 
 import { Logger } from '../../../Logger.js';
@@ -36,8 +12,6 @@ import { runContextBudgetWriteback as defaultRunContextBudgetWriteback } from '.
 import { runScopedFormatAutofix as defaultRunScopedFormatAutofix } from '../../story-close/format-autofix.js';
 
 /**
- * Run the scoped formatter self-heal.
- *
  * @param {object} ctx the shared step context (see {@link runPreGateSteps})
  * @returns {void}
  */
@@ -73,12 +47,7 @@ function formatAutofixStep({
 }
 
 /**
- * Run one of the two baseline write-backs and report it on one progress line.
- *
- * Both steps (Story #5224's maintainability rows, Story #5313's context-budget
- * totals) take the same context and answer in the same shape — `committed`
- * with a `sha`, or a named `reason` — so one wrapper serves both; `describe`
- * renders the committed outcome in the step's own words.
+ * Serves both write-backs, which share an input and result shape.
  *
  * @param {object} ctx the shared step context (see {@link runPreGateSteps})
  * @param {{ tag: string, run: Function, describe: (w: object) => string, noun: string }} step
@@ -106,13 +75,7 @@ async function writebackStep(
 }
 
 /**
- * Run one step, absorbing any throw into a progress line.
- *
- * The absorption is the point, not laziness about error handling: every step
- * here is the *refresh* half of a loop whose *enforcement* half runs
- * immediately afterwards. A step that could abort the close would convert a
- * self-heal opportunity into an outage, and would do it on the path with the
- * least operator attention.
+ * Absorbs any throw: these are refresh halves; enforcement runs right after.
  *
  * @param {{ tag: string, label: string, progress: Function, run: () => Promise<void>|void }} opts
  * @returns {Promise<void>}
@@ -129,12 +92,7 @@ async function bestEffort({ tag, label, progress, run }) {
 }
 
 /**
- * Run every pre-gate self-heal step for a standalone Story close.
- *
- * Both steps commit to `story-<id>`, so both are skipped — with a log line, not
- * a throw — when the caller has no `storyBranch`. That is the resume/legacy
- * path, which has no branch to commit onto and must not trip an exception for
- * saying so.
+ * Without a `storyBranch` there is nothing to commit onto: skip with a log line.
  *
  * @param {{
  *   cwd: string,

package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js

@@ -1,44 +1,10 @@
 /**
- * phases/pull-request.js — open, reuse, or decline to open the PR for a
- * standalone Story.
+ * phases/pull-request.js — open, reuse, or decline to open the Story's PR.
  *
- * Probes for an existing PR with `head = storyBranch`; creates one if none
- * exists. Returns `{ url, alreadyMerged, created }`.
- *
- * `gh pr view --head` is not available on all `gh` versions, so we probe
- * with `gh pr list --head <branch>` and fall back to `gh pr create`.
- *
- * Story #2990 routed the underlying `gh pr list` / `gh pr create` calls
- * through the `lib/gh-exec.js` facade (the same shim the
- * `providers/github/` gateways use) so this phase inherits the typed
- * error classification, timeout handling, and JSON parsing surface
- * instead of carrying its own `execFileSync('gh', …)` plumbing.
- *
- * ## An already-merged PR is not an absent PR (Story #4873)
- *
- * The probe used to ask for `--state open` only. On the recovery path that is
- * a false negative with teeth: a resumed close pushes the branch, the push
- * turns the checks green, armed auto-merge lands the ORIGINAL PR server-side,
- * and the resumed close then sees no OPEN PR on the head — so it opened a
- * SECOND PR against a branch that is now byte-identical to base and
- * squash-merged a zero-file commit onto `main`. Both halves of that are now
- * closed:
- *
- *   1. The probe reads `--state all` and reports a MERGED PR on this head as
- *      the outcome (`alreadyMerged: true`), so the caller lands on the merge
- *      that already happened instead of manufacturing a new one. An OPEN PR
- *      still wins over a merged one — a re-opened head is a live PR.
- *   2. Creation is REFUSED outright when the head-versus-base diff contains no
- *      files. An empty diff means there is nothing to merge, so a PR opened on
- *      it can only ever produce an empty commit.
- *
- * The empty-diff guard fails **open**, not closed: `computeChangeSet` returns
- * `files: null` when it cannot enumerate the diff at all, and absence of
- * evidence must never block a legitimate PR — only a positively-observed empty
- * file list refuses.
- *
- * The function still accepts an injected `gh` facade so tests can wire
- * a fake without spawning real children.
+ * A MERGED PR on the head is reported as the outcome, not treated as absent:
+ * a resumed close whose original PR auto-merged would otherwise open a second
+ * PR and squash an empty commit onto `main`. Creation is also refused on a
+ * positively empty diff; an unenumerable diff fails open.
  */
 
 import { gh as defaultGh } from '../../../gh-exec.js';
@@ -47,21 +13,9 @@ import { computeChangeSet as defaultComputeChangeSet } from '../../change-set.js
 import { buildPullRequestFields } from './normalize-pr-title.js';
 
 /**
- * Pick the PR this head branch should resolve to from a `gh pr list
- * --state all` projection. A live PR always wins; otherwise the first MERGED
- * PR is the outcome to report. A head whose only PRs were CLOSED without
- * merging resolves to nothing — there is a new PR to open.
- *
- * A row carrying a url but no recognizable `state` reads as live, not as
- * nothing: the projection this phase asks for always includes `state`, so an
- * absent one means an older/other `gh`, and the old `--state open` probe
- * treated every returned row as a reusable open PR. Guessing "no PR" there is
- * the failure mode with teeth — it opens a duplicate.
- *
- * Pure, and module-private on purpose: `ensurePullRequestWith` is the only
- * caller and the only surface worth pinning, so the precedence is asserted
- * through it rather than through a test-only export the production
- * dead-export ratchet would then flag.
+ * OPEN wins, then the first MERGED; CLOSED-only resolves to null. A row with
+ * no recognizable `state` reads as live, since guessing "no PR" opens a
+ * duplicate. Module-private: a test-only export would trip dead-exports.
  *
  * @param {Array<{url?: string, state?: string, mergedAt?: string}>} rows
  * @returns {{ url: string, state: 'OPEN'|'MERGED' }|null}
@@ -84,14 +38,8 @@ function pickHeadPullRequest(rows) {
 }
 
 /**
- * Enumerate the head-versus-base diff and report whether it is positively
- * empty. `null` (diff unenumerable) is NOT empty — see the module header.
- *
- * The diff is taken against `origin/<baseBranch>` when that ref resolves,
- * because the local base ref can trail the remote by exactly the merge that
- * makes this diff empty — the very state the guard exists to catch. It falls
- * back to the local ref, and finally to "unknown", when the remote ref cannot
- * be enumerated.
+ * Prefers `origin/<base>`: the local ref can trail by exactly the merge that
+ * makes the diff empty. Unenumerable is NOT empty.
  *
  * @returns {{ empty: boolean, baseRef: string|null }}
  */
@@ -105,9 +53,6 @@ function probeEmptyDiff({ cwd, baseBranch, storyBranch, computeChangeSet }) {
 }
 
 /**
- * Probe for an existing PR with `head = storyBranch`; create one if none
- * exists. Exported for testing.
- *
  * @param {{
  *   cwd: string,
  *   storyId: number,
@@ -132,16 +77,9 @@ export async function ensurePullRequestWith({
   computeChangeSetFn = defaultComputeChangeSet,
   progress = () => {},
 }) {
-  // `cwd` is preserved on the call signature for backwards compatibility
-  // with the SUT's thin wrapper, but `gh-exec` spawns `gh` against the
-  // current process cwd. `single-story-close.js` chdirs into the worktree
-  // before invoking the phase, so the effective cwd matches the legacy
-  // `execFileSync('gh', …, { cwd })` shape.
+  // `gh-exec` spawns `gh` in the process cwd, not `_cwd`.
   try {
-    // `gh pr list --head <branch> --state all --json url,state,mergedAt`
-    // returns a JSON array of rows; an empty array means this head has never
-    // had a PR. `--state all` (not `open`) is load-bearing — see the module
-    // header's duplicate-empty-PR note.
+    // `--state all`, not `open`: a merged PR must be seen.
     const rows = await gh.pr.list(
       ['--head', storyBranch, '--state', 'all'],
       ['url', 'state', 'mergedAt'],
@@ -160,16 +98,11 @@ export async function ensurePullRequestWith({
       return { url: existing.url, alreadyMerged: true, created: false };
     }
   } catch (err) {
-    // `gh pr list` failure is recoverable — fall through to create. Log
-    // the error so an auth issue surfaces visibly.
     Logger.warn?.(
       `[single-story-close] ⚠️ \`gh pr list\` probe failed (continuing to create): ${err?.message ?? err}`,
     );
   }
 
-  // Nothing to merge → nothing to open. Refused before `gh pr create` so the
-  // failure names the empty diff rather than surfacing later as a zero-file
-  // squash commit on the base branch.
   const emptyDiff = probeEmptyDiff({
     cwd: _cwd ?? process.cwd(),
     baseBranch,
@@ -187,10 +120,6 @@ export async function ensurePullRequestWith({
   }
 
   progress('PR', `Opening PR for ${storyBranch} → ${baseBranch}...`);
-  // The repo squash-merges and GitHub uses the PR title as the squash subject
-  // on `main`, so both fields are derived rather than typed — see
-  // `normalize-pr-title.js`. `gh-exec` spawns `gh` against the current process
-  // cwd (the worktree), so the branch read uses the same cwd.
   const { title, body } = buildPullRequestFields({
     storyTitle,
     storyId,

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

@@ -1,44 +1,16 @@
 /**
  * phases/push.js — push the Story branch to origin.
  *
- * `git push -u` makes the local branch track origin/story-<id> so
- * subsequent fetches are cheap. A push failure raises so the caller
- * fails non-zero — the operator must resolve before retrying.
- *
- * Issue #4483 — this phase IS the standalone path's deterministic
- * land-or-block backstop (the counterpart to the Epic finalize seam's
- * `delivery-branch-missing-on-origin` blocker). `git push` exits 0 only
- * after origin has accepted the ref, so the throw below is the origin
- * assertion: every later close phase (PR open, auto-merge, the
- * `closeResult` success envelope) is unreachable unless the Story branch
- * verifiably landed on origin. No post-push `ls-remote` re-probe is
- * added because it would re-ask a question the push exit code already
- * answered authoritatively.
- *
- * Issue #4990 — the push runs in the Story worktree, not the main
- * checkout. `core.hooksPath` is the relative `.husky/_`, so the
- * invocation directory is what selects which tree `pre-push` resolves
- * and measures. Pushing from the main checkout therefore validated a
- * tree other than the one being sent — false red when that checkout sat
- * on unrelated work, and worse, false green whenever it happened to be
- * clean. `worktreePath` falls back to `cwd` because single-tree mode and
- * a disabled `delivery.worktreeIsolation` both legitimately have no
- * worktree, and there the main checkout IS the tree being pushed. The
- * two sibling phases resolve their tree the same way
- * (`base-sync.js`, `close-validation.js`).
- *
- * `gitSync` is accepted as an injected dependency rather than statically
- * imported so the caller's (cache-busted) binding wins. The
- * `single-story-close.js` orchestrator owns the static import; test
- * suites mock the git-utils module URL and re-import the SUT to refresh
- * the binding it passes in.
+ * `git push` exits 0 only once origin accepted the ref, so the throw is the
+ * origin assertion every later phase depends on. It runs from the worktree:
+ * `core.hooksPath` is relative, so the invocation directory decides which
+ * tree `pre-push` measures (the main checkout gave false greens). With no
+ * worktree, the main checkout is the pushed tree.
  */
 
 import { gitSync as defaultGitSync } from '../../../git-utils.js';
 
 /**
- * Push the Story branch with `-u` so the upstream is set.
- *
  * @param {{
  *   cwd: string,
  *   worktreePath?: string|null,
@@ -56,12 +28,7 @@ export function pushStoryBranch({
 }) {
   progress('GIT', `Pushing ${storyBranch} to origin...`);
   try {
-    // No hook-bypass flag here, deliberately. Close runs its own gate chain
-    // before this point, but `--skip-validation` skips that chain, and the
-    // bypass then left nothing running at all. `pre-push` is the backstop,
-    // and it only became reachable once hooks were materialized into
-    // worktrees — which is where every Story branch is built, and where the
-    // cwd below now resolves so the hook reads that tree.
+    // Never bypass hooks: under `--skip-validation`, `pre-push` is the only gate.
     gitSync(worktreePath ?? cwd, 'push', '-u', 'origin', storyBranch);
     progress('GIT', `✅ Pushed ${storyBranch}.`);
   } catch (err) {

package/.agents/scripts/lib/orchestration/single-story-close/phases/review-block.js

@@ -33,12 +33,7 @@ export async function handleCriticalReviewBlock({
       `[single-story-close] failed to post review-block friction: ${err?.message ?? err}`,
     );
   }
-  // Story #4539 — route through the canonical mutator rather than writing
-  // labels directly. A bare `provider.updateTicket` skips the Projects v2
-  // column sync (Story #2548), leaving the board on the Story's prior
-  // status. That is benign today only because agent::blocked and
-  // agent::executing happen to map to the same column — a coincidence, not
-  // a design, and exactly how the next drift gets in.
+  // Canonical mutator, not a bare label write, so the Projects v2 column syncs.
   try {
     await transitionTicketState(provider, storyId, STATE_LABELS.BLOCKED, {});
   } catch (err) {

package/.agents/scripts/lib/orchestration/single-story-close/phases/review-outcome.js

@@ -1,33 +1,13 @@
 /**
- * phases/review-outcome.js — operator-facing rendering of the Story-scope
- * review outcome (Story #4839).
- *
- * The review phase used to report a severity tally and nothing else, which made
- * "every gate ran and found nothing" and "a gate never ran" render identically.
- * Both surfaces the operator actually reads — the close progress stream and the
- * cross-reference comment on the Story — now state the degraded gates
- * explicitly, and always state them (as `none` when healthy) so an absent line
- * can never be mistaken for a clean gate.
- *
- * A degraded gate is **reported, not blocking**: this review is a secondary
- * read, and the close does not gate the merge on it. The rationale for that
- * posture lives with the channel itself in
- * [`review-providers/degraded-gates.js`](../../review-providers/degraded-gates.js).
- *
- * What this module must **not** do (Story #5193) is tell the operator that the
- * canonical `npm run lint` close gate covered the surface instead. A stub
- * `lint` script is a supported consumer shape, so that claim is unverifiable
- * from here — and asserting it talks the operator out of the exact concern the
- * degradation was raised to surface. State the posture; never vouch for
- * coverage this module cannot see.
+ * phases/review-outcome.js — renders the review outcome, always stating the
+ * degraded gates (`none` when healthy) so "never ran" cannot read as
+ * "found nothing". Degraded is reported, not blocking — and never claim
+ * another gate covered the surface; this module cannot see that.
  */
 
 import { summarizeDegradations } from '../../review-providers/degraded-gates.js';
 
 /**
- * Pure: the tally suffix shared by the progress line and the cross-reference
- * comment — severity counts plus the degraded-gate state.
- *
  * @param {{ severity: { critical: number, high: number, medium: number, suggestion: number }, degradations?: unknown }} args
  * @returns {string}
  */
@@ -40,10 +20,6 @@ export function buildOutcomeTally({ severity, degradations }) {
 }
 
 /**
- * Pure: the progress lines announcing a completed review. Always one line
- * naming the tally; a second, explicitly-worded line when a gate did not run so
- * the degradation cannot be skimmed past.
- *
  * @param {{
  *   severity: { critical: number, high: number, medium: number, suggestion: number },
  *   degradations?: unknown,

package/.agents/scripts/lib/orchestration/single-story-close/phases/review-override.js

@@ -1,26 +1,7 @@
 /**
- * phases/review-override.js — the sanctioned, logged override of a Story-scope
- * code-review critical blocker.
- *
- * Split out of `phases/review-block.js`, which owns the opposite outcome: the
- * blocker that *holds*. Keeping the two in one module meant one file owning
- * both "park this Story" and "ship it anyway", and the override's audit trail is
- * substantial enough — three write surfaces, each independently best-effort —
- * to be its own reason to change.
- *
- * **Why an override exists at all.** A critical review finding halts
- * `single-story-close.js` before auto-merge, and no flag overrode a review
- * verdict: `--skip-validation` bypasses the gate chain and `--no-auto-merge`
- * declines to arm, but neither touches the review. So an operator who had read a
- * finding and judged it wrong could only land by merging the PR by hand, which
- * bypasses the gate with no record anywhere of what was overridden or why. This
- * module does not weaken the gate; it relocates that escape hatch out of an
- * untraceable hand-merge and into a mandatory-reason audit trail.
- *
- * Live provenance: Story #5007 / PR #5022, where a FALSE critical blocker — an
- * MI finding on files `delivery.quality.gates.maintainability.ignoreGlobs`
- * exempts, which the `check-baselines.js` ratchet correctly ignored in the same
- * run — halted a legitimate delivery with a hand-merge as the only way out.
+ * phases/review-override.js — the sanctioned, logged override of a critical
+ * review blocker. It replaces an untraceable hand-merge (the only escape from
+ * a false blocker) with a mandatory-reason audit trail.
  */
 
 import { Logger } from '../../../Logger.js';
@@ -33,22 +14,9 @@ import {
   upsertStructuredComment,
 } from '../../ticketing.js';
 
-/** Cap on the reason text copied into the friction signal's `details`. */
 const REASON_SIGNAL_LIMIT = 500;
 
 /**
- * Build the audit record posted when an operator overrides a review blocker.
- * Pure.
- *
- * The body restates the count, the reason, and the fact that auto-merge was
- * armed anyway — an override whose trail says only "overridden" is no better
- * than the hand-merge it replaces.
- *
- * Module-local: an implementation detail of
- * {@link handleOverriddenReviewBlock}, whose posted body is observable through
- * that public entry point. Exporting it would add a public symbol no production
- * path reaches — the exact dead-export shape this repo ratchets against.
- *
  * @param {{ prUrl: string, criticalCount: number, reason: string }} args
  * @returns {string}
  */
@@ -70,15 +38,7 @@ function buildReviewOverrideBody({ prUrl, criticalCount, reason }) {
 }
 
 /**
- * Post one audit record, swallowing the failure into a warning.
- *
- * Every write here is best-effort by design: an override whose audit trail
- * partly failed must still land the delivery the operator authorized, because
- * the close would otherwise fail for a reason the operator cannot act on. The
- * friction signal is the durable record — it is what makes a rising override
- * count visible to the retro.
- *
- * Module-local: the two call sites below are its only callers.
+ * Best-effort: a partly failed trail must not block an authorized delivery.
  *
  * @param {{ post: () => Promise<unknown>, surface: string }} args
  * @returns {Promise<boolean>} true when the record landed.
@@ -96,13 +56,8 @@ async function postAuditRecord({ post, surface }) {
 }
 
 /**
- * Record an operator-authorized override of a critical code-review blocker,
- * then let close continue to the auto-merge phase.
- *
- * Writes to three surfaces: the Story issue via `upsert` so a re-run does not
- * stack duplicates; the PR via `post` so the trail is append-only on the surface
- * a human reviews, and so a reviewer reading the PR need not open the Story to
- * learn the blocker was overridden; and the friction stream.
+ * Records to the Story (upsert, so re-runs don't stack), the PR (append-only,
+ * where reviewers look), and the friction stream.
  *
  * @param {{
  *   provider: object,

package/.agents/scripts/lib/orchestration/single-story-close/phases/worktree-reap.js

@@ -1,30 +1,13 @@
 /**
- * phases/worktree-reap.js — reap the per-Story worktree after close.
- *
- * The Story branch is still alive on `origin` so the PR can land; the
- * local worktree is no longer needed once the PR is open. Reap is
- * best-effort: any failure is logged loudly and the close result still
- * reports success because the operator can clean stale worktrees out of
- * band.
- *
- * **Report what happened, not what was attempted** (Story #4539). This
- * phase used to set `worktreeReaped = true` and log "🧹 Reaped worktree"
- * on any non-throwing call — without reading the returned envelope. Since
- * `reap` signals refusal by *returning* `{ removed: false, reason }`
- * rather than throwing, and a v2-era precondition refused every
- * `story-<id>` worktree outright, the result was that no close ever
- * actually reaped and every close said it did. Best-effort means the close
- * still succeeds on refusal; it does not mean the close may claim an
- * outcome it never checked.
+ * phases/worktree-reap.js — best-effort reap of the per-Story worktree once
+ * the PR is open. `reap` refuses by RETURNING `{ removed: false }`, so report
+ * what happened, never merely that the call did not throw.
  */
 
 import { Logger } from '../../../Logger.js';
 import { WorktreeManager as DefaultWorktreeManager } from '../../../worktree-manager.js';
 
 /**
- * Reap the worktree for a standalone Story when isolation is enabled and
- * `reapOnSuccess` is not explicitly disabled.
- *
  * @param {{
  *   cwd: string,
  *   storyId: number,
@@ -56,20 +39,9 @@ export async function reapWorktreePhase({
           error: (m) => Logger.error(`[single-story-close] ${m}`),
         },
       });
-      // Deliberately NO base ref. This phase runs BEFORE the merge (see
-      // `../runner.js` — reap precedes the confirm phase), so "is this work
-      // integrated into the base?" is the wrong question: the answer is
-      // always no, and supplying a ref would activate `isSafeToRemove`'s
-      // merge-reachability gate and refuse every reap with
-      // `unmerged-commits` — trading one always-refuse precondition for
-      // another.
-      //
-      // What actually makes the reap safe here is that close has already
-      // pushed `story-<id>` to origin and opened the PR, so the work is
-      // durable off-machine; and `isSafeToRemove` still refuses a dirty
-      // tree (`uncommitted-changes`), which is the check that protects
-      // unsaved work. Refusal is signalled by the returned envelope rather
-      // than by throwing — so read it.
+      // NO base ref: this runs before the merge, so a merge-reachability
+      // check would refuse every reap. Safe because the work is pushed, and
+      // a dirty tree is still refused.
       const result = await wm.reap(storyId);
       worktreeReaped = result?.removed === true;
       if (worktreeReaped) {