gsd-pi 2.33.1-dev.29a8268 → 2.33.1-dev.9bafd68

package/dist/resources/extensions/gsd/auto-direct-dispatch.js

@@ -0,0 +1,180 @@
+/**
+ * Direct phase dispatch — handles manual /gsd dispatch commands.
+ * Resolves phase name → unit type + prompt, creates a session, and sends the message.
+ */
+import { deriveState } from "./state.js";
+import { loadFile, parseRoadmap } from "./files.js";
+import { resolveMilestoneFile, resolveSliceFile, relSliceFile, } from "./paths.js";
+import { buildResearchSlicePrompt, buildResearchMilestonePrompt, buildPlanSlicePrompt, buildPlanMilestonePrompt, buildExecuteTaskPrompt, buildCompleteSlicePrompt, buildCompleteMilestonePrompt, buildReassessRoadmapPrompt, buildRunUatPrompt, buildReplanSlicePrompt, } from "./auto-prompts.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { pauseAuto } from "./auto.js";
+export async function dispatchDirectPhase(ctx, pi, phase, base) {
+    const state = await deriveState(base);
+    const mid = state.activeMilestone?.id;
+    const midTitle = state.activeMilestone?.title ?? "";
+    if (!mid) {
+        ctx.ui.notify("Cannot dispatch: no active milestone.", "warning");
+        return;
+    }
+    const normalized = phase.toLowerCase();
+    let unitType;
+    let unitId;
+    let prompt;
+    switch (normalized) {
+        case "research":
+        case "research-milestone":
+        case "research-slice": {
+            const isSlice = normalized === "research-slice" || (normalized === "research" && state.phase !== "pre-planning");
+            if (isSlice) {
+                const sid = state.activeSlice?.id;
+                const sTitle = state.activeSlice?.title ?? "";
+                if (!sid) {
+                    ctx.ui.notify("Cannot dispatch research-slice: no active slice.", "warning");
+                    return;
+                }
+                // When require_slice_discussion is enabled, pause auto-mode before
+                // each new slice so the user can discuss requirements first (#789).
+                const sliceContextFile = resolveSliceFile(base, mid, sid, "CONTEXT");
+                const requireDiscussion = loadEffectiveGSDPreferences()?.preferences?.phases?.require_slice_discussion;
+                if (requireDiscussion && !sliceContextFile) {
+                    ctx.ui.notify(`Slice ${sid} requires discussion before planning. Run /gsd discuss to discuss this slice, then /gsd auto to resume.`, "info");
+                    await pauseAuto(ctx, pi);
+                    return;
+                }
+                unitType = "research-slice";
+                unitId = `${mid}/${sid}`;
+                prompt = await buildResearchSlicePrompt(mid, midTitle, sid, sTitle, base);
+            }
+            else {
+                unitType = "research-milestone";
+                unitId = mid;
+                prompt = await buildResearchMilestonePrompt(mid, midTitle, base);
+            }
+            break;
+        }
+        case "plan":
+        case "plan-milestone":
+        case "plan-slice": {
+            const isSlice = normalized === "plan-slice" || (normalized === "plan" && state.phase !== "pre-planning");
+            if (isSlice) {
+                const sid = state.activeSlice?.id;
+                const sTitle = state.activeSlice?.title ?? "";
+                if (!sid) {
+                    ctx.ui.notify("Cannot dispatch plan-slice: no active slice.", "warning");
+                    return;
+                }
+                unitType = "plan-slice";
+                unitId = `${mid}/${sid}`;
+                prompt = await buildPlanSlicePrompt(mid, midTitle, sid, sTitle, base);
+            }
+            else {
+                unitType = "plan-milestone";
+                unitId = mid;
+                prompt = await buildPlanMilestonePrompt(mid, midTitle, base);
+            }
+            break;
+        }
+        case "execute":
+        case "execute-task": {
+            const sid = state.activeSlice?.id;
+            const sTitle = state.activeSlice?.title ?? "";
+            const tid = state.activeTask?.id;
+            const tTitle = state.activeTask?.title ?? "";
+            if (!sid) {
+                ctx.ui.notify("Cannot dispatch execute-task: no active slice.", "warning");
+                return;
+            }
+            if (!tid) {
+                ctx.ui.notify("Cannot dispatch execute-task: no active task.", "warning");
+                return;
+            }
+            unitType = "execute-task";
+            unitId = `${mid}/${sid}/${tid}`;
+            prompt = await buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, base);
+            break;
+        }
+        case "complete":
+        case "complete-slice":
+        case "complete-milestone": {
+            const isSlice = normalized === "complete-slice" || (normalized === "complete" && state.phase === "summarizing");
+            if (isSlice) {
+                const sid = state.activeSlice?.id;
+                const sTitle = state.activeSlice?.title ?? "";
+                if (!sid) {
+                    ctx.ui.notify("Cannot dispatch complete-slice: no active slice.", "warning");
+                    return;
+                }
+                unitType = "complete-slice";
+                unitId = `${mid}/${sid}`;
+                prompt = await buildCompleteSlicePrompt(mid, midTitle, sid, sTitle, base);
+            }
+            else {
+                unitType = "complete-milestone";
+                unitId = mid;
+                prompt = await buildCompleteMilestonePrompt(mid, midTitle, base);
+            }
+            break;
+        }
+        case "reassess":
+        case "reassess-roadmap": {
+            const roadmapFile = resolveMilestoneFile(base, mid, "ROADMAP");
+            const roadmapContent = roadmapFile ? await loadFile(roadmapFile) : null;
+            if (!roadmapContent) {
+                ctx.ui.notify("Cannot dispatch reassess-roadmap: no roadmap found.", "warning");
+                return;
+            }
+            const roadmap = parseRoadmap(roadmapContent);
+            const completedSlices = roadmap.slices.filter(s => s.done);
+            if (completedSlices.length === 0) {
+                ctx.ui.notify("Cannot dispatch reassess-roadmap: no completed slices.", "warning");
+                return;
+            }
+            const completedSliceId = completedSlices[completedSlices.length - 1].id;
+            unitType = "reassess-roadmap";
+            unitId = `${mid}/${completedSliceId}`;
+            prompt = await buildReassessRoadmapPrompt(mid, midTitle, completedSliceId, base);
+            break;
+        }
+        case "uat":
+        case "run-uat": {
+            const sid = state.activeSlice?.id;
+            if (!sid) {
+                ctx.ui.notify("Cannot dispatch run-uat: no active slice.", "warning");
+                return;
+            }
+            const uatFile = resolveSliceFile(base, mid, sid, "UAT");
+            if (!uatFile) {
+                ctx.ui.notify("Cannot dispatch run-uat: no UAT file found.", "warning");
+                return;
+            }
+            const uatPath = relSliceFile(base, mid, sid, "UAT");
+            unitType = "run-uat";
+            unitId = `${mid}/${sid}`;
+            prompt = await buildRunUatPrompt(mid, sid, uatPath, base);
+            break;
+        }
+        case "replan":
+        case "replan-slice": {
+            const sid = state.activeSlice?.id;
+            const sTitle = state.activeSlice?.title ?? "";
+            if (!sid) {
+                ctx.ui.notify("Cannot dispatch replan-slice: no active slice.", "warning");
+                return;
+            }
+            unitType = "replan-slice";
+            unitId = `${mid}/${sid}`;
+            prompt = await buildReplanSlicePrompt(mid, midTitle, sid, sTitle, base);
+            break;
+        }
+        default:
+            ctx.ui.notify(`Unknown phase "${phase}". Valid phases: research, plan, execute, complete, reassess, uat, replan.`, "warning");
+            return;
+    }
+    ctx.ui.notify(`Dispatching ${unitType} for ${unitId}...`, "info");
+    const result = await ctx.newSession();
+    if (result.cancelled) {
+        ctx.ui.notify("Session creation cancelled.", "warning");
+        return;
+    }
+    pi.sendMessage({ customType: "gsd-dispatch", content: prompt, display: false }, { triggerTurn: true });
+}

package/dist/resources/extensions/gsd/auto-dispatch.js

@@ -0,0 +1,382 @@
+/**
+ * Auto-mode Dispatch Table — declarative phase → unit mapping.
+ *
+ * Each rule maps a GSD state to the unit type, unit ID, and prompt builder
+ * that should be dispatched. Rules are evaluated in order; the first match wins.
+ *
+ * This replaces the 130-line if-else chain in dispatchNextUnit with a
+ * data structure that is inspectable, testable per-rule, and extensible
+ * without modifying orchestration code.
+ */
+import { loadFile, loadActiveOverrides, parseRoadmap } from "./files.js";
+import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveTaskFile, relSliceFile, buildMilestoneFileName, } from "./paths.js";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { buildResearchMilestonePrompt, buildPlanMilestonePrompt, buildResearchSlicePrompt, buildPlanSlicePrompt, buildExecuteTaskPrompt, buildCompleteSlicePrompt, buildCompleteMilestonePrompt, buildValidateMilestonePrompt, buildReplanSlicePrompt, buildRunUatPrompt, buildReassessRoadmapPrompt, buildRewriteDocsPrompt, checkNeedsReassessment, checkNeedsRunUat, } from "./auto-prompts.js";
+// ─── Rewrite Circuit Breaker ──────────────────────────────────────────────
+const MAX_REWRITE_ATTEMPTS = 3;
+let rewriteAttemptCount = 0;
+export function resetRewriteCircuitBreaker() {
+    rewriteAttemptCount = 0;
+}
+/**
+ * Guard for accessing activeSlice/activeTask in dispatch rules.
+ * Returns a stop action if the expected ref is null (corrupt state).
+ */
+function requireSlice(state) {
+    if (!state.activeSlice) {
+        return { action: "stop", reason: `Phase "${state.phase}" but no active slice — run /gsd doctor.`, level: "error" };
+    }
+    return { sid: state.activeSlice.id, sTitle: state.activeSlice.title };
+}
+function requireTask(state) {
+    if (!state.activeSlice || !state.activeTask) {
+        return { action: "stop", reason: `Phase "${state.phase}" but no active slice/task — run /gsd doctor.`, level: "error" };
+    }
+    return { sid: state.activeSlice.id, sTitle: state.activeSlice.title, tid: state.activeTask.id, tTitle: state.activeTask.title };
+}
+function isStopAction(v) {
+    return typeof v === "object" && v !== null && "action" in v;
+}
+// ─── Rules ────────────────────────────────────────────────────────────────
+const DISPATCH_RULES = [
+    {
+        name: "rewrite-docs (override gate)",
+        match: async ({ mid, midTitle, state, basePath }) => {
+            const pendingOverrides = await loadActiveOverrides(basePath);
+            if (pendingOverrides.length === 0)
+                return null;
+            if (rewriteAttemptCount >= MAX_REWRITE_ATTEMPTS) {
+                const { resolveAllOverrides } = await import("./files.js");
+                await resolveAllOverrides(basePath);
+                rewriteAttemptCount = 0;
+                return null;
+            }
+            rewriteAttemptCount++;
+            const unitId = state.activeSlice ? `${mid}/${state.activeSlice.id}` : mid;
+            return {
+                action: "dispatch",
+                unitType: "rewrite-docs",
+                unitId,
+                prompt: await buildRewriteDocsPrompt(mid, midTitle, state.activeSlice, basePath, pendingOverrides),
+            };
+        },
+    },
+    {
+        name: "summarizing → complete-slice",
+        match: async ({ state, mid, midTitle, basePath }) => {
+            if (state.phase !== "summarizing")
+                return null;
+            const sliceRef = requireSlice(state);
+            if (isStopAction(sliceRef))
+                return sliceRef;
+            const { sid, sTitle } = sliceRef;
+            return {
+                action: "dispatch",
+                unitType: "complete-slice",
+                unitId: `${mid}/${sid}`,
+                prompt: await buildCompleteSlicePrompt(mid, midTitle, sid, sTitle, basePath),
+            };
+        },
+    },
+    {
+        name: "uat-verdict-gate (non-PASS blocks progression)",
+        match: async ({ mid, basePath, prefs }) => {
+            // Only applies when UAT dispatch is enabled
+            if (!prefs?.uat_dispatch)
+                return null;
+            const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
+            const roadmapContent = roadmapFile ? await loadFile(roadmapFile) : null;
+            if (!roadmapContent)
+                return null;
+            const roadmap = parseRoadmap(roadmapContent);
+            for (const slice of roadmap.slices.filter(s => s.done)) {
+                const resultFile = resolveSliceFile(basePath, mid, slice.id, "UAT-RESULT");
+                if (!resultFile)
+                    continue;
+                const content = await loadFile(resultFile);
+                if (!content)
+                    continue;
+                const verdictMatch = content.match(/verdict:\s*([\w-]+)/i);
+                const verdict = verdictMatch?.[1]?.toLowerCase();
+                if (verdict && verdict !== "pass" && verdict !== "passed") {
+                    return {
+                        action: "stop",
+                        reason: `UAT verdict for ${slice.id} is "${verdict}" — blocking progression until resolved.\nReview the UAT result and update the verdict to PASS, or re-run /gsd auto after fixing.`,
+                        level: "warning",
+                    };
+                }
+            }
+            return null;
+        },
+    },
+    {
+        name: "run-uat (post-completion)",
+        match: async ({ state, mid, basePath, prefs }) => {
+            const needsRunUat = await checkNeedsRunUat(basePath, mid, state, prefs);
+            if (!needsRunUat)
+                return null;
+            const { sliceId } = needsRunUat;
+            return {
+                action: "dispatch",
+                unitType: "run-uat",
+                unitId: `${mid}/${sliceId}`,
+                prompt: await buildRunUatPrompt(mid, sliceId, relSliceFile(basePath, mid, sliceId, "UAT"), basePath),
+            };
+        },
+    },
+    {
+        name: "reassess-roadmap (post-completion)",
+        match: async ({ state, mid, midTitle, basePath, prefs }) => {
+            // Reassess is opt-in: only fire when explicitly enabled
+            if (!prefs?.phases?.reassess_after_slice)
+                return null;
+            const needsReassess = await checkNeedsReassessment(basePath, mid, state);
+            if (!needsReassess)
+                return null;
+            return {
+                action: "dispatch",
+                unitType: "reassess-roadmap",
+                unitId: `${mid}/${needsReassess.sliceId}`,
+                prompt: await buildReassessRoadmapPrompt(mid, midTitle, needsReassess.sliceId, basePath),
+            };
+        },
+    },
+    {
+        name: "needs-discussion → stop",
+        match: async ({ state, mid, midTitle }) => {
+            if (state.phase !== "needs-discussion")
+                return null;
+            return {
+                action: "stop",
+                reason: `${mid}: ${midTitle} has draft context from a prior discussion — needs its own discussion before planning.\nRun /gsd to discuss.`,
+                level: "warning",
+            };
+        },
+    },
+    {
+        name: "pre-planning (no context) → stop",
+        match: async ({ state, mid, basePath }) => {
+            if (state.phase !== "pre-planning")
+                return null;
+            const contextFile = resolveMilestoneFile(basePath, mid, "CONTEXT");
+            const hasContext = !!(contextFile && await loadFile(contextFile));
+            if (hasContext)
+                return null; // fall through to next rule
+            return {
+                action: "stop",
+                reason: "No context or roadmap yet. Run /gsd to discuss first.",
+                level: "warning",
+            };
+        },
+    },
+    {
+        name: "pre-planning (no research) → research-milestone",
+        match: async ({ state, mid, midTitle, basePath, prefs }) => {
+            if (state.phase !== "pre-planning")
+                return null;
+            // Phase skip: skip research when preference or profile says so
+            if (prefs?.phases?.skip_research)
+                return null;
+            const researchFile = resolveMilestoneFile(basePath, mid, "RESEARCH");
+            if (researchFile)
+                return null; // has research, fall through
+            return {
+                action: "dispatch",
+                unitType: "research-milestone",
+                unitId: mid,
+                prompt: await buildResearchMilestonePrompt(mid, midTitle, basePath),
+            };
+        },
+    },
+    {
+        name: "pre-planning (has research) → plan-milestone",
+        match: async ({ state, mid, midTitle, basePath }) => {
+            if (state.phase !== "pre-planning")
+                return null;
+            return {
+                action: "dispatch",
+                unitType: "plan-milestone",
+                unitId: mid,
+                prompt: await buildPlanMilestonePrompt(mid, midTitle, basePath),
+            };
+        },
+    },
+    {
+        name: "planning (no research, not S01) → research-slice",
+        match: async ({ state, mid, midTitle, basePath, prefs }) => {
+            if (state.phase !== "planning")
+                return null;
+            // Phase skip: skip research when preference or profile says so
+            if (prefs?.phases?.skip_research || prefs?.phases?.skip_slice_research)
+                return null;
+            const sliceRef = requireSlice(state);
+            if (isStopAction(sliceRef))
+                return sliceRef;
+            const { sid, sTitle } = sliceRef;
+            const researchFile = resolveSliceFile(basePath, mid, sid, "RESEARCH");
+            if (researchFile)
+                return null; // has research, fall through
+            // Skip slice research for S01 when milestone research already exists —
+            // the milestone research already covers the same ground for the first slice.
+            const milestoneResearchFile = resolveMilestoneFile(basePath, mid, "RESEARCH");
+            if (milestoneResearchFile && sid === "S01")
+                return null; // fall through to plan-slice
+            return {
+                action: "dispatch",
+                unitType: "research-slice",
+                unitId: `${mid}/${sid}`,
+                prompt: await buildResearchSlicePrompt(mid, midTitle, sid, sTitle, basePath),
+            };
+        },
+    },
+    {
+        name: "planning → plan-slice",
+        match: async ({ state, mid, midTitle, basePath }) => {
+            if (state.phase !== "planning")
+                return null;
+            const sliceRef = requireSlice(state);
+            if (isStopAction(sliceRef))
+                return sliceRef;
+            const { sid, sTitle } = sliceRef;
+            return {
+                action: "dispatch",
+                unitType: "plan-slice",
+                unitId: `${mid}/${sid}`,
+                prompt: await buildPlanSlicePrompt(mid, midTitle, sid, sTitle, basePath),
+            };
+        },
+    },
+    {
+        name: "replanning-slice → replan-slice",
+        match: async ({ state, mid, midTitle, basePath }) => {
+            if (state.phase !== "replanning-slice")
+                return null;
+            const sliceRef = requireSlice(state);
+            if (isStopAction(sliceRef))
+                return sliceRef;
+            const { sid, sTitle } = sliceRef;
+            return {
+                action: "dispatch",
+                unitType: "replan-slice",
+                unitId: `${mid}/${sid}`,
+                prompt: await buildReplanSlicePrompt(mid, midTitle, sid, sTitle, basePath),
+            };
+        },
+    },
+    {
+        name: "executing → execute-task (recover missing task plan → plan-slice)",
+        match: async ({ state, mid, midTitle, basePath }) => {
+            if (state.phase !== "executing" || !state.activeTask)
+                return null;
+            const sliceRef = requireSlice(state);
+            if (isStopAction(sliceRef))
+                return sliceRef;
+            const { sid, sTitle } = sliceRef;
+            const tid = state.activeTask.id;
+            // Guard: if the slice plan exists but the individual task plan files are
+            // missing, the planner created S##-PLAN.md with task entries but never
+            // wrote the tasks/ directory files. Dispatch plan-slice to regenerate
+            // them rather than hard-stopping — fixes the infinite-loop described in
+            // issue #909.
+            const taskPlanPath = resolveTaskFile(basePath, mid, sid, tid, "PLAN");
+            if (!taskPlanPath || !existsSync(taskPlanPath)) {
+                return {
+                    action: "dispatch",
+                    unitType: "plan-slice",
+                    unitId: `${mid}/${sid}`,
+                    prompt: await buildPlanSlicePrompt(mid, midTitle, sid, sTitle, basePath),
+                };
+            }
+            return null;
+        },
+    },
+    {
+        name: "executing → execute-task",
+        match: async ({ state, mid, basePath }) => {
+            if (state.phase !== "executing" || !state.activeTask)
+                return null;
+            const sliceRef = requireSlice(state);
+            if (isStopAction(sliceRef))
+                return sliceRef;
+            const { sid, sTitle } = sliceRef;
+            const tid = state.activeTask.id;
+            const tTitle = state.activeTask.title;
+            return {
+                action: "dispatch",
+                unitType: "execute-task",
+                unitId: `${mid}/${sid}/${tid}`,
+                prompt: await buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, basePath),
+            };
+        },
+    },
+    {
+        name: "validating-milestone → validate-milestone",
+        match: async ({ state, mid, midTitle, basePath, prefs }) => {
+            if (state.phase !== "validating-milestone")
+                return null;
+            // Skip preference: write a minimal pass-through VALIDATION file
+            if (prefs?.phases?.skip_milestone_validation) {
+                const mDir = resolveMilestonePath(basePath, mid);
+                if (mDir) {
+                    if (!existsSync(mDir))
+                        mkdirSync(mDir, { recursive: true });
+                    const validationPath = join(mDir, buildMilestoneFileName(mid, "VALIDATION"));
+                    const content = [
+                        "---",
+                        "verdict: pass",
+                        "remediation_round: 0",
+                        "---",
+                        "",
+                        "# Milestone Validation (skipped by preference)",
+                        "",
+                        "Milestone validation was skipped via `skip_milestone_validation` preference.",
+                    ].join("\n");
+                    writeFileSync(validationPath, content, "utf-8");
+                }
+                return { action: "skip" };
+            }
+            return {
+                action: "dispatch",
+                unitType: "validate-milestone",
+                unitId: mid,
+                prompt: await buildValidateMilestonePrompt(mid, midTitle, basePath),
+            };
+        },
+    },
+    {
+        name: "completing-milestone → complete-milestone",
+        match: async ({ state, mid, midTitle, basePath }) => {
+            if (state.phase !== "completing-milestone")
+                return null;
+            return {
+                action: "dispatch",
+                unitType: "complete-milestone",
+                unitId: mid,
+                prompt: await buildCompleteMilestonePrompt(mid, midTitle, basePath),
+            };
+        },
+    },
+];
+// ─── Resolver ─────────────────────────────────────────────────────────────
+/**
+ * Evaluate dispatch rules in order. Returns the first matching action,
+ * or a "stop" action if no rule matches (unhandled phase).
+ */
+export async function resolveDispatch(ctx) {
+    for (const rule of DISPATCH_RULES) {
+        const result = await rule.match(ctx);
+        if (result)
+            return result;
+    }
+    // No rule matched — unhandled phase
+    return {
+        action: "stop",
+        reason: `Unhandled phase "${ctx.state.phase}" — run /gsd doctor to diagnose.`,
+        level: "info",
+    };
+}
+/** Exposed for testing — returns the rule names in evaluation order. */
+export function getDispatchRuleNames() {
+    return DISPATCH_RULES.map(r => r.name);
+}

package/dist/resources/extensions/gsd/auto-idempotency.js

@@ -0,0 +1,106 @@
+/**
+ * Idempotency checks for auto-mode unit dispatch.
+ *
+ * Handles completed-key membership, artifact cross-validation,
+ * consecutive skip counting, phantom skip loop detection, key eviction,
+ * and fallback persistence.
+ *
+ * Extracted from dispatchNextUnit() in auto.ts. Pure decision logic
+ * with set mutations — does NOT call dispatchNextUnit or stopAuto.
+ */
+import { invalidateAllCaches } from "./cache.js";
+import { verifyExpectedArtifact, persistCompletedKey, removePersistedKey, } from "./auto-recovery.js";
+import { resolveMilestoneFile } from "./paths.js";
+import { MAX_CONSECUTIVE_SKIPS, MAX_LIFETIME_DISPATCHES } from "./auto/session.js";
+import { parseUnitId } from "./unit-id.js";
+/**
+ * Check whether a unit should be skipped (already completed), rerun
+ * (stale completion record), or dispatched normally.
+ *
+ * Mutates s.completedKeySet, s.unitConsecutiveSkips, s.unitLifetimeDispatches,
+ * and s.recentlyEvictedKeys as needed.
+ */
+export function checkIdempotency(ictx) {
+    const { s, unitType, unitId, basePath, notify } = ictx;
+    const idempotencyKey = `${unitType}/${unitId}`;
+    // ── Primary path: key exists in completed set ──
+    if (s.completedKeySet.has(idempotencyKey)) {
+        const artifactExists = verifyExpectedArtifact(unitType, unitId, basePath);
+        if (artifactExists) {
+            // Guard against infinite skip loops
+            const skipCount = (s.unitConsecutiveSkips.get(idempotencyKey) ?? 0) + 1;
+            s.unitConsecutiveSkips.set(idempotencyKey, skipCount);
+            if (skipCount > MAX_CONSECUTIVE_SKIPS) {
+                // Cross-check: verify the unit's milestone is still active (#790)
+                const skippedMid = parseUnitId(unitId).milestone;
+                const skippedMilestoneComplete = skippedMid
+                    ? !!resolveMilestoneFile(basePath, skippedMid, "SUMMARY")
+                    : false;
+                if (skippedMilestoneComplete) {
+                    s.unitConsecutiveSkips.delete(idempotencyKey);
+                    invalidateAllCaches();
+                    notify(`Phantom skip loop cleared: ${unitType} ${unitId} belongs to completed milestone ${skippedMid}. Re-dispatching from fresh state.`, "info");
+                    return { action: "skip", reason: "phantom-loop-cleared" };
+                }
+                s.unitConsecutiveSkips.delete(idempotencyKey);
+                s.completedKeySet.delete(idempotencyKey);
+                s.recentlyEvictedKeys.add(idempotencyKey);
+                removePersistedKey(basePath, idempotencyKey);
+                invalidateAllCaches();
+                notify(`Skip loop detected: ${unitType} ${unitId} skipped ${skipCount} times without advancing. Evicting completion record and forcing reconciliation.`, "warning");
+                return { action: "skip", reason: "evicted" };
+            }
+            // Count toward lifetime cap
+            const lifeSkip = (s.unitLifetimeDispatches.get(idempotencyKey) ?? 0) + 1;
+            s.unitLifetimeDispatches.set(idempotencyKey, lifeSkip);
+            if (lifeSkip > MAX_LIFETIME_DISPATCHES) {
+                return { action: "stop", reason: `Hard loop: ${unitType} ${unitId} (skip cycle)` };
+            }
+            notify(`Skipping ${unitType} ${unitId} — already completed in a prior session. Advancing.`, "info");
+            return { action: "skip", reason: "completed" };
+        }
+        else {
+            // Stale completion record — artifact missing. Remove and re-run.
+            s.completedKeySet.delete(idempotencyKey);
+            removePersistedKey(basePath, idempotencyKey);
+            notify(`Re-running ${unitType} ${unitId} — marked complete but expected artifact missing.`, "warning");
+            return { action: "rerun", reason: "stale-key" };
+        }
+    }
+    // ── Fallback: key missing but artifact exists ──
+    if (verifyExpectedArtifact(unitType, unitId, basePath) && !s.recentlyEvictedKeys.has(idempotencyKey)) {
+        persistCompletedKey(basePath, idempotencyKey);
+        s.completedKeySet.add(idempotencyKey);
+        invalidateAllCaches();
+        // Same consecutive-skip guard as the primary path
+        const skipCount2 = (s.unitConsecutiveSkips.get(idempotencyKey) ?? 0) + 1;
+        s.unitConsecutiveSkips.set(idempotencyKey, skipCount2);
+        if (skipCount2 > MAX_CONSECUTIVE_SKIPS) {
+            const skippedMid2 = parseUnitId(unitId).milestone;
+            const skippedMilestoneComplete2 = skippedMid2
+                ? !!resolveMilestoneFile(basePath, skippedMid2, "SUMMARY")
+                : false;
+            if (skippedMilestoneComplete2) {
+                s.unitConsecutiveSkips.delete(idempotencyKey);
+                invalidateAllCaches();
+                notify(`Phantom skip loop cleared: ${unitType} ${unitId} belongs to completed milestone ${skippedMid2}. Re-dispatching from fresh state.`, "info");
+                return { action: "skip", reason: "phantom-loop-cleared" };
+            }
+            s.unitConsecutiveSkips.delete(idempotencyKey);
+            s.completedKeySet.delete(idempotencyKey);
+            removePersistedKey(basePath, idempotencyKey);
+            invalidateAllCaches();
+            notify(`Skip loop detected: ${unitType} ${unitId} skipped ${skipCount2} times without advancing. Evicting completion record and forcing reconciliation.`, "warning");
+            return { action: "skip", reason: "evicted" };
+        }
+        // Count toward lifetime cap
+        const lifeSkip2 = (s.unitLifetimeDispatches.get(idempotencyKey) ?? 0) + 1;
+        s.unitLifetimeDispatches.set(idempotencyKey, lifeSkip2);
+        if (lifeSkip2 > MAX_LIFETIME_DISPATCHES) {
+            return { action: "stop", reason: `Hard loop: ${unitType} ${unitId} (skip cycle)` };
+        }
+        notify(`Skipping ${unitType} ${unitId} — artifact exists but completion key was missing. Repaired and advancing.`, "info");
+        return { action: "skip", reason: "fallback-persisted" };
+    }
+    return { action: "proceed" };
+}