gsd-pi 2.10.12 → 2.12.0

package/src/resources/extensions/gsd/auto.ts

@@ -16,19 +16,20 @@ import type {
   ExtensionCommandContext,
 } from "@gsd/pi-coding-agent";
 
-import { deriveState } from "./state.js";
+import { deriveState, invalidateStateCache } from "./state.js";
 import type { GSDState } from "./types.js";
-import { loadFile, parseContinue, parsePlan, parseRoadmap, parseSummary, extractUatType, inlinePriorMilestoneSummary, getManifestStatus } from "./files.js";
+import { loadFile, parseContinue, parsePlan, parseRoadmap, parseSummary, extractUatType, inlinePriorMilestoneSummary, getManifestStatus, clearParseCache } from "./files.js";
 export { inlinePriorMilestoneSummary };
 import type { UatType } from "./files.js";
 import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
-import { loadPrompt } from "./prompt-loader.js";
+import { loadPrompt, inlineTemplate } from "./prompt-loader.js";
 import {
   gsdRoot, resolveMilestoneFile, resolveSliceFile, resolveSlicePath,
   resolveMilestonePath, resolveDir, resolveTasksDir, resolveTaskFiles, resolveTaskFile,
   relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relMilestonePath,
   milestonesDir, resolveGsdRootFile, relGsdRootFile,
   buildMilestoneFileName, buildSliceFileName, buildTaskFileName,
+  clearPathCache,
 } from "./paths.js";
 import { saveActivityLog } from "./activity-log.js";
 import { synthesizeCrashRecovery, getDeepDiagnostic } from "./session-forensics.js";
@@ -42,6 +43,18 @@ import {
 } from "./unit-runtime.js";
 import { resolveAutoSupervisorConfig, resolveModelForUnit, resolveModelWithFallbacksForUnit, resolveSkillDiscoveryMode, loadEffectiveGSDPreferences } from "./preferences.js";
 import type { GSDPreferences } from "./preferences.js";
+import {
+  checkPostUnitHooks,
+  getActiveHook,
+  resetHookState,
+  isRetryPending,
+  consumeRetryTrigger,
+  runPreDispatchHooks,
+  persistHookState,
+  restoreHookState,
+  clearPersistedHookState,
+  formatHookStatus,
+} from "./post-unit-hooks.js";
 import {
   validatePlanBoundary,
   validateExecuteBoundary,
@@ -71,6 +84,7 @@ import {
   mergeSliceToMain,
 } from "./worktree.js";
 import { GitServiceImpl, runGit } from "./git-service.js";
+import { nativeCommitCountBetween } from "./native-git-bridge.js";
 import { getPriorSliceCompletionBlocker } from "./dispatch-guard.js";
 import type { GitPreferences } from "./git-service.js";
 import { truncateToWidth, visibleWidth } from "@gsd/pi-tui";
@@ -164,6 +178,14 @@ let unitTimeoutHandle: ReturnType<typeof setTimeout> | null = null;
 let wrapupWarningHandle: ReturnType<typeof setTimeout> | null = null;
 let idleWatchdogHandle: ReturnType<typeof setInterval> | null = null;
 
+/** Dispatch gap watchdog — detects when the state machine stalls between units.
+ *  After handleAgentEnd completes, if auto-mode is still active but no new unit
+ *  has been dispatched (sendMessage not called), this timer fires to force a
+ *  re-evaluation. Covers the case where dispatchNextUnit silently fails or
+ *  an unhandled error kills the dispatch chain. */
+let dispatchGapHandle: ReturnType<typeof setTimeout> | null = null;
+const DISPATCH_GAP_TIMEOUT_MS = 5_000; // 5 seconds
+
 /** SIGTERM handler registered while auto-mode is active — cleared on stop/pause. */
 let _sigtermHandler: (() => void) | null = null;
 
@@ -269,6 +291,48 @@ function clearUnitTimeout(): void {
     clearInterval(idleWatchdogHandle);
     idleWatchdogHandle = null;
   }
+  clearDispatchGapWatchdog();
+}
+
+function clearDispatchGapWatchdog(): void {
+  if (dispatchGapHandle) {
+    clearTimeout(dispatchGapHandle);
+    dispatchGapHandle = null;
+  }
+}
+
+/**
+ * Start a watchdog that fires if no new unit is dispatched within DISPATCH_GAP_TIMEOUT_MS
+ * after handleAgentEnd completes. This catches the case where the dispatch chain silently
+ * breaks (e.g., unhandled exception in dispatchNextUnit) and auto-mode is left active but idle.
+ *
+ * The watchdog is cleared on the next successful unit dispatch (clearUnitTimeout is called
+ * at the start of handleAgentEnd, which calls clearDispatchGapWatchdog).
+ */
+function startDispatchGapWatchdog(ctx: ExtensionContext, pi: ExtensionAPI): void {
+  clearDispatchGapWatchdog();
+  dispatchGapHandle = setTimeout(async () => {
+    dispatchGapHandle = null;
+    if (!active || !cmdCtx) return;
+
+    // Auto-mode is active but no unit was dispatched — the state machine stalled.
+    // Re-derive state and attempt a fresh dispatch.
+    ctx.ui.notify(
+      "Dispatch gap detected — no unit dispatched after previous unit completed. Re-evaluating state.",
+      "warning",
+    );
+
+    try {
+      await dispatchNextUnit(ctx, pi);
+    } catch (retryErr) {
+      const message = retryErr instanceof Error ? retryErr.message : String(retryErr);
+      ctx.ui.notify(
+        `Dispatch gap recovery failed: ${message}. Stopping auto-mode.`,
+        "error",
+      );
+      await stopAuto(ctx, pi);
+    }
+  }, DISPATCH_GAP_TIMEOUT_MS);
 }
 
 export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI): Promise<void> {
@@ -296,6 +360,8 @@ export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI): Promi
   }
 
   resetMetrics();
+  resetHookState();
+  if (basePath) clearPersistedHookState(basePath);
   active = false;
   paused = false;
   stepMode = false;
@@ -423,12 +489,8 @@ async function mergeOrphanedSliceBranches(
 
     // Skip if already merged (no commits ahead of main)
     const mainBranch = getMainBranch(base);
-    const aheadCount = runGit(
-      base,
-      ["rev-list", "--count", `${mainBranch}..${branch}`],
-      { allowFailure: true },
-    );
-    if (!aheadCount || aheadCount === "0") continue;
+    const aheadCount = nativeCommitCountBetween(base, mainBranch, branch);
+    if (aheadCount === 0) continue;
 
     // Read the roadmap from the slice branch to check if the slice is done.
     // relMilestoneFile resolves the actual directory name on disk (handles
@@ -517,6 +579,8 @@ export async function startAuto(
     ctx.ui.setStatus("gsd-auto", stepMode ? "next" : "auto");
     ctx.ui.setFooter(hideFooter);
     ctx.ui.notify(stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "info");
+    // Restore hook state from disk in case session was interrupted
+    restoreHookState(base);
     // Rebuild disk state before resuming — user interaction during pause may have changed files
     try { await rebuildState(base); } catch { /* non-fatal */ }
     try {
@@ -527,6 +591,9 @@ export async function startAuto(
     } catch { /* non-fatal */ }
     // Self-heal: clear stale runtime records where artifacts already exist
     await selfHealRuntimeRecords(base, ctx);
+    invalidateStateCache();
+    clearParseCache();
+    clearPathCache();
     await dispatchNextUnit(ctx, pi);
     return;
   }
@@ -622,6 +689,8 @@ export async function startAuto(
   unitRecoveryCount.clear();
   completedKeySet.clear();
   loadPersistedKeys(base, completedKeySet);
+  resetHookState();
+  restoreHookState(base);
   autoStartTime = Date.now();
   completedUnits = [];
   currentUnit = null;
@@ -716,6 +785,12 @@ export async function handleAgentEnd(
   // Unit completed — clear its timeout
   clearUnitTimeout();
 
+  // Invalidate deriveState() cache — the unit just completed and may have
+  // written planning files (task summaries, roadmap checkboxes, etc.)
+  invalidateStateCache();
+  clearParseCache();
+  clearPathCache();
+
   // Small delay to let files settle (git commits, file writes)
   await new Promise(r => setTimeout(r, 500));
 
@@ -754,13 +829,109 @@ export async function handleAgentEnd(
     }
   }
 
+  // ── Post-unit hooks: check if a configured hook should run before normal dispatch ──
+  if (currentUnit && !stepMode) {
+    const hookUnit = checkPostUnitHooks(currentUnit.type, currentUnit.id, basePath);
+    if (hookUnit) {
+      // Dispatch the hook unit instead of normal flow
+      const hookStartedAt = Date.now();
+      if (currentUnit) {
+        const modelId = ctx.model?.id ?? "unknown";
+        snapshotUnitMetrics(ctx, currentUnit.type, currentUnit.id, currentUnit.startedAt, modelId);
+        saveActivityLog(ctx, basePath, currentUnit.type, currentUnit.id);
+      }
+      currentUnit = { type: hookUnit.unitType, id: hookUnit.unitId, startedAt: hookStartedAt };
+      writeUnitRuntimeRecord(basePath, hookUnit.unitType, hookUnit.unitId, hookStartedAt, {
+        phase: "dispatched",
+        wrapupWarningSent: false,
+        timeoutAt: null,
+        lastProgressAt: hookStartedAt,
+        progressCount: 0,
+        lastProgressKind: "dispatch",
+      });
+
+      const state = await deriveState(basePath);
+      updateProgressWidget(ctx, hookUnit.unitType, hookUnit.unitId, state);
+      const hookState = getActiveHook();
+      ctx.ui.notify(
+        `Running post-unit hook: ${hookUnit.hookName} (cycle ${hookState?.cycle ?? 1})`,
+        "info",
+      );
+
+      // Switch model if the hook specifies one
+      if (hookUnit.model) {
+        const availableModels = ctx.modelRegistry.getAvailable();
+        const match = availableModels.find(m =>
+          m.id === hookUnit.model || `${m.provider}/${m.id}` === hookUnit.model,
+        );
+        if (match) {
+          try {
+            await pi.setModel(match);
+          } catch { /* non-fatal — use current model */ }
+        }
+      }
+
+      const result = await cmdCtx!.newSession();
+      if (result.cancelled) {
+        resetHookState();
+        await stopAuto(ctx, pi);
+        return;
+      }
+      const sessionFile = ctx.sessionManager.getSessionFile();
+      writeLock(basePath, hookUnit.unitType, hookUnit.unitId, completedUnits.length, sessionFile);
+      // Persist hook state so cycle counts survive crashes
+      persistHookState(basePath);
+      pi.sendMessage(
+        { customType: "gsd-auto", content: hookUnit.prompt, display: verbose },
+        { triggerTurn: true },
+      );
+      return; // handleAgentEnd will fire again when hook session completes
+    }
+
+    // Check if a hook requested a retry of the trigger unit
+    if (isRetryPending()) {
+      const trigger = consumeRetryTrigger();
+      if (trigger) {
+        ctx.ui.notify(
+          `Hook requested retry of ${trigger.unitType} ${trigger.unitId}.`,
+          "info",
+        );
+        // Fall through to normal dispatchNextUnit — state derivation will
+        // re-select the same unit since it hasn't been marked complete
+      }
+    }
+  }
+
   // In step mode, pause and show a wizard instead of immediately dispatching
   if (stepMode) {
     await showStepWizard(ctx, pi);
     return;
   }
 
-  await dispatchNextUnit(ctx, pi);
+  try {
+    await dispatchNextUnit(ctx, pi);
+  } catch (dispatchErr) {
+    // dispatchNextUnit threw — without this catch the error would propagate
+    // to the pi event emitter which may silently swallow async rejections,
+    // leaving auto-mode active but permanently stalled (see #381).
+    const message = dispatchErr instanceof Error ? dispatchErr.message : String(dispatchErr);
+    ctx.ui.notify(
+      `Dispatch error after unit completion: ${message}. Retrying in ${DISPATCH_GAP_TIMEOUT_MS / 1000}s.`,
+      "error",
+    );
+
+    // Start the dispatch gap watchdog to retry after a delay.
+    // This gives transient issues (dirty working tree, branch state) time to settle.
+    startDispatchGapWatchdog(ctx, pi);
+    return;
+  }
+
+  // If dispatchNextUnit returned normally but auto-mode is still active and
+  // no new unit timeout was set (meaning sendMessage was never called), start
+  // the dispatch gap watchdog as a safety net.
+  if (active && !unitTimeoutHandle && !wrapupWarningHandle) {
+    startDispatchGapWatchdog(ctx, pi);
+  }
 
   } finally {
     _handlingAgentEnd = false;
@@ -874,6 +1045,7 @@ export function describeNextUnit(state: GSDState): { label: string; description:
 // ─── Progress Widget ──────────────────────────────────────────────────────
 
 function unitVerb(unitType: string): string {
+  if (unitType.startsWith("hook/")) return `hook: ${unitType.slice(5)}`;
   switch (unitType) {
     case "research-milestone":
     case "research-slice": return "researching";
@@ -890,6 +1062,7 @@ function unitVerb(unitType: string): string {
 }
 
 function unitPhaseLabel(unitType: string): string {
+  if (unitType.startsWith("hook/")) return "HOOK";
   switch (unitType) {
     case "research-milestone": return "RESEARCH";
     case "research-slice": return "RESEARCH";
@@ -906,7 +1079,14 @@ function unitPhaseLabel(unitType: string): string {
 }
 
 function peekNext(unitType: string, state: GSDState): string {
+  // Show active hook info in progress display
+  const activeHookState = getActiveHook();
+  if (activeHookState) {
+    return `hook: ${activeHookState.hookName} (cycle ${activeHookState.cycle})`;
+  }
+
   const sid = state.activeSlice?.id ?? "";
+  if (unitType.startsWith("hook/")) return `continue ${sid}`;
   switch (unitType) {
     case "research-milestone": return "plan milestone roadmap";
     case "plan-milestone": return "plan or execute first slice";
@@ -1092,7 +1272,14 @@ function updateProgressWidget(
             .join(theme.fg("dim", " "));
 
           const modelId = cmdCtx?.model?.id ?? "";
-          const sRight = modelId ? theme.fg("dim", modelId) : "";
+          const modelProvider = cmdCtx?.model?.provider ?? "";
+          const modelPhase = phaseLabel ? theme.fg("dim", `[${phaseLabel}] `) : "";
+          const modelDisplay = modelProvider && modelId
+            ? `${modelProvider}/${modelId}`
+            : modelId;
+          const sRight = modelDisplay
+            ? `${modelPhase}${theme.fg("dim", modelDisplay)}`
+            : "";
           lines.push(rightAlign(`${pad}${sLeft}`, sRight, width));
         }
 
@@ -1193,6 +1380,9 @@ async function dispatchNextUnit(
     return;
   }
 
+  // Clear stale directory listing cache so deriveState sees fresh disk state (#431)
+  clearPathCache();
+
   let state = await deriveState(basePath);
   let mid = state.activeMilestone?.id;
   let midTitle = state.activeMilestone?.title;
@@ -1255,6 +1445,9 @@ async function dispatchNextUnit(
           }
         }
         // Re-derive state from the now-merged working tree
+        invalidateStateCache();
+        clearParseCache();
+        clearPathCache();
         state = await deriveState(basePath);
         mid = state.activeMilestone?.id;
         midTitle = state.activeMilestone?.title;
@@ -1319,6 +1512,9 @@ async function dispatchNextUnit(
               "info",
             );
             // Re-derive state from main so downstream logic sees merged state
+            invalidateStateCache();
+            clearParseCache();
+            clearPathCache();
             state = await deriveState(basePath);
             mid = state.activeMilestone?.id;
             midTitle = state.activeMilestone?.title;
@@ -1631,6 +1827,28 @@ async function dispatchNextUnit(
     }
   }
 
+  // ── Pre-dispatch hooks: modify, skip, or replace the unit before dispatch ──
+  const preDispatchResult = runPreDispatchHooks(unitType, unitId, prompt, basePath);
+  if (preDispatchResult.firedHooks.length > 0) {
+    ctx.ui.notify(
+      `Pre-dispatch hook${preDispatchResult.firedHooks.length > 1 ? "s" : ""}: ${preDispatchResult.firedHooks.join(", ")}`,
+      "info",
+    );
+  }
+  if (preDispatchResult.action === "skip") {
+    ctx.ui.notify(`Skipping ${unitType} ${unitId} (pre-dispatch hook).`, "info");
+    // Yield then re-dispatch to advance to next unit
+    await new Promise(r => setImmediate(r));
+    await dispatchNextUnit(ctx, pi);
+    return;
+  }
+  if (preDispatchResult.action === "replace") {
+    prompt = preDispatchResult.prompt ?? prompt;
+    if (preDispatchResult.unitType) unitType = preDispatchResult.unitType;
+  } else if (preDispatchResult.prompt) {
+    prompt = preDispatchResult.prompt;
+  }
+
   const priorSliceBlocker = getPriorSliceCompletionBlocker(basePath, getMainBranch(basePath), unitType, unitId);
   if (priorSliceBlocker) {
     await stopAuto(ctx, pi);
@@ -1870,16 +2088,37 @@ async function dispatchNextUnit(
     let modelSet = false;
 
     for (const modelId of modelsToTry) {
-      // Support "provider/model" format for explicit provider targeting
+      // Resolve model from available models.
+      // Handles multiple formats:
+      //   "provider/model"           → explicit provider targeting (e.g. "anthropic/claude-opus-4-6")
+      //   "bare-id"                  → match by ID across providers
+      //   "org/model-name"           → OpenRouter-style IDs where the full string is the model ID
+      //   "openrouter/org/model"     → explicit provider + OpenRouter model ID
       const slashIdx = modelId.indexOf("/");
       let model;
       if (slashIdx !== -1) {
-        const provider = modelId.substring(0, slashIdx);
+        const maybeProvider = modelId.substring(0, slashIdx);
         const id = modelId.substring(slashIdx + 1);
-        model = availableModels.find(
-          m => m.provider.toLowerCase() === provider.toLowerCase()
-            && m.id.toLowerCase() === id.toLowerCase(),
-        );
+
+        // Check if the prefix before the first slash is a known provider
+        const knownProviders = new Set(availableModels.map(m => m.provider.toLowerCase()));
+        if (knownProviders.has(maybeProvider.toLowerCase())) {
+          // Explicit "provider/model" format (handles "openrouter/org/model" too)
+          model = availableModels.find(
+            m => m.provider.toLowerCase() === maybeProvider.toLowerCase()
+              && m.id.toLowerCase() === id.toLowerCase(),
+          );
+        }
+
+        // If the prefix wasn't a known provider, or no match was found within that provider,
+        // try matching the full string as a model ID (OpenRouter-style IDs like "org/model-name")
+        if (!model) {
+          const lower = modelId.toLowerCase();
+          model = availableModels.find(
+            m => m.id.toLowerCase() === lower
+              || `${m.provider}/${m.id}`.toLowerCase() === lower,
+          );
+        }
       } else {
         // For bare IDs, prefer the current session's provider, then first available match
         const currentProvider = ctx.model?.provider;
@@ -1913,7 +2152,8 @@ async function dispatchNextUnit(
         const fallbackNote = modelId === modelConfig.primary
           ? ""
           : ` (fallback from ${modelConfig.primary})`;
-        ctx.ui.notify(`Model: ${modelId}${fallbackNote}`, "info");
+        const phase = unitPhaseLabel(unitType);
+        ctx.ui.notify(`Model [${phase}]: ${model.provider}/${model.id}${fallbackNote}`, "info");
         modelSet = true;
         break;
       } else {
@@ -2136,7 +2376,10 @@ async function inlineDependencySummaries(
   if (!sliceEntry || sliceEntry.depends.length === 0) return "- (no dependencies)";
 
   const sections: string[] = [];
+  const seen = new Set<string>();
   for (const dep of sliceEntry.depends) {
+    if (seen.has(dep)) continue;
+    seen.add(dep);
     const summaryFile = resolveSliceFile(base, mid, dep, "SUMMARY");
     const summaryContent = summaryFile ? await loadFile(summaryFile) : null;
     const relPath = relSliceFile(base, mid, dep, "SUMMARY");
@@ -2176,6 +2419,7 @@ async function buildResearchMilestonePrompt(mid: string, midTitle: string, base:
   if (requirementsInline) inlined.push(requirementsInline);
   const decisionsInline = await inlineGsdRootFile(base, "decisions.md", "Decisions");
   if (decisionsInline) inlined.push(decisionsInline);
+  inlined.push(inlineTemplate("research", "Research"));
 
   const inlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`;
 
@@ -2208,6 +2452,11 @@ async function buildPlanMilestonePrompt(mid: string, midTitle: string, base: str
   if (requirementsInline) inlined.push(requirementsInline);
   const decisionsInline = await inlineGsdRootFile(base, "decisions.md", "Decisions");
   if (decisionsInline) inlined.push(decisionsInline);
+  inlined.push(inlineTemplate("roadmap", "Roadmap"));
+  inlined.push(inlineTemplate("decisions", "Decisions"));
+  inlined.push(inlineTemplate("plan", "Slice Plan"));
+  inlined.push(inlineTemplate("task-plan", "Task Plan"));
+  inlined.push(inlineTemplate("secrets-manifest", "Secrets Manifest"));
 
   const inlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`;
 
@@ -2244,6 +2493,7 @@ async function buildResearchSlicePrompt(
   if (decisionsInline) inlined.push(decisionsInline);
   const requirementsInline = await inlineGsdRootFile(base, "requirements.md", "Requirements");
   if (requirementsInline) inlined.push(requirementsInline);
+  inlined.push(inlineTemplate("research", "Research"));
 
   const depContent = await inlineDependencySummaries(mid, sid, base);
 
@@ -2279,6 +2529,8 @@ async function buildPlanSlicePrompt(
   if (decisionsInline) inlined.push(decisionsInline);
   const requirementsInline = await inlineGsdRootFile(base, "requirements.md", "Requirements");
   if (requirementsInline) inlined.push(requirementsInline);
+  inlined.push(inlineTemplate("plan", "Slice Plan"));
+  inlined.push(inlineTemplate("task-plan", "Task Plan"));
 
   const depContent = await inlineDependencySummaries(mid, sid, base);
 
@@ -2340,6 +2592,10 @@ async function buildExecuteTaskPrompt(
   );
 
   const carryForwardSection = await buildCarryForwardSection(priorSummaries, base);
+  const inlinedTemplates = [
+    inlineTemplate("task-summary", "Task Summary"),
+    inlineTemplate("decisions", "Decisions"),
+  ].join("\n\n---\n\n");
 
   const taskSummaryPath = `${relSlicePath(base, mid, sid)}/tasks/${tid}-SUMMARY.md`;
 
@@ -2354,6 +2610,7 @@ async function buildExecuteTaskPrompt(
     resumeSection,
     priorTaskLines: priorLines,
     taskSummaryPath,
+    inlinedTemplates,
   });
 }
 
@@ -2386,6 +2643,8 @@ async function buildCompleteSlicePrompt(
       }
     }
   }
+  inlined.push(inlineTemplate("slice-summary", "Slice Summary"));
+  inlined.push(inlineTemplate("uat", "UAT"));
 
   const inlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`;
 
@@ -2412,11 +2671,14 @@ async function buildCompleteMilestonePrompt(
   const inlined: string[] = [];
   inlined.push(await inlineFile(roadmapPath, roadmapRel, "Milestone Roadmap"));
 
-  // Inline all slice summaries
+  // Inline all slice summaries (deduplicated by slice ID)
   const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
   if (roadmapContent) {
     const roadmap = parseRoadmap(roadmapContent);
+    const seenSlices = new Set<string>();
     for (const slice of roadmap.slices) {
+      if (seenSlices.has(slice.id)) continue;
+      seenSlices.add(slice.id);
       const summaryPath = resolveSliceFile(base, mid, slice.id, "SUMMARY");
       const summaryRel = relSliceFile(base, mid, slice.id, "SUMMARY");
       inlined.push(await inlineFile(summaryPath, summaryRel, `${slice.id} Summary`));
@@ -2435,6 +2697,7 @@ async function buildCompleteMilestonePrompt(
   const contextRel = relMilestoneFile(base, mid, "CONTEXT");
   const contextInline = await inlineFileOptional(contextPath, contextRel, "Milestone Context");
   if (contextInline) inlined.push(contextInline);
+  inlined.push(inlineTemplate("milestone-summary", "Milestone Summary"));
 
   const inlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`;
 
@@ -2881,6 +3144,9 @@ async function collectObservabilityWarnings(
   unitType: string,
   unitId: string,
 ): Promise<import("./observability-validator.ts").ValidationIssue[]> {
+  // Hook units have custom artifacts — skip standard observability checks
+  if (unitType.startsWith("hook/")) return [];
+
   const parts = unitId.split("/");
   const mid = parts[0];
   const sid = parts[1];
@@ -3292,6 +3558,9 @@ export function resolveExpectedArtifactPath(unitType: string, unitId: string, ba
  * skipped writing the UAT file (see #176).
  */
 export function verifyExpectedArtifact(unitType: string, unitId: string, base: string): boolean {
+  // Clear stale directory listing cache so artifact checks see fresh disk state (#431)
+  clearPathCache();
+
   // fix-merge has no file artifact — verify by checking git state
   if (unitType === "fix-merge") {
     const unmerged = runGit(base, ["diff", "--name-only", "--diff-filter=U"], { allowFailure: true });

package/src/resources/extensions/gsd/commands.ts

@@ -53,10 +53,10 @@ function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined, reportT
 
 export function registerGSDCommand(pi: ExtensionAPI): void {
   pi.registerCommand("gsd", {
-    description: "GSD — Get Shit Done: /gsd next|auto|stop|status|queue|prefs|doctor|migrate|remote",
+    description: "GSD — Get Shit Done: /gsd next|auto|stop|status|queue|prefs|hooks|doctor|migrate|remote",
 
     getArgumentCompletions: (prefix: string) => {
-      const subcommands = ["next", "auto", "stop", "status", "queue", "discuss", "prefs", "doctor", "migrate", "remote"];
+      const subcommands = ["next", "auto", "stop", "status", "queue", "discuss", "prefs", "hooks", "doctor", "migrate", "remote"];
       const parts = prefix.trim().split(/\s+/);
 
       if (parts.length <= 1) {
@@ -151,6 +151,12 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
         return;
       }
 
+      if (trimmed === "hooks") {
+        const { formatHookStatus } = await import("./post-unit-hooks.js");
+        ctx.ui.notify(formatHookStatus(), "info");
+        return;
+      }
+
       if (trimmed === "migrate" || trimmed.startsWith("migrate ")) {
         await handleMigrate(trimmed.replace(/^migrate\s*/, "").trim(), ctx, pi);
         return;
@@ -168,7 +174,7 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
       }
 
       ctx.ui.notify(
-        `Unknown: /gsd ${trimmed}. Use /gsd, /gsd next, /gsd auto, /gsd stop, /gsd status, /gsd queue, /gsd discuss, /gsd prefs [global|project|status|wizard|setup], /gsd doctor [audit|fix|heal] [M###/S##], /gsd migrate <path>, or /gsd remote [slack|discord|status|disconnect].`,
+        `Unknown: /gsd ${trimmed}. Use /gsd, /gsd next, /gsd auto, /gsd stop, /gsd status, /gsd queue, /gsd discuss, /gsd prefs [global|project|status|wizard|setup], /gsd hooks, /gsd doctor [audit|fix|heal] [M###/S##], /gsd migrate <path>, or /gsd remote [slack|discord|status|disconnect].`,
         "warning",
       );
     },