gsd-pi 2.76.0 → 2.77.0-dev.2daa994b6

package/src/resources/extensions/gsd/slice-cadence.ts

@@ -0,0 +1,299 @@
+/**
+ * Slice-cadence collapse — #4765.
+ *
+ * When `git.collapse_cadence: "slice"` is set, each slice's commits are
+ * squash-merged from the milestone branch to main as soon as the slice
+ * passes validation. Shrinks the orphan window (#4761) from milestone-size
+ * to slice-size and surfaces merge conflicts per-slice rather than all at
+ * once at milestone end.
+ *
+ * This module is deliberately focused and narrower than mergeMilestoneToMain:
+ *   - No worktree teardown (worktree is reused for the next slice)
+ *   - No DB reconciliation (modern worktrees share the main DB via path resolver)
+ *   - No roadmap/summary/gate handling (that's still the milestone's job)
+ *   - Fails loudly on dirty main — caller is responsible for cleanliness
+ *
+ * Kernighan: the v1 surface handles the happy path + conflict. Edge cases
+ * that mergeMilestoneToMain covers (concurrent merges, shared DB paths,
+ * submodules) are explicit non-goals; users opt in via preference and early-
+ * adopter scenarios are scoped narrow.
+ */
+
+import { existsSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+
+import { GSDError, GSD_GIT_ERROR } from "./errors.js";
+import { MergeConflictError } from "./git-service.js";
+import {
+  nativeBranchForceReset,
+  nativeCheckoutBranch,
+  nativeCommit,
+  nativeCommitCountBetween,
+  nativeConflictFiles,
+  nativeDetectMainBranch,
+  nativeMergeSquash,
+} from "./native-git-bridge.js";
+import { resolveGitDir } from "./worktree-manager.js";
+import { logWarning } from "./workflow-logger.js";
+import { emitSliceMerged, emitMilestoneResquash } from "./worktree-telemetry.js";
+
+/**
+ * Auto-worktree milestone branch name. Must match autoWorktreeBranch() in
+ * auto-worktree.ts; duplicated here to avoid a cyclic import.
+ */
+function milestoneBranchName(milestoneId: string): string {
+  return `milestone/${milestoneId}`;
+}
+
+function cleanupMergeArtifacts(projectRoot: string): void {
+  try {
+    const gitDir = resolveGitDir(projectRoot);
+    for (const f of ["SQUASH_MSG", "MERGE_MSG", "MERGE_HEAD"]) {
+      const p = join(gitDir, f);
+      if (existsSync(p)) unlinkSync(p);
+    }
+  } catch (err) {
+    logWarning("worktree", `merge artifact cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+export interface SliceMergeResult {
+  commitSha: string | null;
+  mainBranch: string;
+  milestoneBranch: string;
+  durationMs: number;
+  skipped: boolean;
+  skippedReason?: string;
+}
+
+/**
+ * Squash-merge one slice's commits from the milestone branch to main.
+ *
+ * Preconditions:
+ *   - Caller is on the milestone branch inside the worktree
+ *   - `projectRoot` points at the real project root (not the worktree)
+ *
+ * Post-conditions on success:
+ *   - Slice's commits are a single squash commit on main
+ *   - `milestone/<MID>` is fast-forwarded to main (so next slice's work
+ *     starts from a clean base)
+ *   - caller's process.cwd is restored
+ *
+ * Throws MergeConflictError on conflicts; caller should surface and stop.
+ * Throws GSDError on dirty main / detection failures.
+ */
+export function mergeSliceToMain(
+  projectRoot: string,
+  milestoneId: string,
+  sliceId: string,
+): SliceMergeResult {
+  const started = Date.now();
+  const worktreeCwd = process.cwd();
+  const milestoneBranch = milestoneBranchName(milestoneId);
+  const mainBranch = nativeDetectMainBranch(projectRoot);
+
+  // Fast path: if the milestone branch has no commits ahead of main, there
+  // is nothing to merge. Return a skip result instead of no-op'ing silently
+  // so the caller's telemetry shows the decision.
+  let commitsAhead = 0;
+  try {
+    commitsAhead = nativeCommitCountBetween(projectRoot, mainBranch, milestoneBranch);
+  } catch {
+    // If we can't count, assume there's work and let the merge proceed —
+    // a failing merge is more informative than a silent skip.
+    commitsAhead = 1;
+  }
+  if (commitsAhead === 0) {
+    // Do NOT emit slice-merged here — this is a no-op, not a merge. Emitting
+    // would inflate slicesMerged in telemetry/forensics and distort the
+    // conflict rate denominator.
+    return {
+      commitSha: null,
+      mainBranch,
+      milestoneBranch,
+      durationMs: Date.now() - started,
+      skipped: true,
+      skippedReason: "no-commits-ahead",
+    };
+  }
+
+  process.chdir(projectRoot);
+  try {
+    // Dirty-main check — v1 fails loudly rather than auto-stashing. Users
+    // running slice-cadence opt in knowing main stays clean between merges.
+    const status = execFileSync("git", ["status", "--porcelain"], {
+      cwd: projectRoot,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    }).trim();
+    if (status) {
+      throw new GSDError(
+        GSD_GIT_ERROR,
+        `slice-cadence merge requires a clean project root; uncommitted changes detected. ` +
+        `Commit or stash at ${projectRoot} before retrying. Status:\n${status}`,
+      );
+    }
+
+    nativeCheckoutBranch(projectRoot, mainBranch);
+
+    // Clean any stale merge artifacts before attempting the squash (#2912 pattern)
+    cleanupMergeArtifacts(projectRoot);
+
+    const mergeResult = nativeMergeSquash(projectRoot, milestoneBranch);
+    if (!mergeResult.success) {
+      const conflictedFiles = mergeResult.conflicts.length > 0
+        ? mergeResult.conflicts
+        : nativeConflictFiles(projectRoot);
+      cleanupMergeArtifacts(projectRoot);
+      try {
+        emitSliceMerged(projectRoot, milestoneId, sliceId, {
+          durationMs: Date.now() - started,
+          conflict: true,
+        });
+      } catch { /* silent */ }
+      throw new MergeConflictError(
+        conflictedFiles,
+        "squash",
+        milestoneBranch,
+        mainBranch,
+      );
+    }
+
+    // Commit the squash with a slice-scoped message
+    const commitSha = nativeCommit(
+      projectRoot,
+      `gsd: merge ${sliceId} of ${milestoneId} (slice-cadence)`,
+    );
+
+    // Advance the milestone branch to main so the next slice's commits start
+    // from a clean base. Force-reset is safe because we just merged this
+    // branch's entire delta.
+    nativeBranchForceReset(projectRoot, milestoneBranch, mainBranch);
+
+    const durationMs = Date.now() - started;
+    try {
+      emitSliceMerged(projectRoot, milestoneId, sliceId, {
+        durationMs,
+        conflict: false,
+        commitSha: commitSha ?? undefined,
+      });
+    } catch { /* silent */ }
+
+    return {
+      commitSha,
+      mainBranch,
+      milestoneBranch,
+      durationMs,
+      skipped: false,
+    };
+  } finally {
+    // Always restore cwd even if anything above threw.
+    try { process.chdir(worktreeCwd); } catch { /* best-effort */ }
+  }
+}
+
+/**
+ * Re-squash per-slice commits on main into a single milestone commit.
+ *
+ * Runs at milestone completion when `collapse_cadence: "slice"` AND
+ * `milestone_resquash: true`. The `startSha` is the SHA of main immediately
+ * before the milestone's first slice merge — the caller is responsible for
+ * recording this (AutoSession field, git ref, or DB row).
+ *
+ * Strategy: soft-reset main to startSha, then commit the net diff. The
+ * N slice commits between startSha and HEAD are collapsed into one.
+ *
+ * No-op (returns false) if startSha equals HEAD (nothing to re-squash).
+ */
+export function resquashMilestoneOnMain(
+  projectRoot: string,
+  milestoneId: string,
+  startSha: string,
+): { resquashed: boolean; newSha: string | null } {
+  const mainBranch = nativeDetectMainBranch(projectRoot);
+  const worktreeCwd = process.cwd();
+
+  process.chdir(projectRoot);
+  try {
+    nativeCheckoutBranch(projectRoot, mainBranch);
+
+    // Verify the startSha..HEAD range contains ONLY this milestone's slice-
+    // cadence commits. If any unrelated commits landed on main since the
+    // milestone started (e.g. concurrent work, cherry-picks, hotfixes), a
+    // blind `git reset --soft` would fold them into the re-squash and rewrite
+    // their attribution. Fail closed — the user can resolve manually.
+    const expectedSuffix = `(slice-cadence)`;
+    const expectedMilestoneToken = ` of ${milestoneId} `;
+    let subjectsRaw = "";
+    try {
+      subjectsRaw = execFileSync(
+        "git",
+        ["log", "--format=%s", `${startSha}..HEAD`],
+        { cwd: projectRoot, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
+      );
+    } catch {
+      return { resquashed: false, newSha: null };
+    }
+    const subjects = subjectsRaw.split("\n").filter((s) => s.length > 0);
+    const sliceCount = subjects.length;
+    if (sliceCount === 0) {
+      return { resquashed: false, newSha: null };
+    }
+    const foreign = subjects.filter(
+      (s) => !(s.endsWith(expectedSuffix) && s.includes(expectedMilestoneToken)),
+    );
+    if (foreign.length > 0) {
+      logWarning(
+        "worktree",
+        `slice-cadence: skipping milestone resquash for ${milestoneId} — ` +
+        `${foreign.length} non-slice-cadence commit(s) in ${startSha}..HEAD ` +
+        `would be folded in. First: "${foreign[0]}". Resolve history manually.`,
+      );
+      return { resquashed: false, newSha: null };
+    }
+
+    // Safe to collapse: all commits in the range are this milestone's slices.
+    execFileSync("git", ["reset", "--soft", startSha], {
+      cwd: projectRoot,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    });
+
+    const newSha = nativeCommit(
+      projectRoot,
+      `gsd: complete milestone ${milestoneId} (${sliceCount} slices re-squashed)`,
+      { allowEmpty: true },
+    );
+
+    try {
+      emitMilestoneResquash(projectRoot, milestoneId, {
+        sliceCount,
+        startSha,
+        endSha: newSha ?? undefined,
+      });
+    } catch { /* silent */ }
+
+    return { resquashed: true, newSha };
+  } finally {
+    try { process.chdir(worktreeCwd); } catch { /* best-effort */ }
+  }
+}
+
+/**
+ * Read the effective collapse cadence from validated preferences. Accepts
+ * a raw preferences object (the shape loadEffectiveGSDPreferences returns).
+ */
+export function getCollapseCadence(
+  prefs: { git?: { collapse_cadence?: "milestone" | "slice" } } | undefined | null,
+): "milestone" | "slice" {
+  return prefs?.git?.collapse_cadence ?? "milestone";
+}
+
+export function getMilestoneResquash(
+  prefs: { git?: { milestone_resquash?: boolean } } | undefined | null,
+): boolean {
+  // Default true when cadence is slice — resquash preserves the milestone-
+  // level history shape users expect.
+  return prefs?.git?.milestone_resquash !== false;
+}

package/src/resources/extensions/gsd/state-transition-matrix.ts

@@ -0,0 +1,152 @@
+import type { Phase } from "./types.js";
+
+export type StateTransitionReasonCode =
+  | "state"
+  | "manual"
+  | "recovery"
+  | "dependency"
+  | "policy"
+  | "retry";
+
+export interface StateTransitionEntry {
+  from: Phase | "*";
+  event: string;
+  guard: string;
+  to: Phase;
+  onFail: Phase | "manual-attention" | "blocked" | "no-transition";
+  reasonCode: StateTransitionReasonCode;
+}
+
+export const STATE_TRANSITION_MATRIX: readonly StateTransitionEntry[] = [
+  {
+    from: "needs-discussion",
+    event: "context-ready",
+    guard: "CONTEXT artifact exists or PRD/context express path produced context",
+    to: "researching",
+    onFail: "needs-discussion",
+    reasonCode: "state",
+  },
+  {
+    from: "researching",
+    event: "research-ready",
+    guard: "RESEARCH artifact exists or research is explicitly skipped",
+    to: "planning",
+    onFail: "researching",
+    reasonCode: "state",
+  },
+  {
+    from: "planning",
+    event: "plan-ready",
+    guard: "ROADMAP/PLAN artifacts exist and plan gate passes",
+    to: "executing",
+    onFail: "replanning-slice",
+    reasonCode: "state",
+  },
+  {
+    from: "executing",
+    event: "task-dispatched",
+    guard: "task inputs are ready and dependencies are closed",
+    to: "executing",
+    onFail: "blocked",
+    reasonCode: "dependency",
+  },
+  {
+    from: "executing",
+    event: "slice-complete",
+    guard: "all slice tasks are closed and verification gate passes",
+    to: "summarizing",
+    onFail: "validating-milestone",
+    reasonCode: "state",
+  },
+  {
+    from: "summarizing",
+    event: "summary-ready",
+    guard: "SUMMARY artifact exists for the completed work unit",
+    to: "validating-milestone",
+    onFail: "summarizing",
+    reasonCode: "state",
+  },
+  {
+    from: "validating-milestone",
+    event: "validation-pass",
+    guard: "validation verdict is terminal and not remediation-required",
+    to: "completing-milestone",
+    onFail: "blocked",
+    reasonCode: "state",
+  },
+  {
+    from: "blocked",
+    event: "recovery-plan-ready",
+    guard: "reassessment produced an executable next action",
+    to: "executing",
+    onFail: "blocked",
+    reasonCode: "recovery",
+  },
+  {
+    from: "replanning-slice",
+    event: "replan-ready",
+    guard: "replacement slice/task plan exists and plan gate passes",
+    to: "executing",
+    onFail: "blocked",
+    reasonCode: "recovery",
+  },
+  {
+    from: "completing-milestone",
+    event: "closeout-complete",
+    guard: "closeout gate passes and git transaction succeeds",
+    to: "complete",
+    onFail: "blocked",
+    reasonCode: "state",
+  },
+  {
+    from: "*",
+    event: "manual-block",
+    guard: "operator or hard gate requested manual attention",
+    to: "blocked",
+    onFail: "manual-attention",
+    reasonCode: "manual",
+  },
+  {
+    from: "*",
+    event: "retryable-failure",
+    guard: "retry budget remains for failure class",
+    to: "executing",
+    onFail: "blocked",
+    reasonCode: "retry",
+  },
+] as const;
+
+export interface MatrixValidationResult {
+  ok: boolean;
+  missingEvents: string[];
+  duplicateKeys: string[];
+}
+
+export function findTransition(
+  from: Phase,
+  event: string,
+): StateTransitionEntry | undefined {
+  return STATE_TRANSITION_MATRIX.find((entry) =>
+    (entry.from === from || entry.from === "*") && entry.event === event,
+  );
+}
+
+export function validateTransitionMatrix(requiredEvents: readonly string[]): MatrixValidationResult {
+  const seen = new Set<string>();
+  const duplicateKeys: string[] = [];
+
+  for (const entry of STATE_TRANSITION_MATRIX) {
+    const key = `${entry.from}:${entry.event}`;
+    if (seen.has(key)) duplicateKeys.push(key);
+    seen.add(key);
+  }
+
+  const availableEvents = new Set(STATE_TRANSITION_MATRIX.map((entry) => entry.event));
+  const missingEvents = requiredEvents.filter((event) => !availableEvents.has(event));
+
+  return {
+    ok: missingEvents.length === 0 && duplicateKeys.length === 0,
+    missingEvents,
+    duplicateKeys,
+  };
+}

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

@@ -46,6 +46,7 @@ import { logWarning, logError } from './workflow-logger.js';
 import { extractVerdict } from './verdict-parser.js';
 import { loadEffectiveGSDPreferences } from './preferences.js';
 import { detectPendingEscalation } from './escalation.js';
+import { isTerminalMilestoneSummaryContent } from './milestone-summary-classifier.js';
 
 import {
   isDbAvailable,
@@ -139,6 +140,14 @@ export function isValidationTerminal(validationContent: string): boolean {
   return extractVerdict(validationContent) != null;
 }
 
+async function isTerminalMilestoneSummaryFile(
+  path: string,
+  loader: (path: string) => Promise<string | null>,
+): Promise<boolean> {
+  const content = await loader(path);
+  return content != null && isTerminalMilestoneSummaryContent(content);
+}
+
 // ─── State Derivation ──────────────────────────────────────────────────────
 
 // ── deriveState memoization ─────────────────────────────────────────────────
@@ -211,15 +220,15 @@ export async function getActiveMilestoneId(basePath: string): Promise<string | n
     const content = roadmapFile ? await loadFile(roadmapFile) : null;
     if (!content) {
       const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
-      if (summaryFile) continue;
+      if (summaryFile && await isTerminalMilestoneSummaryFile(summaryFile, loadFile)) continue;
       if (isGhostMilestone(basePath, mid)) continue;
       return mid;
     }
     const roadmap = parseRoadmap(content);
-    if (!isMilestoneComplete(roadmap)) {
-      const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
-      if (!summaryFile) return mid;
-    }
+    const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
+    if (summaryFile && await isTerminalMilestoneSummaryFile(summaryFile, loadFile)) continue;
+    if (!isMilestoneComplete(roadmap)) return mid;
+    return mid;
   }
   return null;
 }
@@ -613,7 +622,7 @@ async function handleAllSlicesDone(
   const validationTerminal = validationContent ? isValidationTerminal(validationContent) : false;
   const verdict = validationContent ? extractVerdict(validationContent) : undefined;
 
-  if (!validationTerminal || verdict === 'needs-remediation') {
+  if (!validationTerminal) {
     return {
       activeMilestone, activeSlice: null, activeTask: null,
       phase: 'validating-milestone',
@@ -624,6 +633,24 @@ async function handleAllSlicesDone(
     };
   }
 
+  // All roadmap slices are done (enforced by caller) and verdict is
+  // needs-remediation — remediation cannot progress without new slices.
+  // Return blocked instead of re-dispatching validate-milestone (#4506).
+  if (verdict === 'needs-remediation') {
+    return {
+      activeMilestone, activeSlice: null, activeTask: null,
+      phase: 'blocked',
+      recentDecisions: [],
+      blockers: [
+        `Milestone ${activeMilestone.id} validation verdict is needs-remediation but all slices are complete. ` +
+          `Add remediation slices via gsd_reassess_roadmap or override the verdict manually.`,
+      ],
+      nextAction: `Resolve ${activeMilestone.id} remediation before proceeding.`,
+      registry, requirements,
+      progress: { milestones: milestoneProgress, slices: sliceProgress },
+    };
+  }
+
   return {
     activeMilestone, activeSlice: null, activeTask: null,
     phase: 'completing-milestone',
@@ -650,7 +677,6 @@ function resolveSliceDependencies(activeMilestoneSlices: SliceRow[]): { activeSl
     }
   }
 
-  // First pass: find a slice with ALL dependencies satisfied (strict)
   let bestFallback: SliceRow | null = null;
   let bestFallbackSatisfied = -1;
 
@@ -660,7 +686,6 @@ function resolveSliceDependencies(activeMilestoneSlices: SliceRow[]): { activeSl
     if (s.depends.every(dep => doneSliceIds.has(dep))) {
       return { activeSlice: { id: s.id, title: s.title }, activeSliceRow: s };
     }
-    // Track the slice with the most satisfied dependencies as fallback
     const satisfied = s.depends.filter(dep => doneSliceIds.has(dep)).length;
     if (satisfied > bestFallbackSatisfied || (satisfied === bestFallbackSatisfied && !bestFallback)) {
       bestFallback = s;
@@ -668,16 +693,13 @@ function resolveSliceDependencies(activeMilestoneSlices: SliceRow[]): { activeSl
     }
   }
 
-  // Fallback: if no slice has all deps met but there ARE incomplete non-deferred
-  // slices, pick the one with the most deps satisfied. This prevents hard-blocking
-  // when dependency metadata is stale (e.g. after reassessment added/removed slices)
-  // or when deps reference slices from previous milestones.
   if (bestFallback) {
     const unmet = bestFallback.depends.filter(dep => !doneSliceIds.has(dep));
-    logWarning("state",
+    logWarning(
+      "state",
       `No slice has all deps satisfied — falling back to ${bestFallback.id} ` +
-      `(${bestFallbackSatisfied}/${bestFallback.depends.length} deps met, ` +
-      `unmet: ${unmet.join(", ")})`,
+        `(${bestFallbackSatisfied}/${bestFallback.depends.length} deps met, ` +
+        `unmet: ${unmet.join(", ")})`,
       { mid: activeMilestoneSlices[0]?.milestone_id, sid: bestFallback.id },
     );
     return { activeSlice: { id: bestFallback.id, title: bestFallback.title }, activeSliceRow: bestFallback };
@@ -1142,7 +1164,7 @@ export async function _deriveStateImpl(basePath: string): Promise<GSDState> {
     const rc = rf ? await cachedLoadFile(rf) : null;
     if (!rc) {
       const sf = resolveMilestoneFile(basePath, mid, "SUMMARY");
-      if (sf) completeMilestoneIds.add(mid);
+      if (sf && await isTerminalMilestoneSummaryFile(sf, cachedLoadFile)) completeMilestoneIds.add(mid);
       continue;
     }
     const rmap = parseRoadmap(rc);
@@ -1151,11 +1173,11 @@ export async function _deriveStateImpl(basePath: string): Promise<GSDState> {
       // Summary is the terminal artifact — if it exists, the milestone is
       // complete even when roadmap checkboxes weren't ticked (#864).
       const sf = resolveMilestoneFile(basePath, mid, "SUMMARY");
-      if (sf) completeMilestoneIds.add(mid);
+      if (sf && await isTerminalMilestoneSummaryFile(sf, cachedLoadFile)) completeMilestoneIds.add(mid);
       continue;
     }
     const sf = resolveMilestoneFile(basePath, mid, "SUMMARY");
-    if (sf) completeMilestoneIds.add(mid);
+    if (sf && await isTerminalMilestoneSummaryFile(sf, cachedLoadFile)) completeMilestoneIds.add(mid);
   }
 
   // Phase 2: Build registry using cached roadmaps (no re-parsing or re-reading)
@@ -1183,12 +1205,14 @@ export async function _deriveStateImpl(basePath: string): Promise<GSDState> {
       const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
       if (summaryFile) {
         const summaryContent = await cachedLoadFile(summaryFile);
-        const summaryTitle = summaryContent
-          ? (parseSummary(summaryContent).title || mid)
-          : mid;
-        registry.push({ id: mid, title: summaryTitle, status: 'complete' });
-        completeMilestoneIds.add(mid);
-        continue;
+        if (summaryContent != null && isTerminalMilestoneSummaryContent(summaryContent)) {
+          const summaryTitle = summaryContent
+            ? (parseSummary(summaryContent).title || mid)
+            : mid;
+          registry.push({ id: mid, title: summaryTitle, status: 'complete' });
+          completeMilestoneIds.add(mid);
+          continue;
+        }
       }
       // Ghost milestone (only META.json, no CONTEXT/ROADMAP/SUMMARY) — skip entirely
       if (isGhostMilestone(basePath, mid)) continue;
@@ -1244,7 +1268,7 @@ export async function _deriveStateImpl(basePath: string): Promise<GSDState> {
       // needs-remediation is terminal but requires re-validation (#3596)
       const needsRevalidation = !validationTerminal || verdict === 'needs-remediation';
 
-      if (summaryFile) {
+      if (summaryFile && await isTerminalMilestoneSummaryFile(summaryFile, cachedLoadFile)) {
         // Summary exists → milestone is complete regardless of validation state.
         // The summary is the terminal artifact (#864).
         registry.push({ id: mid, title, status: 'complete' });
@@ -1270,7 +1294,7 @@ export async function _deriveStateImpl(basePath: string): Promise<GSDState> {
       // Roadmap slices not all checked — but if a summary exists, the milestone
       // is still complete. The summary is the terminal artifact (#864).
       const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
-      if (summaryFile) {
+      if (summaryFile && await isTerminalMilestoneSummaryFile(summaryFile, cachedLoadFile)) {
         registry.push({ id: mid, title, status: 'complete' });
       } else if (!activeMilestoneFound) {
         // Check milestone-level dependencies before promoting to active.
@@ -1450,9 +1474,11 @@ export async function _deriveStateImpl(basePath: string): Promise<GSDState> {
       total: activeRoadmap.slices.length,
     };
 
-    // Force re-validation when verdict is needs-remediation — remediation slices
-    // may have completed since the stale validation was written (#3596).
-    if (!validationTerminal || verdict === 'needs-remediation') {
+    // Force re-validation when VALIDATION.md is absent or non-terminal —
+    // remediation slices may have completed since the stale validation was
+    // written (#3596). But needs-remediation with all slices done is a dead
+    // end — return blocked to avoid an infinite dispatch loop (#4506).
+    if (!validationTerminal) {
       return {
         activeMilestone,
         activeSlice: null,
@@ -1470,6 +1496,27 @@ export async function _deriveStateImpl(basePath: string): Promise<GSDState> {
       };
     }
 
+    if (verdict === 'needs-remediation') {
+      return {
+        activeMilestone,
+        activeSlice: null,
+        activeTask: null,
+        phase: 'blocked',
+        recentDecisions: [],
+        blockers: [
+          `Milestone ${activeMilestone.id} validation verdict is needs-remediation but all slices are complete. ` +
+            `Add remediation slices via gsd_reassess_roadmap or override the verdict manually.`,
+        ],
+        nextAction: `Resolve ${activeMilestone.id} remediation before proceeding.`,
+        registry,
+        requirements,
+        progress: {
+          milestones: milestoneProgress,
+          slices: sliceProgress,
+        },
+      };
+    }
+
     return {
       activeMilestone,
       activeSlice: null,
@@ -1531,7 +1578,6 @@ export async function _deriveStateImpl(basePath: string): Promise<GSDState> {
         activeSlice = { id: s.id, title: s.title };
         break;
       }
-      // Track best fallback
       const satisfied = s.depends.filter(dep => doneSliceIds.has(dep)).length;
       if (satisfied > bestFallbackLegacySatisfied) {
         bestFallbackLegacy = s;
@@ -1539,13 +1585,13 @@ export async function _deriveStateImpl(basePath: string): Promise<GSDState> {
       }
     }
 
-    // Fallback: if no slice has all deps met, pick the one with the most deps satisfied
     if (!activeSlice && bestFallbackLegacy) {
       const unmet = bestFallbackLegacy.depends.filter(dep => !doneSliceIds.has(dep));
-      logWarning("state",
+      logWarning(
+        "state",
         `No slice has all deps satisfied — falling back to ${bestFallbackLegacy.id} ` +
-        `(${bestFallbackLegacySatisfied}/${bestFallbackLegacy.depends.length} deps met, ` +
-        `unmet: ${unmet.join(", ")})`,
+          `(${bestFallbackLegacySatisfied}/${bestFallbackLegacy.depends.length} deps met, ` +
+          `unmet: ${unmet.join(", ")})`,
       );
       activeSlice = { id: bestFallbackLegacy.id, title: bestFallbackLegacy.title };
     }