gsd-pi 2.78.0 → 2.78.1-dev.2ff77b0ce

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

@@ -124,9 +124,9 @@ const STATUS_SECTION_MAP: Array<{ status: string; heading: string }> = [
 /**
  * Generate full REQUIREMENTS.md content from an array of Requirement objects.
  * Groups requirements by status into sections (## Active, ## Validated, etc.),
- * each containing ### RXXX — Description headings with bullet fields.
- * Only emits sections that have content. Appends Traceability table and
- * Coverage Summary at the bottom.
+ * each containing ### RXXX — Description headings with bullet fields. Empty
+ * status sections are emitted too because the deep-mode validator treats their
+ * presence as part of the canonical contract.
  */
 export function generateRequirementsMd(requirements: Requirement[]): string {
   const lines: string[] = [];
@@ -147,12 +147,10 @@ export function generateRequirementsMd(requirements: Requirement[]): string {
   // Emit sections in canonical order
   for (const { status, heading } of STATUS_SECTION_MAP) {
     const reqs = byStatus.get(status);
-    if (!reqs || reqs.length === 0) continue;
-
     lines.push(`## ${heading}`);
     lines.push('');
 
-    for (const r of reqs) {
+    for (const r of reqs ?? []) {
       lines.push(`### ${r.id} — ${r.description || 'Untitled'}`);
 
       // Emit bullet fields — only those with content
@@ -199,6 +197,14 @@ export function generateRequirementsMd(requirements: Requirement[]): string {
   return lines.join('\n') + '\n';
 }
 
+function isRootCanonicalArtifact(opts: SaveArtifactOpts): boolean {
+  if (opts.milestone_id || opts.slice_id || opts.task_id) return false;
+  return (
+    opts.artifact_type === 'PROJECT' ||
+    opts.artifact_type === 'REQUIREMENTS'
+  );
+}
+
 // ─── Next Decision ID ─────────────────────────────────────────────────────
 
 /**
@@ -298,36 +304,49 @@ export async function saveRequirementToDb(
     const db = await import('./gsd-db.js');
 
     // Atomic ID assignment + insert inside a transaction.
-    const id = db.transaction(() => {
+    const txResult = db.transaction(() => {
       const adapter = db._getAdapter();
       if (!adapter) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
 
+      const existingRow = adapter
+        .prepare(
+          `SELECT * FROM requirements
+           WHERE LOWER(TRIM(description)) = LOWER(TRIM(:description))
+             AND LOWER(COALESCE(status, 'active')) = 'active'
+             AND superseded_by IS NULL
+           ORDER BY id
+           LIMIT 1`,
+        )
+        .get({ ':description': fields.description });
       const row = adapter
         .prepare('SELECT MAX(CAST(SUBSTR(id, 2) AS INTEGER)) as max_num FROM requirements')
         .get();
       const maxNum = row ? (row['max_num'] as number | null) : null;
-      const nextId = (maxNum == null || isNaN(maxNum))
+      const nextId = existingRow
+        ? String(existingRow['id'])
+        : (maxNum == null || isNaN(maxNum))
         ? 'R001'
         : `R${String(maxNum + 1).padStart(3, '0')}`;
 
       const requirement: Requirement = {
         id: nextId,
-        class: fields.class,
-        status: fields.status ?? 'active',
+        class: fields.class || (existingRow?.['class'] as string | undefined) || '',
+        status: fields.status ?? (existingRow?.['status'] as string | undefined) ?? 'active',
         description: fields.description,
         why: fields.why,
         source: fields.source,
-        primary_owner: fields.primary_owner ?? '',
-        supporting_slices: fields.supporting_slices ?? '',
-        validation: fields.validation ?? '',
-        notes: fields.notes ?? '',
-        full_content: '',
-        superseded_by: null,
+        primary_owner: fields.primary_owner ?? (existingRow?.['primary_owner'] as string | undefined) ?? '',
+        supporting_slices: fields.supporting_slices ?? (existingRow?.['supporting_slices'] as string | undefined) ?? '',
+        validation: fields.validation ?? (existingRow?.['validation'] as string | undefined) ?? '',
+        notes: fields.notes ?? (existingRow?.['notes'] as string | undefined) ?? '',
+        full_content: (existingRow?.['full_content'] as string | undefined) ?? '',
+        superseded_by: (existingRow?.['superseded_by'] as string | null | undefined) ?? null,
       };
 
       db.upsertRequirement(requirement);
-      return nextId;
+      return { id: nextId };
     });
+    const { id } = txResult;
 
     // Fetch all requirements for full file regeneration
     const adapter = db._getAdapter();
@@ -356,13 +375,7 @@ export async function saveRequirementToDb(
     try {
       await saveFile(filePath, md);
     } catch (diskErr) {
-      logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveRequirementToDb', error: String((diskErr as Error).message) });
-      try {
-        db.deleteRequirementById(id);
-      } catch (rollbackErr) {
-        logError('manifest', 'SPLIT BRAIN: disk write failed AND DB rollback failed — DB has orphaned row', { fn: 'saveRequirementToDb', id, error: String((rollbackErr as Error).message) });
-      }
-      throw diskErr;
+      logWarning('projection', 'REQUIREMENTS.md projection write failed; DB requirement remains committed', { fn: 'saveRequirementToDb', id, error: String((diskErr as Error).message) });
     }
     invalidateStateCache();
     clearPathCache();
@@ -498,13 +511,7 @@ export async function saveDecisionToDb(
     try {
       await saveFile(filePath, md);
     } catch (diskErr) {
-      logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveDecisionToDb', error: String((diskErr as Error).message) });
-      try {
-        db.deleteDecisionById(id);
-      } catch (rollbackErr) {
-        logError('manifest', 'SPLIT BRAIN: disk write failed AND DB rollback failed — DB has orphaned row', { fn: 'saveDecisionToDb', id, error: String((rollbackErr as Error).message) });
-      }
-      throw diskErr;
+      logWarning('projection', 'DECISIONS.md projection write failed; DB decision remains committed', { fn: 'saveDecisionToDb', id, error: String((diskErr as Error).message) });
     }
     // #2661: When a decision defers a slice, update the slice status in the DB
     // so the dispatcher skips it. Without this, STATE.md and DECISIONS.md are
@@ -532,8 +539,8 @@ export async function saveDecisionToDb(
     // ADR-013 dual-write: keep the memory store in sync with every decision
     // persisted via the legacy gsd_save_decision path. Without this, prompts
     // that still call gsd_save_decision (discuss.md, plan-milestone.md,
-    // guided-plan-slice.md, et al. during the deprecation window) would
-    // create decisions rows invisible to memory_query and loadMemoryBlock.
+    // plan-slice.md, et al.) would create decisions rows invisible to
+    // memory_query and loadMemoryBlock.
     // Best-effort — never throw, never roll back the decision on failure.
     try {
       const { createMemory } = await import('./memory-store.js');
@@ -627,34 +634,7 @@ export async function updateRequirementInDb(
   try {
     const db = await import('./gsd-db.js');
 
-    let existing = db.getRequirementById(id);
-
-    // If requirement doesn't exist in DB, seed the entire requirements table
-    // from REQUIREMENTS.md first (#3346). This handles the standard workflow
-    // where requirements are authored in markdown during discussion but never
-    // imported into the database — making gsd_requirement_update always fail
-    // with "not_found" at milestone completion.
-    if (!existing) {
-      const reqFilePath = resolveGsdRootFile(basePath, 'REQUIREMENTS');
-      try {
-        const content = readFileSync(reqFilePath, 'utf-8');
-        const { parseRequirementsSections } = await import('./md-importer.js');
-        const parsed = parseRequirementsSections(content);
-        if (parsed.length > 0) {
-          logWarning('manifest', `Seeding ${parsed.length} requirements from REQUIREMENTS.md into DB (first update triggers import)`, { fn: 'updateRequirementInDb' });
-          for (const req of parsed) {
-            // Only seed if not already in DB (avoid overwriting concurrent inserts)
-            if (!db.getRequirementById(req.id)) {
-              db.upsertRequirement(req);
-            }
-          }
-          // Re-check after seeding
-          existing = db.getRequirementById(id);
-        }
-      } catch {
-        // REQUIREMENTS.md missing or unparseable — fall through to skeleton
-      }
-    }
+    const existing = db.getRequirementById(id);
 
     const base: Requirement = existing ?? {
       id,
@@ -710,11 +690,7 @@ export async function updateRequirementInDb(
     try {
       await saveFile(filePath, md);
     } catch (diskErr) {
-      logError('manifest', 'disk write failed, reverting DB row', { fn: 'updateRequirementInDb', error: String((diskErr as Error).message) });
-      if (existing) {
-        db.upsertRequirement(existing);
-      }
-      throw diskErr;
+      logWarning('projection', 'REQUIREMENTS.md projection write failed; DB requirement update remains committed', { fn: 'updateRequirementInDb', id, error: String((diskErr as Error).message) });
     }
     // Invalidate file-read caches so deriveState() sees the updated markdown.
     // Do NOT clear the artifacts table — we just wrote to it intentionally.
@@ -756,18 +732,28 @@ export async function saveArtifactToDb(
     if (!fullPath.startsWith(gsdDir)) {
       throw new GSDError(GSD_IO_ERROR, `saveArtifactToDb: path escapes .gsd/ directory: ${opts.path}`);
     }
+    let contentToPersist = opts.content;
+    if (opts.artifact_type === 'REQUIREMENTS' && opts.path === 'REQUIREMENTS.md') {
+      const activeRequirements = db.getActiveRequirements();
+      if (activeRequirements.length === 0) {
+        throw new GSDError(GSD_STALE_STATE, 'saveArtifactToDb: REQUIREMENTS final save requires active DB-backed requirements');
+      }
+      contentToPersist = generateRequirementsMd(activeRequirements);
+    }
 
-    // Shrinkage guard: if the file already exists and the new content is
-    // significantly smaller (<50%), preserve the richer file on disk and
-    // store its content in the DB instead of the abbreviated version.
-    let dbContent = opts.content;
+    // Shrinkage guard: if the projection file already exists and the new
+    // content is significantly smaller (<50%), preserve the richer file on
+    // disk, but keep the DB row authoritative with the caller-provided content.
+    // The disk file is a stale projection until the next explicit render.
+    // Root canonical artifacts are exempt because their content is rendered
+    // from canonical DB state, and cleanup/consolidation is often intentionally
+    // much smaller than a malformed accumulated file.
     let skipDiskWrite = false;
-    if (existsSync(fullPath)) {
+    if (!isRootCanonicalArtifact(opts) && existsSync(fullPath)) {
       const existingSize = statSync(fullPath).size;
-      const newSize = Buffer.byteLength(opts.content, 'utf-8');
+      const newSize = Buffer.byteLength(contentToPersist, 'utf-8');
       if (existingSize > 0 && newSize < existingSize * 0.5) {
-        logWarning('manifest', `new content (${newSize}B) is <50% of existing file (${existingSize}B), preserving disk file`, { fn: 'saveArtifactToDb', path: opts.path });
-        dbContent = readFileSync(fullPath, 'utf-8');
+        logWarning('projection', `new content (${newSize}B) is <50% of existing projection (${existingSize}B), preserving disk file while DB remains authoritative`, { fn: 'saveArtifactToDb', path: opts.path });
         skipDiskWrite = true;
       }
     }
@@ -778,17 +764,15 @@ export async function saveArtifactToDb(
       milestone_id: opts.milestone_id ?? null,
       slice_id: opts.slice_id ?? null,
       task_id: opts.task_id ?? null,
-      full_content: dbContent,
+      full_content: contentToPersist,
     });
 
     // Write the file to disk (only if we're not preserving a richer existing file)
     if (!skipDiskWrite) {
       try {
-        await saveFile(fullPath, opts.content);
+        await saveFile(fullPath, contentToPersist);
       } catch (diskErr) {
-        logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveArtifactToDb', error: String((diskErr as Error).message) });
-        db.deleteArtifactByPath(opts.path);
-        throw diskErr;
+        logWarning('projection', 'artifact projection write failed; DB artifact remains committed', { fn: 'saveArtifactToDb', path: opts.path, error: String((diskErr as Error).message) });
       }
     }
     // Invalidate file-read caches so deriveState() sees the updated markdown.

package/src/resources/extensions/gsd/deep-project-setup-policy.ts

@@ -0,0 +1,257 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { GSDPreferences } from "./preferences.js";
+import { atomicWriteSync } from "./atomic-write.js";
+import { clearParseCache } from "./files.js";
+import { gsdRoot, clearPathCache } from "./paths.js";
+import { validateArtifact } from "./schemas/validate.js";
+import { getProjectResearchStatus } from "./project-research-policy.js";
+// NB: planning-depth.ts also imports from this module. The ESM cycle is safe
+// because both sides only consume each other's function exports lazily.
+import { ensureWorkflowPreferencesCaptured } from "./planning-depth.js";
+
+export type DeepProjectSetupStage =
+  | "workflow-preferences"
+  | "project"
+  | "requirements"
+  | "research-decision"
+  | "project-research";
+
+export type DeepProjectSetupState =
+  | { status: "not-applicable"; stage: null; reason: string }
+  | { status: "complete"; stage: null; reason: string }
+  | { status: "pending"; stage: DeepProjectSetupStage; reason: string }
+  | { status: "blocked"; stage: DeepProjectSetupStage; reason: string };
+
+type ResearchDecision = "research" | "skip";
+type ResearchDecisionSource = "workflow-preferences" | "research-decision" | "user";
+
+const EXPLICIT_RESEARCH_SOURCES = new Set<ResearchDecisionSource>([
+  "research-decision",
+  "user",
+]);
+
+function clearCaches(): void {
+  clearPathCache();
+  clearParseCache();
+}
+
+function runtimeDir(basePath: string): string {
+  return join(gsdRoot(basePath), "runtime");
+}
+
+export function researchDecisionPath(basePath: string): string {
+  return join(runtimeDir(basePath), "research-decision.json");
+}
+
+export function isWorkflowPrefsCaptured(basePath: string): boolean {
+  const prefsPath = join(gsdRoot(basePath), "PREFERENCES.md");
+  if (!existsSync(prefsPath)) return false;
+  let content: string;
+  try {
+    content = readFileSync(prefsPath, "utf-8");
+  } catch {
+    return false;
+  }
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return false;
+  return /^workflow_prefs_captured:\s*true\s*$/m.test(match[1]);
+}
+
+export function writeDefaultResearchSkipDecision(
+  basePath: string,
+  reason = "deterministic-default",
+  previousSource?: string,
+): void {
+  const payload: Record<string, unknown> = {
+    decision: "skip",
+    decided_at: new Date().toISOString(),
+    source: "workflow-preferences",
+    reason,
+  };
+  if (previousSource) payload.previous_source = previousSource;
+  atomicWriteSync(researchDecisionPath(basePath), `${JSON.stringify(payload, null, 2)}\n`, "utf-8");
+  clearCaches();
+}
+
+function readDecision(basePath: string): {
+  exists: boolean;
+  valid: boolean;
+  decision?: ResearchDecision;
+  source?: string;
+} {
+  const path = researchDecisionPath(basePath);
+  if (!existsSync(path)) return { exists: false, valid: false };
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown>;
+    const decision = parsed.decision === "research" || parsed.decision === "skip"
+      ? parsed.decision
+      : undefined;
+    return {
+      exists: true,
+      valid: decision !== undefined,
+      decision,
+      source: typeof parsed.source === "string" ? parsed.source : undefined,
+    };
+  } catch {
+    return { exists: true, valid: false };
+  }
+}
+
+function isExplicitResearchDecision(decision: {
+  decision?: ResearchDecision;
+  source?: string;
+}): boolean {
+  return decision.decision === "research" && EXPLICIT_RESEARCH_SOURCES.has(decision.source as ResearchDecisionSource);
+}
+
+/**
+ * True if all post-PREFERENCES setup artifacts (PROJECT.md, REQUIREMENTS.md,
+ * and a valid research-decision marker) are present and validate. Used to
+ * decide whether a missing `workflow_prefs_captured: true` flag is genuine
+ * incomplete setup or post-setup drift that should be self-healed.
+ */
+function downstreamSetupArtifactsValid(root: string, basePath: string): boolean {
+  const projectPath = join(root, "PROJECT.md");
+  if (!existsSync(projectPath) || !validateArtifact(projectPath, "project").ok) return false;
+
+  const requirementsPath = join(root, "REQUIREMENTS.md");
+  if (!existsSync(requirementsPath) || !validateArtifact(requirementsPath, "requirements").ok) return false;
+
+  const marker = readDecision(basePath);
+  if (!marker.exists || !marker.valid) return false;
+
+  return true;
+}
+
+export function resolveDeepProjectSetupState(
+  prefs: GSDPreferences | undefined,
+  basePath: string,
+): DeepProjectSetupState {
+  if (prefs?.planning_depth !== "deep") {
+    return {
+      status: "not-applicable",
+      stage: null,
+      reason: "Deep planning mode is not enabled.",
+    };
+  }
+
+  const root = gsdRoot(basePath);
+  if (!isWorkflowPrefsCaptured(basePath)) {
+    // Self-heal: if all downstream setup artifacts already exist and validate,
+    // the missing `workflow_prefs_captured: true` flag is drift (manual edit,
+    // partial write, merge conflict). Restore it instead of forcing the user
+    // back through setup — the original Bug #2 false-pending root cause.
+    if (downstreamSetupArtifactsValid(root, basePath)) {
+      ensureWorkflowPreferencesCaptured(basePath);
+      // Fall through — checks below will pass since downstreamSetupArtifactsValid
+      // already verified them.
+    } else {
+      return {
+        status: "pending",
+        stage: "workflow-preferences",
+        reason: ".gsd/PREFERENCES.md is missing workflow_prefs_captured: true.",
+      };
+    }
+  }
+
+  const projectPath = join(root, "PROJECT.md");
+  if (!existsSync(projectPath)) {
+    return {
+      status: "pending",
+      stage: "project",
+      reason: ".gsd/PROJECT.md is missing.",
+    };
+  }
+  if (!validateArtifact(projectPath, "project").ok) {
+    return {
+      status: "pending",
+      stage: "project",
+      reason: ".gsd/PROJECT.md is invalid.",
+    };
+  }
+
+  const requirementsPath = join(root, "REQUIREMENTS.md");
+  if (!existsSync(requirementsPath)) {
+    return {
+      status: "pending",
+      stage: "requirements",
+      reason: ".gsd/REQUIREMENTS.md is missing.",
+    };
+  }
+  if (!validateArtifact(requirementsPath, "requirements").ok) {
+    return {
+      status: "pending",
+      stage: "requirements",
+      reason: ".gsd/REQUIREMENTS.md is invalid.",
+    };
+  }
+
+  const marker = readDecision(basePath);
+  if (!marker.exists) {
+    writeDefaultResearchSkipDecision(basePath, "missing-default-repair");
+    return {
+      status: "complete",
+      stage: null,
+      reason: "Project research is skipped by the deterministic default.",
+    };
+  }
+  if (!marker.valid) {
+    writeDefaultResearchSkipDecision(basePath, "malformed-default-repair");
+    return {
+      status: "complete",
+      stage: null,
+      reason: "Malformed project research decision was repaired to the deterministic skip default.",
+    };
+  }
+  if (marker.decision === "skip") {
+    return {
+      status: "complete",
+      stage: null,
+      reason: "Project research was skipped.",
+    };
+  }
+  if (!isExplicitResearchDecision(marker)) {
+    writeDefaultResearchSkipDecision(basePath, "legacy-workflow-research-default", marker.source);
+    return {
+      status: "complete",
+      stage: null,
+      reason: "Legacy workflow-defaulted project research was normalized to skip.",
+    };
+  }
+
+  const researchStatus = getProjectResearchStatus(basePath);
+  if (researchStatus.globalBlocker) {
+    return {
+      status: "blocked",
+      stage: "project-research",
+      reason:
+        "Project research wrote PROJECT-RESEARCH-BLOCKER.md, so no verified research exists. Fix the blocker cause, delete the blocker, and rerun auto.",
+    };
+  }
+  if (researchStatus.allDimensionBlockers) {
+    return {
+      status: "blocked",
+      stage: "project-research",
+      reason:
+        "Project research produced only dimension blocker files, so no usable research exists. Fix the blocker cause, delete the dimension blocker files in `.gsd/research/`, and rerun auto.",
+    };
+  }
+  if (!researchStatus.complete) {
+    return {
+      status: "pending",
+      stage: "project-research",
+      reason: researchStatus.missingDimensions.length > 0
+        ? `Project research is missing dimensions: ${researchStatus.missingDimensions.join(", ")}.`
+        : "Project research has not produced a verified research set.",
+    };
+  }
+
+  return {
+    status: "complete",
+    stage: null,
+    reason: "All deep project setup gates are complete.",
+  };
+}
+

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

@@ -10,8 +10,8 @@ import { existsSync, openSync, readSync, closeSync, readdirSync, readFileSync, s
 import { dirname, join, parse as parsePath } from "node:path";
 import { homedir } from "node:os";
 import { gsdRoot } from "./paths.js";
+import { gsdHome } from "./gsd-home.js";
 
-const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 
 // ─── Types ──────────────────────────────────────────────────────────────────────
 
@@ -720,8 +720,8 @@ function detectVerificationCommands(
  */
 export function hasGlobalSetup(): boolean {
   return (
-    existsSync(join(gsdHome, "PREFERENCES.md")) ||
-    existsSync(join(gsdHome, "preferences.md"))
+    existsSync(join(gsdHome(), "PREFERENCES.md")) ||
+    existsSync(join(gsdHome(), "preferences.md"))
   );
 }
 
@@ -730,18 +730,18 @@ export function hasGlobalSetup(): boolean {
  * Returns true if ~/.gsd/ doesn't exist or has no preferences or auth.
  */
 export function isFirstEverLaunch(): boolean {
-  if (!existsSync(gsdHome)) return true;
+  if (!existsSync(gsdHome())) return true;
 
   // If we have preferences, not first launch
   if (
-    existsSync(join(gsdHome, "PREFERENCES.md")) ||
-    existsSync(join(gsdHome, "preferences.md"))
+    existsSync(join(gsdHome(), "PREFERENCES.md")) ||
+    existsSync(join(gsdHome(), "preferences.md"))
   ) {
     return false;
   }
 
   // If we have auth.json, not first launch (onboarding.ts already ran)
-  if (existsSync(join(gsdHome, "agent", "auth.json"))) return false;
+  if (existsSync(join(gsdHome(), "agent", "auth.json"))) return false;
 
   // Check legacy path too
   const legacyPath = join(homedir(), ".pi", "agent", "gsd-preferences.md");

package/src/resources/extensions/gsd/dispatch-guard.ts

@@ -54,21 +54,16 @@ export function getPriorSliceCompletionBlocker(
     // completion, which is wrong when the SUMMARY is a failure-path report
     // (verification FAILED, blocker placeholder, etc.). Resolve as follows:
     //   1. When DB is available and status is closed → skip (authoritative).
-    //   2. When SUMMARY exists but looks like a failure/blocker report →
-    //      do not short-circuit; fall through to the slice-level check so
-    //      the guard can still block dependents of an active milestone.
-    //   3. Otherwise (SUMMARY without failure markers) → skip. Preserves
-    //      the #1716 contract where a completed milestone with unchecked
-    //      remediation slices is still treated as done.
-    const summaryPath = resolveMilestoneFile(base, mid, "SUMMARY");
+    //   2. When DB is unavailable, legacy SUMMARY.md fallback may skip.
+    //      DB-backed projects must not treat SUMMARY.md as authoritative.
     if (isDbAvailable()) {
       const milestoneRow = getMilestone(mid);
       if (milestoneRow && isClosedStatus(milestoneRow.status)) continue;
-    }
-    if (summaryPath) {
+    } else {
+      const summaryPath = resolveMilestoneFile(base, mid, "SUMMARY");
       let summaryContent: string | null = null;
-      try { summaryContent = readFileSync(summaryPath, "utf-8"); } catch { /* ignore */ }
-      if (!summaryContent || classifyMilestoneSummaryContent(summaryContent) !== "failure") {
+      try { summaryContent = summaryPath ? readFileSync(summaryPath, "utf-8") : null; } catch { /* ignore */ }
+      if (summaryContent && classifyMilestoneSummaryContent(summaryContent) !== "failure") {
         continue;
       }
     }

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -87,7 +87,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   | `git.push_branches`    | `false`      | `true`       |
   | `git.pre_merge_check`  | `false`      | `true`       |
   | `git.merge_strategy`   | `"squash"`   | `"squash"`   |
-  | `git.isolation`        | `"worktree"` | `"worktree"` |
+  | `git.isolation`        | `"none"`     | `"none"`     |
   | `unique_milestone_ids` | `false`      | `true`       |
 
   Quick setup: `/gsd mode` (global) or `/gsd mode project` (project-level).
@@ -126,6 +126,8 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `idle_timeout_minutes`: minutes of inactivity before the supervisor intervenes (default: 10).
   - `hard_timeout_minutes`: minutes before the supervisor forces termination (default: 30).
 
+- `min_request_interval_ms`: number — minimum integer milliseconds between auto-mode LLM request dispatches. Non-integer values are rounded down (e.g., `1000.9 → 1000`). Use this to proactively slow auto-mode on rate-limited providers and reduce 429 errors. Set to `0` to disable. Default: `0` (disabled).
+
 - `git`: configures GSD's git behavior. All fields are optional — omit any to use defaults. Keys:
   - `auto_push`: boolean — automatically push commits to the remote after committing. Default: `false`.
   - `push_branches`: boolean — push the milestone branch to the remote after commits. Default: `false`.
@@ -135,7 +137,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `commit_type`: string — override the conventional commit type prefix. Must be one of: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`, `build`, `style`. Default: inferred from diff content.
   - `main_branch`: string — the primary branch name for new git repos (e.g., `"main"`, `"master"`, `"trunk"`). Also used by `getMainBranch()` as the preferred branch when auto-detection is ambiguous. Default: `"main"`.
   - `merge_strategy`: `"squash"` or `"merge"` — controls how worktree branches are merged back. `"squash"` combines all commits into one; `"merge"` preserves individual commits. Default: `"squash"`.
-  - `isolation`: `"worktree"`, `"branch"`, or `"none"` — controls auto-mode git isolation strategy. `"worktree"` creates a milestone worktree for isolated work; `"branch"` works directly in the project root but creates a milestone branch (useful for submodule-heavy repos); `"none"` works directly on the current branch with no worktree or milestone branch (ideal for step-mode with hot reloads). Default: `"worktree"`.
+  - `isolation`: `"none"`, `"worktree"`, or `"branch"` — controls auto-mode git isolation strategy. `"none"` works directly on the current branch with no worktree or milestone branch (default, ideal for step-mode with hot reloads); `"worktree"` creates a milestone worktree for isolated work; `"branch"` works directly in the project root but creates a milestone branch (useful for submodule-heavy repos). `worktree` requires a committed `HEAD`; in a zero-commit repo, GSD temporarily treats it as `none` until the first commit exists. Default: `"none"`.
   - `manage_gitignore`: boolean — when `false`, GSD will not touch `.gitignore` at all. Useful when your project has a strictly managed `.gitignore` and you don't want GSD adding entries. Default: `true`.
   - `worktree_post_create`: string — script to run after a worktree is created (both auto-mode and manual `/worktree`). Receives `SOURCE_DIR` and `WORKTREE_DIR` as environment variables. Can be absolute or relative to project root. Runs with 30-second timeout. Failure is non-fatal (logged as warning). Default: none.
   - `auto_pr`: boolean — automatically create a GitHub pull request after a milestone branch is merged. Requires `gh` CLI to be installed. Default: `false`.
@@ -157,12 +159,20 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
 
 - `token_profile`: `"budget"`, `"balanced"`, `"quality"`, or `"burn-max"` — coordinates model selection, phase skipping, and context compression. `budget` skips research/reassessment and uses cheaper models; `balanced` (default) skips research/reassessment to reduce token burn; `quality` prefers higher-quality models; `burn-max` keeps full-context defaults, disables downgrade routing, and keeps phase skips off.
 
+- `planning_depth`: `"light"` or `"deep"` — controls project-level discovery before milestone planning. `"light"` is the default milestone discussion flow. `"deep"` runs workflow preferences, project discussion, requirements discussion, a research-decision gate, and optional project research before milestone planning. Enable it with `/gsd new-project --deep`, `/gsd new-milestone --deep`, or by setting `planning_depth: deep` in project-local `.gsd/PREFERENCES.md`. Global `~/.gsd/PREFERENCES.md` does not opt every fresh repo into deep mode. Deep mode writes `.gsd/PROJECT.md`, `.gsd/REQUIREMENTS.md`, `.gsd/runtime/research-decision.json`, and, when research is approved, `.gsd/research/STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, and `PITFALLS.md`.
+
 - `phases`: fine-grained control over which phases run. Usually set by `token_profile`, but can be overridden. Keys:
   - `skip_research`: boolean — skip milestone-level research. Default: `false`.
   - `reassess_after_slice`: boolean — run a dedicated roadmap-reassessment unit after each completed slice. Default: `false` (per ADR-003 §4). The plan-slice agent for the next slice performs JIT reassessment via a prompt preamble at zero additional token cost; a dedicated reassess session is opt-in. Set to `true` (e.g. via the `burn-max` profile) if you want the explicit session.
   - `skip_reassess`: boolean — force-disable roadmap reassessment even if `reassess_after_slice` is enabled. Default: `false`.
   - `skip_slice_research`: boolean — skip per-slice research. Default: `false`.
 
+- `reactive_execution`: controls automatic parallel task dispatch inside a slice. Reactive execution is enabled by default when omitted; set `enabled: false` to opt out. With default-on behavior, GSD only attempts a reactive batch when at least three ready tasks are available and the task-plan IO graph is non-ambiguous. If you set `enabled: true` explicitly, GSD uses the earlier opt-in threshold of two ready tasks. Keys:
+  - `enabled`: boolean — set `false` to force sequential task execution. Default: `true`.
+  - `max_parallel`: number — maximum tasks to dispatch in one batch, range `1`-`8`. Default: `2`.
+  - `isolation_mode`: `"same-tree"` — currently the only supported value.
+  - `subagent_model`: string — optional model override for reactive task subagents. Falls back to the `models.subagent` routing when omitted.
+
 - `remote_questions`: route interactive questions to Slack/Discord for headless auto-mode. Keys:
   - `channel`: `"slack"` or `"discord"` — channel type.
   - `channel_id`: string or number — channel ID.
@@ -193,6 +203,8 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `hooks`: boolean — enable routing hooks. Default: `true`.
   - `capability_routing`: boolean — enable capability-profile scoring for model selection within a tier. Requires `enabled: true`. Default: `false`.
 
+- `disabled_model_providers`: string[] — provider IDs to hide from model selection and routing (for example `["google-gemini-cli"]`). This only affects model availability (`/model`, auto-model selection, routing); it does not disable tool auth flows like `google_search`.
+
 - `uok`: Unified Orchestration Kernel controls. Keys:
   - `enabled`: boolean — enable kernel wrappers and contract observers. Default: `true`.
   - `legacy_fallback.enabled`: boolean — emergency release fallback that forces legacy orchestration behavior even when `uok.enabled` is `true`. Default: `false`.
@@ -292,7 +304,7 @@ mode: solo
 ---
 ```
 
-Equivalent to setting `git.auto_push: true`, `git.push_branches: false`, `git.pre_merge_check: false`, `git.merge_strategy: squash`, `git.isolation: worktree`, `unique_milestone_ids: false`.
+Equivalent to setting `git.auto_push: true`, `git.push_branches: false`, `git.pre_merge_check: false`, `git.merge_strategy: squash`, `git.isolation: none`, `unique_milestone_ids: false`.
 
 **Team — unique IDs, push branches, pre-merge checks:**
 
@@ -303,7 +315,7 @@ mode: team
 ---
 ```
 
-Equivalent to setting `git.auto_push: false`, `git.push_branches: true`, `git.pre_merge_check: true`, `git.merge_strategy: squash`, `git.isolation: worktree`, `unique_milestone_ids: true`.
+Equivalent to setting `git.auto_push: false`, `git.push_branches: true`, `git.pre_merge_check: true`, `git.merge_strategy: squash`, `git.isolation: none`, `unique_milestone_ids: true`.
 
 **Mode with overrides — team mode but with auto-push:**