mandrel 2.0.0 → 2.2.0

package/.agents/scripts/lib/orchestration/post-merge/phases/notification.js

@@ -1,78 +0,0 @@
-/**
- * phases/notification.js — post-merge story-complete notification phase.
- *
- * Fires a single consolidated story-merged webhook, then a rolled-up
- * `epic-progress` webhook (comment-suppressed) so operators see the
- * Epic's stories-done count tick up at each story-close without
- * subscribing to the per-story `story-merged` channel. The rolled-up
- * dispatch is best-effort — a flaky webhook MUST NOT block story-close.
- */
-
-import { notify } from '../../../../notify.js';
-import { Logger } from '../../../Logger.js';
-
-function reapPhaseLogger(progress) {
-  return progress ?? (() => {});
-}
-
-export async function notificationPhase(ctx, state) {
-  const {
-    epicId,
-    storyId,
-    story,
-    epicBranch,
-    config,
-    progress,
-    provider,
-    notifyFn = notify,
-    logger = Logger,
-  } = ctx;
-  const closedTickets = state.ticketClosure?.closedTickets ?? [];
-  const log = reapPhaseLogger(progress);
-  log('NOTIFY', `Sending story-complete notification for Story #${storyId}...`);
-  await notifyFn(
-    epicId,
-    {
-      severity: 'medium',
-      message: `✅ Story #${storyId} — *${story.title}* — has been completed and merged into \`${epicBranch}\`. ${closedTickets.length} ticket(s) closed.`,
-      event: 'story-merged',
-      level: 'story',
-      epicId,
-    },
-    { config },
-  );
-  // Fire a rolled-up `epic-progress` webhook so operators see the Epic's
-  // overall stories-done count tick up at each story-close, without
-  // subscribing to the per-story `story-merged` channel. Comment is
-  // suppressed (skipComment: true) — the operator-facing GitHub
-  // comment is owned by the wave-record path; this fire is webhook-only.
-  // Failures are swallowed by design (warn-then-continue) so a flaky
-  // webhook never blocks story-close.
-  if (provider && epicId) {
-    try {
-      const subs = (await provider.getSubTickets?.(epicId)) ?? [];
-      const stories = subs.filter(
-        (t) => Array.isArray(t.labels) && t.labels.includes('type::story'),
-      );
-      const total = stories.length;
-      const done = stories.filter((s) => s.state === 'closed').length;
-      const pct = total === 0 ? 0 : Math.round((done / total) * 100);
-      await notifyFn(
-        epicId,
-        {
-          severity: 'medium',
-          message: `Epic #${epicId} progress · ${done}/${total} stories done (${pct}%) · Story #${storyId} merged`,
-          event: 'epic-progress',
-          level: 'epic',
-          epicId,
-        },
-        { config, skipComment: true },
-      );
-    } catch (err) {
-      logger?.warn?.(
-        `[notificationPhase] rolled-up epic-progress dispatch failed (swallowed): ${err?.message ?? err}`,
-      );
-    }
-  }
-  log('NOTIFY', '✅ Notification sent');
-}

package/.agents/scripts/lib/orchestration/post-merge/phases/temp-cleanup.js

@@ -1,68 +0,0 @@
-/**
- * phases/temp-cleanup.js — remove the per-Story manifest pair under
- * `temp/epic-<eid>/stories/story-<sid>/manifest.{md,json}` (Epic #1030
- * Story #1040). Falls back to the legacy flat
- * `temp/story-manifest-<id>.{md,json}` layout when `epicId` is unknown
- * — both paths are tried so partial migrations don't leak files in
- * either layout. All deletes are idempotent; ENOENT is silently
- * absorbed.
- */
-
-import path from 'node:path';
-import { storyArtifactPath } from '../../../config/temp-paths.js';
-
-function reapPhaseLogger(progress) {
-  return progress ?? (() => {});
-}
-
-export async function tempCleanupPhase(ctx) {
-  const { storyId, epicId, projectRoot, progress, unlinkFn, config } = ctx;
-  const log = reapPhaseLogger(progress);
-  const unlink = unlinkFn ?? (await import('node:fs/promises')).unlink;
-
-  // Per-Epic layout (Epic #1030 Story #1040): `temp/epic-<eid>/stories/story-<sid>/manifest.{md,json}`.
-  // Legacy flat layout: `temp/story-manifest-<sid>.{md,json}`. The migration
-  // tolerates both — try the per-Epic path first when `epicId` is known,
-  // and always sweep the legacy path so a half-migrated cohort doesn't
-  // leave residue.
-  const targets = [];
-  if (epicId) {
-    const eid = Number(epicId);
-    const sid = Number(storyId);
-    targets.push(
-      {
-        path: storyArtifactPath(eid, sid, 'manifest.md', config),
-        label: `temp/epic-${epicId}/stories/story-${storyId}/manifest.md`,
-      },
-      {
-        path: storyArtifactPath(eid, sid, 'manifest.json', config),
-        label: `temp/epic-${epicId}/stories/story-${storyId}/manifest.json`,
-      },
-    );
-  }
-  // Legacy flat layout is rooted at the framework's projectRoot — this is
-  // a half-migrated-cohort sweep, not a configured-tempRoot target. Once
-  // the legacy paths can no longer exist on any live install, this block
-  // can be deleted entirely.
-  const legacyBase = path.join(
-    projectRoot,
-    'temp',
-    `story-manifest-${storyId}`,
-  );
-  targets.push(
-    { path: `${legacyBase}.md`, label: `temp/story-manifest-${storyId}.md` },
-    {
-      path: `${legacyBase}.json`,
-      label: `temp/story-manifest-${storyId}.json`,
-    },
-  );
-
-  for (const target of targets) {
-    try {
-      await unlink(target.path);
-      log('CLEANUP', `🗑️  Deleted ${target.label}`);
-    } catch {
-      // File may not exist — deletion is idempotent.
-    }
-  }
-}

package/.agents/scripts/lib/orchestration/post-merge/phases/ticket-closure.js

@@ -1,118 +0,0 @@
-/**
- * phases/ticket-closure.js — post-merge ticket transition + cascade phase.
- *
- * Transitions the Story to `agent::done`, then runs cascade completion
- * so any parent Epic-side rollup that is now fully resolved closes too.
- *
- * **2-tier closure (Story #3127).** Under the 2-tier hierarchy a Story
- * is the leaf unit of execution and has no child tickets — `tasks`
- * arrives as an empty array. `batchTransitionTickets` handles the empty
- * input cleanly (the loop trivially completes), the Story is
- * transitioned alone, and cascade completion walks upward to
- * parent. No branch on hierarchy mode is required here.
- *
- * Notifications are intentionally
- * NOT routed through the per-ticket transitions here — `notificationPhase`
- * fires a single rolled-up story-complete message immediately after this
- * phase, so threading `notify` through would double-emit events on every
- * close (Story #2534 / Task #2539).
- */
-
-import { batchTransitionTickets } from '../../../story-lifecycle.js';
-import { toDone } from '../../label-transitions.js';
-import { cascadeCompletion, STATE_LABELS } from '../../ticketing.js';
-
-function reapPhaseLogger(progress) {
-  return progress ?? (() => {});
-}
-
-export async function ticketClosurePhase(ctx) {
-  const { provider, tasks, storyId, progress, logger } = ctx;
-  const log = reapPhaseLogger(progress);
-
-  // The `notify` function is intentionally NOT forwarded to per-ticket
-  // transitions here. `notificationPhase` fires a single consolidated
-  // story-complete message immediately after this phase; passing notify
-  // through would emit redundant state-transition events (one from the
-  // cascade-up triggered by any child ticket, one from the explicit
-  // Story toDone below) that show up as duplicate Slack/webhook lines per
-  // story close.
-  log(
-    'TICKETS',
-    `Transitioning ${tasks.length} child ticket(s) to agent::done...`,
-  );
-  const batch = await batchTransitionTickets(
-    provider,
-    tasks,
-    STATE_LABELS.DONE,
-    { progress: log },
-  );
-  const closedTickets = [...batch.transitioned, ...batch.skipped];
-
-  // Story #2534 / Task #2539 — auto-transition `agent::closing →
-  // agent::done` deterministically and idempotently on every successful
-  // merge. The pre-Story #2534 path silently swallowed transport errors
-  // here, which made an already-merged-but-not-labelled Story look closed
-  // in the close-result envelope. We now:
-  //   - read the Story snapshot first to detect an "already done" state
-  //     (label `agent::done` AND issue state `closed`) and treat re-runs
-  //     as a no-op record, satisfying the idempotency contract;
-  //   - otherwise call `toDone` unconditionally — there is no other
-  //     conditional skip in any normal exit path;
-  //   - rethrow transport errors so the surrounding
-  //     `runPhase('ticket-closure', ...)` logs the failure loudly via
-  //     `[phase=ticket-closure] <message>` instead of letting the close
-  //     report success on a half-failed transition.
-  log('TICKETS', `Transitioning Story #${storyId} to agent::done...`);
-  let storySnapshot = null;
-  try {
-    storySnapshot = await provider.getTicket(storyId);
-  } catch (err) {
-    logger?.warn?.(
-      `[phase=tickets]   Story #${storyId} snapshot read failed (continuing with transition): ${err?.message ?? err}`,
-    );
-  }
-  const alreadyDone =
-    storySnapshot &&
-    Array.isArray(storySnapshot.labels) &&
-    storySnapshot.labels.includes(STATE_LABELS.DONE) &&
-    storySnapshot.state === 'closed';
-  if (alreadyDone) {
-    log(
-      'TICKETS',
-      `  #${storyId} already agent::done — no-op (idempotent re-run)`,
-    );
-    closedTickets.push(storyId);
-  } else {
-    await toDone(provider, [storyId]);
-    closedTickets.push(storyId);
-    log('TICKETS', `  #${storyId} → agent::done ✅`);
-  }
-
-  log('TICKETS', 'Running cascade completion...');
-  let cascadedTo = [];
-  let cascadeFailed = [];
-  try {
-    const cascade = (await cascadeCompletion(provider, storyId)) ?? {
-      cascadedTo: [],
-      failed: [],
-    };
-    cascadedTo = cascade.cascadedTo ?? [];
-    cascadeFailed = cascade.failed ?? [];
-    if (cascadedTo.length > 0) {
-      log(
-        'TICKETS',
-        `  Cascaded to: ${cascadedTo.map((id) => `#${id}`).join(', ')}`,
-      );
-    }
-    for (const { parentId, error } of cascadeFailed) {
-      logger.error(
-        `  Cascade partial-failure on parent #${parentId}: ${error}`,
-      );
-    }
-  } catch (err) {
-    logger.error(`  Cascade fully failed (non-fatal): ${err.message}`);
-  }
-
-  return { closedTickets, cascadedTo, cascadeFailed };
-}

package/.agents/scripts/lib/orchestration/post-merge/phases/worktree-reap.js

@@ -1,397 +0,0 @@
-/**
- * phases/worktree-reap.js — post-merge worktree reap phase.
- *
- * After a Story branch is merged (pre-v2: into the Epic branch; v2:
- * squash-merged to `main` via `single-story-close.js`), this phase removes
- * the per-Story worktree at `.worktrees/story-<id>/`. The reap is split
- * into three concerns:
- *
- *   1. `worktreeReapPhase` — the phase entry point. Honors the
- *      `worktreeIsolation.{enabled,reapOnSuccess}` config, delegates the
- *      actual remove to `WorktreeManager.reap`, then runs a re-prune
- *      retry loop to clear stale `.git/worktrees/<name>/` registry
- *      entries that Windows file-locks occasionally leave behind.
- *   2. `applyStillRegisteredState` — classifies a still-registered entry
- *      after retries as either `stale-registry-entry` (operationally
- *      complete; schedule pending-cleanup drain) or `still-registered`
- *      (genuine failure; OPERATOR ACTION REQUIRED).
- *   3. Friction-signal emission via `signals-writer` so retrospectives
- *      surface lock failures and stale-registry escalations.
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { setTimeout as sleepPromise } from 'node:timers/promises';
-import { getStoryBranch } from '../../../git-utils.js';
-import { appendSignal } from '../../../observability/signals-writer.js';
-import { recordPendingCleanup } from '../../../worktree/lifecycle/pending-cleanup.js';
-import { WorktreeManager } from '../../../worktree-manager.js';
-
-const WINDOWS_LOCK_RE =
-  /(permission denied|access is denied|directory not empty|resource busy|device or resource busy|sharing violation|EACCES|EBUSY|ENOTEMPTY)/i;
-
-/**
- * Backoff delays (ms) between `git worktree prune` + re-list passes when a
- * worktree entry is still registered after a successful reap. On Windows the
- * registry-cleanup half of `git worktree remove` often loses a race with a
- * background file handle (Defender / Search indexer / the editor) — the
- * directory and branch are gone, but `.git/worktrees/<name>/` is locked
- * for a beat. Three retries (250ms, 1s, 4s) cover the common case without
- * adding noticeable latency to clean POSIX runs.
- */
-const STALE_REGISTRY_REPRUNE_DELAYS_MS = [250, 1000, 4000];
-
-function isWindowsReapLockFailure(reason) {
-  return typeof reason === 'string' && WINDOWS_LOCK_RE.test(reason);
-}
-
-function findStillRegisteredEntry(entries, storyId) {
-  if (!Array.isArray(entries)) return undefined;
-  const want = Number(storyId);
-  return entries.find((r) => {
-    if (!r || typeof r.path !== 'string') return false;
-    const match = r.path.match(/[/\\]story-(\d+)$/);
-    return match ? Number(match[1]) === want : false;
-  });
-}
-
-function resolveWorktreeRoot(repoRoot, delivery) {
-  if (!repoRoot) return null;
-  const configuredRoot = delivery?.worktreeIsolation?.root ?? '.worktrees';
-  return path.join(repoRoot, configuredRoot);
-}
-
-async function retryPruneUntilCleared(
-  wm,
-  storyId,
-  { sleep, delays = STALE_REGISTRY_REPRUNE_DELAYS_MS } = {},
-) {
-  const sleepFn = typeof sleep === 'function' ? sleep : sleepPromise;
-  let attempts = 0;
-  let lastEntry;
-  for (const delay of delays) {
-    await sleepFn(delay);
-    attempts += 1;
-    if (typeof wm.prune === 'function') {
-      try {
-        await wm.prune();
-      } catch {
-        // best-effort — prune failure is non-fatal; fall through to list check
-      }
-    }
-    const refreshed = (await wm.list()) ?? [];
-    lastEntry = findStillRegisteredEntry(refreshed, storyId);
-    if (!lastEntry) return { cleared: true, attempts };
-  }
-  return { cleared: false, attempts, stillRegistered: lastEntry };
-}
-
-function reapPhaseLogger(progress) {
-  return progress ?? (() => {});
-}
-
-export function createWorktreeReapState(overrides = {}) {
-  return {
-    status: 'not-run',
-    path: null,
-    reason: null,
-    method: null,
-    pendingCleanup: null,
-    branchDeleted: null,
-    remoteBranchDeleted: null,
-    ...overrides,
-  };
-}
-
-async function emitReapFailureFriction({
-  storyId,
-  epicId,
-  reapResult,
-  epicBranch,
-  logger,
-  config,
-}) {
-  if (!epicId || !storyId) return;
-  const reason = String(reapResult?.reason ?? 'unknown');
-  const wtPath = reapResult?.path ?? '(unknown path)';
-  try {
-    await appendSignal({
-      epicId: Number(epicId),
-      storyId: Number(storyId),
-      signal: {
-        kind: 'friction',
-        ts: new Date().toISOString(),
-        epicId: Number(epicId),
-        storyId: Number(storyId),
-        category: 'reap-failure',
-        emitter: { tool: 'story-close.js' },
-        details: { message: `Worktree reap failed: ${reason}` },
-        epicBranch,
-        worktreePath: wtPath,
-        reason,
-      },
-      config,
-    });
-  } catch (err) {
-    logger?.warn?.(
-      `[post-merge-pipeline] friction signal append failed: ${err?.message ?? err}`,
-    );
-  }
-}
-
-function resolveSkipState(wtConfig, log) {
-  if (!wtConfig?.enabled) {
-    log('WORKTREE', '⏭️ Skipping worktree reap (worktree isolation disabled)');
-    return createWorktreeReapState({ status: 'skipped-disabled' });
-  }
-  if (!(wtConfig.reapOnSuccess ?? true)) {
-    log('WORKTREE', '⏭️ Skipping worktree reap (reapOnSuccess=false)');
-    return createWorktreeReapState({ status: 'skipped-config' });
-  }
-  return null;
-}
-
-function resolveInitialReapStatus(reapResult) {
-  if (reapResult.removed) return 'removed';
-  if (reapResult.method === 'deferred-to-sweep') return 'deferred-to-sweep';
-  return 'failed';
-}
-
-function initialReapState(reapResult) {
-  return createWorktreeReapState({
-    status: resolveInitialReapStatus(reapResult),
-    path: reapResult.path ?? null,
-    reason: reapResult.reason ?? null,
-    method: reapResult.method ?? null,
-    pendingCleanup: reapResult.pendingCleanup ?? null,
-    branchDeleted:
-      reapResult.branchDeleted !== undefined ? reapResult.branchDeleted : null,
-    remoteBranchDeleted:
-      reapResult.remoteBranchDeleted !== undefined
-        ? reapResult.remoteBranchDeleted
-        : null,
-  });
-}
-
-async function logReapOutcome({
-  reapResult,
-  log,
-  logger,
-  storyId,
-  epicId,
-  epicBranch,
-  config,
-}) {
-  if (reapResult.removed) {
-    log('WORKTREE', `🗑️  Reaped worktree: ${reapResult.path}`);
-    return;
-  }
-  if (!reapResult.reason) return;
-  await emitReapFailureFriction({
-    storyId,
-    epicId,
-    reapResult,
-    epicBranch,
-    logger,
-    config,
-  });
-  log(
-    'WORKTREE',
-    `⚠️  Worktree not reaped (${reapResult.reason}): ${reapResult.path}`,
-  );
-  if (isWindowsReapLockFailure(reapResult.reason)) {
-    logger.error(
-      `[story-close] OPERATOR ACTION REQUIRED: Worktree at ${reapResult.path} ` +
-        `could not be removed (Windows lock/permission error: ${reapResult.reason}). ` +
-        'Close any editor/terminal holding the path, then run ' +
-        '`git worktree remove <path> --force && git worktree prune` to clean up.',
-    );
-  }
-}
-
-async function detectStillRegistered({ wm, storyId, log, sleep }) {
-  const leftover = (await wm.list()) ?? [];
-  const initial = findStillRegisteredEntry(leftover, storyId);
-  if (!initial) return null;
-  const retry = await retryPruneUntilCleared(wm, storyId, { sleep });
-  if (retry.cleared) {
-    log(
-      'WORKTREE',
-      `🧹 Stale worktree registry entry cleared after ${retry.attempts} re-prune attempt(s)`,
-    );
-    return null;
-  }
-  return retry.stillRegistered ?? initial;
-}
-
-async function escalateStillRegistered({
-  state,
-  stillRegistered,
-  storyId,
-  epicId,
-  epicBranch,
-  logger,
-  config,
-}) {
-  logger.error(
-    `[story-close] OPERATOR ACTION REQUIRED: Worktree still registered after reap: ` +
-      `${stillRegistered.path}. Run ` +
-      '`git worktree remove <path> --force && git worktree prune` to clean up.',
-  );
-  await emitReapFailureFriction({
-    storyId,
-    epicId,
-    reapResult: {
-      path: stillRegistered.path,
-      reason: 'still-registered-after-reap',
-    },
-    epicBranch,
-    logger,
-    config,
-  });
-  return state;
-}
-
-function logStaleRegistryEntry({ state, stillRegistered, logger }) {
-  logger.warn(
-    `[story-close] Worktree directory removed and branch deleted, but ` +
-      `\`git worktree list\` still shows ${stillRegistered.path}. ` +
-      'Scheduled for background prune via pending-cleanup; ' +
-      `branchDeleted=${state.branchDeleted}.`,
-  );
-  return state;
-}
-
-export async function worktreeReapPhase(ctx) {
-  const {
-    delivery,
-    storyId,
-    epicId,
-    epicBranch,
-    repoRoot,
-    progress,
-    logger,
-    worktreeManagerFactory,
-    config,
-    sleep,
-    recordPendingCleanupFn = recordPendingCleanup,
-    pathExistsFn = fs.existsSync,
-  } = ctx;
-  const wtConfig = delivery?.worktreeIsolation;
-  const log = reapPhaseLogger(progress);
-  const skipState = resolveSkipState(wtConfig, log);
-  if (skipState) return skipState;
-
-  const wm = worktreeManagerFactory
-    ? worktreeManagerFactory({ repoRoot, config: wtConfig })
-    : new WorktreeManager({ repoRoot, config: wtConfig });
-  const reapResult = await wm.reap(storyId, { epicBranch });
-  let state = initialReapState(reapResult);
-  await logReapOutcome({
-    reapResult,
-    log,
-    logger,
-    storyId,
-    epicId,
-    epicBranch,
-    config,
-  });
-
-  const stillRegistered = await detectStillRegistered({
-    wm,
-    storyId,
-    log,
-    sleep,
-  });
-  if (!stillRegistered) return state;
-
-  state = applyStillRegisteredState({
-    state,
-    stillRegistered,
-    reapResult,
-    storyId,
-    delivery,
-    repoRoot,
-    logger,
-    recordPendingCleanupFn,
-    pathExistsFn,
-  });
-  if (state.status === 'still-registered') {
-    return escalateStillRegistered({
-      state,
-      stillRegistered,
-      storyId,
-      epicId,
-      epicBranch,
-      logger,
-      config,
-    });
-  }
-  if (state.status === 'stale-registry-entry') {
-    return logStaleRegistryEntry({ state, stillRegistered, logger });
-  }
-  return state;
-}
-
-/**
- * Decide how to treat a worktree entry that is still registered after reap +
- * re-prune retries. Two outcomes:
- *
- *   - `stale-registry-entry` (operationally complete): the reap succeeded,
- *     the worktree directory is gone, and the local branch was deleted by
- *     reap. The only artifact left is the `.git/worktrees/<name>/` registry
- *     entry — a Windows file-lock artifact, not a genuine cleanup failure.
- *     Record a pending-cleanup entry so the post-close drain (or the next
- *     plan-time sweep) re-runs `git worktree prune`, and let the close
- *     pipeline report `branchDeleted: true` honestly.
- *   - `still-registered` (genuine failure): the directory is still on disk
- *     OR the branch was not deleted. The pre-existing OPERATOR ACTION
- *     escalation still fires.
- */
-function applyStillRegisteredState({
-  state,
-  stillRegistered,
-  reapResult,
-  storyId,
-  delivery,
-  repoRoot,
-  logger,
-  recordPendingCleanupFn,
-  pathExistsFn,
-}) {
-  const pathGone = !pathExistsFn(stillRegistered.path);
-  const branchDeleted = reapResult.branchDeleted === true;
-  const operationallyComplete =
-    reapResult.removed === true && pathGone && branchDeleted;
-  if (!operationallyComplete) {
-    return {
-      ...state,
-      status: 'still-registered',
-      path: stillRegistered.path,
-      reason: 'still-registered-after-reap',
-    };
-  }
-  const worktreeRoot = resolveWorktreeRoot(repoRoot, delivery);
-  let manifestEntry = null;
-  if (worktreeRoot) {
-    try {
-      manifestEntry = recordPendingCleanupFn(worktreeRoot, {
-        storyId: Number(storyId),
-        branch: getStoryBranch(storyId),
-        path: stillRegistered.path,
-        push: false,
-      });
-    } catch (err) {
-      logger?.warn?.(
-        `[post-merge-pipeline] pending-cleanup record failed (continuing): ${err?.message ?? err}`,
-      );
-    }
-  }
-  return {
-    ...state,
-    status: 'stale-registry-entry',
-    path: stillRegistered.path,
-    reason: 'stale-registry-entry',
-    pendingCleanup: manifestEntry ?? state.pendingCleanup,
-  };
-}