gsd-pi 2.76.0-dev.fe143342a → 2.77.0-dev.1594b263e

package/src/resources/extensions/gsd/model-router.ts

@@ -109,6 +109,7 @@ export const MODEL_CAPABILITY_TIER: Record<string, ComplexityTier> = {
   "gpt-5.2-codex": "heavy",
   "gpt-5.3-codex": "heavy",
   "gpt-5.4": "heavy",
+  "gpt-5.5": "heavy",
   "o1": "heavy",
   "o3": "heavy",
   "o4-mini": "heavy",
@@ -144,6 +145,7 @@ const MODEL_COST_PER_1K_INPUT: Record<string, number> = {
   "gpt-5.3-codex": 0.005,
   "gpt-5.3-codex-spark": 0.0003,
   "gpt-5.4": 0.005,
+  "gpt-5.5": 0.005,
   "o4-mini": 0.005,
   "o4-mini-deep-research": 0.005,
   "gemini-2.0-flash": 0.0001,
@@ -187,6 +189,10 @@ export const MODEL_CAPABILITY_PROFILES: Record<string, ModelCapabilities> = {
   "gpt-5.3-codex":                { coding: 94, debugging: 91, research: 74, reasoning: 89, speed: 50, longContext: 80, instruction: 89 },
   "gpt-5.3-codex-spark":          { coding: 68, debugging: 58, research: 42, reasoning: 52, speed: 90, longContext: 50, instruction: 74 },
   "gpt-5.4":                      { coding: 95, debugging: 92, research: 88, reasoning: 94, speed: 42, longContext: 88, instruction: 92 },
+  // GPT-5.5 scores are relative to the existing gpt-5.4 profile and backed by
+  // OpenAI's 2026-04-23 published eval deltas across coding, tool use, and long context.
+  // Source: https://openai.com/index/introducing-gpt-5-5/
+  "gpt-5.5":                      { coding: 96, debugging: 93, research: 89, reasoning: 95, speed: 42, longContext: 90, instruction: 93 },
 
   // ── OpenAI o-series (reasoning-first) ──────────────────────────────────────
   "o1":                           { coding: 78, debugging: 82, research: 78, reasoning: 90, speed: 20, longContext: 65, instruction: 82 },
@@ -561,6 +567,23 @@ function bareModelId(modelId: string): string {
   return modelId.includes("/") ? modelId.split("/").pop()! : modelId;
 }
 
+// ─── Provider-specific Tool Limits ─────────────────────────────────────────
+
+/**
+ * Groq enforces a hard limit of 128 tools per request.
+ * Requests exceeding this limit receive a 400 error:
+ * "maximum number of items is 128"
+ * @see https://console.groq.com/docs/tool-use
+ */
+export const GROQ_MAX_TOOLS = 128;
+
+/**
+ * Provider IDs that map to the Groq API backend.
+ * Used to detect Groq at the GSD routing layer where only the provider string
+ * is available (the pi-ai openai-completions adapter is shared across providers).
+ */
+const GROQ_PROVIDER_IDS = new Set(["groq"]);
+
 // ─── Tool Compatibility Filter (ADR-005 Phase 3) ───────────────────────────
 
 /**
@@ -588,10 +611,17 @@ export function isToolCompatibleWithProvider(
 /**
  * Filter a list of tool names to only those compatible with a provider.
  * Used by the routing pipeline to adjust tool sets when switching providers.
+ *
+ * @param toolNames - The full list of active tool names to filter.
+ * @param providerApi - The pi-ai API string (e.g. "openai-completions").
+ * @param provider - Optional provider ID (e.g. "groq"). Used to apply
+ *   provider-specific limits that can't be expressed as API-level capabilities
+ *   (e.g. Groq's 128-tool hard limit on the shared openai-completions adapter).
  */
 export function filterToolsForProvider(
   toolNames: string[],
   providerApi: string,
+  provider?: string,
 ): { compatible: string[]; filtered: string[] } {
   const providerCaps = getProviderCapabilities(providerApi);
 
@@ -611,6 +641,17 @@ export function filterToolsForProvider(
     }
   }
 
+  // Groq enforces a hard limit of 128 tools per request (#4376).
+  // Trim the compatible list to GROQ_MAX_TOOLS and move the excess to filtered.
+  if (provider && GROQ_PROVIDER_IDS.has(provider) && compatible.length > GROQ_MAX_TOOLS) {
+    const trimmed = compatible.splice(GROQ_MAX_TOOLS);
+    filtered.push(...trimmed);
+    console.warn(
+      `[gsd] Groq tool limit: ${compatible.length + trimmed.length} tools active but Groq allows at most ${GROQ_MAX_TOOLS}. ` +
+        `Trimming to the first ${GROQ_MAX_TOOLS} tools. Removed: ${trimmed.join(", ")}`,
+    );
+  }
+
   return { compatible, filtered };
 }
 
@@ -620,11 +661,17 @@ export function filterToolsForProvider(
  *
  * This is a hard filter only — it removes tools that would fail at the
  * provider level. It does NOT remove tools based on soft heuristics.
+ *
+ * @param activeToolNames - The full list of currently active tool names.
+ * @param selectedModelApi - The pi-ai API string for the selected model.
+ * @param provider - Optional provider ID (e.g. "groq") for provider-specific
+ *   limits beyond what the API-level capability profile expresses.
  */
 export function adjustToolSet(
   activeToolNames: string[],
   selectedModelApi: string,
+  provider?: string,
 ): { toolNames: string[]; removedTools: string[] } {
-  const { compatible, filtered } = filterToolsForProvider(activeToolNames, selectedModelApi);
+  const { compatible, filtered } = filterToolsForProvider(activeToolNames, selectedModelApi, provider);
   return { toolNames: compatible, removedTools: filtered };
 }

package/src/resources/extensions/gsd/native-git-bridge.ts

@@ -894,11 +894,37 @@ export function nativeResetPaths(basePath: string, paths: string[]): void {
   }
 }
 
+/**
+ * Read `commit.gpgsign` from the repo config. Returns true only if the value
+ * is the literal string "true". Any other state (unset, false, error) → false.
+ *
+ * Used by nativeCommit to route signing-required commits through the git CLI,
+ * because the libgit2 native path does not invoke configured signers.
+ * (Issue #4980 CRIT-2)
+ */
+function shouldSignCommits(basePath: string): boolean {
+  try {
+    const result = execFileSync("git", ["config", "--get", "commit.gpgsign"], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+      env: GIT_NO_PROMPT_ENV,
+    }).trim();
+    return result === "true";
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Create a commit from the current index.
  * Returns the commit SHA on success, or null if nothing to commit.
  * Native: libgit2 commit create.
- * Fallback: `git commit --no-verify -F -`.
+ * Fallback: `git commit -F -` (runs hooks; honors commit.gpgsign).
+ *
+ * The fallback intentionally does NOT use --no-verify — user pre-commit /
+ * commit-msg / prepare-commit-msg hooks must fire on every GSD-automated
+ * commit. (Issue #4980 CRIT-1)
  */
 export function nativeCommit(
   basePath: string,
@@ -906,7 +932,10 @@ export function nativeCommit(
   options?: { allowEmpty?: boolean; input?: string },
 ): string | null {
   const native = loadNative();
-  if (native) {
+  // libgit2's commit-create does not invoke configured GPG/SSH signers. When
+  // commit.gpgsign=true, route through the git CLI fallback so signing
+  // happens. (Issue #4980 CRIT-2)
+  if (native && !shouldSignCommits(basePath)) {
     try {
       return native.gitCommit(basePath, message, options?.allowEmpty);
     } catch (e) {
@@ -916,9 +945,10 @@ export function nativeCommit(
     }
   }
 
-  // Fallback: use git commit with stdin pipe for safe multi-line messages
+  // Fallback / signed-commit path: use git CLI with stdin pipe for safe
+  // multi-line messages. Hooks run; commit.gpgsign honored.
   try {
-    const args = ["commit", "--no-verify", "-F", "-"];
+    const args = ["commit", "-F", "-"];
     if (options?.allowEmpty) args.push("--allow-empty");
     const result = execFileSync("git", args, {
       cwd: basePath,

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

@@ -4,7 +4,6 @@
 import { execFileSync } from "node:child_process";
 import type { NotificationPreferences } from "./types.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { CmuxClient, emitOsc777Notification, resolveCmuxConfig } from "../cmux/index.js";
 import { sendRemoteNotification } from "../remote-questions/notify.js";
 
 export type NotifyLevel = "info" | "success" | "warning" | "error";
@@ -39,20 +38,33 @@ export function sendDesktopNotification(
 
   if (!shouldSendDesktopNotification(kind, loaded?.notifications)) return;
 
-  const cmux = resolveCmuxConfig(loaded);
-  if (cmux.notifications) {
-    const delivered = CmuxClient.fromPreferences(loaded).notify(title, message);
-    if (delivered) return;
-    emitOsc777Notification(title, message);
-  }
-
-  try {
-    const command = buildDesktopNotificationCommand(process.platform, title, message, level);
-    if (!command) return;
-    execFileSync(command.file, command.args, { timeout: 3000, stdio: "ignore" });
-  } catch {
-    // Non-fatal — desktop notifications are best-effort
-  }
+  // cmux delivery and desktop delivery are independent — if cmux import or
+  // delivery fails, we must still attempt the native desktop notification.
+  const runCmux = async () => {
+    try {
+      const { CmuxClient, emitOsc777Notification, resolveCmuxConfig } = await import("../cmux/index.js");
+      const cmux = resolveCmuxConfig(loaded);
+      if (cmux.notifications) {
+        const delivered = CmuxClient.fromPreferences(loaded).notify(title, message);
+        if (delivered) return true;
+        emitOsc777Notification(title, message);
+      }
+    } catch {
+      // cmux unavailable — fall through to desktop notification
+    }
+    return false;
+  };
+
+  void runCmux().then((deliveredByCmux) => {
+    if (deliveredByCmux) return;
+    try {
+      const command = buildDesktopNotificationCommand(process.platform, title, message, level);
+      if (!command) return;
+      execFileSync(command.file, command.args, { timeout: 3000, stdio: "ignore" });
+    } catch {
+      // Non-fatal — desktop notifications are best-effort
+    }
+  }).catch(() => {});
 }
 
 export function shouldSendDesktopNotification(

package/src/resources/extensions/gsd/pre-execution-checks.ts

@@ -328,6 +328,16 @@ function extractPathFromAnnotation(raw: string): string {
     return backtickMatch[2].trim();
   }
 
+  // Strip leading/trailing double or single quotes wrapping the whole value.
+  // Plan documents sometimes emit `"src/foo.ts"` or `'src/bar.ts'` as input
+  // annotations. Stripping the wrapper allows the inner path to be checked
+  // correctly instead of producing a false-positive "file not found" error
+  // for a literal string with quote characters in it (#3747).
+  const quoteMatch = trimmed.match(/^(["'])([^"']+)\1$/);
+  if (quoteMatch) {
+    return quoteMatch[2].trim();
+  }
+
   const annotatedMatch = trimmed.match(/^(.+?)\s+[—–-]\s+.+$/);
   if (annotatedMatch) {
     const prefix = annotatedMatch[1].trim();
@@ -398,13 +408,19 @@ function containsGlobPattern(candidate: string): boolean {
 
 /**
  * Build a set of files that will be created by tasks up to (but not including) taskIndex.
+ * Also includes outputs of completed tasks at any position — a completed task has already
+ * run and its outputs are available regardless of sequence position or disk state (#4071).
  * All paths are normalized for consistent comparison.
  */
 function getExpectedOutputsUpTo(tasks: TaskRow[], taskIndex: number): Set<string> {
   const outputs = new Set<string>();
-  for (let i = 0; i < taskIndex; i++) {
-    for (const file of tasks[i].expected_output) {
-      outputs.add(normalizeFilePath(file));
+  for (let i = 0; i < tasks.length; i++) {
+    const task = tasks[i];
+    // Include prior tasks (i < taskIndex) OR completed tasks at any position
+    if (i < taskIndex || task.status === "completed") {
+      for (const file of task.expected_output) {
+        outputs.add(normalizeFilePath(file));
+      }
     }
   }
   return outputs;
@@ -491,13 +507,19 @@ export function checkTaskOrdering(
   const results: PreExecutionCheckJSON[] = [];
 
   // Build map: normalized file → task index that creates it
-  const fileCreators = new Map<string, { taskId: string; index: number; originalPath: string }>();
+  const fileCreators = new Map<string, { taskId: string; index: number; originalPath: string; completed: boolean }>();
   for (let i = 0; i < tasks.length; i++) {
     const task = tasks[i];
     for (const file of task.expected_output) {
       const normalizedFile = normalizeFilePath(file);
-      if (!fileCreators.has(normalizedFile)) {
-        fileCreators.set(normalizedFile, { taskId: task.id, index: i, originalPath: file });
+      const existing = fileCreators.get(normalizedFile);
+      if (!existing || (!existing.completed && task.status === "completed")) {
+        fileCreators.set(normalizedFile, {
+          taskId: task.id,
+          index: i,
+          originalPath: file,
+          completed: task.status === "completed",
+        });
       }
     }
   }
@@ -521,7 +543,11 @@ export function checkTaskOrdering(
       const creator = fileCreators.get(normalizedFile);
       const absolutePath = resolve(basePath, normalizedFile);
       const existsOnDisk = existsSync(absolutePath);
-      if (creator && creator.index > i && !existsOnDisk) {
+      // Skip if the creating task has already completed — its output is available
+      // regardless of disk state (e.g. file was a temp artifact cleaned up after
+      // the task ran, or a replan introduced a new earlier-sequence task that
+      // reads this pre-execution output). (#4071)
+      if (creator && creator.index > i && !existsOnDisk && !creator.completed) {
         // Task reads file that is created later — impossible ordering
         results.push({
           category: "file",

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

@@ -392,6 +392,14 @@ export interface GSDPreferences {
     checkpoints?: boolean;
     auto_rollback?: boolean;
     timeout_scale_cap?: number;
+    /**
+     * Glob patterns for files that are always expected side-effects of any task.
+     * Files matching any pattern here are excluded from unexpected-change warnings.
+     * Supports standard glob syntax (e.g. `tracking/history/**`, `*.log`).
+     * Fixes #4385/#4436 — audit-trail snapshots, build artifacts, and other
+     * project-level secondary writes shouldn't require per-task declaration.
+     */
+    file_change_allowlist?: string[];
   };
 
 

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

@@ -987,6 +987,27 @@ export function validatePreferences(preferences: GSDPreferences): {
     if (g.merge_to_main !== undefined) {
       warnings.push("git.merge_to_main is deprecated — milestone-level merge is now always used. Remove this setting.");
     }
+    // #4765 — collapse cadence + milestone resquash
+    if (g.collapse_cadence !== undefined) {
+      const validCadence = new Set(["milestone", "slice"]);
+      if (typeof g.collapse_cadence === "string" && validCadence.has(g.collapse_cadence)) {
+        git.collapse_cadence = g.collapse_cadence as "milestone" | "slice";
+      } else {
+        errors.push("git.collapse_cadence must be one of: milestone, slice");
+      }
+    }
+    if (g.milestone_resquash !== undefined) {
+      if (typeof g.milestone_resquash === "boolean") {
+        git.milestone_resquash = g.milestone_resquash;
+        const cadence = (git.collapse_cadence as string | undefined)
+          ?? (typeof g.collapse_cadence === "string" ? g.collapse_cadence : undefined);
+        if (cadence !== "slice") {
+          warnings.push('git.milestone_resquash is ignored unless git.collapse_cadence is "slice"');
+        }
+      } else {
+        errors.push("git.milestone_resquash must be a boolean");
+      }
+    }
 
     if (Object.keys(git).length > 0) {
       validated.git = git as GitPreferences;

package/src/resources/extensions/gsd/prompt-cache-optimizer.ts

@@ -55,6 +55,10 @@ const SEMI_STATIC_LABELS = new Set([
   "prior-summaries",
   "project-context",
   "overrides",
+  // KNOWLEDGE is milestone-scoped (stable within a session), so it belongs
+  // in the cacheable prefix. See issue #4719.
+  "knowledge",
+  "project-knowledge",
 ]);
 
 /** Labels that change per-task */

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

@@ -10,7 +10,11 @@ Your working directory is `{{workingDirectory}}`. All file reads, writes, and sh
 
 All slices are done. You are closing out the milestone — verifying that the assembled work actually delivers the promised outcome, writing the milestone summary, and updating project state. The milestone summary is the final record. After you finish, the system merges the worktree back to the integration branch. If there are queued milestones, the next one starts its own research → plan → execute cycle from a clean slate — the milestone summary is how it learns what was already built.
 
-All relevant context has been preloaded below — the roadmap, all slice summaries, requirements, decisions, and project context are inlined. Start working immediately without re-reading these files.
+Preloaded context below — the roadmap, compact slice-summary excerpts, requirements, decisions, and project context. **Slice summaries are excerpts, not full files.** They include frontmatter fields, section heads (deviations, known limitations, follow-ups), and short narrative only. When drafting LEARNINGS, the Decision Re-evaluation table, or cross-slice narrative, Read the full slice SUMMARY.md files listed under "On-demand Slice Summaries" — do that selectively as needed, not preemptively.
+
+Start with what the excerpts give you. Read full files when the section heads signal richer context you need.
+
+**On-demand Read ordering:** Complete all slice SUMMARY Reads you need for cross-slice synthesis, the Decision Re-evaluation table, and LEARNINGS **before** calling `gsd_complete_milestone` (step 10). Once that tool runs, the milestone is marked complete in the DB — running out of tool budget between step 10 and the LEARNINGS write (step 12) leaves the milestone committed without its LEARNINGS artifact.
 
 {{inlinedContext}}
 

package/src/resources/extensions/gsd/prompts/discuss-headless.md

@@ -162,7 +162,20 @@ Preserve the specification's exact terminology, emphasis, and specific framing.
 6. For each architectural or pattern decision, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
 7. {{commitInstruction}}
 
-After writing the files, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
+### Ready-phrase pre-condition (NON-BYPASSABLE)
+
+Before emitting the ready phrase, verify in the CURRENT turn that you have:
+
+- [ ] Written `.gsd/PROJECT.md` (step 2)
+- [ ] Written `.gsd/REQUIREMENTS.md` (step 3)
+- [ ] Written `{{contextPath}}` (step 4)
+- [ ] Called `gsd_plan_milestone` (step 5)
+
+If ANY box is unchecked, **STOP**. Do NOT emit the ready phrase. Emit the missing tool calls in this same turn. The system detects missing artifacts and will reject premature ready signals — you will be asked again and retries are capped.
+
+Do not announce the ready phrase as something you are "about to" do. Do not narrate "now writing the files" as a substitute for actually writing them. The ready phrase is a post-write signal, not an intent signal.
+
+After completing steps 1–7 above, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
 
 ### Multi-Milestone
 
@@ -234,7 +247,21 @@ For single-milestone projects, do NOT write this file.
 
 7. {{multiMilestoneCommitInstruction}}
 
-After writing the files, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
+### Ready-phrase pre-condition (NON-BYPASSABLE)
+
+Before emitting the ready phrase, verify in the CURRENT turn that you have:
+
+- [ ] Written `.gsd/PROJECT.md`
+- [ ] Written `.gsd/REQUIREMENTS.md`
+- [ ] Written the primary milestone `CONTEXT.md`
+- [ ] Called `gsd_plan_milestone` for the primary milestone
+- [ ] Written `.gsd/DISCUSSION-MANIFEST.json` with `gates_completed === total`
+
+If ANY box is unchecked, **STOP**. Do NOT emit the ready phrase. Emit the missing tool calls in this same turn. The system detects missing artifacts and will reject premature ready signals — you will be asked again and retries are capped.
+
+Do not announce the ready phrase as something you are "about to" do. Do not narrate "now writing the files" as a substitute for actually writing them. The ready phrase is a post-write signal, not an intent signal.
+
+After completing every step above, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
 
 ## Critical Rules
 

package/src/resources/extensions/gsd/prompts/discuss.md

@@ -339,7 +339,20 @@ These sections are in addition to whatever other context the discussion surfaced
 6. For each architectural or pattern decision made during discussion, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
 7. {{commitInstruction}}
 
-After writing the files, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
+### Ready-phrase pre-condition (NON-BYPASSABLE)
+
+Before emitting the ready phrase, verify in the CURRENT turn that you have:
+
+- [ ] Written `.gsd/PROJECT.md` (step 2)
+- [ ] Written `.gsd/REQUIREMENTS.md` (step 3)
+- [ ] Written `{{contextPath}}` (step 4)
+- [ ] Called `gsd_plan_milestone` (step 5)
+
+If ANY box is unchecked, **STOP**. Do NOT emit the ready phrase. Emit the missing tool calls in this same turn. The system detects missing artifacts and will reject premature ready signals — you will be asked again and retries are capped.
+
+Do not announce the ready phrase as something you are "about to" do. Do not narrate "now writing the files" as a substitute for actually writing them. The ready phrase is a post-write signal, not an intent signal.
+
+After completing steps 1–7 above, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
 
 ### Multi-Milestone
 
@@ -418,6 +431,20 @@ For single-milestone projects, do NOT write this file — it is only for multi-m
 
 7. {{multiMilestoneCommitInstruction}}
 
-After writing the files, say exactly: "Milestone M001 ready." — nothing else. Auto-mode will start automatically.
+### Ready-phrase pre-condition (NON-BYPASSABLE)
+
+Before emitting the ready phrase, verify in the CURRENT turn that you have:
+
+- [ ] Written `.gsd/PROJECT.md` (Phase 1)
+- [ ] Written `.gsd/REQUIREMENTS.md` (Phase 1)
+- [ ] Written primary-milestone `CONTEXT.md` (Phase 2)
+- [ ] Called `gsd_plan_milestone` for the primary milestone (Phase 2)
+- [ ] Written `.gsd/DISCUSSION-MANIFEST.json` with `gates_completed === total` (Phase 3)
+
+If ANY box is unchecked, **STOP**. Do NOT emit the ready phrase. Emit the missing tool calls in this same turn. The system detects missing artifacts and will reject premature ready signals — you will be asked again and retries are capped.
+
+Do not announce the ready phrase as something you are "about to" do. Do not narrate "now writing the files" as a substitute for actually writing them. The ready phrase is a post-write signal, not an intent signal.
+
+After completing all phases above, say exactly: "Milestone M001 ready." — nothing else. Auto-mode will start automatically.
 
 {{inlinedTemplates}}

package/src/resources/extensions/gsd/prompts/doctor-heal.md

@@ -7,9 +7,10 @@ Rules:
 2. Read before edit.
 3. Prefer fixing authoritative artifacts over masking warnings.
 4. For missing summaries or UAT files, generate the real artifact from existing slice/task context when possible — do not leave placeholders if you can reconstruct the real content.
-5. After each repair cluster, verify the relevant invariant directly from disk.
-6. When done, rerun `/gsd doctor {{doctorCommandSuffix}}` mentally by ensuring the remaining issue set for this scope is reduced or cleared.
-7. Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')` — use `gsd_milestone_status` to inspect DB state. Direct access bypasses the WAL connection owned by the engine and can corrupt in-flight writes.
+5. For a missing milestone `CONTEXT.md` when the milestone is already past `pre-planning` (phase is `executing`, `summarizing`, `validating-milestone`, or `completing-milestone`): the artifact was skipped during bootstrap and must be reconstructed before execution can resume. Read `PROJECT.md`, `REQUIREMENTS.md`, the milestone's `ROADMAP.md`, and any slice-level context on disk, then write `.gsd/milestones/<milestone-id>/<milestone-id>-CONTEXT.md` with the real context for the scoped milestone. Do not leave a stub — the plan gate will reject it on the next cycle.
+6. After each repair cluster, verify the relevant invariant directly from disk.
+7. When done, rerun `/gsd doctor {{doctorCommandSuffix}}` mentally by ensuring the remaining issue set for this scope is reduced or cleared.
+8. Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')` — use `gsd_milestone_status` to inspect DB state. Direct access bypasses the WAL connection owned by the engine and can corrupt in-flight writes.
 
 ## Doctor Summary
 
@@ -27,4 +28,4 @@ Then:
 - Repair the unresolved issues in scope
 - Keep changes minimal and targeted
 - If unresolved issues remain outside scope, leave them untouched and mention them briefly
-- End with: "GSD doctor heal complete."
+- End with: "GSD doctor heal complete."

package/src/resources/extensions/gsd/prompts/parallel-research-slices.md

@@ -15,8 +15,11 @@ Dispatch ALL slices simultaneously using the `subagent` tool in **parallel mode*
 1. Call `subagent` with `tasks: [...]` containing one entry per slice below
 2. Wait for ALL subagents to complete
 3. Verify each slice's RESEARCH file was written (check the `.gsd/{{mid}}/` directory)
-4. If any subagent failed to write its RESEARCH file, re-run it individually
-5. Report which slices completed research and which (if any) failed
+4. If a subagent failed to write its RESEARCH file, retry it **once** individually
+5. If it fails a second time, write a partial RESEARCH file for that slice with a `## BLOCKER` section explaining the failure — do NOT retry again
+6. Report which slices completed research and which (if any) needed a blocker note
+
+**Important**: Each failed slice gets exactly one retry. After that, write the blocker and move on. Never retry the same slice more than once.
 
 ## Subagent Prompts
 

package/src/resources/extensions/gsd/prompts/plan-slice.md

@@ -20,9 +20,22 @@ Pay particular attention to **Forward Intelligence** sections — they contain h
 
 You have full tool access. Before decomposing, explore the relevant code to ground your plan in reality.
 
-### Verify Roadmap Assumptions
+### Verify Roadmap Assumptions (JIT Reassessment — ADR-003 §4)
 
-Check prior slice summaries (inlined above as dependency summaries, if present). If prior slices discovered constraints, changed approaches, or flagged fragility, adjust your plan accordingly. The roadmap description may be stale — verify it against the current codebase state.
+Before planning this slice, verify that the roadmap's assumptions still hold given prior slice summaries. Check inlined dependency summaries (below) for discovered constraints, changed approaches, or flagged fragility.
+
+**If the remaining roadmap needs adjustment, modify it before proceeding:**
+
+- If a downstream slice's title/demo/dependencies are now wrong, call `gsd_reassess_roadmap` with the corrected `sliceChanges.modified` entry.
+- If new work surfaced that deserves its own slice, add it via `sliceChanges.added`.
+- If a downstream slice is now redundant or out of scope, remove it via `sliceChanges.removed`.
+- **Bias strongly toward "roadmap is fine."** Most slice completions produce no structural change. Only adjust when there is concrete evidence a downstream slice is wrong — not speculative concern. Over-reassessment is costlier than a later mid-slice replan.
+
+Completed slices are immutable: never modify or remove a slice whose status is complete.
+
+Then proceed with planning this slice against the (possibly updated) roadmap.
+
+The roadmap description may be stale — verify it against the current codebase state.
 
 ### Explore Slice Scope
 

package/src/resources/extensions/gsd/prompts/system.md

@@ -213,6 +213,7 @@ Fix the root cause, not symptoms. When applying a temporary mitigation, label it
 - State uncertainty plainly: "Not sure this handles X - testing it." No performed confidence, no hedging paragraphs.
 - All user-visible narration must be grammatical English. Do not emit compressed planner notes like "Need inspect X" or "Maybe read Y first". If it would look acceptable in a commit comment or standup note, it's acceptable here.
 - When debugging, stay curious. Problems are puzzles. Say what's interesting about the failure before reaching for fixes.
+- After completing a task, give a brief completion summary and present 2-4 contextual next-step options as a numbered list (the last option is always "Other"). This reduces cognitive load by letting the user pick rather than formulate what's next. Omit the numbered list when the response must follow a strict output format (JSON, patches, commit messages, structured data).
 
 Good narration: "Three existing handlers follow a middleware pattern - using that instead of a custom wrapper."
 Good narration: "Tests pass. Running slice-level verification."

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

@@ -14,8 +14,9 @@
  * Manual: /gsd export --html
  */
 
-import { writeFileSync, readFileSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, mkdirSync, existsSync } from 'node:fs';
 import { join, basename } from 'node:path';
+import { atomicWriteSync } from './atomic-write.js';
 import { gsdRoot } from './paths.js';
 import { formatCost, formatTokenCount } from './metrics.js';
 import { formatDateShort, formatDuration } from '../shared/format-utils.js';
@@ -83,7 +84,7 @@ export function loadReportsIndex(basePath: string): ReportsIndex | null {
 function saveReportsIndex(basePath: string, index: ReportsIndex): void {
   const dir = reportsDir(basePath);
   mkdirSync(dir, { recursive: true });
-  writeFileSync(reportsIndexPath(basePath), JSON.stringify(index, null, 2) + '\n', 'utf-8');
+  atomicWriteSync(reportsIndexPath(basePath), JSON.stringify(index, null, 2) + '\n', 'utf-8');
 }
 
 // ─── Write a report snapshot ──────────────────────────────────────────────────
@@ -121,7 +122,7 @@ export function writeReportSnapshot(args: WriteReportSnapshotArgs): string {
   const filename = `${prefix}-${timestamp}.html`;
   const filePath = join(dir, filename);
 
-  writeFileSync(filePath, args.html, 'utf-8');
+  atomicWriteSync(filePath, args.html, 'utf-8');
 
   // Load or init registry
   const existing = loadReportsIndex(args.basePath);
@@ -170,7 +171,7 @@ export function writeReportSnapshot(args: WriteReportSnapshotArgs): string {
 
 export function regenerateHtmlIndex(basePath: string, index: ReportsIndex): void {
   const html = buildIndexHtml(index);
-  writeFileSync(reportsHtmlIndexPath(basePath), html, 'utf-8');
+  atomicWriteSync(reportsHtmlIndexPath(basePath), html, 'utf-8');
 }
 
 function buildIndexHtml(index: ReportsIndex): string {