gsd-pi 2.78.1-dev.0fdacd524 → 2.78.1-dev.2ff77b0ce

package/dist/resources/extensions/gsd/commands-scan.js

@@ -16,6 +16,7 @@
 import { existsSync, mkdirSync } from "node:fs";
 import { join, relative } from "node:path";
 import { loadPrompt } from "./prompt-loader.js";
+import { currentDirectoryRoot } from "./commands/context.js";
 // ─── Constants ────────────────────────────────────────────────────────────────
 export const DEFAULT_FOCUS = "tech+arch";
 export const VALID_FOCUS_AREAS = ["tech", "arch", "quality", "concerns", "tech+arch"];
@@ -66,7 +67,7 @@ export function checkExistingDocuments(paths) {
 }
 // ─── Command handler ──────────────────────────────────────────────────────────
 export async function handleScan(args, ctx, pi) {
-    const basePath = process.cwd();
+    const basePath = currentDirectoryRoot();
     const { focus } = parseScanArgs(args);
     const outputDir = join(basePath, ".gsd", "codebase");
     const outputPaths = buildScanOutputPaths(focus, basePath);

package/dist/resources/extensions/gsd/commands-ship.js

@@ -6,11 +6,14 @@
  */
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { deriveState } from "./state.js";
 import { resolveMilestoneFile, resolveSlicePath, resolveSliceFile } from "./paths.js";
 import { getLedger, getProjectTotals, aggregateByModel, formatCost, formatTokenCount, loadLedgerFromDisk } from "./metrics.js";
 import { nativeGetCurrentBranch, nativeDetectMainBranch } from "./native-git-bridge.js";
 import { formatDuration } from "../shared/format-utils.js";
+import { parseEvalReviewFrontmatter } from "./eval-review-schema.js";
+import { currentDirectoryRoot } from "./commands/context.js";
 function git(basePath, args) {
     return execFileSync("git", args, { cwd: basePath, encoding: "utf-8" }).trim();
 }
@@ -68,6 +71,48 @@ function collectSliceSummaries(basePath, milestoneId) {
     }
     return summaries;
 }
+/**
+ * Inspect a single slice's EVAL-REVIEW.md without throwing.
+ *
+ * One async file read attempt — no `existsSync` precheck (defense against the
+ * TOCTOU race that bit prior implementations). ENOENT is treated as `absent`.
+ * Other read errors
+ * propagate so callers can decide how to handle them; the {@link handleShip}
+ * caller wraps them in a non-blocking warning rather than aborting the
+ * ship.
+ *
+ * @param basePath - project root.
+ * @param milestoneId - active milestone ID.
+ * @param sliceId - slice ID to check.
+ * @returns A {@link SliceEvalCheck} discriminating on the four valid states.
+ * @throws Forwarded `readFile` errors other than `ENOENT`.
+ */
+export async function checkSliceEvalReview(basePath, milestoneId, sliceId) {
+    const path = resolveSliceFile(basePath, milestoneId, sliceId, "EVAL-REVIEW");
+    if (!path) {
+        return { sliceId, kind: "absent" };
+    }
+    let raw;
+    try {
+        raw = await readFile(path, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return { sliceId, kind: "absent" };
+        }
+        throw err;
+    }
+    const parsed = parseEvalReviewFrontmatter(raw);
+    if (!parsed.ok) {
+        return { sliceId, kind: "malformed", error: parsed.error, pointer: parsed.pointer };
+    }
+    return {
+        sliceId,
+        kind: "ok",
+        verdict: parsed.data.verdict,
+        overall_score: parsed.data.overall_score,
+    };
+}
 function generatePRContent(basePath, milestoneId, milestoneTitle) {
     const title = `feat: ${milestoneTitle || milestoneId}`;
     const sections = [];
@@ -131,7 +176,7 @@ function generatePRContent(basePath, milestoneId, milestoneTitle) {
     return { title, body: sections.join("\n") };
 }
 export async function handleShip(args, ctx, _pi) {
-    const basePath = process.cwd();
+    const basePath = currentDirectoryRoot();
     const dryRun = args.includes("--dry-run");
     const draft = args.includes("--draft");
     const force = args.includes("--force");
@@ -154,6 +199,27 @@ export async function handleShip(args, ctx, _pi) {
         ctx.ui.notify(`Milestone ${milestoneId} may not be complete (phase: ${state.phase}). Use --force to ship anyway.`, "warning");
         return;
     }
+    // 2b. Pre-ship soft warning on EVAL-REVIEW.md status (non-blocking).
+    for (const sliceId of listSliceIds(basePath, milestoneId)) {
+        let result;
+        try {
+            result = await checkSliceEvalReview(basePath, milestoneId, sliceId);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            ctx.ui.notify(`Could not read EVAL-REVIEW.md for ${sliceId}: ${msg}`, "warning");
+            continue;
+        }
+        if (result.kind === "absent") {
+            ctx.ui.notify(`Slice ${sliceId} has no EVAL-REVIEW.md — consider /gsd eval-review ${sliceId} (non-blocking).`, "warning");
+        }
+        else if (result.kind === "malformed") {
+            ctx.ui.notify(`Slice ${sliceId} EVAL-REVIEW.md frontmatter invalid at ${result.pointer}: ${result.error} (non-blocking).`, "warning");
+        }
+        else if (result.verdict === "NOT_IMPLEMENTED") {
+            ctx.ui.notify(`Slice ${sliceId} eval verdict NOT_IMPLEMENTED (overall ${result.overall_score}/100) — shipping anyway, but the eval gap is unresolved.`, "warning");
+        }
+    }
     // 3. Generate PR content
     const { title, body } = generatePRContent(basePath, milestoneId, milestoneTitle);
     // 4. Dry-run — just show the PR content

package/dist/resources/extensions/gsd/commands-workflow-templates.js

@@ -13,6 +13,7 @@ import { createGitService, runGit } from "./git-service.js";
 import { isAutoActive, isAutoPaused } from "./auto.js";
 import { getErrorMessage } from "./error-utils.js";
 import { resolvePlugin } from "./workflow-plugins.js";
+import { currentDirectoryRoot } from "./commands/context.js";
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 /**
  * Generate a URL-friendly slug from text.
@@ -142,7 +143,7 @@ export async function handleStart(args, ctx, pi) {
     // ─── Resume detection ───────────────────────────────────────────────────
     // /gsd start --resume or /gsd start resume → resume in-progress workflow
     if (trimmed === "--resume" || trimmed === "resume") {
-        const basePath = process.cwd();
+        const basePath = currentDirectoryRoot();
         const inProgress = findInProgressWorkflows(basePath);
         if (inProgress.length === 0) {
             ctx.ui.notify("No in-progress workflows found.", "info");
@@ -181,7 +182,7 @@ export async function handleStart(args, ctx, pi) {
     }
     // Show in-progress workflows when /gsd start is called with no args
     if (!trimmed) {
-        const basePath = process.cwd();
+        const basePath = currentDirectoryRoot();
         const inProgress = findInProgressWorkflows(basePath);
         if (inProgress.length > 0) {
             const wf = inProgress[0];
@@ -256,7 +257,7 @@ export async function handleStart(args, ctx, pi) {
     // ─── Resolved template ───────────────────────────────────────────────────
     const templateId = match.id;
     const template = match.template;
-    const basePath = process.cwd();
+    const basePath = currentDirectoryRoot();
     const date = new Date().toISOString().split("T")[0];
     // Load the workflow template content — prefer a project/global plugin
     // override if one exists (same name, .md format).
@@ -436,7 +437,7 @@ export function dispatchMarkdownPhasePlugin(plugin, description, ctx, pi) {
         return;
     }
     const templateId = plugin.name;
-    const basePath = process.cwd();
+    const basePath = currentDirectoryRoot();
     const date = new Date().toISOString().split("T")[0];
     let workflowContent;
     try {

package/dist/resources/extensions/gsd/context-budget.js

@@ -21,6 +21,8 @@ const VERIFICATION_RATIO = 0.10;
 const CHARS_PER_TOKEN = 4;
 /** Default context window when none can be resolved (D002) */
 const DEFAULT_CONTEXT_WINDOW = 200_000;
+/** Conservative effective context for Claude Code subscription routing (#4676) */
+const CLAUDE_CODE_EFFECTIVE_CONTEXT_WINDOW = 200_000;
 /** Percentage of context consumed before suggesting a continue-here checkpoint */
 const CONTINUE_THRESHOLD_PERCENT = 70;
 // ─── Task count bounds ───────────────────────────────────────────────────────
@@ -109,7 +111,7 @@ export function truncateAtSectionBoundary(content, budgetChars) {
  *
  * Supports "provider/model" format in preferences for explicit provider targeting.
  */
-export function resolveExecutorContextWindow(registry, preferences, sessionContextWindow) {
+export function resolveExecutorContextWindow(registry, preferences, sessionContextWindow, sessionProvider) {
     // Step 1: Try configured executor model
     if (preferences?.models?.execution && registry) {
         const executionConfig = preferences.models.execution;
@@ -119,13 +121,13 @@ export function resolveExecutorContextWindow(registry, preferences, sessionConte
         if (modelId) {
             const model = findModelById(registry, modelId);
             if (model && model.contextWindow > 0) {
-                return model.contextWindow;
+                return resolveEffectiveContextWindow(model.contextWindow, model.provider);
             }
         }
     }
     // Step 2: Fall back to session context window
     if (sessionContextWindow && sessionContextWindow > 0) {
-        return sessionContextWindow;
+        return resolveEffectiveContextWindow(sessionContextWindow, sessionProvider);
     }
     // Step 3: Fall back to default (D002)
     return DEFAULT_CONTEXT_WINDOW;
@@ -151,6 +153,12 @@ function resolveTaskCountMax(contextWindow) {
     }
     return 3; // fallback — unreachable given tiers include 0
 }
+function resolveEffectiveContextWindow(contextWindow, provider) {
+    if (provider?.toLowerCase() === "claude-code" && contextWindow > CLAUDE_CODE_EFFECTIVE_CONTEXT_WINDOW) {
+        return CLAUDE_CODE_EFFECTIVE_CONTEXT_WINDOW;
+    }
+    return contextWindow;
+}
 /**
  * Split content into sections at `### ` headings or `---` dividers.
  * Each section includes its leading marker.

package/dist/resources/extensions/gsd/db-writer.js

@@ -108,9 +108,9 @@ const STATUS_SECTION_MAP = [
 /**
  * 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) {
     const lines = [];
@@ -129,11 +129,9 @@ export function generateRequirementsMd(requirements) {
     // 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
             if (r.class)
@@ -179,6 +177,12 @@ export function generateRequirementsMd(requirements) {
     lines.push(`- Unmapped active requirements: 0`);
     return lines.join('\n') + '\n';
 }
+function isRootCanonicalArtifact(opts) {
+    if (opts.milestone_id || opts.slice_id || opts.task_id)
+        return false;
+    return (opts.artifact_type === 'PROJECT' ||
+        opts.artifact_type === 'REQUIREMENTS');
+}
 // ─── Next Decision ID ─────────────────────────────────────────────────────
 /**
  * Compute the next decision ID from the current DB state.
@@ -257,34 +261,45 @@ export async function saveRequirementToDb(fields, basePath) {
     try {
         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'] : null;
-            const nextId = (maxNum == null || isNaN(maxNum))
-                ? 'R001'
-                : `R${String(maxNum + 1).padStart(3, '0')}`;
+            const nextId = existingRow
+                ? String(existingRow['id'])
+                : (maxNum == null || isNaN(maxNum))
+                    ? 'R001'
+                    : `R${String(maxNum + 1).padStart(3, '0')}`;
             const requirement = {
                 id: nextId,
-                class: fields.class,
-                status: fields.status ?? 'active',
+                class: fields.class || existingRow?.['class'] || '',
+                status: fields.status ?? existingRow?.['status'] ?? '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'] ?? '',
+                supporting_slices: fields.supporting_slices ?? existingRow?.['supporting_slices'] ?? '',
+                validation: fields.validation ?? existingRow?.['validation'] ?? '',
+                notes: fields.notes ?? existingRow?.['notes'] ?? '',
+                full_content: existingRow?.['full_content'] ?? '',
+                superseded_by: existingRow?.['superseded_by'] ?? null,
             };
             db.upsertRequirement(requirement);
-            return nextId;
+            return { id: nextId };
         });
+        const { id } = txResult;
         // Fetch all requirements for full file regeneration
         const adapter = db._getAdapter();
         let allRequirements = [];
@@ -312,14 +327,7 @@ export async function saveRequirementToDb(fields, basePath) {
             await saveFile(filePath, md);
         }
         catch (diskErr) {
-            logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveRequirementToDb', error: String(diskErr.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.message) });
-            }
-            throw diskErr;
+            logWarning('projection', 'REQUIREMENTS.md projection write failed; DB requirement remains committed', { fn: 'saveRequirementToDb', id, error: String(diskErr.message) });
         }
         invalidateStateCache();
         clearPathCache();
@@ -427,14 +435,7 @@ export async function saveDecisionToDb(fields, basePath) {
             await saveFile(filePath, md);
         }
         catch (diskErr) {
-            logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveDecisionToDb', error: String(diskErr.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.message) });
-            }
-            throw diskErr;
+            logWarning('projection', 'DECISIONS.md projection write failed; DB decision remains committed', { fn: 'saveDecisionToDb', id, error: String(diskErr.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
@@ -461,8 +462,8 @@ export async function saveDecisionToDb(fields, basePath) {
         // 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');
@@ -548,34 +549,7 @@ export function extractDeferredSliceRef(fields) {
 export async function updateRequirementInDb(id, updates, basePath) {
     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 = existing ?? {
             id,
             class: '',
@@ -626,11 +600,7 @@ export async function updateRequirementInDb(id, updates, basePath) {
             await saveFile(filePath, md);
         }
         catch (diskErr) {
-            logError('manifest', 'disk write failed, reverting DB row', { fn: 'updateRequirementInDb', error: String(diskErr.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.message) });
         }
         // Invalidate file-read caches so deriveState() sees the updated markdown.
         // Do NOT clear the artifacts table — we just wrote to it intentionally.
@@ -657,17 +627,27 @@ export async function saveArtifactToDb(opts, basePath) {
         if (!fullPath.startsWith(gsdDir)) {
             throw new GSDError(GSD_IO_ERROR, `saveArtifactToDb: path escapes .gsd/ directory: ${opts.path}`);
         }
-        // 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;
+        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 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;
             }
         }
@@ -677,17 +657,15 @@ export async function saveArtifactToDb(opts, basePath) {
             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.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.message) });
             }
         }
         // Invalidate file-read caches so deriveState() sees the updated markdown.

package/dist/resources/extensions/gsd/deep-project-setup-policy.js

@@ -0,0 +1,212 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+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";
+const EXPLICIT_RESEARCH_SOURCES = new Set([
+    "research-decision",
+    "user",
+]);
+function clearCaches() {
+    clearPathCache();
+    clearParseCache();
+}
+function runtimeDir(basePath) {
+    return join(gsdRoot(basePath), "runtime");
+}
+export function researchDecisionPath(basePath) {
+    return join(runtimeDir(basePath), "research-decision.json");
+}
+export function isWorkflowPrefsCaptured(basePath) {
+    const prefsPath = join(gsdRoot(basePath), "PREFERENCES.md");
+    if (!existsSync(prefsPath))
+        return false;
+    let content;
+    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, reason = "deterministic-default", previousSource) {
+    const payload = {
+        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) {
+    const path = researchDecisionPath(basePath);
+    if (!existsSync(path))
+        return { exists: false, valid: false };
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        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) {
+    return decision.decision === "research" && EXPLICIT_RESEARCH_SOURCES.has(decision.source);
+}
+/**
+ * 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, basePath) {
+    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, basePath) {
+    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.",
+    };
+}