gsd-pi 2.25.0 → 2.26.0

package/README.md

@@ -32,6 +32,7 @@ Full documentation is available in the [`docs/`](./docs/) directory:
 - **[Token Optimization](./docs/token-optimization.md)** — profiles, context compression, complexity routing (v2.17)
 - **[Cost Management](./docs/cost-management.md)** — budgets, tracking, projections
 - **[Git Strategy](./docs/git-strategy.md)** — worktree isolation, branching, merge behavior
+- **[Parallel Orchestration](./docs/parallel-orchestration.md)** — run multiple milestones simultaneously
 - **[Working in Teams](./docs/working-in-teams.md)** — unique IDs, shared artifacts
 - **[Skills](./docs/skills.md)** — bundled skills, discovery, custom authoring
 - **[Commands Reference](./docs/commands.md)** — all commands and keyboard shortcuts
@@ -112,9 +113,11 @@ Each slice flows through phases automatically:
 
 ```
 Research → Plan → Execute (per task) → Complete → Reassess Roadmap → Next Slice
+                                                                      ↓ (all slices done)
+                                                              Validate Milestone → Complete Milestone
 ```
 
-**Research** scouts the codebase and relevant docs. **Plan** decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded. **Complete** writes the summary, UAT script, marks the roadmap, and commits. **Reassess** checks if the roadmap still makes sense given what was learned.
+**Research** scouts the codebase and relevant docs. **Plan** decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded. **Complete** writes the summary, UAT script, marks the roadmap, and commits. **Reassess** checks if the roadmap still makes sense given what was learned. **Validate Milestone** runs a reconciliation gate after all slices complete — comparing roadmap success criteria against actual results before sealing the milestone.
 
 ### `/gsd auto` — The Main Event
 
@@ -556,7 +559,13 @@ Anthropic, OpenAI, Google (Gemini), OpenRouter, GitHub Copilot, Amazon Bedrock,
 
 If you have a **Claude Max**, **Codex**, or **GitHub Copilot** subscription, you can use those directly — Pi handles the OAuth flow. No API key needed.
 
-> **Note:** Using OAuth tokens from subscription plans (e.g. Claude Max) outside their native applications may not be explicitly permitted by the provider's Terms of Service. GSD supports API key authentication for all providers as an alternative. Use at your own discretion.
+> **⚠️ Important:** Using OAuth tokens from subscription plans outside their native applications may violate the provider's Terms of Service. In particular:
+>
+> - **Google Gemini** — Using Gemini CLI or Antigravity OAuth tokens in third-party tools has resulted in **Google account suspensions**. This affects your entire Google account, not just the Gemini service. **Use a Gemini API key instead.**
+> - **Claude Max** — Anthropic's ToS may not explicitly permit OAuth use outside Claude's own applications.
+> - **GitHub Copilot** — Usage outside GitHub's own tools may be restricted by your subscription terms.
+>
+> GSD supports API key authentication for all providers as the safe alternative. **We strongly recommend using API keys over OAuth for Google Gemini.**
 
 ### OpenRouter
 

package/dist/headless.js

@@ -137,18 +137,37 @@ function formatProgress(event, verbose) {
 // ---------------------------------------------------------------------------
 // Completion Detection
 // ---------------------------------------------------------------------------
-const TERMINAL_KEYWORDS = ['complete', 'stopped', 'blocked'];
+/**
+ * Detect genuine auto-mode termination notifications.
+ *
+ * Only matches the actual stop signals emitted by stopAuto():
+ *   "Auto-mode stopped..."
+ *   "Step-mode stopped..."
+ *
+ * Does NOT match progress notifications that happen to contain words like
+ * "complete" or "stopped" (e.g., "Override resolved — rewrite-docs completed",
+ * "All slices are complete — nothing to discuss", "Skipped 5+ completed units").
+ *
+ * Blocked detection is separate — checked via isBlockedNotification.
+ */
+const TERMINAL_PREFIXES = ['auto-mode stopped', 'step-mode stopped'];
 const IDLE_TIMEOUT_MS = 15_000;
+// new-milestone is a long-running creative task where the LLM may pause
+// between tool calls (e.g. after mkdir, before writing files). Use a
+// longer idle timeout to avoid killing the session prematurely (#808).
+const NEW_MILESTONE_IDLE_TIMEOUT_MS = 120_000;
 function isTerminalNotification(event) {
     if (event.type !== 'extension_ui_request' || event.method !== 'notify')
         return false;
     const message = String(event.message ?? '').toLowerCase();
-    return TERMINAL_KEYWORDS.some((kw) => message.includes(kw));
+    return TERMINAL_PREFIXES.some((prefix) => message.startsWith(prefix));
 }
 function isBlockedNotification(event) {
     if (event.type !== 'extension_ui_request' || event.method !== 'notify')
         return false;
-    return String(event.message ?? '').toLowerCase().includes('blocked');
+    const message = String(event.message ?? '').toLowerCase();
+    // Blocked notifications come through stopAuto as "Auto-mode stopped (Blocked: ...)"
+    return message.includes('blocked:');
 }
 function isMilestoneReadyNotification(event) {
     if (event.type !== 'extension_ui_request' || event.method !== 'notify')
@@ -285,6 +304,7 @@ export async function runHeadless(options) {
     });
     // Idle timeout — fallback completion detection
     let idleTimer = null;
+    const effectiveIdleTimeout = isNewMilestone ? NEW_MILESTONE_IDLE_TIMEOUT_MS : IDLE_TIMEOUT_MS;
     function resetIdleTimer() {
         if (idleTimer)
             clearTimeout(idleTimer);
@@ -292,7 +312,7 @@ export async function runHeadless(options) {
             idleTimer = setTimeout(() => {
                 completed = true;
                 resolveCompletion();
-            }, IDLE_TIMEOUT_MS);
+            }, effectiveIdleTimeout);
         }
     }
     // Overall timeout

package/dist/resources/extensions/async-jobs/index.ts

@@ -54,6 +54,14 @@ export default function AsyncJobs(pi: ExtensionAPI) {
 					? output.slice(0, maxLen) + "\n\n[... truncated, use await_job for full output]"
 					: output;
 
+				// Deliver as follow-up without triggering a new LLM turn (#875).
+				// When the agent is streaming: the message is queued and picked up
+				// by the agent loop's getFollowUpMessages() after the current turn.
+				// When the agent is idle: the message is appended to context so it's
+				// visible on the next user-initiated prompt. Previously triggerTurn:true
+				// caused spurious autonomous turns — the model would interpret completed
+				// job output as requiring action and cascade into unbounded self-reinforcing
+				// loops (running more commands, spawning more jobs, burning context).
 				pi.sendMessage(
 					{
 						customType: "async_job_result",
@@ -64,7 +72,7 @@ export default function AsyncJobs(pi: ExtensionAPI) {
 						].join("\n"),
 						display: true,
 					},
-					{ deliverAs: "followUp", triggerTurn: true },
+					{ deliverAs: "followUp" },
 				);
 			},
 		});

package/dist/resources/extensions/bg-shell/index.ts

@@ -66,6 +66,7 @@ import { waitForReady } from "./readiness-detector.js";
 import { queryShellEnv, sendAndWait, runOnSession } from "./interaction.js";
 import { formatUptime, formatTokenCount, resolveBgShellPersistenceCwd } from "./utilities.js";
 import { BgManagerOverlay } from "./overlay.js";
+import { toPosixPath } from "../shared/path-display.js";
 
 // ── Re-exports for consumers ───────────────────────────────────────────────
 
@@ -337,7 +338,7 @@ export default function (pi: ExtensionAPI) {
 					text += `  type: ${bg.processType}\n`;
 					text += `  status: ${bg.status}\n`;
 					text += `  command: ${bg.command}\n`;
-					text += `  cwd: ${bg.cwd}`;
+					text += `  cwd: ${toPosixPath(bg.cwd)}`;
 
 					if (bg.group) text += `\n  group: ${bg.group}`;
 					if (bg.readyPort) text += `\n  ready_port: ${bg.readyPort}`;
@@ -694,7 +695,7 @@ export default function (pi: ExtensionAPI) {
 					}
 
 					let text = `Shell environment for ${bg.id} (${bg.label}):\n`;
-					text += `  cwd: ${envResult.cwd}\n`;
+					text += `  cwd: ${toPosixPath(envResult.cwd)}\n`;
 					text += `  shell: ${envResult.shell}\n`;
 
 					const envEntries = Object.entries(envResult.env);

package/dist/resources/extensions/gsd/auto-recovery.ts

@@ -90,6 +90,10 @@ export function resolveExpectedArtifactPath(unitType: string, unitId: string, ba
       const dir = resolveMilestonePath(base, mid);
       return dir ? join(dir, buildMilestoneFileName(mid, "SUMMARY")) : null;
     }
+    case "replan-slice": {
+      const dir = resolveSlicePath(base, mid, sid!);
+      return dir ? join(dir, buildSliceFileName(sid!, "REPLAN")) : null;
+    }
     case "rewrite-docs":
       return null;
     default:
@@ -127,10 +131,9 @@ export function verifyExpectedArtifact(unitType: string, unitId: string, base: s
   }
 
   const absPath = resolveExpectedArtifactPath(unitType, unitId, base);
-  // Unit types with no verifiable artifact always pass (e.g. replan-slice).
-  // For all other types, null means the parent directory is missing on disk
-  // — treat as stale completion state so the key gets evicted (#313).
-  if (!absPath) return unitType === "replan-slice";
+  // For unit types with no verifiable artifact (null path), the parent directory
+  // is missing on disk — treat as stale completion state so the key gets evicted (#313).
+  if (!absPath) return false;
   if (!existsSync(absPath)) return false;
 
   // plan-slice must produce a plan with actual task entries, not just a scaffold.

package/dist/resources/extensions/gsd/auto-worktree.ts

@@ -6,7 +6,7 @@
  * manages create, enter, detect, and teardown for auto-mode worktrees.
  */
 
-import { existsSync, cpSync, readFileSync, writeFileSync, readdirSync, mkdirSync, realpathSync, utimesSync } from "node:fs";
+import { existsSync, cpSync, readFileSync, writeFileSync, readdirSync, mkdirSync, realpathSync, utimesSync, unlinkSync } from "node:fs";
 import { isAbsolute, join, resolve } from "node:path";
 import { copyWorktreeDb, reconcileWorktreeDb, isDbAvailable } from "./gsd-db.js";
 import { execSync, execFileSync } from "node:child_process";
@@ -312,7 +312,8 @@ export function createAutoWorktree(basePath: string, milestoneId: string): strin
 
 /**
  * Copy .gsd/ planning artifacts from source repo to a new worktree.
- * Copies milestones/, DECISIONS.md, REQUIREMENTS.md, PROJECT.md, QUEUE.md.
+ * Copies milestones/, DECISIONS.md, REQUIREMENTS.md, PROJECT.md, QUEUE.md,
+ * STATE.md, KNOWLEDGE.md, and OVERRIDES.md.
  * Skips runtime files (auto.lock, metrics.json, etc.) and the worktrees/ dir.
  * Best-effort — failures are non-fatal since auto-mode can recreate artifacts.
  */
@@ -330,7 +331,7 @@ function copyPlanningArtifacts(srcBase: string, wtPath: string): void {
   }
 
   // Copy top-level planning files
-  for (const file of ["DECISIONS.md", "REQUIREMENTS.md", "PROJECT.md", "QUEUE.md"]) {
+  for (const file of ["DECISIONS.md", "REQUIREMENTS.md", "PROJECT.md", "QUEUE.md", "STATE.md", "KNOWLEDGE.md", "OVERRIDES.md"]) {
     const src = join(srcGsd, file);
     if (existsSync(src)) {
       try {
@@ -559,6 +560,16 @@ export function mergeMilestoneToMain(
   //    when main is already checked out in the project-root worktree, #757)
   const currentBranchAtBase = nativeGetCurrentBranch(originalBasePath_);
   if (currentBranchAtBase !== mainBranch) {
+    // Remove untracked .gsd/ state files that may conflict with the branch
+    // being checked out. These are regenerated by doctor/rebuildState and
+    // are not meaningful in the main working tree — the worktree had the
+    // real state. Without this, `git checkout main` fails with
+    // "Your local changes would be overwritten" (#827).
+    const gsdStateFiles = ["STATE.md", "completed-units.json", "auto.lock"];
+    for (const f of gsdStateFiles) {
+      const p = join(originalBasePath_, ".gsd", f);
+      try { unlinkSync(p); } catch { /* non-fatal — file may not exist */ }
+    }
     nativeCheckoutBranch(originalBasePath_, mainBranch);
   }
 

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

@@ -166,6 +166,41 @@ import { hasPendingCaptures, loadPendingCaptures, countPendingCaptures } from ".
 // auto-mode reads stale state from the project root and re-dispatches
 // already-completed units.
 
+/**
+ * Sync milestone artifacts from project root INTO worktree before deriveState.
+ * Covers the case where the LLM wrote artifacts to the main repo filesystem
+ * (e.g. via absolute paths) but the worktree has stale data. Also deletes
+ * gsd.db in the worktree so it rebuilds from fresh disk state (#853).
+ * Non-fatal — sync failure should never block dispatch.
+ */
+function syncProjectRootToWorktree(projectRoot: string, worktreePath: string, milestoneId: string | null): void {
+  if (!worktreePath || !projectRoot || worktreePath === projectRoot) return;
+  if (!milestoneId) return;
+
+  const prGsd = join(projectRoot, ".gsd");
+  const wtGsd = join(worktreePath, ".gsd");
+
+  // Copy milestone directory from project root to worktree if the project root
+  // has newer artifacts (e.g. slices that don't exist in the worktree yet)
+  try {
+    const srcMilestone = join(prGsd, "milestones", milestoneId);
+    const dstMilestone = join(wtGsd, "milestones", milestoneId);
+    if (existsSync(srcMilestone)) {
+      mkdirSync(dstMilestone, { recursive: true });
+      cpSync(srcMilestone, dstMilestone, { recursive: true, force: false });
+    }
+  } catch { /* non-fatal */ }
+
+  // Delete worktree gsd.db so it rebuilds from the freshly synced files.
+  // Stale DB rows are the root cause of the infinite skip loop (#853).
+  try {
+    const wtDb = join(wtGsd, "gsd.db");
+    if (existsSync(wtDb)) {
+      unlinkSync(wtDb);
+    }
+  } catch { /* non-fatal */ }
+}
+
 /**
  * Sync dispatch-critical .gsd/ state files from worktree to project root.
  * Only runs when inside an auto-worktree (worktreePath differs from projectRoot).
@@ -261,28 +296,30 @@ const MAX_CONSECUTIVE_SKIPS = 3;
 /** Persisted completed-unit keys — survives restarts. Loaded from .gsd/completed-units.json. */
 const completedKeySet = new Set<string>();
 
-/** Resource sync timestamp captured at auto-mode start. If the managed-resources
- *  manifest changes mid-session (e.g. /gsd:update or dev edit + copy-resources),
+/** Resource version captured at auto-mode start. If the managed-resources
+ *  manifest version changes mid-session (e.g. npm update -g gsd-pi),
  *  templates on disk may expect variables the in-memory code doesn't provide.
- *  Detect this and stop gracefully instead of crashing. */
-let resourceSyncedAtOnStart: number | null = null;
+ *  Detect this and stop gracefully instead of crashing.
+ *  Uses gsdVersion (semver) instead of syncedAt (timestamp) so that
+ *  launching a second session doesn't falsely trigger staleness (#804). */
+let resourceVersionOnStart: string | null = null;
 
-function readResourceSyncedAt(): number | null {
+function readResourceVersion(): string | null {
   const agentDir = process.env.GSD_CODING_AGENT_DIR || join(homedir(), ".gsd", "agent");
   const manifestPath = join(agentDir, "managed-resources.json");
   try {
     const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
-    return typeof manifest?.syncedAt === "number" ? manifest.syncedAt : null;
+    return typeof manifest?.gsdVersion === "string" ? manifest.gsdVersion : null;
   } catch {
     return null;
   }
 }
 
 function checkResourcesStale(): string | null {
-  if (resourceSyncedAtOnStart === null) return null;
-  const current = readResourceSyncedAt();
+  if (resourceVersionOnStart === null) return null;
+  const current = readResourceVersion();
   if (current === null) return null;
-  if (current !== resourceSyncedAtOnStart) {
+  if (current !== resourceVersionOnStart) {
     return "GSD resources were updated since this session started. Restart gsd to load the new code.";
   }
   return null;
@@ -942,6 +979,11 @@ export async function startAuto(
     ctx.ui.notify(`Debug logging enabled → ${getDebugLogPath()}`, "info");
   }
 
+  // Invalidate all caches before initial state derivation to ensure we read
+  // fresh disk state. Without this, a stale cache from a prior session (e.g.
+  // after a discussion that wrote new artifacts) may cause deriveState to
+  // return pre-planning when the roadmap already exists (#800).
+  invalidateAllCaches();
   let state = await deriveState(base);
 
   // ── Stale worktree state recovery (#654) ─────────────────────────────────
@@ -1075,7 +1117,7 @@ export async function startAuto(
   restoreHookState(base);
   resetProactiveHealing();
   autoStartTime = Date.now();
-  resourceSyncedAtOnStart = readResourceSyncedAt();
+  resourceVersionOnStart = readResourceVersion();
   completedUnits = [];
   pendingQuickTasks = [];
   currentUnit = null;
@@ -1374,10 +1416,13 @@ export async function handleAgentEnd(
     // fixLevel:"task" ensures doctor only fixes task-level issues (e.g. marking
     // checkboxes). Slice/milestone completion transitions (summary stubs,
     // roadmap [x] marking) are left for the complete-slice dispatch unit.
+    // Exception: after complete-slice itself, use fixLevel:"all" so roadmap
+    // checkboxes get fixed even if complete-slice crashed (#839).
     try {
       const scopeParts = currentUnit.id.split("/").slice(0, 2);
       const doctorScope = scopeParts.join("/");
-      const report = await runGSDDoctor(basePath, { fix: true, scope: doctorScope, fixLevel: "task" });
+      const effectiveFixLevel = currentUnit.type === "complete-slice" ? "all" as const : "task" as const;
+      const report = await runGSDDoctor(basePath, { fix: true, scope: doctorScope, fixLevel: effectiveFixLevel });
       if (report.fixesApplied.length > 0) {
         ctx.ui.notify(`Post-hook: applied ${report.fixesApplied.length} fix(es).`, "info");
       }
@@ -2011,6 +2056,7 @@ async function dispatchNextUnit(
   pi: ExtensionAPI,
 ): Promise<void> {
   if (!active || !cmdCtx) {
+    debugLog(`dispatchNextUnit early return — active=${active}, cmdCtx=${!!cmdCtx}`);
     if (active && !cmdCtx) {
       ctx.ui.notify("Auto-mode session expired. Run /gsd auto to restart.", "info");
     }
@@ -2020,6 +2066,7 @@ async function dispatchNextUnit(
   // Reentrancy guard: allow recursive calls from skip paths (_skipDepth > 0)
   // but block concurrent external calls (watchdog, step wizard, etc.)
   if (_dispatching && _skipDepth === 0) {
+    debugLog("dispatchNextUnit reentrancy guard — another dispatch in progress, bailing");
     return; // Another dispatch is in progress — bail silently
   }
   _dispatching = true;
@@ -2055,7 +2102,7 @@ async function dispatchNextUnit(
   // Lightweight check for critical issues that would cause the next unit
   // to fail or corrupt state. Auto-heals what it can, blocks on the rest.
   try {
-    const healthGate = preDispatchHealthGate(basePath);
+    const healthGate = await preDispatchHealthGate(basePath);
     if (healthGate.fixesApplied.length > 0) {
       ctx.ui.notify(`Pre-dispatch: ${healthGate.fixesApplied.join(", ")}`, "info");
     }
@@ -2068,6 +2115,14 @@ async function dispatchNextUnit(
     // Non-fatal — health gate failure should never block dispatch
   }
 
+  // ── Sync project root artifacts into worktree (#853) ─────────────────
+  // When the LLM writes artifacts to the main repo filesystem instead of
+  // the worktree, the worktree's gsd.db becomes stale. Sync before
+  // deriveState to ensure the worktree has the latest artifacts.
+  if (originalBasePath && basePath !== originalBasePath && currentMilestoneId) {
+    syncProjectRootToWorktree(originalBasePath, basePath, currentMilestoneId);
+  }
+
   const stopDeriveTimer = debugTime("derive-state");
   let state = await deriveState(basePath);
   stopDeriveTimer({
@@ -3751,6 +3806,20 @@ export async function dispatchDirectPhase(
           ctx.ui.notify("Cannot dispatch research-slice: no active slice.", "warning");
           return;
         }
+
+        // When require_slice_discussion is enabled, pause auto-mode before
+        // each new slice so the user can discuss requirements first (#789).
+        const sliceContextFile = resolveSliceFile(base, mid, sid, "CONTEXT");
+        const requireDiscussion = loadEffectiveGSDPreferences()?.preferences?.phases?.require_slice_discussion;
+        if (requireDiscussion && !sliceContextFile) {
+          ctx.ui.notify(
+            `Slice ${sid} requires discussion before planning. Run /gsd discuss to discuss this slice, then /gsd auto to resume.`,
+            "info",
+          );
+          await pauseAuto(ctx, pi);
+          return;
+        }
+
         unitType = "research-slice";
         unitId = `${mid}/${sid}`;
         prompt = await buildResearchSlicePrompt(mid, midTitle, sid, sTitle, base);

package/dist/resources/extensions/gsd/doctor-proactive.ts

@@ -19,6 +19,7 @@ import { join } from "node:path";
 import { gsdRoot, resolveGsdRootFile } from "./paths.js";
 import { readCrashLock, isLockProcessAlive, clearLock } from "./crash-recovery.js";
 import { abortAndReset } from "./git-self-heal.js";
+import { rebuildState } from "./doctor.js";
 
 // ── Health Score Tracking ──────────────────────────────────────────────────
 
@@ -131,7 +132,7 @@ export interface PreDispatchHealthResult {
  *
  * Returns { proceed: true } if dispatch should continue.
  */
-export function preDispatchHealthGate(basePath: string): PreDispatchHealthResult {
+export async function preDispatchHealthGate(basePath: string): Promise<PreDispatchHealthResult> {
   const issues: string[] = [];
   const fixesApplied: string[] = [];
 
@@ -172,17 +173,17 @@ export function preDispatchHealthGate(basePath: string): PreDispatchHealthResult
   }
 
   // ── STATE.md existence check ──
-  // If STATE.md is missing, deriveState will still work but the LLM
-  // may get confused. Rebuild it silently.
+  // If STATE.md is missing, rebuild it now so the next unit has accurate
+  // context. Non-blocking — if the rebuild throws, dispatch continues anyway.
   try {
     const stateFile = resolveGsdRootFile(basePath, "STATE");
     const milestonesDir = join(gsdRoot(basePath), "milestones");
     if (existsSync(milestonesDir) && !existsSync(stateFile)) {
-      issues.push("STATE.md missing — will rebuild after this unit");
-      // Don't block dispatch — rebuilding happens in post-hook
+      await rebuildState(basePath);
+      fixesApplied.push("rebuilt missing STATE.md before dispatch");
     }
   } catch {
-    // Non-fatal
+    // Non-fatal — dispatch continues without STATE.md if rebuild fails
   }
 
   // If we had critical issues that couldn't be auto-healed, block dispatch

package/dist/resources/extensions/gsd/doctor.ts

@@ -1144,8 +1144,31 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
             unitId: taskUnitId,
             message: `Task ${task.id} is marked done but summary is missing`,
             file: relTaskFile(basePath, milestoneId, slice.id, task.id, "SUMMARY"),
-            fixable: false,
+            fixable: true,
           });
+          // Write a stub summary so validate-milestone can proceed.
+          // This prevents infinite skip loops when tasks are marked done
+          // without summaries (#820).
+          if (shouldFix("task_done_missing_summary")) {
+            const stubPath = join(
+              basePath, ".gsd", "milestones", milestoneId, "slices", slice.id, "tasks",
+              `${task.id}-SUMMARY.md`,
+            );
+            const stubContent = [
+              `---`,
+              `status: done`,
+              `result: unknown`,
+              `doctor_generated: true`,
+              `---`,
+              ``,
+              `# ${task.id}: ${task.title || "Unknown"}`,
+              ``,
+              `Summary stub generated by \`/gsd doctor\` — task was marked done but no summary existed.`,
+              ``,
+            ].join("\n");
+            await saveFile(stubPath, stubContent);
+            fixesApplied.push(`created stub summary for ${taskUnitId}`);
+          }
         }
 
         if (!task.done && hasSummary) {

package/dist/resources/extensions/gsd/files.ts

@@ -5,6 +5,7 @@
 
 import { promises as fs } from 'node:fs';
 import { dirname, resolve } from 'node:path';
+import { randomBytes } from 'node:crypto';
 import { resolveMilestoneFile, relMilestoneFile, resolveGsdRootFile } from './paths.js';
 import { milestoneIdSort, findMilestoneIds } from './guided-flow.js';
 
@@ -705,9 +706,19 @@ export async function saveFile(path: string, content: string): Promise<void> {
   const dir = dirname(path);
   await fs.mkdir(dir, { recursive: true });
 
-  const tmpPath = path + '.tmp';
+  // Use a unique temp path per call to avoid collisions when parallel
+  // tool calls target the same file (e.g. concurrent gsd_save_decision).
+  // rename() is atomic on POSIX, so last-writer-wins is correct for
+  // regenerate-from-DB writes.
+  const tmpPath = path + `.tmp.${randomBytes(4).toString("hex")}`;
   await fs.writeFile(tmpPath, content, 'utf-8');
-  await fs.rename(tmpPath, path);
+  try {
+    await fs.rename(tmpPath, path);
+  } catch (err) {
+    // Clean up orphaned temp file on rename failure
+    await fs.unlink(tmpPath).catch(() => {});
+    throw err;
+  }
 }
 
 export function parseRequirementCounts(content: string | null): RequirementCounts {

package/dist/resources/extensions/gsd/guided-flow.ts

@@ -636,9 +636,11 @@ async function showQueueAdd(
   const existingContext = await buildExistingMilestonesContext(basePath, milestoneIds, state);
 
   // ── Determine next milestone ID ─────────────────────────────────────
+  // Note: the LLM will use the gsd_generate_milestone_id tool to get IDs
+  // at creation time, but we still mention the next ID in the preamble
+  // for context about where the sequence is.
   const uniqueEnabled = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
   const nextId = nextMilestoneId(milestoneIds, uniqueEnabled);
-  const nextIdPlus1 = nextMilestoneId([...milestoneIds, nextId], uniqueEnabled);
 
   // ── Build preamble ──────────────────────────────────────────────────
   const activePart = state.activeMilestone
@@ -659,8 +661,6 @@ async function showQueueAdd(
   const queueInlinedTemplates = inlineTemplate("context", "Context");
   const prompt = loadPrompt("queue", {
     preamble,
-    nextId,
-    nextIdPlus1,
     existingMilestonesContext: existingContext,
     inlinedTemplates: queueInlinedTemplates,
     commitInstruction: buildDocsCommitInstruction("docs: queue <milestone list>"),
@@ -959,12 +959,22 @@ export async function showDiscuss(
 
   // Loop: show picker, dispatch discuss, repeat until "not_yet"
   while (true) {
-    const actions = pendingSlices.map((s, i) => ({
-      id: s.id,
-      label: `${s.id}: ${s.title}`,
-      description: state.activeSlice?.id === s.id ? "active slice" : "upcoming",
-      recommended: i === 0,
-    }));
+    const actions = pendingSlices.map((s, i) => {
+      // Check if this slice has already been discussed (CONTEXT file exists)
+      const contextFile = resolveSliceFile(basePath, mid, s.id, "CONTEXT");
+      const discussed = !!contextFile;
+      const statusParts: string[] = [];
+      if (state.activeSlice?.id === s.id) statusParts.push("active");
+      else statusParts.push("upcoming");
+      statusParts.push(discussed ? "discussed ✓" : "not discussed");
+
+      return {
+        id: s.id,
+        label: `${s.id}: ${s.title}`,
+        description: statusParts.join(" · "),
+        recommended: i === 0,
+      };
+    });
 
     const choice = await showNextAction(ctx, {
       title: "GSD — Discuss a slice",

package/dist/resources/extensions/gsd/index.ts

@@ -36,7 +36,7 @@ import { loadPrompt } from "./prompt-loader.js";
 import { deriveState } from "./state.js";
 import { isAutoActive, isAutoPaused, handleAgentEnd, pauseAuto, getAutoDashboardData, markToolStart, markToolEnd } from "./auto.js";
 import { saveActivityLog } from "./activity-log.js";
-import { checkAutoStartAfterDiscuss, getDiscussionMilestoneId } from "./guided-flow.js";
+import { checkAutoStartAfterDiscuss, getDiscussionMilestoneId, findMilestoneIds, nextMilestoneId } from "./guided-flow.js";
 import { GSDDashboardOverlay } from "./dashboard-overlay.js";
 import {
   loadEffectiveGSDPreferences,
@@ -59,6 +59,7 @@ import { homedir } from "node:os";
 import { shortcutDesc } from "../shared/terminal.js";
 import { Text } from "@gsd/pi-tui";
 import { pauseAutoForProviderError } from "./provider-error-pause.js";
+import { toPosixPath } from "../shared/path-display.js";
 
 // ── Agent Instructions ────────────────────────────────────────────────────
 // Lightweight "always follow" files injected into every GSD agent session.
@@ -467,6 +468,46 @@ export default function (pi: ExtensionAPI) {
     },
   });
 
+  // ── gsd_generate_milestone_id — canonical milestone ID generation ──────
+  // The LLM cannot generate random suffixes for unique_milestone_ids on its
+  // own. This tool calls back into the TS code that owns ID generation,
+  // ensuring the preference is always respected and IDs are always valid.
+  pi.registerTool({
+    name: "gsd_generate_milestone_id",
+    label: "Generate Milestone ID",
+    description:
+      "Generate the next milestone ID for a new GSD milestone. " +
+      "Scans existing milestones on disk and respects the unique_milestone_ids preference. " +
+      "Always use this tool when creating a new milestone — never invent milestone IDs manually.",
+    promptSnippet: "Generate a valid milestone ID (respects unique_milestone_ids preference)",
+    promptGuidelines: [
+      "ALWAYS call gsd_generate_milestone_id before creating a new milestone directory or writing milestone files.",
+      "Never invent or hardcode milestone IDs like M001, M002 — always use this tool.",
+      "Call it once per milestone you need to create. For multi-milestone projects, call it once for each milestone in sequence.",
+      "The tool returns the correct format based on project preferences (e.g. M001 or M001-r5jzab).",
+    ],
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, _signal, _onUpdate, _ctx) {
+      try {
+        const basePath = process.cwd();
+        const existingIds = findMilestoneIds(basePath);
+        const uniqueEnabled = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
+        const newId = nextMilestoneId(existingIds, uniqueEnabled);
+        return {
+          content: [{ type: "text" as const, text: newId }],
+          details: { operation: "generate_milestone_id", id: newId, existingCount: existingIds.length, uniqueEnabled },
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text" as const, text: `Error generating milestone ID: ${msg}` }],
+          isError: true,
+          details: { operation: "generate_milestone_id", error: msg },
+        };
+      }
+    },
+  });
+
   // ── session_start: render branded GSD header + load tool keys + remote status ──
   pi.on("session_start", async (_event, ctx) => {
     // Theme access throws in RPC mode (no TUI) — header is decorative, skip it
@@ -608,12 +649,12 @@ export default function (pi: ExtensionAPI) {
         "",
         "[WORKTREE CONTEXT — OVERRIDES CURRENT WORKING DIRECTORY ABOVE]",
         `IMPORTANT: Ignore the "Current working directory" shown earlier in this prompt.`,
-        `The actual current working directory is: ${process.cwd()}`,
+        `The actual current working directory is: ${toPosixPath(process.cwd())}`,
         "",
         `You are working inside a GSD worktree.`,
         `- Worktree name: ${worktreeName}`,
-        `- Worktree path (this is the real cwd): ${process.cwd()}`,
-        `- Main project: ${worktreeMainCwd}`,
+        `- Worktree path (this is the real cwd): ${toPosixPath(process.cwd())}`,
+        `- Main project: ${toPosixPath(worktreeMainCwd)}`,
         `- Branch: worktree/${worktreeName}`,
         "",
         "All file operations, bash commands, and GSD state resolve against the worktree path above.",
@@ -625,12 +666,12 @@ export default function (pi: ExtensionAPI) {
         "",
         "[WORKTREE CONTEXT — OVERRIDES CURRENT WORKING DIRECTORY ABOVE]",
         `IMPORTANT: Ignore the "Current working directory" shown earlier in this prompt.`,
-        `The actual current working directory is: ${process.cwd()}`,
+        `The actual current working directory is: ${toPosixPath(process.cwd())}`,
         "",
         "You are working inside a GSD auto-worktree.",
         `- Milestone worktree: ${autoWorktree.worktreeName}`,
-        `- Worktree path (this is the real cwd): ${process.cwd()}`,
-        `- Main project: ${autoWorktree.originalBase}`,
+        `- Worktree path (this is the real cwd): ${toPosixPath(process.cwd())}`,
+        `- Main project: ${toPosixPath(autoWorktree.originalBase)}`,
         `- Branch: ${autoWorktree.branch}`,
         "",
         "All file operations, bash commands, and GSD state resolve against the worktree path above.",