mandrel 1.85.0 → 1.86.0

package/.agents/rules/git-conventions.md

@@ -120,6 +120,39 @@ rejected by `pre-push` hooks):
       (`--no-errors-on-unmatched` or equivalent) before escalating via
       `agent::blocked`.
 
+## Local checkout hygiene
+
+**Invariant: the delivering flow owns tidying the local checkout — reaping its
+own merged refs and fast-forwarding the base branch. `/git-cleanup` is a
+recovery tool, not a routine chore.**
+
+Every flow that lands work — `/deliver` (Epic and standalone-Story paths),
+`/git-deliver` — is responsible for leaving the local checkout tidy without
+operator intervention:
+
+- **Fast-forwarding the base branch is owned by the flow.** The standalone
+  multi-Story path fast-forwards `main` itself in its summary phase (via
+  `git-cleanup.js --fast-forward-main --execute --yes`); the Epic path
+  fast-forwards `epic/<id>` / `main` on its merge-and-reap beat. No workflow
+  ends by telling the operator to "run `/git-cleanup` afterwards to catch up".
+- **Reaping merged local refs is owned by the flow's next boot.** `/plan` and
+  `/git-deliver` open with a **protected boot sweep**
+  (`boot-sweep.js`) that fast-forwards `main`, prunes stale remote-tracking
+  refs, and reaps every local branch whose PR is already merged — skipping any
+  candidate with unpushed work, a dirty worktree, or a still-open parent
+  ticket. A branch a flow leaves behind (e.g. a `/git-deliver` feature branch
+  whose PR merges out of band) is therefore reaped automatically at the next
+  workflow boot, not left for the operator to sweep by hand.
+- **`/git-cleanup` is recovery, not routine.** Run it by hand only to recover
+  an unusual state the automated hygiene does not cover — triaging stashes,
+  reaping across non-standard branch namespaces, or `--remote` pruning after a
+  force-push diverged a tip. It is **not** the expected way to keep `main`
+  current or to clear merged branches after a normal delivery; the delivering
+  flows already own that. If you find yourself reaching for `/git-cleanup`
+  after every routine `/deliver` or `/git-deliver` run, that is a signal the
+  owning flow's hygiene step regressed — fix the flow, do not codify the manual
+  sweep.
+
 ## Meta Labels (Retrospective Signal Routing)
 
 Two `meta::*` labels route retrospective signals into durable substrates so

package/.agents/scripts/boot-sweep.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+/* node:coverage ignore file */
+
+/**
+ * boot-sweep.js — protected boot-sweep CLI (Story #4373).
+ *
+ * A thin, non-interactive wrapper over the scope-agnostic
+ * [`sweepMergedBranches`](./lib/single-story-sweep.js) engine, exposed so
+ * workflow prose can invoke a *protected* boot sweep directly. Unlike the
+ * plain `git-cleanup.js --branches` phase (which reaps every merged
+ * candidate the planner surfaces), this surface always applies the
+ * `evaluateProtection` partition — a merged branch with unpushed work, a
+ * dirty worktree, or a still-open parent Story ticket is skipped, not
+ * reaped.
+ *
+ * The sweep is best-effort: any failure (lock contention, git/gh error)
+ * is swallowed and reported in the result envelope, never thrown, so a
+ * caller can wire it into a boot path without risking the host run.
+ *
+ * Usage:
+ *   node .agents/scripts/boot-sweep.js [--include <glob>...] \
+ *     [--exclude <glob>...] [--current <branch>] [--base <branch>] \
+ *     [--no-fast-forward] [--json]
+ *
+ * Defaults: `--include story-*`, fast-forward the base branch on.
+ * Exit code is always 0 — a boot sweep never fails its host.
+ */
+
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+
+import { runAsCli } from './lib/cli-utils.js';
+import { PROJECT_ROOT, resolveConfig } from './lib/config-resolver.js';
+import { Logger } from './lib/Logger.js';
+import { createProvider } from './lib/provider-factory.js';
+import { buildProtectionCtx } from './lib/single-story-sweep/protection-ctx.js';
+import { sweepMergedBranches } from './lib/single-story-sweep.js';
+
+const HELP = `Usage: node .agents/scripts/boot-sweep.js [options]
+
+Runs the protected merged-branch boot sweep non-interactively: reaps every
+local branch whose PR is MERGED and whose HEAD matches the merged headRefOid,
+skipping any candidate the protection partition flags (unpushed work, dirty
+worktree, still-open parent Story), then fast-forwards the base branch.
+
+Options:
+  --include <glob>     Branch glob to sweep (repeatable). Default: story-*
+  --exclude <glob>     Branch glob to exclude (repeatable).
+  --current <branch>   A branch to always exclude (e.g. the active story).
+  --base <branch>      Base branch to fast-forward. Default: project baseBranch.
+  --no-fast-forward    Skip the base-branch fast-forward step.
+  --json               Emit the result envelope as JSON.
+`;
+
+/**
+ * Run the protected boot sweep. Best-effort: swallows any error and
+ * returns the sweep envelope so no caller can be blocked by a failure.
+ *
+ * DI-friendly: `injectedConfig` / `injectedProvider` let a caller (e.g.
+ * `epic-deliver-prepare.js`) reuse an already-resolved config + provider,
+ * and `injectedSweep` swaps the engine for unit tests.
+ *
+ * @param {{
+ *   cwd?: string,
+ *   base?: string,
+ *   include?: string[],
+ *   exclude?: string[],
+ *   current?: string,
+ *   fastForward?: boolean,
+ *   injectedConfig?: object,
+ *   injectedProvider?: object,
+ *   injectedSweep?: Function,
+ *   logger?: { info?: Function, warn?: Function },
+ * }} [args]
+ * @returns {Promise<object>} the {@link sweepMergedBranches} envelope.
+ */
+export async function runBootSweep({
+  cwd,
+  base,
+  include,
+  exclude,
+  current,
+  fastForward = true,
+  injectedConfig,
+  injectedProvider,
+  injectedSweep,
+  logger = Logger,
+} = {}) {
+  const root = path.resolve(cwd ?? PROJECT_ROOT);
+  try {
+    // Config/provider resolution is inside the try so a malformed
+    // `.agentrc.json` (or a provider-construction throw) degrades to the
+    // swallowed `ok:false` envelope below rather than propagating and
+    // exiting non-zero — the "host continues, exit 0" boot-sweep contract
+    // must hold even when config resolution is the thing that fails.
+    const config = injectedConfig ?? resolveConfig({ cwd: root });
+    const provider = injectedProvider ?? createProvider(config);
+    const baseBranch = base ?? config.project?.baseBranch ?? 'main';
+
+    const includeGlobs =
+      Array.isArray(include) && include.length > 0 ? include : ['story-*'];
+    const excludeGlobs = Array.isArray(exclude) ? [...exclude] : [];
+    if (typeof current === 'string' && current.length > 0) {
+      excludeGlobs.push(current);
+    }
+
+    const tempRoot = config?.project?.paths?.tempRoot ?? 'temp';
+    const lockPath = path.resolve(root, tempRoot, 'boot-sweep.lock');
+    const lockTimeoutMs =
+      config.delivery?.worktreeIsolation?.sweepLockMs ?? 60_000;
+
+    const sweepFn = injectedSweep ?? sweepMergedBranches;
+    return await sweepFn({
+      cwd: root,
+      baseBranch,
+      include: includeGlobs,
+      exclude: excludeGlobs,
+      fastForward,
+      logTag: '[boot-sweep]',
+      logger: {
+        info: (m) => logger.info?.(m),
+        warn: (m) => logger.warn?.(m),
+      },
+      protectionCtx: buildProtectionCtx({ cwd: root, provider }),
+      lockPath,
+      lockTimeoutMs,
+    });
+  } catch (err) {
+    const msg = err?.message ?? String(err);
+    logger.warn?.(`[boot-sweep] sweep threw (host continues): ${msg}`);
+    return {
+      ok: false,
+      skipped: true,
+      error: msg,
+      candidates: 0,
+      localDeleted: 0,
+      remoteDeleted: 0,
+      protected: [],
+      failures: [],
+    };
+  }
+}
+
+async function main() {
+  const { values } = parseArgs({
+    options: {
+      base: { type: 'string' },
+      cwd: { type: 'string' },
+      include: { type: 'string', multiple: true, default: [] },
+      exclude: { type: 'string', multiple: true, default: [] },
+      current: { type: 'string' },
+      'no-fast-forward': { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+      help: { type: 'boolean', short: 'h' },
+    },
+    strict: false,
+  });
+
+  if (values.help) {
+    Logger.info(HELP);
+    return;
+  }
+
+  const result = await runBootSweep({
+    cwd: typeof values.cwd === 'string' ? values.cwd : undefined,
+    base: typeof values.base === 'string' ? values.base : undefined,
+    include: Array.isArray(values.include) ? values.include : [],
+    exclude: Array.isArray(values.exclude) ? values.exclude : [],
+    current: typeof values.current === 'string' ? values.current : undefined,
+    fastForward: values['no-fast-forward'] !== true,
+  });
+
+  if (values.json) {
+    Logger.info(JSON.stringify(result, null, 2));
+  } else {
+    const protectedCount = result.protected?.length ?? 0;
+    Logger.info(
+      `[boot-sweep] reaped ${result.localDeleted} local + ${result.remoteDeleted} remote; protected ${protectedCount}.`,
+    );
+  }
+}
+
+runAsCli(import.meta.url, main, { source: 'boot-sweep' });

package/.agents/scripts/epic-deliver-prepare.js

@@ -36,6 +36,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
 
+import { runBootSweep } from './boot-sweep.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { getPaths, getRunners, resolveConfig } from './lib/config-resolver.js';
 import { currentBranch as gitCurrentBranch } from './lib/git-branch-lifecycle.js';
@@ -218,6 +219,49 @@ async function runPreflightGuardsForPrepare({
   });
 }
 
+/**
+ * Route the Epic boot cleanup through the shared protected boot-sweep
+ * engine (Story #4373). Reaps merged, done `story-*` branches left over
+ * from prior runs — the protection partition skips any branch with
+ * unpushed work, a dirty worktree, or a still-open parent Story, so an
+ * in-flight Story is never touched. Fast-forward is off: the prepare may
+ * run on the Epic branch, and the fast-forward phase would otherwise
+ * check out the base branch.
+ *
+ * Best-effort — a sweep failure (lock contention, git/gh error) is
+ * swallowed and never blocks or fails the prepare. Skipped in the same
+ * injected-test shape the preflight guards use (a provider injected with
+ * no git seam) so unit tests never spawn real git/gh.
+ */
+async function runBootSweepForPrepare({
+  cwd,
+  config,
+  provider,
+  injectedProvider,
+  injectedGit,
+  injectedSweep,
+  skipPreflightGuards,
+}) {
+  const suppressed =
+    skipPreflightGuards || (Boolean(injectedProvider) && !injectedGit);
+  if (suppressed) return;
+  try {
+    await runBootSweep({
+      cwd,
+      include: ['story-*'],
+      fastForward: false,
+      injectedConfig: config,
+      injectedProvider: provider,
+      injectedSweep,
+      logger: Logger,
+    });
+  } catch (err) {
+    Logger.warn(
+      `[epic-deliver-prepare] ⚠️ boot sweep threw (prepare continues): ${err?.message ?? err}`,
+    );
+  }
+}
+
 /**
  * Resolve the Epic state, preferring the preflight cache (Story #3027) and
  * falling back to a fresh snapshot + wave-DAG pass on miss or baseSha
@@ -333,6 +377,7 @@ export async function runEpicDeliverPrepare({
   steal = false,
   asOperator,
   injectedGit,
+  injectedSweep,
   leaseHeartbeatAt,
   leaseNow,
   skipPreflightGuards = false,
@@ -365,6 +410,16 @@ export async function runEpicDeliverPrepare({
     skipPreflightGuards,
   });
 
+  await runBootSweepForPrepare({
+    cwd,
+    config,
+    provider,
+    injectedProvider,
+    injectedGit,
+    injectedSweep,
+    skipPreflightGuards,
+  });
+
   const { state, cacheStatus } = await resolvePrepareState({
     epicId,
     cwd,

package/.agents/scripts/lib/orchestration/epic-cleanup.js

@@ -29,8 +29,12 @@
  */
 
 import { spawnSync } from 'node:child_process';
-
 import { parseWorktreePorcelain } from '../worktree/inspector.js';
+import {
+  executeFastForward,
+  planFastForward,
+} from './git-cleanup/phases/fast-forward.js';
+import { makeFfProbes } from './git-cleanup/phases/git-probes-ff.js';
 
 const WT_SCRATCH_BRANCH = 'wt-branch';
 
@@ -328,6 +332,51 @@ export function deleteWtBranchIfPresent(opts) {
   return { deleted: false, present: true, stderr };
 }
 
+/**
+ * Fast-forward the base branch to its remote after a confirmed merge, so a
+ * post-`/deliver` local checkout converges to `origin/<baseBranch>` without a
+ * manual `git pull`. Reuses `planFastForward` + `executeFastForward` from the
+ * git-cleanup phase library (the single source of the FF state machine),
+ * feeding them probes bound to the injected `gitSpawn`.
+ *
+ * @param {{
+ *   cwd: string,
+ *   baseBranch?: string,
+ *   remoteName?: string,
+ *   gitSpawn: (cwd: string, ...args: string[]) => { status: number, stdout: string, stderr: string },
+ *   logger?: { info?: Function, warn?: Function },
+ * }} opts
+ * @returns {{ ok: boolean, applied: boolean, skipped: boolean, reason?: string, behind?: number, stderr?: string }}
+ */
+export function fastForwardBaseBranch(opts) {
+  const {
+    cwd,
+    baseBranch = 'main',
+    remoteName = 'origin',
+    gitSpawn,
+    logger,
+  } = opts;
+  const probe = makeFfProbes(gitSpawn);
+  const plan = planFastForward({
+    cwd,
+    baseBranch,
+    remoteName,
+    isCleanFn: probe.isClean,
+    currentBranchFn: probe.currentBranch,
+    fetchFn: probe.fetch,
+    canFastForwardFn: probe.canFastForward,
+  });
+  return executeFastForward({
+    cwd,
+    baseBranch,
+    remoteName,
+    plan,
+    checkoutFn: probe.checkout,
+    mergeFn: probe.merge,
+    ...(logger ? { logger } : {}),
+  });
+}
+
 /**
  * Reap every branch owned by the Epic. Best-effort — failures aggregate into
  * the result rather than throwing.
@@ -350,6 +399,7 @@ export function deleteWtBranchIfPresent(opts) {
  *   switched: { switched: boolean, from: string|null, to: string|null, stderr?: string } | null,
  *   pruned: { pruned: string[], stderr?: string } | null,
  *   wtBranch: { deleted: boolean, present: boolean, reason?: string, stderr?: string } | null,
+ *   fastForward: { ok: boolean, applied: boolean, skipped: boolean, reason?: string, behind?: number, stderr?: string } | null,
  *   epicBranchKept: boolean,
  *   ok: boolean,
  * }}
@@ -375,6 +425,7 @@ export function reapEpicBranches(opts) {
       switched: null,
       pruned: null,
       wtBranch: null,
+      fastForward: null,
       epicBranchKept: false,
       ok: true,
     };
@@ -463,6 +514,26 @@ export function reapEpicBranches(opts) {
     logger?.info?.(`[epic-cleanup] deleted stale ${WT_SCRATCH_BRANCH} ref`);
   }
 
+  // After a confirmed merge (epic branch NOT kept), fast-forward the base
+  // branch so the local checkout converges to `origin/<baseBranch>` with no
+  // manual `git pull`. When the epic branch is kept (open PR), the merge is
+  // not confirmed, so the FF is skipped with an explicit reason rather than
+  // moving `main` under an in-flight PR.
+  const fastForward = epicHasOpenPr
+    ? { ok: true, applied: false, skipped: true, reason: 'epic-branch-kept' }
+    : fastForwardBaseBranch({
+        cwd,
+        baseBranch,
+        remoteName: remote,
+        gitSpawn,
+        logger,
+      });
+  if (fastForward.applied) {
+    logger?.info?.(
+      `[epic-cleanup] fast-forwarded ${baseBranch} by ${fastForward.behind} commit(s) to ${remote}/${baseBranch}`,
+    );
+  }
+
   const failures = reaped.filter((r) => !r.branchDeleted);
   return {
     epicId: state?.epicId ?? null,
@@ -471,7 +542,224 @@ export function reapEpicBranches(opts) {
     switched,
     pruned,
     wtBranch,
+    fastForward,
     epicBranchKept: epicHasOpenPr,
     ok: failures.length === 0,
   };
 }
+
+/**
+ * Does a local branch head ref exist? Thin `git rev-parse --verify` wrapper
+ * exported for the resume-detect path (and its tests).
+ *
+ * @param {{ cwd: string, gitSpawn: Function, branch: string }} opts
+ * @returns {boolean}
+ */
+export function localRefExists({ cwd, gitSpawn, branch }) {
+  const res = gitSpawn(
+    cwd,
+    'rev-parse',
+    '--verify',
+    '--quiet',
+    `refs/heads/${branch}`,
+  );
+  return res.status === 0;
+}
+
+/**
+ * Probe whether the Epic branch's PR is MERGED and, if so, its URL (needed
+ * for the `epic.merge.armed` payload). Fails CLOSED to
+ * `{ merged: false, prUrl: null }` on any probe error — an indeterminate
+ * probe must never auto-arm a destructive reap.
+ *
+ * @param {{
+ *   epicBranch: string,
+ *   cwd: string,
+ *   spawnFn?: typeof spawnSync,
+ *   logger?: { warn?: Function },
+ * }} opts
+ * @returns {{ merged: boolean, prUrl: string|null }}
+ */
+export function epicPrMergeState(opts) {
+  const { epicBranch, cwd, spawnFn = spawnSync, logger } = opts;
+  if (typeof epicBranch !== 'string' || epicBranch.length === 0) {
+    return { merged: false, prUrl: null };
+  }
+  let result;
+  try {
+    result = spawnFn(
+      'gh',
+      [
+        'pr',
+        'list',
+        '--head',
+        epicBranch,
+        '--state',
+        'merged',
+        '--json',
+        'number,url,mergedAt',
+        '--limit',
+        '1',
+      ],
+      { cwd, encoding: 'utf-8', shell: false },
+    );
+  } catch (err) {
+    logger?.warn?.(
+      `[epic-cleanup] merged-PR probe threw for ${epicBranch} (treating as unmerged): ${err?.message ?? err}`,
+    );
+    return { merged: false, prUrl: null };
+  }
+  if (!result || result.status !== 0) {
+    logger?.warn?.(
+      `[epic-cleanup] merged-PR probe failed for ${epicBranch} (status=${result?.status}): ${(result?.stderr ?? '').trim()}`,
+    );
+    return { merged: false, prUrl: null };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(String(result.stdout ?? '').trim() || '[]');
+  } catch {
+    return { merged: false, prUrl: null };
+  }
+  if (!Array.isArray(parsed) || parsed.length === 0) {
+    return { merged: false, prUrl: null };
+  }
+  const row = parsed[0];
+  const prUrl =
+    typeof row?.url === 'string' && row.url.length > 0 ? row.url : null;
+  // A merged-state row with no usable URL cannot arm (the schema requires a
+  // `prUrl`), so treat it as not-armable.
+  return { merged: prUrl !== null, prUrl };
+}
+
+/**
+ * Detect a merged-but-uncleaned Epic: the PR merged but one or more local
+ * `epic/<id>` / `story-<id>` refs still linger. This is the signal `/deliver`
+ * idempotent resume uses to auto-fire `epic.merge.armed` so Phase 9 reaps
+ * without a manual command. Pure given its injected ports.
+ *
+ * @param {{
+ *   state: object|null,
+ *   cwd: string,
+ *   gitSpawn: Function,
+ *   spawnFn?: Function,
+ *   prMergeStateFn?: typeof epicPrMergeState,
+ *   logger?: { warn?: Function, info?: Function },
+ * }} opts
+ * @returns {{
+ *   epicId: number|null,
+ *   epicBranch: string|null,
+ *   presentRefs: string[],
+ *   localRefsPresent: boolean,
+ *   merged: boolean,
+ *   prUrl: string|null,
+ *   shouldArm: boolean,
+ *   reason: string,
+ * }}
+ */
+export function detectMergedUncleanedEpic(opts) {
+  const {
+    state,
+    cwd,
+    gitSpawn,
+    spawnFn,
+    prMergeStateFn = epicPrMergeState,
+    logger,
+  } = opts;
+  const { epicBranch, storyBranches } = listEpicBranchesFromState(state);
+  if (!epicBranch) {
+    return {
+      epicId: null,
+      epicBranch: null,
+      presentRefs: [],
+      localRefsPresent: false,
+      merged: false,
+      prUrl: null,
+      shouldArm: false,
+      reason: 'no-state',
+    };
+  }
+  const presentRefs = [epicBranch, ...storyBranches].filter((branch) =>
+    localRefExists({ cwd, gitSpawn, branch }),
+  );
+  if (presentRefs.length === 0) {
+    // Already clean — nothing to arm. This is the idempotent no-op that
+    // makes re-running `/deliver` on an already-reaped Epic safe.
+    return {
+      epicId: state.epicId,
+      epicBranch,
+      presentRefs,
+      localRefsPresent: false,
+      merged: false,
+      prUrl: null,
+      shouldArm: false,
+      reason: 'no-local-refs',
+    };
+  }
+  const { merged, prUrl } = prMergeStateFn({
+    epicBranch,
+    cwd,
+    spawnFn,
+    logger,
+  });
+  const shouldArm = merged && prUrl !== null;
+  return {
+    epicId: state.epicId,
+    epicBranch,
+    presentRefs,
+    localRefsPresent: true,
+    merged,
+    prUrl,
+    shouldArm,
+    reason: shouldArm ? 'merged-uncleaned' : 'not-merged',
+  };
+}
+
+/**
+ * `/deliver` idempotent-resume auto-arm: detect a merged-but-uncleaned Epic
+ * and, when found, fire `epic.merge.armed` on the injected lifecycle `bus` so
+ * the Cleaner → BranchCleaner chain reaps Phase 9 without an operator command.
+ * A no-op (and never throws on a clean/unmerged Epic) so re-running resume is
+ * safe.
+ *
+ * @param {{
+ *   state: object|null,
+ *   cwd: string,
+ *   gitSpawn: Function,
+ *   spawnFn?: Function,
+ *   bus: { emit: (event: string, payload: object) => Promise<unknown> },
+ *   detectFn?: typeof detectMergedUncleanedEpic,
+ *   logger?: { warn?: Function, info?: Function },
+ * }} opts
+ * @returns {Promise<{ armed: boolean, reason: string, prUrl: string|null, detection: object }>}
+ */
+export async function armCleanupIfMerged(opts) {
+  const { state, cwd, gitSpawn, spawnFn, bus, detectFn, logger } = opts;
+  if (!bus || typeof bus.emit !== 'function') {
+    throw new TypeError('armCleanupIfMerged requires a bus exposing emit()');
+  }
+  const detect = detectFn ?? detectMergedUncleanedEpic;
+  const detection = detect({ state, cwd, gitSpawn, spawnFn, logger });
+  if (!detection.shouldArm) {
+    return {
+      armed: false,
+      reason: detection.reason,
+      prUrl: detection.prUrl,
+      detection,
+    };
+  }
+  const payload = { prUrl: detection.prUrl };
+  if (Number.isInteger(detection.epicId) && detection.epicId > 0) {
+    payload.epicId = detection.epicId;
+  }
+  await bus.emit('epic.merge.armed', payload);
+  logger?.info?.(
+    `[epic-cleanup] resume auto-arm: fired epic.merge.armed for ${detection.epicBranch} (${detection.prUrl})`,
+  );
+  return {
+    armed: true,
+    reason: 'merged-uncleaned',
+    prUrl: detection.prUrl,
+    detection,
+  };
+}