gsd-pi 2.65.0-dev.5c8557b → 2.65.0-dev.6cc5110

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

@@ -1,48 +1,81 @@
-You are executing GSD auto-mode.
+# Milestone Validation — Parallel Review
 
-## UNIT: Validate Milestone {{milestoneId}} ("{{milestoneTitle}}")
+You are the validation orchestrator for **{{milestoneId}} — {{milestoneTitle}}**.
 
 ## Working Directory
 
 Your working directory is `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` to any other directory.
 
-## Your Role in the Pipeline
+## Mission
 
-All slices are done. Before the milestone can be completed, you must validate that the planned work was delivered as specified. Compare the roadmap's success criteria and slice definitions against the actual slice summaries and UAT results. This is a reconciliation gate — catch gaps, regressions, or missing deliverables before the milestone is sealed.
+Dispatch 3 independent parallel reviewers, then synthesize their findings into the final VALIDATION verdict.
 
 This is remediation round {{remediationRound}}. If this is round 0, this is the first validation pass. If > 0, prior validation found issues and remediation slices were added and executed — verify those remediation slices resolved the issues.
 
+## Context
+
 All relevant context has been preloaded below — the roadmap, all slice summaries, UAT results, requirements, decisions, and project context are inlined. Start working immediately without re-reading these files.
 
 {{inlinedContext}}
 
-{{skillActivation}}
+## Execution Protocol
+
+### Step 1 — Dispatch Parallel Reviewers
+
+Call `subagent` with `tasks: [...]` containing ALL THREE reviewers simultaneously:
+
+**Reviewer A — Requirements Coverage**
+Prompt: "Review milestone {{milestoneId}} requirements coverage. Working directory: {{workingDirectory}}. Read `.gsd/{{milestoneId}}/REQUIREMENTS.md` (or equivalent requirements file). For each requirement, check the slice SUMMARY files in `.gsd/{{milestoneId}}/` to determine if it is: COVERED (clearly demonstrated), PARTIAL (mentioned but not fully demonstrated), or MISSING (no evidence). Output a markdown table with columns: Requirement | Status | Evidence. End with a one-line verdict: PASS if all covered, NEEDS-ATTENTION if partials exist, FAIL if any missing."
+
+**Reviewer B — Cross-Slice Integration**
+Prompt: "Review milestone {{milestoneId}} cross-slice integration. Working directory: {{workingDirectory}}. Read `{{roadmapPath}}` and find the boundary map (produces/consumes contracts). For each boundary, check that the producing slice's SUMMARY confirms it produced the artifact, and the consuming slice's SUMMARY confirms it consumed it. Output a markdown table: Boundary | Producer Summary | Consumer Summary | Status. End with a one-line verdict: PASS if all boundaries honored, NEEDS-ATTENTION if any gaps."
+
+**Reviewer C — UAT & Acceptance Criteria**
+Prompt: "Review milestone {{milestoneId}} UAT and acceptance criteria. Working directory: {{workingDirectory}}. Read `.gsd/{{milestoneId}}/CONTEXT.md` for acceptance criteria. Check for UAT-RESULT files in each slice directory. Verify each acceptance criterion maps to either a passing UAT result or clear SUMMARY evidence. Output a checklist: [ ] Criterion | Evidence. End with a one-line verdict: PASS if all criteria met, NEEDS-ATTENTION if gaps exist."
+
+### Step 2 — Synthesize Findings
 
-## Validation Steps
+After all reviewers complete, aggregate their verdicts:
+- If ALL reviewers say PASS → overall verdict: `pass`
+- If any reviewer says NEEDS-ATTENTION → overall verdict: `needs-attention`
+- If any reviewer says FAIL → overall verdict: `needs-remediation`
 
-1. For each **success criterion** in `{{roadmapPath}}`, check whether slice summaries and UAT results provide evidence that it was met. Record pass/fail per criterion.
-2. For each **slice** in the roadmap, verify its demo/deliverable claim against its summary. Flag any slice whose summary does not substantiate its claimed output.
-3. Check **cross-slice integration points** — do boundary map entries (produces/consumes) align with what was actually built?
-4. Check **requirement coverage** — are all active requirements addressed by at least one slice?
-5. If **Verification Classes** are provided in the inlined context above, check each non-empty class:
-   - For each verification class (Contract, Integration, Operational, UAT), determine whether slice summaries, UAT results, or observable behavior provide evidence that this verification tier was addressed.
-   - Document the compliance status of each class in a dedicated verification classes section.
-   - If `Operational` verification is non-empty and no evidence of operational verification exists, flag this explicitly — it means planned operational checks (migrations, deployments, runtime verification) were not proven.
-   - A milestone with unaddressed verification classes may still pass if the gaps are minor, but the gaps MUST be documented in the Deferred Work Inventory.
-6. Determine a verdict:
-   - `pass` — all criteria met, all slices delivered, no gaps
-   - `needs-attention` — minor gaps that do not block completion (document them)
-   - `needs-remediation` — material gaps found; remediation slices must be added to the roadmap
+### Step 3 — Write VALIDATION File
 
-## Persist Validation
+Write to `{{validationPath}}`:
 
-**Persist validation results through `gsd_validate_milestone`.** Call it with: `milestoneId`, `verdict`, `remediationRound`, `successCriteriaChecklist`, `sliceDeliveryAudit`, `crossSliceIntegration`, `requirementCoverage`, `verificationClasses` (when non-empty), `verdictRationale`, and `remediationPlan` (if verdict is `needs-remediation`). The tool writes the validation to the DB and renders VALIDATION.md to disk.
+```markdown
+---
+verdict: <pass|needs-attention|needs-remediation>
+remediation_round: {{remediationRound}}
+reviewers: 3
+---
+
+# Milestone Validation: {{milestoneId}}
+
+## Reviewer A — Requirements Coverage
+<paste Reviewer A output>
+
+## Reviewer B — Cross-Slice Integration
+<paste Reviewer B output>
+
+## Reviewer C — UAT & Acceptance Criteria
+<paste Reviewer C output>
+
+## Synthesis
+<2-3 sentences summarizing overall findings and verdict rationale>
+
+## Remediation Plan
+<if verdict is not pass: specific actions required>
+```
 
 **DB access safety:** Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')` — the engine owns the WAL connection. Use `gsd_milestone_status` to read milestone and slice state. All data you need is already inlined in the context above or accessible via the `gsd_*` tools. Direct DB access corrupts the WAL and bypasses tool-level validation.
 
 If verdict is `needs-remediation`:
-- After calling `gsd_validate_milestone`, use `gsd_reassess_roadmap` to add remediation slices. Pass `milestoneId`, a synthetic `completedSliceId` (e.g. "VALIDATION"), `verdict: "roadmap-adjusted"`, `assessment` text, and `sliceChanges` with the new slices in the `added` array. The tool persists the changes to the DB and re-renders ROADMAP.md.
-- These remediation slices will be planned and executed before validation re-runs.
+- Add new slices to `{{roadmapPath}}` with unchecked `[ ]` status
+- These slices will be planned and executed before validation re-runs
+
+**You MUST write `{{validationPath}}` before finishing.**
 
 **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.
 

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

@@ -192,28 +192,33 @@ export async function handleQuick(
   const taskDirRel = `.gsd/quick/${taskNum}-${slug}`;
   const date = new Date().toISOString().split("T")[0];
 
-  // Create git branch for the quick task
+  // Create git branch for the quick task (unless isolation:none — #3337)
   const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git ?? {};
   const git = new GitServiceImpl(basePath, gitPrefs);
   const branchName = `gsd/quick/${taskNum}-${slug}`;
   let originalBranch = git.getCurrentBranch();
 
+  const { getIsolationMode } = await import("./preferences.js");
+  const usesBranch = getIsolationMode() !== "none";
+
   let branchCreated = false;
-  try {
-    const current = originalBranch;
-    if (current !== branchName) {
-      // Auto-commit any dirty state before switching
-      try {
-        git.autoCommit("quick-task", `Q${taskNum}`, []);
-      } catch { /* nothing to commit — fine */ }
-
-      runGit(basePath, ["checkout", "-b", branchName]);
-      branchCreated = true;
+  if (usesBranch) {
+    try {
+      const current = originalBranch;
+      if (current !== branchName) {
+        // Auto-commit any dirty state before switching
+        try {
+          git.autoCommit("quick-task", `Q${taskNum}`, []);
+        } catch { /* nothing to commit — fine */ }
+
+        runGit(basePath, ["checkout", "-b", branchName]);
+        branchCreated = true;
+      }
+    } catch (err) {
+      // Branch creation failed — continue on current branch
+      const message = err instanceof Error ? err.message : String(err);
+      ctx.ui.notify(`Could not create branch ${branchName}: ${message}. Working on current branch.`, "warning");
     }
-  } catch (err) {
-    // Branch creation failed — continue on current branch
-    const message = err instanceof Error ? err.message : String(err);
-    ctx.ui.notify(`Could not create branch ${branchName}: ${message}. Working on current branch.`, "warning");
   }
 
   const actualBranch = branchCreated ? branchName : git.getCurrentBranch();

package/src/resources/extensions/gsd/reactive-graph.ts

@@ -131,6 +131,24 @@ export function isGraphAmbiguous(graph: DerivedTaskNode[]): boolean {
   );
 }
 
+/**
+ * Returns tasks that are missing IO annotations (no inputFiles and no outputFiles).
+ * These tasks prevent parallel dispatch by making the graph ambiguous.
+ * Used to surface actionable diagnostics when parallel execution falls back to sequential.
+ */
+export function getMissingAnnotationTasks(
+  graph: DerivedTaskNode[],
+): Array<{ id: string; title: string }> {
+  return graph
+    .filter(
+      (node) =>
+        !node.done &&
+        node.inputFiles.length === 0 &&
+        node.outputFiles.length === 0,
+    )
+    .map((node) => ({ id: node.id, title: node.title }));
+}
+
 /**
  * Detect deadlock: no tasks are ready and none are in-flight, yet incomplete
  * tasks remain. This indicates a circular dependency or impossible state.

package/src/resources/extensions/gsd/roadmap-slices.ts

@@ -66,6 +66,17 @@ function parseTableSlices(section: string): RoadmapSliceEntry[] {
   const lines = section.split("\n");
   const slices: RoadmapSliceEntry[] = [];
 
+  // Detect dependency column index from the header row (#3383, #3336).
+  // Only parse deps from this column (or cells with explicit "depends"/"deps" keywords).
+  let depColumnIndex = -1;
+  for (const line of lines) {
+    if (!line.includes("|")) continue;
+    if (/S\d+/.test(line)) break; // reached data rows
+    const headerCells = line.split("|").map(c => c.trim()).filter(Boolean);
+    depColumnIndex = headerCells.findIndex(c => /^(depends|deps|depend)/i.test(c));
+    if (depColumnIndex >= 0) break;
+  }
+
   for (const line of lines) {
     // Skip non-table lines, separator lines (|---|---|), and header rows
     if (!line.includes("|")) continue;
@@ -95,12 +106,17 @@ function parseTableSlices(section: string): RoadmapSliceEntry[] {
       if (/\bmedium\b/.test(cellLower) || /\bmed\b/.test(cellLower)) { risk = "medium"; break; }
     }
 
-    // Extract dependencies from cells containing S-prefixed IDs (excluding the slice's own ID)
+    // Extract dependencies only from the dependency column or cells with
+    // explicit "depends"/"deps" keywords — never from title cells (#3383).
     let depends: string[] = [];
-    for (const cell of cells) {
-      if (/depends|deps/i.test(cell) || (cell.match(/S\d+/g)?.length ?? 0) > 0) {
-        const depIds = (cell.match(/S\d+/g) ?? []).filter(d => d !== id);
-        if (depIds.length > 0 || /none|—|-/i.test(cell)) {
+    if (depColumnIndex >= 0 && cells[depColumnIndex]) {
+      const depCell = cells[depColumnIndex]!;
+      const depIds = (depCell.match(/S\d+/g) ?? []).filter(d => d !== id);
+      depends = expandDependencies(depIds);
+    } else {
+      for (const cell of cells) {
+        if (/depends|deps/i.test(cell)) {
+          const depIds = (cell.match(/S\d+/g) ?? []).filter(d => d !== id);
           depends = expandDependencies(depIds);
           break;
         }

package/src/resources/extensions/gsd/safety/content-validator.ts

@@ -54,12 +54,12 @@ const VALIDATORS: Record<string, ContentValidatorFn> = {
 function validatePlanSlice(content: string): ContentViolation[] {
   const violations: ContentViolation[] = [];
 
-  // Must have at least 2 task entries (checkbox pattern)
+  // Must have at least 1 task entry — single-task slices are valid (#3649)
   const taskCount = (content.match(/- \[[ x]\] \*\*T\d+/g) || []).length;
-  if (taskCount < 2) {
+  if (taskCount < 1) {
     violations.push({
       severity: "warning",
-      reason: `Slice plan has only ${taskCount} task(s) — expected at least 2`,
+      reason: `Slice plan has ${taskCount} task(s) — expected at least 1`,
     });
   }
 

package/src/resources/extensions/gsd/session-lock.ts

@@ -288,6 +288,20 @@ export function acquireSessionLock(basePath: string): SessionLockResult {
   const gsdDir = gsdRoot(basePath);
   const lockTarget = effectiveLockTarget(gsdDir);
 
+  // #3218: Pre-flight stale lock cleanup — if the .lock/ directory exists but
+  // no auto.lock metadata is present (or the PID is dead), remove the lock
+  // directory before attempting acquisition. This prevents the 30-min stale
+  // window from blocking /gsd after crashes, SIGKILL, or laptop sleep.
+  const lockDir = lockTarget + ".lock";
+  if (existsSync(lockDir)) {
+    const existingData = readExistingLockData(lp);
+    const isOrphan = !existingData || (existingData.pid && !isPidAlive(existingData.pid));
+    if (isOrphan) {
+      try { rmSync(lockDir, { recursive: true, force: true }); } catch { /* best-effort */ }
+      try { if (existsSync(lp)) unlinkSync(lp); } catch { /* best-effort */ }
+    }
+  }
+
   try {
     // Try to acquire an exclusive OS-level lock on the lock target.
     // We lock a directory since proper-lockfile works best on directories,
@@ -344,9 +358,11 @@ export function acquireSessionLock(basePath: string): SessionLockResult {
       }
     }
 
+    // #3218: Provide actionable workaround when lock recovery fails
+    const lockDirPath = lockTarget + ".lock";
     const reason = existingPid
       ? `Another auto-mode session (PID ${existingPid}) appears to be running.\nStop it with \`kill ${existingPid}\` before starting a new session.`
-      : `Another auto-mode session is already running on this project.`;
+      : `Another auto-mode session lock is stuck on this project.\nRun: rm -rf "${lockDirPath}" && rm -f "${lp}"`;
 
     return { acquired: false, reason, existingPid };
   }

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

@@ -55,6 +55,7 @@ import {
   getSlice,
   insertMilestone,
   insertSlice,
+  insertTask,
   updateTaskStatus,
   getPendingSliceGateCount,
   type MilestoneRow,
@@ -78,10 +79,20 @@ import {
  * as ghosts, causing auto-mode to skip them entirely.
  */
 export function isGhostMilestone(basePath: string, mid: string): boolean {
-  // If the milestone has a DB row, it's a known milestone — not a ghost.
+  // If the milestone has a DB row, it's usually a known milestone — not a ghost.
+  // Exception: a "queued" row with no disk artifacts is a phantom from
+  // gsd_milestone_generate_id that was never planned (#3645).
   if (isDbAvailable()) {
     const dbRow = getMilestone(mid);
-    if (dbRow) return false;
+    if (dbRow) {
+      if (dbRow.status === 'queued') {
+        const hasContent = resolveMilestoneFile(basePath, mid, "CONTEXT")
+          || resolveMilestoneFile(basePath, mid, "ROADMAP")
+          || resolveMilestoneFile(basePath, mid, "SUMMARY");
+        return !hasContent;
+      }
+      return false;
+    }
   }
 
   // If a worktree exists for this milestone, it was legitimately created.
@@ -178,7 +189,7 @@ export async function getActiveMilestoneId(basePath: string): Promise<string | n
       const byId = new Map(allMilestones.map(m => [m.id, m]));
       for (const id of sortedIds) {
         const m = byId.get(id)!;
-        if (m.status === "complete" || m.status === "done" || m.status === "parked") continue;
+        if (isClosedStatus(m.status) || m.status === "parked") continue;
         return m.id;
       }
       return null;
@@ -431,13 +442,10 @@ export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
       continue;
     }
 
-    // Check roadmap: all slices done means milestone is complete
-    const slices = getMilestoneSlices(m.id);
-    if (slices.length > 0 && slices.every(s => isStatusDone(s.status))) {
-      // All slices done but no summary — still counts as complete for dep resolution
-      // if a summary file exists
-      // Note: without summary file, the milestone is in validating/completing state, not complete
-    }
+    // Milestones with all slices done but no SUMMARY file are in
+    // validating/completing state — intentionally NOT added to
+    // completeMilestoneIds.  The SUMMARY file (checked above) is the
+    // terminal artifact that proves completion per #864.
   }
 
   // Phase 2: Build registry and find active milestone
@@ -446,6 +454,10 @@ export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
   let activeMilestoneSlices: SliceRow[] = [];
   let activeMilestoneFound = false;
   let activeMilestoneHasDraft = false;
+  // Queued shells (DB row, no slices, no content files) are deferred during
+  // the main loop so they don't eclipse real active milestones (#3470).
+  // If no real active milestone is found, the first deferred shell is promoted.
+  let firstDeferredQueuedShell: { id: string; title: string; deps: string[] } | null = null;
 
   for (const m of milestones) {
     if (parkedMilestoneIds.has(m.id)) {
@@ -453,9 +465,10 @@ export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
       continue;
     }
 
-    // Ghost milestone check: no slices in DB AND no substantive files on disk
+    // Ghost milestone check: no slices in DB AND no substantive files on disk.
+    // Skip queued milestones — they are handled by the deferred-shell logic below (#3470).
     const slices = getMilestoneSlices(m.id);
-    if (slices.length === 0 && !isStatusDone(m.status)) {
+    if (slices.length === 0 && !isStatusDone(m.status) && m.status !== 'queued') {
       // Check disk for ghost detection
       if (isGhostMilestone(basePath, m.id)) continue;
     }
@@ -500,6 +513,23 @@ export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
         continue;
       }
 
+      // Defer queued shell milestones with no substantive content (#3470).
+      // A queued milestone with no slices and no context/draft file is a
+      // placeholder that should not block later real active milestones.
+      // If no real active milestone is found after the loop, the first
+      // deferred shell is promoted to active (#2921).
+      if (m.status === 'queued' && slices.length === 0) {
+        const contextFile = resolveMilestoneFile(basePath, m.id, "CONTEXT");
+        const draftFile = resolveMilestoneFile(basePath, m.id, "CONTEXT-DRAFT");
+        if (!contextFile && !draftFile) {
+          if (!firstDeferredQueuedShell) {
+            firstDeferredQueuedShell = { id: m.id, title, deps };
+          }
+          registry.push({ id: m.id, title, status: 'pending', ...(deps.length > 0 ? { dependsOn: deps } : {}) });
+          continue;
+        }
+      }
+
       // Handle all-slices-done case (validating/completing)
       if (allSlicesDone) {
         const validationFile = resolveMilestoneFile(basePath, m.id, "VALIDATION");
@@ -532,6 +562,16 @@ export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
     }
   }
 
+  // Promote deferred queued shell if no real active milestone was found (#3470/#2921).
+  if (!activeMilestoneFound && firstDeferredQueuedShell) {
+    const shell = firstDeferredQueuedShell;
+    activeMilestone = { id: shell.id, title: shell.title };
+    activeMilestoneSlices = [];
+    activeMilestoneFound = true;
+    const entry = registry.find(e => e.id === shell.id);
+    if (entry) entry.status = 'active';
+  }
+
   const milestoneProgress = {
     done: registry.filter(e => e.status === 'complete').length,
     total: registry.length,
@@ -636,12 +676,15 @@ export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
     const validationFile = resolveMilestoneFile(basePath, activeMilestone.id, "VALIDATION");
     const validationContent = validationFile ? await loadFile(validationFile) : null;
     const validationTerminal = validationContent ? isValidationTerminal(validationContent) : false;
+    const verdict = validationContent ? extractVerdict(validationContent) : undefined;
     const sliceProgress = {
       done: activeMilestoneSlices.length,
       total: activeMilestoneSlices.length,
     };
 
-    if (!validationTerminal) {
+    // 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') {
       return {
         activeMilestone, activeSlice: null, activeTask: null,
         phase: 'validating-milestone',
@@ -738,6 +781,44 @@ export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
   // ── Get tasks from DB ────────────────────────────────────────────────
   let tasks = getSliceTasks(activeMilestone.id, activeSlice.id);
 
+  // ── Reconcile missing tasks: plan file has tasks but DB is empty (#3600) ──
+  // When the planning agent writes S##-PLAN.md with task entries but never
+  // calls the gsd_plan_slice persistence tool, the DB has zero task rows
+  // even though the plan file contains valid tasks. Without this reconciliation,
+  // deriveState returns phase='planning' forever — the dispatcher re-dispatches
+  // plan-slice in an infinite loop.
+  if (tasks.length === 0 && planFile) {
+    try {
+      const planContent = await loadFile(planFile);
+      if (planContent) {
+        const diskPlan = parsePlan(planContent);
+        if (diskPlan.tasks.length > 0) {
+          for (let i = 0; i < diskPlan.tasks.length; i++) {
+            const t = diskPlan.tasks[i];
+            try {
+              insertTask({
+                id: t.id,
+                sliceId: activeSlice.id,
+                milestoneId: activeMilestone.id,
+                title: t.title,
+                status: t.done ? 'complete' : 'pending',
+                sequence: i + 1,
+              });
+            } catch (insertErr) {
+              // Task may already exist from a partial previous import — skip
+              logWarning("reconcile", `failed to insert task ${t.id} from plan file: ${insertErr instanceof Error ? insertErr.message : String(insertErr)}`);
+            }
+          }
+          tasks = getSliceTasks(activeMilestone.id, activeSlice.id);
+          logWarning("reconcile", `imported ${tasks.length} tasks from plan file for ${activeMilestone.id}/${activeSlice.id} — DB was empty (#3600)`, { mid: activeMilestone.id, sid: activeSlice.id });
+        }
+      }
+    } catch (err) {
+      // Non-fatal — fall through to the existing "empty plan" logic
+      logError("reconcile", `plan-file task import failed for ${activeMilestone.id}/${activeSlice.id}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
   // ── Reconcile stale task status (#2514) ──────────────────────────────
   // When a session disconnects after the agent writes SUMMARY + VERIFY
   // artifacts but before postUnitPostVerification updates the DB, tasks
@@ -870,7 +951,12 @@ export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
   // ── REPLAN-TRIGGER detection ─────────────────────────────────────────
   if (!blockerTaskId) {
     const sliceRow = getSlice(activeMilestone.id, activeSlice.id);
-    if (sliceRow?.replan_triggered_at) {
+    // Check DB column first, fall back to disk trigger file when DB write
+    // was best-effort and failed (triage-resolution.ts dual-write gap).
+    const dbTriggered = !!sliceRow?.replan_triggered_at;
+    const diskTriggered = !dbTriggered &&
+      !!resolveSliceFile(basePath, activeMilestone.id, activeSlice.id, "REPLAN-TRIGGER");
+    if (dbTriggered || diskTriggered) {
       // Loop protection: if replan_history has entries, replan was already done
       const replanHistory = getReplanHistory(activeMilestone.id, activeSlice.id);
       if (replanHistory.length === 0) {
@@ -1099,22 +1185,25 @@ export async function _deriveStateImpl(basePath: string): Promise<GSDState> {
       const validationFile = resolveMilestoneFile(basePath, mid, "VALIDATION");
       const validationContent = validationFile ? await cachedLoadFile(validationFile) : null;
       const validationTerminal = validationContent ? isValidationTerminal(validationContent) : false;
+      const verdict = validationContent ? extractVerdict(validationContent) : undefined;
+      // needs-remediation is terminal but requires re-validation (#3596)
+      const needsRevalidation = !validationTerminal || verdict === 'needs-remediation';
 
       if (summaryFile) {
         // Summary exists → milestone is complete regardless of validation state.
         // The summary is the terminal artifact (#864).
         registry.push({ id: mid, title, status: 'complete' });
-      } else if (!validationTerminal && !activeMilestoneFound) {
-        // No summary and no terminal validation → validating-milestone
+      } else if (needsRevalidation && !activeMilestoneFound) {
+        // No summary and needs (re-)validation → validating-milestone
         activeMilestone = { id: mid, title };
         activeRoadmap = roadmap;
         activeMilestoneFound = true;
         registry.push({ id: mid, title, status: 'active' });
-      } else if (!validationTerminal && activeMilestoneFound) {
-        // No summary and no terminal validation, but another milestone is already active
+      } else if (needsRevalidation && activeMilestoneFound) {
+        // Needs (re-)validation, but another milestone is already active
         registry.push({ id: mid, title, status: 'pending' });
       } else if (!activeMilestoneFound) {
-        // Terminal validation but no summary → completing-milestone
+        // Terminal validation (pass/needs-attention) but no summary → completing-milestone
         activeMilestone = { id: mid, title };
         activeRoadmap = roadmap;
         activeMilestoneFound = true;
@@ -1299,12 +1388,15 @@ export async function _deriveStateImpl(basePath: string): Promise<GSDState> {
     const validationFile = resolveMilestoneFile(basePath, activeMilestone.id, "VALIDATION");
     const validationContent = validationFile ? await cachedLoadFile(validationFile) : null;
     const validationTerminal = validationContent ? isValidationTerminal(validationContent) : false;
+    const verdict = validationContent ? extractVerdict(validationContent) : undefined;
     const sliceProgress = {
       done: activeRoadmap.slices.length,
       total: activeRoadmap.slices.length,
     };
 
-    if (!validationTerminal) {
+    // 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') {
       return {
         activeMilestone,
         activeSlice: null,

package/src/resources/extensions/gsd/templates/context-enhanced.md

@@ -0,0 +1,138 @@
+# {{milestoneId}}: {{milestoneTitle}}
+
+**Gathered:** {{date}}
+**Status:** Ready for planning
+
+## Project Description
+
+{{description}}
+
+## Why This Milestone
+
+{{whatProblemThisSolves_AND_whyNow}}
+
+## Codebase Brief
+
+### Technology Stack
+
+{{techStack}}
+
+### Key Modules
+
+{{keyModules}}
+
+### Patterns in Use
+
+{{patternsInUse}}
+
+## User-Visible Outcome
+
+### When this milestone is complete, the user can:
+
+- {{literalUserActionInRealEnvironment}}
+- {{literalUserActionInRealEnvironment}}
+
+### Entry point / environment
+
+- Entry point: {{CLI command / URL / bot / extension / service / workflow}}
+- Environment: {{local dev / browser / mobile / launchd / CI / production-like}}
+- Live dependencies involved: {{telegram / database / webhook / rpc subprocess / none}}
+
+## Completion Class
+
+- Contract complete means: {{what can be proven by tests / fixtures / artifacts}}
+- Integration complete means: {{what must work across real subsystems}}
+- Operational complete means: {{what must work under real lifecycle conditions, or none}}
+
+## Architectural Decisions
+
+### {{decisionTitle}}
+
+**Decision:** {{decisionStatement}}
+
+**Rationale:** {{rationale}}
+
+**Evidence:** {{evidence}}
+
+**Alternatives Considered:**
+- {{alternative1}} — {{whyNotChosen1}}
+- {{alternative2}} — {{whyNotChosen2}}
+
+---
+
+> Add additional decisions as separate `### Decision Title` blocks following the same structure above.
+
+## Interface Contracts
+
+{{interfaceContracts}}
+
+> Document API boundaries, function signatures, data shapes, or protocol agreements that must be honored. Leave blank or remove if not applicable to this milestone.
+
+## Error Handling Strategy
+
+{{errorHandlingStrategy}}
+
+> Describe the approach for handling failures, edge cases, and error propagation. Include retry policies, fallback behaviors, and user-facing error messages where relevant.
+
+## Final Integrated Acceptance
+
+To call this milestone complete, we must prove:
+
+- {{one real end-to-end scenario}}
+- {{one real end-to-end scenario}}
+- {{what cannot be simulated if this milestone is to be considered truly done}}
+
+## Testing Requirements
+
+{{testingRequirements}}
+
+> Specify test types (unit, integration, e2e), coverage expectations, and any specific test scenarios that must pass.
+
+## Acceptance Criteria
+
+{{acceptanceCriteria}}
+
+> Per-slice acceptance criteria gathered during discussion. Each slice should have clear, testable criteria.
+
+## Risks and Unknowns
+
+- {{riskOrUnknown}} — {{whyItMatters}}
+
+## Existing Codebase / Prior Art
+
+- `{{fileOrModule}}` — {{howItRelates}}
+- `{{fileOrModule}}` — {{howItRelates}}
+
+> See `.gsd/DECISIONS.md` for all architectural and pattern decisions — it is an append-only register; read it during planning, append to it during execution.
+
+## Relevant Requirements
+
+- {{requirementId}} — {{howThisMilestoneAdvancesIt}}
+
+## Scope
+
+### In Scope
+
+- {{inScopeItem}}
+
+### Out of Scope / Non-Goals
+
+- {{outOfScopeItem}}
+
+## Technical Constraints
+
+- {{constraint}}
+
+## Integration Points
+
+- {{systemOrService}} — {{howThisMilestoneInteractsWithIt}}
+
+## Ecosystem Notes
+
+{{ecosystemNotes}}
+
+> Research findings, best practices, known issues, and relevant external documentation discovered during preparation.
+
+## Open Questions
+
+- {{question}} — {{currentThinking}}