gsd-pi 2.44.0-dev.d25d507 → 2.45.0-dev.1afbdaa

package/dist/help-text.js

@@ -32,7 +32,7 @@ const SUBCOMMAND_HELP = {
     install: [
         'Usage: gsd install <source> [-l, --local]',
         '',
-        'Install a package/extension source and run declared lifecycle hooks.',
+        'Install a package/extension source and run post-install validation (dependency checks, setup).',
         '',
         'Examples:',
         '  gsd install npm:@foo/bar',

package/dist/loader.js

@@ -26,6 +26,40 @@ if (firstArg === '--help' || firstArg === '-h') {
     printHelp(gsdVersion);
     process.exit(0);
 }
+// ---------------------------------------------------------------------------
+// Runtime dependency checks — fail fast with clear diagnostics before any
+// heavy imports. Reads minimum Node version from the engines field in
+// package.json (already parsed above) and verifies git is available.
+// ---------------------------------------------------------------------------
+{
+    const MIN_NODE_MAJOR = 22;
+    const red = '\x1b[31m';
+    const bold = '\x1b[1m';
+    const dim = '\x1b[2m';
+    const reset = '\x1b[0m';
+    // -- Node version --
+    const nodeMajor = parseInt(process.versions.node.split('.')[0], 10);
+    if (nodeMajor < MIN_NODE_MAJOR) {
+        process.stderr.write(`\n${red}${bold}Error:${reset} GSD requires Node.js >= ${MIN_NODE_MAJOR}.0.0\n` +
+            `       You are running Node.js ${process.versions.node}\n\n` +
+            `${dim}Install a supported version:${reset}\n` +
+            `  nvm install ${MIN_NODE_MAJOR}   ${dim}# if using nvm${reset}\n` +
+            `  fnm install ${MIN_NODE_MAJOR}   ${dim}# if using fnm${reset}\n` +
+            `  brew install node@${MIN_NODE_MAJOR} ${dim}# macOS Homebrew${reset}\n\n`);
+        process.exit(1);
+    }
+    // -- git --
+    try {
+        const { execFileSync } = await import('child_process');
+        execFileSync('git', ['--version'], { stdio: 'ignore' });
+    }
+    catch {
+        process.stderr.write(`\n${red}${bold}Error:${reset} GSD requires git but it was not found on PATH.\n\n` +
+            `${dim}Install git:${reset}\n` +
+            `  https://git-scm.com/downloads\n\n`);
+        process.exit(1);
+    }
+}
 import { agentDir, appRoot } from './app-paths.js';
 import { serializeBundledExtensionPaths } from './bundled-extension-paths.js';
 import { discoverExtensionEntryPaths } from './extension-discovery.js';

package/dist/resources/extensions/gsd/activity-log.js

@@ -134,6 +134,13 @@ export function pruneActivityLogs(activityDir, retentionDays) {
         for (const entry of entries) {
             if (entry.seq === maxSeq)
                 continue; // always preserve highest-seq
+            if (retentionDays === 0) {
+                try {
+                    unlinkSync(entry.filePath);
+                }
+                catch { /* skip */ }
+                continue;
+            }
             try {
                 const mtime = statSync(entry.filePath).mtimeMs;
                 if (Math.floor(mtime) <= cutoff)

package/dist/resources/extensions/gsd/auto/infra-errors.js

@@ -17,6 +17,9 @@ export const INFRA_ERROR_CODES = new Set([
     "EDQUOT", // disk quota exceeded
     "EMFILE", // too many open files (process)
     "ENFILE", // too many open files (system)
+    "ECONNREFUSED", // connection refused (offline / local server down)
+    "ENOTFOUND", // DNS lookup failed (offline / no network)
+    "ENETUNREACH", // network unreachable (offline / no route)
 ]);
 /**
  * Detect whether an error is an unrecoverable infrastructure failure.

package/dist/resources/extensions/gsd/auto/phases.js

@@ -11,10 +11,15 @@ import { MAX_RECOVERY_CHARS, BUDGET_THRESHOLDS, } from "./types.js";
 import { detectStuck } from "./detect-stuck.js";
 import { runUnit } from "./run-unit.js";
 import { debugLog } from "../debug-logger.js";
-import { gsdRoot } from "../paths.js";
-import { atomicWriteSync } from "../atomic-write.js";
 import { PROJECT_FILES } from "../detection.js";
+import { MergeConflictError } from "../git-service.js";
 import { join } from "node:path";
+import { existsSync, cpSync } from "node:fs";
+import { logWarning } from "../workflow-logger.js";
+import { gsdRoot } from "../paths.js";
+import { atomicWriteSync } from "../atomic-write.js";
+import { verifyExpectedArtifact } from "../auto-recovery.js";
+import { writeUnitRuntimeRecord } from "../unit-runtime.js";
 // ─── generateMilestoneReport ──────────────────────────────────────────────────
 /**
  * Generate and write an HTML milestone report snapshot.
@@ -100,8 +105,8 @@ export async function runPreDispatch(ic, loopState) {
             return { action: "break", reason: "health-gate-failed" };
         }
     }
-    catch {
-        // Non-fatal
+    catch (e) {
+        logWarning("engine", "Pre-dispatch health gate threw unexpectedly", { error: String(e) });
     }
     // Sync project root artifacts into worktree
     if (s.originalBasePath &&
@@ -145,20 +150,20 @@ export async function runPreDispatch(ic, loopState) {
         loopState.recentUnits.length = 0;
         loopState.stuckRecoveryAttempts = 0;
         // Worktree lifecycle on milestone transition — merge current, enter next
-        deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
-        // Opt-in: create draft PR on milestone completion
-        if (prefs?.git?.auto_pr) {
-            try {
-                const { createDraftPR } = await import("../git-service.js");
-                const prUrl = createDraftPR(s.basePath, s.currentMilestoneId, `[GSD] ${s.currentMilestoneId} complete`, `Milestone ${s.currentMilestoneId} completed by GSD auto-mode.\n\nSee .gsd/${s.currentMilestoneId}/ for details.`);
-                if (prUrl) {
-                    ctx.ui.notify(`Draft PR created: ${prUrl}`, "info");
-                }
-            }
-            catch {
-                // Non-fatal — PR creation is best-effort
+        try {
+            deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
+        }
+        catch (mergeErr) {
+            if (mergeErr instanceof MergeConflictError) {
+                // Real code conflicts — stop the loop instead of retrying forever (#2330)
+                ctx.ui.notify(`Merge conflict: ${mergeErr.conflictedFiles.join(", ")}. Resolve conflicts manually and run /gsd auto to resume.`, "error");
+                await deps.stopAuto(ctx, pi, `Merge conflict on milestone ${s.currentMilestoneId}`);
+                return { action: "break", reason: "merge-conflict" };
             }
+            // Non-conflict merge errors — log and continue
+            logWarning("engine", "Milestone merge failed with non-conflict error", { milestone: s.currentMilestoneId, error: String(mergeErr) });
         }
+        // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
         deps.invalidateAllCaches();
         state = await deps.deriveState(s.basePath);
         mid = state.activeMilestone?.id;
@@ -176,15 +181,18 @@ export async function runPreDispatch(ic, loopState) {
             .filter((m) => m.status !== "complete" && m.status !== "parked")
             .map((m) => m.id);
         deps.pruneQueueOrder(s.basePath, pendingIds);
-        // Reset completed-units tracking for the new milestone — stale entries
-        // from the previous milestone cause the dispatch loop to skip units
-        // that haven't actually been completed in the new milestone's context.
-        s.completedUnits = [];
+        // Archive the old completed-units.json instead of wiping it (#2313).
         try {
             const completedKeysPath = join(gsdRoot(s.basePath), "completed-units.json");
+            if (existsSync(completedKeysPath) && s.currentMilestoneId) {
+                const archivePath = join(gsdRoot(s.basePath), `completed-units-${s.currentMilestoneId}.json`);
+                cpSync(completedKeysPath, archivePath);
+            }
             atomicWriteSync(completedKeysPath, JSON.stringify([], null, 2));
         }
-        catch { /* non-fatal */ }
+        catch (e) {
+            logWarning("engine", "Failed to archive completed-units on milestone transition", { error: String(e) });
+        }
         // Rebuild STATE.md immediately so it reflects the new active milestone.
         // This bypasses the 30-second throttle in the normal rebuild path —
         // milestone transitions are rare and important enough to warrant an
@@ -192,8 +200,8 @@ export async function runPreDispatch(ic, loopState) {
         try {
             await deps.rebuildState(s.basePath);
         }
-        catch {
-            // Non-fatal — STATE.md will be rebuilt on the next regular cycle
+        catch (e) {
+            logWarning("engine", "STATE.md rebuild failed after milestone transition", { error: String(e) });
         }
     }
     if (mid) {
@@ -209,20 +217,17 @@ export async function runPreDispatch(ic, loopState) {
         if (incomplete.length === 0 && state.registry.length > 0) {
             // All milestones complete — merge milestone branch before stopping
             if (s.currentMilestoneId) {
-                deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
-                // Opt-in: create draft PR on milestone completion
-                if (prefs?.git?.auto_pr) {
-                    try {
-                        const { createDraftPR } = await import("../git-service.js");
-                        const prUrl = createDraftPR(s.basePath, s.currentMilestoneId, `[GSD] ${s.currentMilestoneId} complete`, `Milestone ${s.currentMilestoneId} completed by GSD auto-mode.\n\nSee .gsd/${s.currentMilestoneId}/ for details.`);
-                        if (prUrl) {
-                            ctx.ui.notify(`Draft PR created: ${prUrl}`, "info");
-                        }
-                    }
-                    catch {
-                        // Non-fatal — PR creation is best-effort
+                try {
+                    deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
+                }
+                catch (mergeErr) {
+                    if (mergeErr instanceof MergeConflictError) {
+                        ctx.ui.notify(`Merge conflict: ${mergeErr.conflictedFiles.join(", ")}. Resolve conflicts manually and run /gsd auto to resume.`, "error");
+                        await deps.stopAuto(ctx, pi, `Merge conflict on milestone ${s.currentMilestoneId}`);
+                        return { action: "break", reason: "merge-conflict" };
                     }
                 }
+                // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
             }
             deps.sendDesktopNotification("GSD", "All milestones complete!", "success", "milestone");
             deps.logCmuxEvent(prefs, "All milestones complete.", "success");
@@ -277,20 +282,17 @@ export async function runPreDispatch(ic, loopState) {
     if (state.phase === "complete") {
         // Milestone merge on complete (before closeout so branch state is clean)
         if (s.currentMilestoneId) {
-            deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
-            // Opt-in: create draft PR on milestone completion
-            if (prefs?.git?.auto_pr) {
-                try {
-                    const { createDraftPR } = await import("../git-service.js");
-                    const prUrl = createDraftPR(s.basePath, s.currentMilestoneId, `[GSD] ${s.currentMilestoneId} complete`, `Milestone ${s.currentMilestoneId} completed by GSD auto-mode.\n\nSee .gsd/${s.currentMilestoneId}/ for details.`);
-                    if (prUrl) {
-                        ctx.ui.notify(`Draft PR created: ${prUrl}`, "info");
-                    }
-                }
-                catch {
-                    // Non-fatal — PR creation is best-effort
+            try {
+                deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
+            }
+            catch (mergeErr) {
+                if (mergeErr instanceof MergeConflictError) {
+                    ctx.ui.notify(`Merge conflict: ${mergeErr.conflictedFiles.join(", ")}. Resolve conflicts manually and run /gsd auto to resume.`, "error");
+                    await deps.stopAuto(ctx, pi, `Merge conflict on milestone ${s.currentMilestoneId}`);
+                    return { action: "break", reason: "merge-conflict" };
                 }
             }
+            // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
         }
         deps.sendDesktopNotification("GSD", `Milestone ${mid} complete!`, "success", "milestone");
         deps.logCmuxEvent(prefs, `Milestone ${mid} complete.`, "success");
@@ -364,7 +366,7 @@ export async function runDispatch(ic, preData, loopState) {
             if (loopState.stuckRecoveryAttempts === 0) {
                 // Level 1: try verifying the artifact, then cache invalidation + retry
                 loopState.stuckRecoveryAttempts++;
-                const artifactExists = deps.verifyExpectedArtifact(unitType, unitId, s.basePath);
+                const artifactExists = verifyExpectedArtifact(unitType, unitId, s.basePath);
                 if (artifactExists) {
                     debugLog("autoLoop", {
                         phase: "stuck-recovery",
@@ -584,13 +586,14 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
     const unitStartSeq = ic.nextSeq();
     deps.emitJournalEvent({ ts: new Date().toISOString(), flowId: ic.flowId, seq: unitStartSeq, eventType: "unit-start", data: { unitType, unitId } });
     deps.captureAvailableSkills();
-    deps.writeUnitRuntimeRecord(s.basePath, unitType, unitId, s.currentUnit.startedAt, {
+    writeUnitRuntimeRecord(s.basePath, unitType, unitId, s.currentUnit.startedAt, {
         phase: "dispatched",
         wrapupWarningSent: false,
         timeoutAt: null,
         lastProgressAt: s.currentUnit.startedAt,
         progressCount: 0,
         lastProgressKind: "dispatch",
+        recoveryAttempts: 0, // Reset so re-dispatched units get full recovery budget (#2322)
     });
     // Status bar + progress widget
     ctx.ui.setStatus("gsd-auto", "auto");
@@ -643,8 +646,8 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
                     (requirementsContent?.length ?? 0) +
                     (projectContent?.length ?? 0);
         }
-        catch {
-            // Non-fatal
+        catch (e) {
+            logWarning("engine", "Baseline char count measurement failed", { error: String(e) });
         }
     }
     // Cache-optimize prompt section ordering
@@ -653,7 +656,7 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
     }
     catch (reorderErr) {
         const msg = reorderErr instanceof Error ? reorderErr.message : String(reorderErr);
-        process.stderr.write(`[gsd] prompt reorder failed (non-fatal): ${msg}\n`);
+        logWarning("engine", "Prompt reorder failed", { error: msg });
     }
     // Select and apply model (with tier escalation on retry — normal units only)
     const modelResult = await deps.selectAndApplyModel(ctx, pi, unitType, unitId, s.basePath, prefs, s.verbose, s.autoModeStartModel, sidecarItem ? undefined : { isRetry, previousTier });
@@ -698,7 +701,7 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
     });
     // Write preliminary lock (no session path yet — runUnit creates a new session).
     // Crash recovery can still identify the in-flight unit from this lock.
-    deps.writeLock(deps.lockBase(), unitType, unitId, s.completedUnits.length);
+    deps.writeLock(deps.lockBase(), unitType, unitId);
     debugLog("autoLoop", {
         phase: "runUnit-start",
         iteration: ic.iteration,
@@ -715,8 +718,8 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
     });
     // Now that runUnit has called newSession(), the session file path is correct.
     const sessionFile = deps.getSessionFile(ctx);
-    deps.updateSessionLock(deps.lockBase(), unitType, unitId, s.completedUnits.length, sessionFile);
-    deps.writeLock(deps.lockBase(), unitType, unitId, s.completedUnits.length, sessionFile);
+    deps.updateSessionLock(deps.lockBase(), unitType, unitId, sessionFile);
+    deps.writeLock(deps.lockBase(), unitType, unitId, sessionFile);
     // Tag the most recent window entry with error info for stuck detection
     if (unitResult.status === "error" || unitResult.status === "cancelled") {
         const lastEntry = loopState.recentUnits[loopState.recentUnits.length - 1];
@@ -760,8 +763,8 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
                     warning: "Task completed with 0 tool calls — likely hallucinated, marking as failed",
                 });
                 ctx.ui.notify(`${unitType} ${unitId} completed with 0 tool calls — hallucinated summary, will retry`, "warning");
-                // Do NOT add to completedUnits — fall through to next iteration
-                // where dispatch will re-derive and re-dispatch this task.
+                // Fall through to next iteration where dispatch will re-derive
+                // and re-dispatch this task.
                 return { action: "next", data: { unitStartedAt: s.currentUnit.startedAt } };
             }
         }
@@ -771,25 +774,8 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
     }
     const skipArtifactVerification = unitType.startsWith("hook/") || unitType === "custom-step";
     const artifactVerified = skipArtifactVerification ||
-        deps.verifyExpectedArtifact(unitType, unitId, s.basePath);
+        verifyExpectedArtifact(unitType, unitId, s.basePath);
     if (artifactVerified) {
-        s.completedUnits.push({
-            type: unitType,
-            id: unitId,
-            startedAt: s.currentUnit.startedAt,
-            finishedAt: Date.now(),
-        });
-        if (s.completedUnits.length > 200) {
-            s.completedUnits = s.completedUnits.slice(-200);
-        }
-        // Flush completed-units to disk so the record survives crashes
-        try {
-            const completedKeysPath = join(gsdRoot(s.basePath), "completed-units.json");
-            const keys = s.completedUnits.map((u) => `${u.type}/${u.id}`);
-            atomicWriteSync(completedKeysPath, JSON.stringify(keys, null, 2));
-        }
-        catch { /* non-fatal: disk flush failure */ }
-        deps.clearUnitRuntimeRecord(s.basePath, unitType, unitId);
         s.unitDispatchCount.delete(`${unitType}/${unitId}`);
         s.unitRecoveryCount.delete(`${unitType}/${unitId}`);
     }
@@ -822,8 +808,8 @@ export async function runFinalize(ic, iterData, sidecarItem) {
     // Sidecar items use lightweight pre-verification opts
     const preVerificationOpts = sidecarItem
         ? sidecarItem.kind === "hook"
-            ? { skipSettleDelay: true, skipDoctor: true, skipStateRebuild: true, skipWorktreeSync: true }
-            : { skipSettleDelay: true, skipStateRebuild: true }
+            ? { skipSettleDelay: true, skipWorktreeSync: true }
+            : { skipSettleDelay: true }
         : undefined;
     const preResult = await deps.postUnitPreVerification(postUnitCtx, preVerificationOpts);
     if (preResult === "dispatched") {

package/dist/resources/extensions/gsd/auto/run-unit.js

@@ -6,6 +6,7 @@
 import { NEW_SESSION_TIMEOUT_MS } from "./session.js";
 import { _setCurrentResolve, _setSessionSwitchInFlight } from "./resolve.js";
 import { debugLog } from "../debug-logger.js";
+import { logWarning } from "../workflow-logger.js";
 /**
  * Execute a single unit: create a new session, send the prompt, and await
  * the agent_end promise. Returns a UnitResult describing what happened.
@@ -66,7 +67,9 @@ export async function runUnit(ctx, pi, s, unitType, unitId, prompt) {
             process.chdir(s.basePath);
         }
     }
-    catch { /* non-fatal — chdir may fail if dir was removed */ }
+    catch (e) {
+        logWarning("engine", "Failed to chdir to basePath before dispatch", { basePath: s.basePath, error: String(e) });
+    }
     // ── Send the prompt ──
     debugLog("runUnit", { phase: "send-message", unitType, unitId });
     pi.sendMessage({ customType: "gsd-auto", content: prompt, display: s.verbose }, { triggerTurn: true });
@@ -90,8 +93,8 @@ export async function runUnit(ctx, pi, s, unitType, unitId, prompt) {
             cmdCtxAny.clearQueue();
         }
     }
-    catch {
-        // Non-fatal — clearQueue may not be available in all contexts
+    catch (e) {
+        logWarning("engine", "clearQueue failed after unit completion", { error: String(e) });
     }
     return result;
 }

package/dist/resources/extensions/gsd/auto/session.js

@@ -46,7 +46,6 @@ export class AutoSession {
     // ── Current unit ─────────────────────────────────────────────────────────
     currentUnit = null;
     currentUnitRouting = null;
-    completedUnits = [];
     currentMilestoneId = null;
     // ── Model state ──────────────────────────────────────────────────────────
     autoModeStartModel = null;
@@ -100,14 +99,6 @@ export class AutoSession {
     get lockBasePath() {
         return this.originalBasePath || this.basePath;
     }
-    completeCurrentUnit() {
-        if (!this.currentUnit)
-            return null;
-        const done = { ...this.currentUnit, finishedAt: Date.now() };
-        this.completedUnits.push(done);
-        this.currentUnit = null;
-        return done;
-    }
     reset() {
         this.clearTimers();
         // Lifecycle
@@ -129,7 +120,6 @@ export class AutoSession {
         // Unit
         this.currentUnit = null;
         this.currentUnitRouting = null;
-        this.completedUnits = [];
         this.currentMilestoneId = null;
         // Model
         this.autoModeStartModel = null;
@@ -164,7 +154,6 @@ export class AutoSession {
             activeRunDir: this.activeRunDir,
             currentMilestoneId: this.currentMilestoneId,
             currentUnit: this.currentUnit,
-            completedUnits: this.completedUnits.length,
             unitDispatchCount: Object.fromEntries(this.unitDispatchCount),
         };
     }

package/dist/resources/extensions/gsd/auto-artifact-paths.js

@@ -0,0 +1,112 @@
+// GSD Auto-mode — Artifact Path Resolution
+//
+// resolveExpectedArtifactPath and diagnoseExpectedArtifact moved here from
+// auto-recovery.ts (Phase 5 dead-code cleanup). The artifact verification
+// function was removed entirely — callers now query WorkflowEngine directly.
+import { resolveMilestonePath, resolveSlicePath, relMilestoneFile, relSliceFile, buildMilestoneFileName, buildSliceFileName, buildTaskFileName, } from "./paths.js";
+import { join } from "node:path";
+/**
+ * Resolve the expected artifact for a unit to an absolute path.
+ */
+export function resolveExpectedArtifactPath(unitType, unitId, base) {
+    const parts = unitId.split("/");
+    const mid = parts[0];
+    const sid = parts[1];
+    switch (unitType) {
+        case "discuss-milestone": {
+            const dir = resolveMilestonePath(base, mid);
+            return dir ? join(dir, buildMilestoneFileName(mid, "CONTEXT")) : null;
+        }
+        case "research-milestone": {
+            const dir = resolveMilestonePath(base, mid);
+            return dir ? join(dir, buildMilestoneFileName(mid, "RESEARCH")) : null;
+        }
+        case "plan-milestone": {
+            const dir = resolveMilestonePath(base, mid);
+            return dir ? join(dir, buildMilestoneFileName(mid, "ROADMAP")) : null;
+        }
+        case "research-slice": {
+            const dir = resolveSlicePath(base, mid, sid);
+            return dir ? join(dir, buildSliceFileName(sid, "RESEARCH")) : null;
+        }
+        case "plan-slice": {
+            const dir = resolveSlicePath(base, mid, sid);
+            return dir ? join(dir, buildSliceFileName(sid, "PLAN")) : null;
+        }
+        case "reassess-roadmap": {
+            const dir = resolveSlicePath(base, mid, sid);
+            return dir ? join(dir, buildSliceFileName(sid, "ASSESSMENT")) : null;
+        }
+        case "run-uat": {
+            const dir = resolveSlicePath(base, mid, sid);
+            return dir ? join(dir, buildSliceFileName(sid, "UAT-RESULT")) : null;
+        }
+        case "execute-task": {
+            const tid = parts[2];
+            const dir = resolveSlicePath(base, mid, sid);
+            return dir && tid
+                ? join(dir, "tasks", buildTaskFileName(tid, "SUMMARY"))
+                : null;
+        }
+        case "complete-slice": {
+            const dir = resolveSlicePath(base, mid, sid);
+            return dir ? join(dir, buildSliceFileName(sid, "SUMMARY")) : null;
+        }
+        case "validate-milestone": {
+            const dir = resolveMilestonePath(base, mid);
+            return dir ? join(dir, buildMilestoneFileName(mid, "VALIDATION")) : null;
+        }
+        case "complete-milestone": {
+            const dir = resolveMilestonePath(base, mid);
+            return dir ? join(dir, buildMilestoneFileName(mid, "SUMMARY")) : null;
+        }
+        case "replan-slice": {
+            const dir = resolveSlicePath(base, mid, sid);
+            return dir ? join(dir, buildSliceFileName(sid, "REPLAN")) : null;
+        }
+        case "rewrite-docs":
+            return null;
+        case "reactive-execute":
+            // Reactive execute produces multiple task summaries — verified separately
+            return null;
+        default:
+            return null;
+    }
+}
+export function diagnoseExpectedArtifact(unitType, unitId, base) {
+    const parts = unitId.split("/");
+    const mid = parts[0];
+    const sid = parts[1];
+    switch (unitType) {
+        case "discuss-milestone":
+            return `${relMilestoneFile(base, mid, "CONTEXT")} (milestone context from discussion)`;
+        case "research-milestone":
+            return `${relMilestoneFile(base, mid, "RESEARCH")} (milestone research)`;
+        case "plan-milestone":
+            return `${relMilestoneFile(base, mid, "ROADMAP")} (milestone roadmap)`;
+        case "research-slice":
+            return `${relSliceFile(base, mid, sid, "RESEARCH")} (slice research)`;
+        case "plan-slice":
+            return `${relSliceFile(base, mid, sid, "PLAN")} (slice plan)`;
+        case "execute-task": {
+            const tid = parts[2];
+            return `Task ${tid} marked [x] in ${relSliceFile(base, mid, sid, "PLAN")} + summary written`;
+        }
+        case "complete-slice":
+            return `Slice ${sid} marked [x] in ${relMilestoneFile(base, mid, "ROADMAP")} + summary + UAT written`;
+        case "replan-slice":
+            return `${relSliceFile(base, mid, sid, "REPLAN")} + updated ${relSliceFile(base, mid, sid, "PLAN")}`;
+        case "rewrite-docs":
+            return "Active overrides resolved in .gsd/OVERRIDES.md + plan documents updated";
+        case "reassess-roadmap":
+            return `${relSliceFile(base, mid, sid, "ASSESSMENT")} (roadmap reassessment)`;
+        case "run-uat":
+            return `${relSliceFile(base, mid, sid, "UAT-RESULT")} (UAT result)`;
+        case "validate-milestone":
+            return `${relMilestoneFile(base, mid, "VALIDATION")} (milestone validation report)`;
+        case "complete-milestone":
+            return `${relMilestoneFile(base, mid, "SUMMARY")} (milestone summary)`;
+        default:
+            return null;
+    }
+}