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

package/src/resources/extensions/gsd/gsd-db.ts

@@ -180,7 +180,7 @@ function openRawDb(path: string): unknown {
   return new Database(path);
 }
 
-const SCHEMA_VERSION = 21;
+export const SCHEMA_VERSION = 22;
 
 function indexExists(db: DbAdapter, name: string): boolean {
   return !!db.prepare(
@@ -559,18 +559,6 @@ function initSchema(db: DbAdapter, fileBacked: boolean): void {
 
     db.exec("CREATE INDEX IF NOT EXISTS idx_memories_active ON memories(superseded_by)");
 
-    // Existing DBs may arrive here before migrateSchema() has added columns
-    // that fresh installs already have. Add only columns needed by bootstrap
-    // indexes so old DBs can open far enough for the normal migration chain.
-    ensureBootstrapIndexColumns(db);
-
-    if (columnExists(db, "memories", "scope")) {
-      db.exec("CREATE INDEX IF NOT EXISTS idx_memories_scope ON memories(scope)");
-    }
-    db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_kind ON memory_sources(kind)");
-    db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_scope ON memory_sources(scope)");
-    db.exec("CREATE INDEX IF NOT EXISTS idx_memory_relations_from ON memory_relations(from_id)");
-    db.exec("CREATE INDEX IF NOT EXISTS idx_memory_relations_to ON memory_relations(to_id)");
     db.exec("CREATE INDEX IF NOT EXISTS idx_replan_history_milestone ON replan_history(milestone_id, created_at)");
 
     // v13 indexes — hot-path dispatch queries
@@ -588,9 +576,6 @@ function initSchema(db: DbAdapter, fileBacked: boolean): void {
     db.exec("CREATE INDEX IF NOT EXISTS idx_turn_git_tx_turn ON turn_git_transactions(trace_id, turn_id)");
     db.exec("CREATE INDEX IF NOT EXISTS idx_audit_events_trace ON audit_events(trace_id, ts)");
     db.exec("CREATE INDEX IF NOT EXISTS idx_audit_events_turn ON audit_events(trace_id, turn_id, ts)");
-    // ADR-011 Phase 2 — also created by the v17 migration; fresh installs
-    // skip migrations so the index must be created here too.
-    db.exec("CREATE INDEX IF NOT EXISTS idx_tasks_escalation_pending ON tasks(milestone_id, slice_id, escalation_pending)");
 
     db.exec(`CREATE VIEW IF NOT EXISTS active_decisions AS SELECT * FROM decisions WHERE superseded_by IS NULL`);
     db.exec(`CREATE VIEW IF NOT EXISTS active_requirements AS SELECT * FROM requirements WHERE superseded_by IS NULL`);
@@ -598,6 +583,17 @@ function initSchema(db: DbAdapter, fileBacked: boolean): void {
 
     const existing = db.prepare("SELECT count(*) as cnt FROM schema_version").get();
     if (existing && (existing["cnt"] as number) === 0) {
+      // Fresh install — all tables are created above with the full current schema,
+      // so it is safe to create all migration-specific indexes here.  For existing
+      // databases these indexes are created inside the individual migration guards
+      // in migrateSchema() after the corresponding columns have been added.
+      db.exec("CREATE INDEX IF NOT EXISTS idx_tasks_escalation_pending ON tasks(milestone_id, slice_id, escalation_pending)");
+      db.exec("CREATE INDEX IF NOT EXISTS idx_memories_scope ON memories(scope)");
+      db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_kind ON memory_sources(kind)");
+      db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_scope ON memory_sources(scope)");
+      db.exec("CREATE INDEX IF NOT EXISTS idx_memory_relations_from ON memory_relations(from_id)");
+      db.exec("CREATE INDEX IF NOT EXISTS idx_memory_relations_to ON memory_relations(to_id)");
+
       db.prepare(
         "INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)",
       ).run({
@@ -674,14 +670,6 @@ function ensureColumn(db: DbAdapter, table: string, column: string, ddl: string)
   if (!columnExists(db, table, column)) db.exec(ddl);
 }
 
-function ensureBootstrapIndexColumns(db: DbAdapter): void {
-  ensureColumn(db, "memories", "scope", `ALTER TABLE memories ADD COLUMN scope TEXT NOT NULL DEFAULT 'project'`);
-  ensureColumn(db, "memories", "tags", `ALTER TABLE memories ADD COLUMN tags TEXT NOT NULL DEFAULT '[]'`);
-  ensureColumn(db, "memory_sources", "scope", `ALTER TABLE memory_sources ADD COLUMN scope TEXT NOT NULL DEFAULT 'project'`);
-  ensureColumn(db, "memory_sources", "tags", `ALTER TABLE memory_sources ADD COLUMN tags TEXT NOT NULL DEFAULT '[]'`);
-  ensureColumn(db, "tasks", "escalation_pending", `ALTER TABLE tasks ADD COLUMN escalation_pending INTEGER NOT NULL DEFAULT 0`);
-}
-
 function migrateSchema(db: DbAdapter): void {
   const row = db.prepare("SELECT MAX(version) as v FROM schema_version").get();
   const currentVersion = row ? (row["v"] as number) : 0;
@@ -949,19 +937,24 @@ function migrateSchema(db: DbAdapter): void {
     }
 
     if (currentVersion < 12) {
+      // NOTE: The original DDL used COALESCE(task_id, '') in the PRIMARY KEY
+      // expression, which is invalid SQLite syntax and causes startup errors on
+      // DBs that migrate through v12. The corrected DDL uses
+      // task_id TEXT NOT NULL DEFAULT '' with a plain column list PK. DBs that
+      // were created with the broken DDL are repaired by the v22 migration below.
       db.exec(`
         CREATE TABLE IF NOT EXISTS quality_gates (
           milestone_id TEXT NOT NULL,
           slice_id TEXT NOT NULL,
           gate_id TEXT NOT NULL,
           scope TEXT NOT NULL DEFAULT 'slice',
-          task_id TEXT DEFAULT NULL,
+          task_id TEXT NOT NULL DEFAULT '',
           status TEXT NOT NULL DEFAULT 'pending',
           verdict TEXT NOT NULL DEFAULT '',
           rationale TEXT NOT NULL DEFAULT '',
           findings TEXT NOT NULL DEFAULT '',
           evaluated_at TEXT DEFAULT NULL,
-          PRIMARY KEY (milestone_id, slice_id, gate_id, COALESCE(task_id, '')),
+          PRIMARY KEY (milestone_id, slice_id, gate_id, task_id),
           FOREIGN KEY (milestone_id, slice_id) REFERENCES slices(milestone_id, id)
         )
       `);
@@ -1119,6 +1112,10 @@ function migrateSchema(db: DbAdapter): void {
           tags TEXT NOT NULL DEFAULT '[]'
         )
       `);
+      // If memory_sources already existed before v18 (created by an earlier
+      // version of initSchema that lacked scope/tags), add the missing columns.
+      ensureColumn(db, "memory_sources", "scope", `ALTER TABLE memory_sources ADD COLUMN scope TEXT NOT NULL DEFAULT 'project'`);
+      ensureColumn(db, "memory_sources", "tags", `ALTER TABLE memory_sources ADD COLUMN tags TEXT NOT NULL DEFAULT '[]'`);
       db.exec("CREATE INDEX IF NOT EXISTS idx_memories_scope ON memories(scope)");
       db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_kind ON memory_sources(kind)");
       db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_scope ON memory_sources(scope)");
@@ -1189,6 +1186,52 @@ function migrateSchema(db: DbAdapter): void {
       });
     }
 
+    if (currentVersion < 22) {
+      // v22: Repair quality_gates tables that were created by the broken v12
+      // migration (which used COALESCE(task_id, '') as a PK expression — invalid
+      // SQLite DDL). Those DBs have task_id nullable (dflt_value NULL, notnull 0).
+      // Rebuild the table with the correct schema, migrating existing rows via
+      // COALESCE so no data is lost.
+      const qgInfo = db.prepare("PRAGMA table_info(quality_gates)").all() as Array<Record<string, unknown>>;
+      const taskIdCol = qgInfo.find((r) => r["name"] === "task_id");
+      const needsRepair = taskIdCol && (taskIdCol["notnull"] === 0 || taskIdCol["notnull"] === "0");
+      if (needsRepair) {
+        db.exec(`
+          CREATE TABLE quality_gates_new (
+            milestone_id TEXT NOT NULL,
+            slice_id TEXT NOT NULL,
+            gate_id TEXT NOT NULL,
+            scope TEXT NOT NULL DEFAULT 'slice',
+            task_id TEXT NOT NULL DEFAULT '',
+            status TEXT NOT NULL DEFAULT 'pending',
+            verdict TEXT NOT NULL DEFAULT '',
+            rationale TEXT NOT NULL DEFAULT '',
+            findings TEXT NOT NULL DEFAULT '',
+            evaluated_at TEXT DEFAULT NULL,
+            PRIMARY KEY (milestone_id, slice_id, gate_id, task_id),
+            FOREIGN KEY (milestone_id, slice_id) REFERENCES slices(milestone_id, id)
+          )
+        `);
+        db.exec(`
+          INSERT OR IGNORE INTO quality_gates_new
+            (milestone_id, slice_id, gate_id, scope, task_id, status, verdict, rationale, findings, evaluated_at)
+          SELECT milestone_id, slice_id, gate_id, scope, COALESCE(task_id, ''), status, verdict, rationale, findings, evaluated_at
+          FROM quality_gates
+        `);
+        db.exec("DROP TABLE quality_gates");
+        db.exec("ALTER TABLE quality_gates_new RENAME TO quality_gates");
+        db.exec("CREATE INDEX IF NOT EXISTS idx_quality_gates_pending ON quality_gates(milestone_id, slice_id, status)");
+      }
+      // Ensure scope column exists on quality_gates and assessments (guard
+      // against DBs that somehow lack it after a partial migration).
+      ensureColumn(db, "quality_gates", "scope", "ALTER TABLE quality_gates ADD COLUMN scope TEXT NOT NULL DEFAULT 'slice'");
+      ensureColumn(db, "assessments", "scope", "ALTER TABLE assessments ADD COLUMN scope TEXT NOT NULL DEFAULT ''");
+      db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
+        ":version": 22,
+        ":applied_at": new Date().toISOString(),
+      });
+    }
+
     db.exec("COMMIT");
   } catch (err) {
     db.exec("ROLLBACK");
@@ -2733,7 +2776,10 @@ export function reconcileWorktreeDb(
           FROM wt.artifacts
         `).run());
 
-        // Merge milestones — worktree may have updated status/planning fields
+        // Merge milestones — worktree may have updated status/planning fields.
+        // Never downgrade status: complete > active > pre-planning (#4372).
+        // A stale worktree may carry an older 'active' status for a milestone
+        // that the main DB has already marked 'complete'; preserve the higher status.
         merged.milestones = countChanges(adapter.prepare(`
           INSERT OR REPLACE INTO milestones (
             id, title, status, depends_on, created_at, completed_at,
@@ -2741,11 +2787,25 @@ export function reconcileWorktreeDb(
             verification_contract, verification_integration, verification_operational, verification_uat,
             definition_of_done, requirement_coverage, boundary_map_markdown
           )
-          SELECT id, title, status, depends_on, created_at, completed_at,
-                 vision, success_criteria, key_risks, proof_strategy,
-                 verification_contract, verification_integration, verification_operational, verification_uat,
-                 definition_of_done, requirement_coverage, boundary_map_markdown
-          FROM wt.milestones
+          SELECT w.id, w.title,
+                 CASE
+                   WHEN m.status IN ('complete', 'done') AND w.status NOT IN ('complete', 'done')
+                   THEN m.status ELSE w.status
+                 END,
+                 w.depends_on,
+                 CASE
+                   WHEN m.status IN ('complete', 'done') AND w.status NOT IN ('complete', 'done')
+                   THEN m.created_at ELSE w.created_at
+                 END,
+                 CASE
+                   WHEN m.status IN ('complete', 'done') AND w.status NOT IN ('complete', 'done')
+                   THEN m.completed_at ELSE w.completed_at
+                 END,
+                 w.vision, w.success_criteria, w.key_risks, w.proof_strategy,
+                 w.verification_contract, w.verification_integration, w.verification_operational, w.verification_uat,
+                 w.definition_of_done, w.requirement_coverage, w.boundary_map_markdown
+          FROM wt.milestones w
+          LEFT JOIN milestones m ON m.id = w.id
         `).run());
 
         // Merge slices — preserve worktree progress but never downgrade completed status (#2558).
@@ -2886,6 +2946,9 @@ export function insertAssessment(entry: {
   fullContent: string;
 }): void {
   if (!currentDb) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+  // Idempotent: PRIMARY KEY is `path`, which is deterministic given (milestone_id, scope) per
+  // the artifact-path resolver. Retrying the same reassess-roadmap silently overwrites the row
+  // instead of accumulating duplicates.
   currentDb.prepare(
     `INSERT OR REPLACE INTO assessments (path, milestone_id, slice_id, task_id, status, scope, full_content, created_at)
      VALUES (:path, :milestone_id, :slice_id, :task_id, :status, :scope, :full_content, :created_at)`,
@@ -3040,7 +3103,7 @@ function rowToGate(row: Record<string, unknown>): GateRow {
     scope: row["scope"] as GateScope,
     task_id: (row["task_id"] as string) ?? "",
     status: row["status"] as GateStatus,
-    verdict: (row["verdict"] as GateVerdict) || "",
+    verdict: row["status"] === "pending" ? null : (row["verdict"] as GateVerdict),
     rationale: (row["rationale"] as string) || "",
     findings: (row["findings"] as string) || "",
     evaluated_at: (row["evaluated_at"] as string) ?? null,
@@ -3144,7 +3207,7 @@ export function getGateResults(milestoneId: string, sliceId: string, scope?: Gat
 export function markAllGatesOmitted(milestoneId: string, sliceId: string): void {
   if (!currentDb) return;
   currentDb.prepare(
-    `UPDATE quality_gates SET status = 'omitted', verdict = 'omitted', evaluated_at = :now
+    `UPDATE quality_gates SET status = 'complete', verdict = 'omitted', evaluated_at = :now
      WHERE milestone_id = :mid AND slice_id = :sid AND status = 'pending'`,
   ).run({
     ":mid": milestoneId,

package/src/resources/extensions/gsd/guided-flow-queue.ts

@@ -18,6 +18,7 @@ import {
   resolveGsdRootFile, relGsdRootFile, relSliceFile,
 } from "./paths.js";
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { atomicWriteSync } from "./atomic-write.js";
 import { nativeAddPaths, nativeCommit } from "./native-git-bridge.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { loadQueueOrder, sortByQueueOrder, saveQueueOrder } from "./queue-order.js";
@@ -435,5 +436,7 @@ function syncProjectMdSequence(
   const separatorLine = lines[tableStart + 1];
   const newTable = [headerLine, separatorLine, ...newRows];
   lines.splice(tableStart, tableEnd - tableStart, ...newTable);
-  writeFileSync(projectPath, lines.join("\n"), "utf-8");
+  // Atomic write: tmp+rename avoids a torn PROJECT.md appearing dirty in
+  // another worktree's working tree during a concurrent /gsd auto merge.
+  atomicWriteSync(projectPath, lines.join("\n"), "utf-8");
 }

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

@@ -13,7 +13,7 @@ import { loadFile, saveFile } from "./files.js";
 import { isDbAvailable, getMilestoneSlices } from "./gsd-db.js";
 import { parseRoadmapSlices } from "./roadmap-slices.js";
 import { loadPrompt, inlineTemplate } from "./prompt-loader.js";
-import { buildSkillActivationBlock } from "./auto-prompts.js";
+import { buildDiscussMilestonePrompt, buildSkillActivationBlock } from "./auto-prompts.js";
 import { deriveState } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { startAutoDetached } from "./auto.js";
@@ -38,8 +38,8 @@ import { isInheritedRepo } from "./repo-identity.js";
 import { ensureGitignore, ensurePreferences, untrackRuntimeFiles } from "./gitignore.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { resolveUokFlags } from "./uok/flags.js";
-import { ensurePlanV2Graph } from "./uok/plan-v2.js";
-import { detectProjectState } from "./detection.js";
+import { ensurePlanV2Graph, isMissingFinalizedContextResult } from "./uok/plan-v2.js";
+import { detectProjectState, hasGsdBootstrapArtifacts } from "./detection.js";
 import { showProjectInit, offerMigration } from "./init-wizard.js";
 import { validateDirectory } from "./validate-directory.js";
 import { showConfirm } from "../shared/tui.js";
@@ -93,24 +93,29 @@ function needsPlanV2Gate(state: GSDState): boolean {
     || state.phase === "completing-milestone";
 }
 
+type PlanV2GateDecision = "pass" | "recover-missing-context" | "block";
+
 function runPlanV2Gate(
   ctx: ExtensionContext,
   basePath: string,
   state: GSDState,
-): boolean {
+): PlanV2GateDecision {
   const prefs = loadEffectiveGSDPreferences()?.preferences;
   const uokFlags = resolveUokFlags(prefs);
-  if (!uokFlags.planV2 || !needsPlanV2Gate(state)) return true;
+  if (!uokFlags.planV2 || !needsPlanV2Gate(state)) return "pass";
   const compiled = ensurePlanV2Graph(basePath, state);
   if (!compiled.ok) {
+    if (isMissingFinalizedContextResult(compiled)) {
+      return "recover-missing-context";
+    }
     const reason = compiled.reason ?? "plan-v2 compilation failed";
     ctx.ui.notify(
-      `Plan gate failed-closed: ${reason}. Complete plan/discuss artifacts before execution.`,
+      `Plan gate failed-closed: ${reason}. Complete plan/discuss artifacts before execution.\n\nIf this keeps happening, try: /gsd doctor heal`,
       "error",
     );
-    return false;
+    return "block";
   }
-  return true;
+  return "pass";
 }
 
 // ─── Commit Instruction Helpers ──────────────────────────────────────────────
@@ -130,8 +135,20 @@ interface PendingAutoStartEntry {
   milestoneId: string; // the milestone being discussed
   step?: boolean; // preserve step mode through discuss → auto transition
   createdAt: number; // timestamp for staleness detection (#3274)
+  // #4573: counter for how many times the LLM emitted the ready phrase
+  // without writing the required artifacts. Cleared on entry delete/recreate.
+  readyRejectCount?: number;
 }
 
+// #4573: cap for how many times we nudge the LLM after a premature ready
+// phrase before giving up and asking the user to re-run /gsd.
+const MAX_READY_REJECTS = 2;
+
+// #4573: matches the canonical ready phrase the discuss prompt asks the LLM
+// to emit. Accepts any M-prefixed milestone ID (three digits + optional
+// suffix) with optional trailing punctuation.
+const READY_PHRASE_RE = /\bMilestone\s+M\d{3}[A-Z0-9-]*\s+ready\.?/i;
+
 const pendingAutoStartMap = new Map<string, PendingAutoStartEntry>();
 
 /**
@@ -279,6 +296,215 @@ export function checkAutoStartAfterDiscuss(): boolean {
   return true;
 }
 
+/**
+ * Extract the concatenated text content from an assistant message, whether it
+ * stores content as a string or as an array of text blocks.
+ */
+function extractAssistantText(msg: any): string {
+  if (!msg) return "";
+  const content = msg.content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const parts: string[] = [];
+  for (const block of content) {
+    if (!block || typeof block !== "object") continue;
+    if (block.type === "text" && typeof block.text === "string") parts.push(block.text);
+  }
+  return parts.join("\n");
+}
+
+/**
+ * Return true if the assistant message contains any tool-use block.
+ */
+function hasToolUse(msg: any): boolean {
+  if (!msg) return false;
+  const content = msg.content;
+  if (!Array.isArray(content)) return false;
+  return content.some((b: any) => b && typeof b === "object" && (b.type === "tool_use" || b.type === "tool-use"));
+}
+
+/**
+ * #4573 — Detect and recover from the "ready phrase without files" failure mode.
+ *
+ * When the LLM emits "Milestone {{id}} ready." but has not written CONTEXT.md
+ * or ROADMAP.md, `checkAutoStartAfterDiscuss()` silently returns false and the
+ * next /gsd invocation loops into the "All milestones complete" warning.
+ *
+ * This function, called from `handleAgentEnd` after `checkAutoStartAfterDiscuss`
+ * returns false, pattern-matches the ready phrase on the last assistant message.
+ * If it fired AND neither CONTEXT.md nor ROADMAP.md exists, it:
+ *   1. Notifies the user that the signal was rejected.
+ *   2. Injects a system message via `pi.sendMessage(..., {triggerTurn:true})`
+ *      telling the LLM the signal was premature and to emit the writes now.
+ *   3. Caps at `MAX_READY_REJECTS` per-entry; beyond that, gives up and asks
+ *      the user to re-run /gsd.
+ *
+ * Returns true when a nudge (or give-up) was emitted, signaling the caller to
+ * skip `resolveAgentEnd`.
+ */
+export function maybeHandleReadyPhraseWithoutFiles(event: { messages: any[] }): boolean {
+  const entry = _getPendingAutoStart();
+  if (!entry) return false;
+  const { ctx, pi, basePath, milestoneId } = entry;
+
+  // Gate: last assistant message must contain the ready phrase
+  const lastMsg = event.messages[event.messages.length - 1];
+  const text = extractAssistantText(lastMsg);
+  if (!READY_PHRASE_RE.test(text)) return false;
+
+  // Gate: artifacts must still be missing — if they exist, the happy path
+  // already fired and we have nothing to do.
+  const contextFile = resolveMilestoneFile(basePath, milestoneId, "CONTEXT");
+  const roadmapFile = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+  if (contextFile || roadmapFile) return false;
+
+  entry.readyRejectCount = (entry.readyRejectCount ?? 0) + 1;
+
+  if (entry.readyRejectCount > MAX_READY_REJECTS) {
+    // Give up: clear state and tell the user to re-run /gsd. Avoids an
+    // infinite nudge loop when the LLM never produces the writes.
+    pendingAutoStartMap.delete(basePath);
+    ctx.ui.notify(
+      `Milestone ${milestoneId}: LLM signaled "ready" ${entry.readyRejectCount} times without writing files. ` +
+      `Stopping auto-nudge. Run /gsd to try again.`,
+      "error",
+    );
+    return true;
+  }
+
+  ctx.ui.notify(
+    `Milestone ${milestoneId}: "ready" signal rejected — CONTEXT.md and ROADMAP.md are missing. Asking the LLM to complete the writes.`,
+    "warning",
+  );
+
+  const nudge =
+    `You emitted "Milestone ${milestoneId} ready." but neither ` +
+    `.gsd/milestones/${milestoneId}/${milestoneId}-CONTEXT.md nor ` +
+    `.gsd/milestones/${milestoneId}/${milestoneId}-ROADMAP.md exists on disk. ` +
+    `The ready phrase is a POST-WRITE signal and has been rejected. ` +
+    `In this turn: (1) write PROJECT.md, REQUIREMENTS.md, and the milestone ` +
+    `CONTEXT.md, (2) call gsd_plan_milestone, then (3) emit the ready phrase. ` +
+    `Do not describe these steps — execute them as tool calls. ` +
+    `This is retry ${entry.readyRejectCount}/${MAX_READY_REJECTS}; further ` +
+    `premature signals will clear the session.`;
+
+  try {
+    pi.sendMessage(
+      { customType: "gsd-ready-no-files", content: nudge, display: false },
+      { triggerTurn: true },
+    );
+  } catch (e) {
+    logWarning("guided", `ready-phrase nudge sendMessage failed: ${(e as Error).message}`);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * #4573 — Detect and recover from the "announces tool, never calls it" stall.
+ *
+ * The LLM emits text like "I'll now write the CONTEXT.md file" but the turn
+ * ends with zero tool-use blocks. The harness has no post-turn tool-call
+ * validation, so the unit promise resolves and the user sees a stalled state.
+ *
+ * This function, called from `handleAgentEnd`, inspects the last assistant
+ * message. If ALL of the following are true, it injects a recovery message:
+ *   - Text-only (no tool-use blocks)
+ *   - Contains a commit-intent phrase ("I'll write", "I'll call", etc.)
+ *   - Auto-mode is active OR a discussion autostart is pending
+ *   - `emptyTurnRetryCount` is under the cap
+ *
+ * Per-handler state is held on the `PendingAutoStartEntry` when present, and
+ * on a module-level map otherwise. The counter resets on any successful
+ * tool-use turn via `resetEmptyTurnCounter`.
+ */
+const emptyTurnCounterByBase = new Map<string, number>();
+const MAX_EMPTY_TURN_RETRIES = 2;
+
+// Phrases that indicate the LLM is about to do something but has not yet.
+// Kept tight to avoid flagging legitimate narration like "I'll wait for your answer."
+const COMMIT_INTENT_RE =
+  /\b(?:I['’]ll|I will|Next,? I['’]ll|Now I['’]ll|Let me|I['’]m going to|I am going to)\s+(?:now\s+)?(?:write|create|call|invoke|update|add|make|run|execute|generate|produce|emit|compose|implement|save|apply|commit)\b/i;
+
+/**
+ * Reset the empty-turn counter for a basePath after a successful tool-use turn.
+ * Called from handleAgentEnd when the last message contains tool_use blocks.
+ */
+export function resetEmptyTurnCounter(basePath?: string): void {
+  if (basePath) emptyTurnCounterByBase.delete(basePath);
+  else emptyTurnCounterByBase.clear();
+}
+
+export function maybeHandleEmptyIntentTurn(
+  event: { messages: any[] },
+  isAuto: boolean,
+): boolean {
+  // Gate: only fire when there is system-driven work in flight. Interactive
+  // /gsd discuss (user-driven) produces legitimate text-only turns.
+  if (!isAuto && pendingAutoStartMap.size === 0) return false;
+
+  const lastMsg = event.messages[event.messages.length - 1];
+  if (!lastMsg) return false;
+  if (hasToolUse(lastMsg)) return false;
+
+  const text = extractAssistantText(lastMsg).trim();
+  if (!text) return false;
+
+  // Skip if the LLM is emitting the ready phrase — that is the ready-no-files
+  // path, handled by maybeHandleReadyPhraseWithoutFiles.
+  if (READY_PHRASE_RE.test(text)) return false;
+
+  // Skip if the LLM is clearly handing back to the user. Keep the heuristic
+  // tight: a trailing question mark on the last non-empty line is the common
+  // signal for "I asked the user a question and stopped."
+  const lines = text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  const lastLine = lines[lines.length - 1] ?? "";
+  if (lastLine.endsWith("?")) return false;
+
+  // Must contain a commit-intent phrase — this is the stall we care about.
+  if (!COMMIT_INTENT_RE.test(text)) return false;
+
+  // Resolve the target basePath + pi for injection. Prefer the pending
+  // autostart entry (discuss flow); otherwise we cannot inject.
+  const entry = _getPendingAutoStart();
+  if (!entry) return false;
+  const { ctx, pi, basePath } = entry;
+
+  const count = (emptyTurnCounterByBase.get(basePath) ?? 0) + 1;
+  emptyTurnCounterByBase.set(basePath, count);
+
+  if (count > MAX_EMPTY_TURN_RETRIES) {
+    ctx.ui.notify(
+      `Empty-turn recovery: LLM announced intent ${count} times without calling any tool. ` +
+      `Stopping auto-nudge.`,
+      "error",
+    );
+    return false; // let the normal flow resolve/pause the unit
+  }
+
+  ctx.ui.notify(
+    `Empty-turn detected: LLM announced intent but called no tool. Prompting it to execute.`,
+    "info",
+  );
+
+  const nudge =
+    `Your last turn announced an action (e.g. "I'll write…" or "Let me call…") ` +
+    `but contained no tool call. The system records zero tool-use blocks for ` +
+    `that turn. Execute the announced action NOW as a tool call in this turn. ` +
+    `Do not describe it again. Retry ${count}/${MAX_EMPTY_TURN_RETRIES}.`;
+
+  try {
+    pi.sendMessage(
+      { customType: "gsd-empty-turn-recovery", content: nudge, display: false },
+      { triggerTurn: true },
+    );
+  } catch (e) {
+    logWarning("guided", `empty-turn nudge sendMessage failed: ${(e as Error).message}`);
+    return false;
+  }
+  return true;
+}
+
 /**
  * Extract milestone IDs from PROJECT.md milestone sequence table.
  * Looks for rows like "| M001 | Name | Status |" and extracts the ID column.
@@ -604,8 +830,13 @@ export async function showHeadlessMilestoneCreation(
   // Set pending auto start (auto-mode triggers on "Milestone X ready." via checkAutoStartAfterDiscuss)
   pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, createdAt: Date.now() });
 
-  // Dispatch — headless milestone creation is a planning activity
-  await dispatchWorkflow(pi, prompt, "gsd-run", ctx, "plan-milestone");
+  // Dispatch as discuss-milestone. The LLM writes PROJECT.md, REQUIREMENTS.md,
+  // and CONTEXT.md, then calls gsd_plan_milestone — this is semantically the
+  // discuss path, just non-interactive. Using "plan-milestone" here caused
+  // model/tool routing to skip discuss-flow tool scoping and
+  // `checkAutoStartAfterDiscuss` guardrails that rely on the
+  // "discuss-"-prefixed unitType.
+  await dispatchWorkflow(pi, prompt, "gsd-run", ctx, "discuss-milestone");
 }
 
 
@@ -1260,9 +1491,7 @@ export async function showSmartEntry(
   // A zombie .gsd/ state (symlink exists but missing PREFERENCES.md and
   // milestones/) must trigger the init wizard, not skip it (#2942).
   const gsdPath = gsdRoot(basePath);
-  const hasBootstrapArtifacts = existsSync(gsdPath)
-    && (existsSync(join(gsdPath, "PREFERENCES.md"))
-        || existsSync(join(gsdPath, "milestones")));
+  const hasBootstrapArtifacts = hasGsdBootstrapArtifacts(gsdPath);
 
   if (!hasBootstrapArtifacts) {
     const detection = detectProjectState(basePath);
@@ -1352,7 +1581,8 @@ export async function showSmartEntry(
     logWarning("guided", `STATE.md rebuild failed: ${(err as Error).message}`);
   }
 
-  if (!runPlanV2Gate(ctx, basePath, state)) return;
+  const planV2GateDecision = runPlanV2Gate(ctx, basePath, state);
+  if (planV2GateDecision === "block") return;
 
   if (!state.activeMilestone?.id) {
     // Guard: if a discuss session is already in flight, don't re-inject the prompt.
@@ -1440,6 +1670,23 @@ export async function showSmartEntry(
   const milestoneId = state.activeMilestone.id;
   const milestoneTitle = state.activeMilestone.title;
 
+  if (planV2GateDecision === "recover-missing-context") {
+    pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId, step: stepMode, createdAt: Date.now() });
+    await dispatchWorkflow(
+      pi,
+      await buildDiscussMilestonePrompt(
+        milestoneId,
+        milestoneTitle,
+        basePath,
+        getStructuredQuestionsAvailability(pi, ctx),
+      ),
+      "gsd-discuss",
+      ctx,
+      "discuss-milestone",
+    );
+    return;
+  }
+
   // ── All milestones complete → New milestone ──────────────────────────
   if (state.phase === "complete") {
     const choice = await showNextAction(ctx, {

package/src/resources/extensions/gsd/health-widget.ts

@@ -108,6 +108,7 @@ export function initHealthWidget(ctx: ExtensionContext): void {
     let data = initialData;
     let cachedLines: string[] | undefined;
     let refreshInFlight = false;
+    let isDisposed = false;
 
     const refresh = async () => {
       if (refreshInFlight) return;
@@ -115,7 +116,7 @@ export function initHealthWidget(ctx: ExtensionContext): void {
       try {
         data = loadHealthWidgetData(basePath);
         cachedLines = undefined;
-        _tui.requestRender();
+        if (!isDisposed) _tui.requestRender();
       } catch { /* non-fatal */ } finally {
         refreshInFlight = false;
       }
@@ -140,6 +141,7 @@ export function initHealthWidget(ctx: ExtensionContext): void {
       },
       invalidate(): void { cachedLines = undefined; cachedWidth = undefined; },
       dispose(): void {
+        isDisposed = true;
         clearInterval(refreshTimer);
       },
     };