gsd-pi 2.41.0-dev.0acbce9 → 2.41.0-dev.5a170d0

package/src/resources/extensions/gsd/post-unit-hooks.ts

@@ -1,524 +1,86 @@
-// GSD Extension — Hook Engine (Post-Unit, Pre-Dispatch, State Persistence)
-// Manages hook queue, cycle tracking, artifact verification, pre-dispatch
-// interception, and durable hook state for user-configured extensibility.
+// GSD Extension — Hook Engine Facade
+//
+// Thin facade over RuleRegistry. All mutable state and logic lives in the
+// registry instance; these exported functions delegate through getOrCreateRegistry()
+// so existing call-sites and tests work without modification.
 
 import type {
-  PostUnitHookConfig,
-  PreDispatchHookConfig,
   HookExecutionState,
   HookDispatchResult,
   PreDispatchResult,
-  PersistedHookState,
   HookStatusEntry,
 } from "./types.js";
-import { resolvePostUnitHooks, resolvePreDispatchHooks } from "./preferences.js";
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { getOrCreateRegistry, resolveHookArtifactPath } from "./rule-registry.js";
 
-// ─── Hook Queue State ──────────────────────────────────────────────────────
+// Re-export resolveHookArtifactPath so existing importers still work.
+export { resolveHookArtifactPath } from "./rule-registry.js";
 
-/** Currently executing hook, or null if in normal dispatch flow. */
-let activeHook: HookExecutionState | null = null;
+// ─── Post-Unit Hooks ───────────────────────────────────────────────────────
 
-/** Queue of hooks remaining for the current trigger unit. */
-let hookQueue: Array<{
-  config: PostUnitHookConfig;
-  triggerUnitType: string;
-  triggerUnitId: string;
-}> = [];
-
-/** Cycle counts per hook+trigger, keyed as "hookName/triggerUnitType/triggerUnitId". */
-const cycleCounts = new Map<string, number>();
-
-/** Set when a hook completes with retry_on artifact present — signals caller to re-run trigger. */
-let retryPending = false;
-
-/** Stores the trigger unit info for pending retries so caller knows what to re-run. */
-let retryTrigger: { unitType: string; unitId: string; retryArtifact: string } | null = null;
-
-// ─── Public API ────────────────────────────────────────────────────────────
-
-/**
- * Called after a unit completes. Returns the next hook unit to dispatch,
- * or null if no hooks apply (normal dispatch should proceed).
- *
- * Call flow:
- * 1. A core unit (e.g. execute-task) completes → handleAgentEnd calls this
- * 2. If hooks match, returns first hook to dispatch. Caller sends the prompt.
- * 3. Hook unit completes → handleAgentEnd calls this again (activeHook is set)
- * 4. Checks retry_on / next hook / done → returns next action or null
- */
 export function checkPostUnitHooks(
   completedUnitType: string,
   completedUnitId: string,
   basePath: string,
 ): HookDispatchResult | null {
-  // If we just completed a hook unit, handle its result
-  if (activeHook) {
-    return handleHookCompletion(basePath);
-  }
-
-  // Don't trigger hooks for other hook units (prevent hook-on-hook chains)
-  // Don't trigger hooks for triage units (prevent hook-on-triage chains)
-  // Don't trigger hooks for quick-task units (lightweight one-offs from captures)
-  if (completedUnitType.startsWith("hook/") || completedUnitType === "triage-captures" || completedUnitType === "quick-task") return null;
-
-  // Check if any hooks are configured for this unit type
-  const hooks = resolvePostUnitHooks().filter(h =>
-    h.after.includes(completedUnitType),
-  );
-  if (hooks.length === 0) return null;
-
-  // Build hook queue for this trigger
-  hookQueue = hooks.map(config => ({
-    config,
-    triggerUnitType: completedUnitType,
-    triggerUnitId: completedUnitId,
-  }));
-
-  return dequeueNextHook(basePath);
+  return getOrCreateRegistry().evaluatePostUnit(completedUnitType, completedUnitId, basePath);
 }
 
-/**
- * Returns whether a hook is currently active (for progress display).
- */
 export function getActiveHook(): HookExecutionState | null {
-  return activeHook;
+  return getOrCreateRegistry().getActiveHook();
 }
 
-/**
- * Returns true if a retry of the trigger unit was requested by a hook.
- * Caller should re-dispatch the original trigger unit, then hooks will
- * fire again on its next completion.
- */
 export function isRetryPending(): boolean {
-  return retryPending;
+  return getOrCreateRegistry().isRetryPending();
 }
 
-/**
- * Returns the trigger unit info for a pending retry, or null.
- * Clears the retry state after reading.
- */
 export function consumeRetryTrigger(): { unitType: string; unitId: string; retryArtifact: string } | null {
-  if (!retryPending || !retryTrigger) return null;
-  const trigger = { ...retryTrigger };
-  retryPending = false;
-  retryTrigger = null;
-  return trigger;
+  return getOrCreateRegistry().consumeRetryTrigger();
 }
 
-/**
- * Reset all hook state. Called on auto-mode start/stop.
- */
 export function resetHookState(): void {
-  activeHook = null;
-  hookQueue = [];
-  cycleCounts.clear();
-  retryPending = false;
-  retryTrigger = null;
-}
-
-// ─── Internal ──────────────────────────────────────────────────────────────
-
-function dequeueNextHook(basePath: string): HookDispatchResult | null {
-  while (hookQueue.length > 0) {
-    const entry = hookQueue.shift()!;
-    const { config, triggerUnitType, triggerUnitId } = entry;
-
-    // Check idempotency — if artifact already exists, skip this hook
-    if (config.artifact) {
-      const artifactPath = resolveHookArtifactPath(basePath, triggerUnitId, config.artifact);
-      if (existsSync(artifactPath)) continue;
-    }
-
-    // Check cycle limit
-    const cycleKey = `${config.name}/${triggerUnitType}/${triggerUnitId}`;
-    const currentCycle = (cycleCounts.get(cycleKey) ?? 0) + 1;
-    const maxCycles = config.max_cycles ?? 1;
-    if (currentCycle > maxCycles) continue;
-
-    cycleCounts.set(cycleKey, currentCycle);
-
-    activeHook = {
-      hookName: config.name,
-      triggerUnitType,
-      triggerUnitId,
-      cycle: currentCycle,
-      pendingRetry: false,
-    };
-
-    // Build the prompt with variable substitution
-    const [mid, sid, tid] = triggerUnitId.split("/");
-    let prompt = config.prompt
-      .replace(/\{milestoneId\}/g, mid ?? "")
-      .replace(/\{sliceId\}/g, sid ?? "")
-      .replace(/\{taskId\}/g, tid ?? "");
-
-    // Inject browser safety instruction for hooks that may use browser tools (#1345).
-    // Vite HMR and other persistent connections prevent networkidle from resolving.
-    prompt += "\n\n**Browser tool safety:** Do NOT use `browser_wait_for` with `condition: \"network_idle\"` — it hangs indefinitely when dev servers keep persistent connections (Vite HMR, WebSocket). Use `selector_visible`, `text_visible`, or `delay` instead.";
-
-    return {
-      hookName: config.name,
-      prompt,
-      model: config.model,
-      unitType: `hook/${config.name}`,
-      unitId: triggerUnitId,
-    };
-  }
-
-  // No more hooks — clear active state and return null for normal dispatch
-  activeHook = null;
-  return null;
-}
-
-function handleHookCompletion(basePath: string): HookDispatchResult | null {
-  const hook = activeHook!;
-  const hooks = resolvePostUnitHooks();
-  const config = hooks.find(h => h.name === hook.hookName);
-
-  // Check if retry was requested via retry_on artifact
-  if (config?.retry_on) {
-    const retryArtifactPath = resolveHookArtifactPath(basePath, hook.triggerUnitId, config.retry_on);
-    if (existsSync(retryArtifactPath)) {
-      // Check cycle limit before allowing retry
-      const cycleKey = `${config.name}/${hook.triggerUnitType}/${hook.triggerUnitId}`;
-      const currentCycle = cycleCounts.get(cycleKey) ?? 1;
-      const maxCycles = config.max_cycles ?? 1;
-
-      if (currentCycle < maxCycles) {
-        // Signal retry — caller will re-dispatch the trigger unit
-        activeHook = null;
-        hookQueue = [];
-        retryPending = true;
-        retryTrigger = { unitType: hook.triggerUnitType, unitId: hook.triggerUnitId, retryArtifact: config.retry_on };
-        return null;
-      }
-      // Max cycles reached — fall through to normal completion
-    }
-  }
-
-  // Hook completed normally — try next hook in queue
-  activeHook = null;
-  return dequeueNextHook(basePath);
-}
-
-/**
- * Resolve the path where a hook artifact is expected to be written.
- * Uses the trigger unit's directory context:
- *   - Task-level (M001/S01/T01): .gsd/milestones/M001/slices/S01/tasks/T01-{artifact}
- *   - Slice-level (M001/S01):    .gsd/milestones/M001/slices/S01/{artifact}
- *   - Milestone-level (M001):    .gsd/milestones/M001/{artifact}
- */
-export function resolveHookArtifactPath(basePath: string, unitId: string, artifactName: string): string {
-  const parts = unitId.split("/");
-  if (parts.length === 3) {
-    const [mid, sid, tid] = parts;
-    return join(basePath, ".gsd", "milestones", mid, "slices", sid, "tasks", `${tid}-${artifactName}`);
-  }
-  if (parts.length === 2) {
-    const [mid, sid] = parts;
-    return join(basePath, ".gsd", "milestones", mid, "slices", sid, artifactName);
-  }
-  return join(basePath, ".gsd", "milestones", parts[0], artifactName);
+  getOrCreateRegistry().resetState();
 }
 
-// ═══════════════════════════════════════════════════════════════════════════
-// Phase 2: Pre-Dispatch Hooks
-// ═══════════════════════════════════════════════════════════════════════════
+// ─── Pre-Dispatch Hooks ────────────────────────────────────────────────────
 
-/**
- * Run pre-dispatch hooks for a unit about to be dispatched.
- * Returns a result indicating whether the unit should proceed (with optional
- * prompt modifications), be skipped, or be replaced entirely.
- *
- * Multiple hooks can fire for the same unit type. They compose:
- * - "modify" hooks stack (all prepend/append applied in order)
- * - "skip" short-circuits (first matching skip wins)
- * - "replace" short-circuits (first matching replace wins)
- * - Skip/replace hooks take precedence over modify hooks
- */
 export function runPreDispatchHooks(
   unitType: string,
   unitId: string,
   prompt: string,
   basePath: string,
 ): PreDispatchResult {
-  // Don't intercept hook units
-  if (unitType.startsWith("hook/")) {
-    return { action: "proceed", prompt, firedHooks: [] };
-  }
-
-  const hooks = resolvePreDispatchHooks().filter(h =>
-    h.before.includes(unitType),
-  );
-  if (hooks.length === 0) {
-    return { action: "proceed", prompt, firedHooks: [] };
-  }
-
-  const [mid, sid, tid] = unitId.split("/");
-  const substitute = (text: string): string =>
-    text
-      .replace(/\{milestoneId\}/g, mid ?? "")
-      .replace(/\{sliceId\}/g, sid ?? "")
-      .replace(/\{taskId\}/g, tid ?? "");
-
-  const firedHooks: string[] = [];
-  let currentPrompt = prompt;
-
-  for (const hook of hooks) {
-    if (hook.action === "skip") {
-      // Check optional skip condition
-      if (hook.skip_if) {
-        const conditionPath = resolveHookArtifactPath(basePath, unitId, hook.skip_if);
-        if (!existsSync(conditionPath)) continue; // Condition not met, don't skip
-      }
-      firedHooks.push(hook.name);
-      return { action: "skip", firedHooks };
-    }
-
-    if (hook.action === "replace") {
-      firedHooks.push(hook.name);
-      return {
-        action: "replace",
-        prompt: substitute(hook.prompt ?? ""),
-        unitType: hook.unit_type,
-        model: hook.model,
-        firedHooks,
-      };
-    }
-
-    if (hook.action === "modify") {
-      firedHooks.push(hook.name);
-      if (hook.prepend) {
-        currentPrompt = `${substitute(hook.prepend)}\n\n${currentPrompt}`;
-      }
-      if (hook.append) {
-        currentPrompt = `${currentPrompt}\n\n${substitute(hook.append)}`;
-      }
-    }
-  }
-
-  return {
-    action: "proceed",
-    prompt: currentPrompt,
-    model: hooks.find(h => h.action === "modify" && h.model)?.model,
-    firedHooks,
-  };
+  return getOrCreateRegistry().evaluatePreDispatch(unitType, unitId, prompt, basePath);
 }
 
-// ═══════════════════════════════════════════════════════════════════════════
-// Phase 3: Hook State Persistence
-// ═══════════════════════════════════════════════════════════════════════════
+// ─── State Persistence ─────────────────────────────────────────────────────
 
-const HOOK_STATE_FILE = "hook-state.json";
-
-function hookStatePath(basePath: string): string {
-  return join(basePath, ".gsd", HOOK_STATE_FILE);
-}
-
-/**
- * Persist current hook cycle counts to disk so they survive crashes/restarts.
- * Called after each hook dispatch and on auto-mode pause.
- */
 export function persistHookState(basePath: string): void {
-  const state: PersistedHookState = {
-    cycleCounts: Object.fromEntries(cycleCounts),
-    savedAt: new Date().toISOString(),
-  };
-  try {
-    const dir = join(basePath, ".gsd");
-    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-    writeFileSync(hookStatePath(basePath), JSON.stringify(state, null, 2), "utf-8");
-  } catch {
-    // Non-fatal — state is recreatable from artifacts
-  }
+  getOrCreateRegistry().persistState(basePath);
 }
 
-/**
- * Restore hook cycle counts from disk after a crash/restart.
- * Called during auto-mode resume.
- */
 export function restoreHookState(basePath: string): void {
-  try {
-    const filePath = hookStatePath(basePath);
-    if (!existsSync(filePath)) return;
-    const raw = readFileSync(filePath, "utf-8");
-    const state: PersistedHookState = JSON.parse(raw);
-    if (state.cycleCounts && typeof state.cycleCounts === "object") {
-      cycleCounts.clear();
-      for (const [key, value] of Object.entries(state.cycleCounts)) {
-        if (typeof value === "number") {
-          cycleCounts.set(key, value);
-        }
-      }
-    }
-  } catch {
-    // Non-fatal — fresh state is fine
-  }
+  getOrCreateRegistry().restoreState(basePath);
 }
 
-/**
- * Clear persisted hook state file from disk.
- * Called on clean auto-mode stop.
- */
 export function clearPersistedHookState(basePath: string): void {
-  try {
-    const filePath = hookStatePath(basePath);
-    if (existsSync(filePath)) {
-      writeFileSync(filePath, JSON.stringify({ cycleCounts: {}, savedAt: new Date().toISOString() }, null, 2), "utf-8");
-    }
-  } catch {
-    // Non-fatal
-  }
+  getOrCreateRegistry().clearPersistedState(basePath);
 }
 
-// ═══════════════════════════════════════════════════════════════════════════
-// Phase 3: Hook Status Reporting
-// ═══════════════════════════════════════════════════════════════════════════
+// ─── Status & Manual Trigger ───────────────────────────────────────────────
 
-/**
- * Get status of all configured hooks for display by /gsd hooks.
- */
 export function getHookStatus(): HookStatusEntry[] {
-  const entries: HookStatusEntry[] = [];
-
-  // Post-unit hooks
-  const postHooks = resolvePostUnitHooks();
-  for (const hook of postHooks) {
-    const activeCycles: Record<string, number> = {};
-    for (const [key, count] of cycleCounts) {
-      if (key.startsWith(`${hook.name}/`)) {
-        activeCycles[key] = count;
-      }
-    }
-    entries.push({
-      name: hook.name,
-      type: "post",
-      enabled: hook.enabled !== false,
-      targets: hook.after,
-      activeCycles,
-    });
-  }
-
-  // Pre-dispatch hooks
-  const preHooks = resolvePreDispatchHooks();
-  for (const hook of preHooks) {
-    entries.push({
-      name: hook.name,
-      type: "pre",
-      enabled: hook.enabled !== false,
-      targets: hook.before,
-      activeCycles: {},
-    });
-  }
-
-  return entries;
+  return getOrCreateRegistry().getHookStatus();
 }
 
-/**
- * Manually trigger a specific hook for a unit.
- * This bypasses the normal flow and forces the hook to run even if its artifact exists.
- * 
- * @param hookName - The name of the hook to trigger (e.g., "code-review")
- * @param unitType - The type of unit that triggered the hook (e.g., "execute-task")
- * @param unitId - The unit ID (e.g., "M001/S01/T01")
- * @param basePath - The project base path
- * @returns The hook dispatch result or null if hook not found
- */
 export function triggerHookManually(
   hookName: string,
   unitType: string,
   unitId: string,
   basePath: string,
 ): HookDispatchResult | null {
-  // Find the hook configuration
-  const hook = resolvePostUnitHooks().find(h => h.name === hookName);
-  if (!hook) {
-    console.error(`[triggerHookManually] Hook "${hookName}" not found in post_unit_hooks`);
-    return null;
-  }
-
-  if (!hook.prompt || typeof hook.prompt !== 'string' || hook.prompt.trim().length === 0) {
-    console.error(`[triggerHookManually] Hook "${hookName}" has empty prompt`);
-    return null;
-  }
-
-  // Reset any active hook state to allow manual triggering
-  activeHook = {
-    hookName: hook.name,
-    triggerUnitType: unitType,
-    triggerUnitId: unitId,
-    cycle: 1,
-    pendingRetry: false,
-  };
-
-  // Build the hook queue with just this hook
-  hookQueue = [{
-    config: hook,
-    triggerUnitType: unitType,
-    triggerUnitId: unitId,
-  }];
-
-  // Set the cycle count for this specific hook+trigger
-  const cycleKey = `${hook.name}/${unitType}/${unitId}`;
-  const currentCycle = (cycleCounts.get(cycleKey) ?? 0) + 1;
-  cycleCounts.set(cycleKey, currentCycle);
-
-  // Update active hook with the cycle count
-  activeHook.cycle = currentCycle;
-
-  // Build the prompt with variable substitution
-  const [mid, sid, tid] = unitId.split("/");
-  const prompt = hook.prompt
-    .replace(/\{milestoneId\}/g, mid ?? "")
-    .replace(/\{sliceId\}/g, sid ?? "")
-    .replace(/\{taskId\}/g, tid ?? "");
-
-  console.log(`[triggerHookManually] Built prompt for ${hookName}, length: ${prompt.length}`);
-
-  return {
-    hookName: hook.name,
-    prompt,
-    model: hook.model,
-    unitType: `hook/${hook.name}`,
-    unitId,
-  };
+  return getOrCreateRegistry().triggerHookManually(hookName, unitType, unitId, basePath);
 }
 
-/**
- * Format hook status for terminal display.
- */
 export function formatHookStatus(): string {
-  const entries = getHookStatus();
-  if (entries.length === 0) {
-    return "No hooks configured. Add post_unit_hooks or pre_dispatch_hooks to .gsd/preferences.md";
-  }
-
-  const lines: string[] = ["Configured Hooks:", ""];
-
-  const postHooks = entries.filter(e => e.type === "post");
-  const preHooks = entries.filter(e => e.type === "pre");
-
-  if (postHooks.length > 0) {
-    lines.push("Post-Unit Hooks (run after unit completes):");
-    for (const hook of postHooks) {
-      const status = hook.enabled ? "enabled" : "disabled";
-      const cycles = Object.keys(hook.activeCycles).length;
-      const cycleInfo = cycles > 0 ? ` (${cycles} active cycle${cycles === 1 ? "" : "s"})` : "";
-      lines.push(`  ${hook.name} [${status}] → after: ${hook.targets.join(", ")}${cycleInfo}`);
-    }
-    lines.push("");
-  }
-
-  if (preHooks.length > 0) {
-    lines.push("Pre-Dispatch Hooks (run before unit dispatches):");
-    for (const hook of preHooks) {
-      const status = hook.enabled ? "enabled" : "disabled";
-      lines.push(`  ${hook.name} [${status}] → before: ${hook.targets.join(", ")}`);
-    }
-    lines.push("");
-  }
-
-  return lines.join("\n");
+  return getOrCreateRegistry().formatHookStatus();
 }

package/src/resources/extensions/gsd/preferences-types.ts

@@ -88,6 +88,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "widget_mode",
   "reactive_execution",
   "github",
+  "service_tier",
 ]);
 
 /** Canonical list of all dispatch unit types. */
@@ -220,6 +221,8 @@ export interface GSDPreferences {
   reactive_execution?: ReactiveExecutionConfig;
   /** GitHub sync configuration. Opt-in: syncs GSD events to GitHub Issues, Milestones, and PRs. */
   github?: GitHubSyncConfig;
+  /** OpenAI service tier preference. "priority" = 2x cost, faster. "flex" = 0.5x cost, slower. Only affects gpt-5.4 models. */
+  service_tier?: "priority" | "flex";
 }
 
 export interface LoadedGSDPreferences {

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

@@ -285,6 +285,7 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
     github: (base.github || override.github)
       ? { ...(base.github ?? {}), ...(override.github ?? {}) } as import("../github-sync/types.js").GitHubSyncConfig
       : undefined,
+    service_tier: override.service_tier ?? base.service_tier,
   };
 }
 

package/src/resources/extensions/gsd/prompt-loader.ts

@@ -17,12 +17,36 @@
  * that aren't read until the end of a long auto-mode run.
  */
 
-import { readFileSync, readdirSync } from "node:fs";
+import { readFileSync, readdirSync, existsSync } from "node:fs";
 import { GSDError, GSD_PARSE_ERROR } from "./errors.js";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
 
-const __extensionDir = dirname(fileURLToPath(import.meta.url));
+/**
+ * Resolve the GSD extension directory.
+ *
+ * `import.meta.url` resolves to whichever copy of this module is executing.
+ * On Windows (npm global install via MSYS2 / Git Bash) this can resolve to
+ * the npm-global `AppData/Roaming/npm/…` path, which does NOT contain the
+ * prompts/ and templates/ subtrees that initResources() copies to
+ * `~/.gsd/agent/extensions/gsd/`. Detect the mismatch and fall back to
+ * the user-local agent directory.
+ */
+function resolveExtensionDir(): string {
+  const moduleDir = dirname(fileURLToPath(import.meta.url));
+  if (existsSync(join(moduleDir, "prompts"))) return moduleDir;
+
+  // Fallback: user-local agent directory
+  const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+  const agentGsdDir = join(gsdHome, "agent", "extensions", "gsd");
+  if (existsSync(join(agentGsdDir, "prompts"))) return agentGsdDir;
+
+  // Last resort: return the module dir (warmCache will silently handle the miss)
+  return moduleDir;
+}
+
+const __extensionDir = resolveExtensionDir();
 const promptsDir = join(__extensionDir, "prompts");
 const templatesDir = join(__extensionDir, "templates");
 
@@ -45,7 +69,11 @@ function warmCache(): void {
       }
     }
   } catch {
-    // prompts/ may not exist in test environments — lazy loading still works
+    // prompts/ may not exist in test environments — lazy loading still works.
+    // Emit a diagnostic when running outside tests so wrong-path bugs are visible.
+    if (!process.env.VITEST && !process.env.NODE_TEST) {
+      process.stderr.write(`[gsd:prompt-loader] warmCache: prompts dir not found: ${promptsDir}\n`);
+    }
   }
 
   try {
@@ -57,7 +85,10 @@ function warmCache(): void {
       }
     }
   } catch {
-    // templates/ may not exist in test environments — lazy loading still works
+    // templates/ may not exist in test environments — lazy loading still works.
+    if (!process.env.VITEST && !process.env.NODE_TEST) {
+      process.stderr.write(`[gsd:prompt-loader] warmCache: templates dir not found: ${templatesDir}\n`);
+    }
   }
 }
 

package/src/resources/extensions/gsd/prompts/complete-milestone.md

@@ -17,16 +17,17 @@ All relevant context has been preloaded below — the roadmap, all slice summari
 Then:
 1. Use the **Milestone Summary** output template from the inlined context above
 2. {{skillActivation}}
-3. Verify each **success criterion** from the milestone definition in `{{roadmapPath}}`. For each criterion, confirm it was met with specific evidence from slice summaries, test results, or observable behavior. List any criterion that was NOT met.
-4. Verify the milestone's **definition of done** — all slices are `[x]`, all slice summaries exist, and any cross-slice integration points work correctly.
-5. Validate **requirement status transitions**. For each requirement that changed status during this milestone, confirm the transition is supported by evidence. Requirements can move between Active, Validated, Deferred, Blocked, or Out of Scope — but only with proof.
-6. Write `{{milestoneSummaryPath}}` using the milestone-summary template. Fill all frontmatter fields and narrative sections. The `requirement_outcomes` field must list every requirement that changed status with `from_status`, `to_status`, and `proof`.
-7. Update `.gsd/REQUIREMENTS.md` if any requirement status transitions were validated in step 5.
-8. Update `.gsd/PROJECT.md` to reflect milestone completion and current project state.
-9. Review all slice summaries for cross-cutting lessons, patterns, or gotchas that emerged during this milestone. Append any non-obvious, reusable insights to `.gsd/KNOWLEDGE.md`.
-10. Do not commit manually — the system auto-commits your changes after this unit completes.
-
-**Important:** Do NOT skip the success criteria and definition of done verification (steps 3-4). The milestone summary must reflect actual verified outcomes, not assumed success. If any criterion was not met, document it clearly in the summary and do not mark the milestone as passing verification.
+3. **Verify code changes exist.** Run `git diff --stat HEAD $(git merge-base HEAD main) -- ':!.gsd/'` (or the equivalent for the integration branch). If no non-`.gsd/` files appear in the diff, the milestone produced only planning artifacts and no actual code. In that case, do NOT mark the milestone as passing verification — document the gap clearly in the summary and state that implementation is missing.
+4. Verify each **success criterion** from the milestone definition in `{{roadmapPath}}`. For each criterion, confirm it was met with specific evidence from slice summaries, test results, or observable behavior. List any criterion that was NOT met.
+5. Verify the milestone's **definition of done** — all slices are `[x]`, all slice summaries exist, and any cross-slice integration points work correctly.
+6. Validate **requirement status transitions**. For each requirement that changed status during this milestone, confirm the transition is supported by evidence. Requirements can move between Active, Validated, Deferred, Blocked, or Out of Scope — but only with proof.
+7. Write `{{milestoneSummaryPath}}` using the milestone-summary template. Fill all frontmatter fields and narrative sections. The `requirement_outcomes` field must list every requirement that changed status with `from_status`, `to_status`, and `proof`.
+8. Update `.gsd/REQUIREMENTS.md` if any requirement status transitions were validated in step 5.
+9. Update `.gsd/PROJECT.md` to reflect milestone completion and current project state.
+10. Review all slice summaries for cross-cutting lessons, patterns, or gotchas that emerged during this milestone. Append any non-obvious, reusable insights to `.gsd/KNOWLEDGE.md`.
+11. Do not commit manually — the system auto-commits your changes after this unit completes.
+
+**Important:** Do NOT skip the code change verification, success criteria, or definition of done verification (steps 3-5). The milestone summary must reflect actual verified outcomes, not assumed success. If any criterion was not met or no code changes exist, document it clearly in the summary and do not mark the milestone as passing verification.
 
 **File system safety:** When scanning milestone directories for evidence, use `ls` or `find` to list directory contents first — never pass a directory path (e.g. `tasks/`, `slices/`) directly to the `read` tool. The `read` tool only accepts file paths, not directories.