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

package/dist/resources/extensions/gsd/paths.js

@@ -9,10 +9,13 @@
  * via prefix matching, so existing projects work without migration.
  */
 import { readdirSync, existsSync, realpathSync, Dirent } from "node:fs";
-import { join, dirname, normalize } from "node:path";
+import { join, dirname, normalize, resolve } from "node:path";
+import { homedir } from "node:os";
 import { spawnSync } from "node:child_process";
 import { nativeScanGsdTree } from "./native-parser-bridge.js";
 import { DIR_CACHE_MAX } from "./constants.js";
+import { gsdHome } from "./gsd-home.js";
+import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
 // ─── Directory Listing Cache ──────────────────────────────────────────────────
 const dirEntryCache = new Map();
 const dirListCache = new Map();
@@ -268,6 +271,36 @@ const LEGACY_GSD_ROOT_FILES = {
 };
 // ─── GSD Root Discovery ───────────────────────────────────────────────────────
 const gsdRootCache = new Map();
+export function resolveGsdPathContract(workRoot, originalProjectRoot) {
+    const resolvedWorkRoot = resolve(workRoot || process.cwd());
+    const isWorktree = isGsdWorktreePath(resolvedWorkRoot);
+    if (isWorktree && !originalProjectRoot?.trim()) {
+        const externalMatch = /[/\\]\.gsd[/\\]projects[/\\][^/\\]+[/\\]worktrees(?:[/\\]|$)/.exec(resolvedWorkRoot);
+        if (externalMatch) {
+            const worktreesIdx = externalMatch[0].search(/[/\\]worktrees(?:[/\\]|$)/);
+            const projectGsd = resolvedWorkRoot.slice(0, externalMatch.index + worktreesIdx);
+            return {
+                projectRoot: dirname(dirname(projectGsd)),
+                workRoot: resolvedWorkRoot,
+                projectGsd,
+                worktreeGsd: join(resolvedWorkRoot, ".gsd"),
+                projectDb: join(projectGsd, "gsd.db"),
+                isWorktree,
+            };
+        }
+    }
+    const projectRoot = resolve(resolveWorktreeProjectRoot(resolvedWorkRoot, originalProjectRoot));
+    const projectGsd = join(projectRoot, ".gsd");
+    const worktreeGsd = isWorktree ? join(resolvedWorkRoot, ".gsd") : null;
+    return {
+        projectRoot,
+        workRoot: resolvedWorkRoot,
+        projectGsd,
+        worktreeGsd,
+        projectDb: join(projectGsd, "gsd.db"),
+        isWorktree,
+    };
+}
 /** Exported for tests only — do not call in production code. */
 export function _clearGsdRootCache() {
     gsdRootCache.clear();
@@ -288,9 +321,44 @@ export function gsdRoot(basePath) {
     if (cached)
         return cached;
     const result = probeGsdRoot(basePath);
+    // Defense-in-depth: if basePath resolves to the user's home directory and
+    // the result equals gsdHome(), refuse — project-scoped writes must never
+    // land in the global ~/.gsd. Paths under ~/.gsd/projects/<hash>/ are still
+    // valid (their basePath does not equal homedir).
+    assertNotGlobalGsdHome(basePath, result);
     gsdRootCache.set(basePath, result);
     return result;
 }
+function assertNotGlobalGsdHome(basePath, result) {
+    const norm = (p) => {
+        let r;
+        try {
+            r = realpathSync.native(p);
+        }
+        catch {
+            r = p;
+        }
+        const s = r.replaceAll("\\", "/").replace(/\/+$/, "");
+        return process.platform === "win32" ? s.toLowerCase() : s;
+    };
+    let baseNorm;
+    let homeNorm;
+    let resultNorm;
+    let gsdHomeNorm;
+    try {
+        baseNorm = norm(basePath);
+        homeNorm = norm(homedir());
+        resultNorm = norm(result);
+        gsdHomeNorm = norm(gsdHome());
+    }
+    catch {
+        return;
+    }
+    if (baseNorm === homeNorm && resultNorm === gsdHomeNorm) {
+        throw new Error(`Refusing to use ${result} as a project .gsd directory — that is the global GSD home. ` +
+            `Run GSD from inside a project directory.`);
+    }
+}
 /**
  * Detect if a path is inside a .gsd/worktrees/<name>/ structure.
  *
@@ -325,6 +393,9 @@ function isInsideGsdWorktree(p) {
     return false;
 }
 function probeGsdRoot(rawBasePath) {
+    const contract = resolveGsdPathContract(rawBasePath);
+    if (contract.isWorktree)
+        return contract.projectGsd;
     // 1. Fast path — check the input path directly
     const local = join(rawBasePath, ".gsd");
     if (existsSync(local))

package/dist/resources/extensions/gsd/planning-depth.js

@@ -0,0 +1,114 @@
+// gsd-2 / Deep planning mode — Helper to set planning_depth in .gsd/PREFERENCES.md.
+//
+// Persists the user's deep-mode opt-in across sessions. Reads the existing
+// preferences file (if any), parses its YAML frontmatter, sets/updates
+// planning_depth, and writes the file back preserving body content and other
+// frontmatter keys.
+import { existsSync, readFileSync } from "node:fs";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { atomicWriteSync } from "./atomic-write.js";
+import { getProjectGSDPreferencesPath } from "./preferences.js";
+import { logWarning } from "./workflow-logger.js";
+import { researchDecisionPath, writeDefaultResearchSkipDecision, } from "./deep-project-setup-policy.js";
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+/**
+ * Set planning_depth in the project's .gsd/PREFERENCES.md.
+ * Creates the file if it does not exist. Preserves existing frontmatter
+ * keys and body content. Intended to be called when the user opts into
+ * (or out of) deep mode via `/gsd new-project --deep` or similar.
+ */
+export function setPlanningDepth(basePath, depth) {
+    const path = getProjectGSDPreferencesPath(basePath);
+    const { frontmatter, body } = readProjectPreferencesParts(path);
+    frontmatter.planning_depth = depth;
+    if (depth === "deep") {
+        applyDeepWorkflowPreferenceDefaults(frontmatter);
+    }
+    writeProjectPreferencesParts(path, frontmatter, body);
+    if (depth === "deep") {
+        ensureResearchDecisionDefault(basePath);
+    }
+}
+export function ensureWorkflowPreferencesCaptured(basePath) {
+    const path = getProjectGSDPreferencesPath(basePath);
+    const { frontmatter, body } = readProjectPreferencesParts(path);
+    frontmatter.planning_depth = "deep";
+    applyDeepWorkflowPreferenceDefaults(frontmatter);
+    writeProjectPreferencesParts(path, frontmatter, body);
+    ensureResearchDecisionDefault(basePath);
+}
+function readProjectPreferencesParts(path) {
+    let frontmatter = {};
+    let body = "";
+    if (existsSync(path)) {
+        const content = readFileSync(path, "utf-8");
+        const match = content.match(FRONTMATTER_RE);
+        if (match) {
+            try {
+                const parsed = parseYaml(match[1]);
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                    frontmatter = parsed;
+                }
+                body = match[2];
+            }
+            catch (err) {
+                // Invalid YAML — don't lose user content. Treat the whole file as
+                // a legacy non-frontmatter document and preserve it via the body
+                // path. The depth setter then prepends a fresh frontmatter block.
+                logWarning("guided", `PREFERENCES.md frontmatter has invalid YAML — preserving body and rewriting frontmatter: ${err instanceof Error ? err.message : String(err)}`);
+                body = content;
+            }
+        }
+        else {
+            // No frontmatter delimiters — preserve existing content as body.
+            body = content;
+        }
+    }
+    return { frontmatter, body };
+}
+function writeProjectPreferencesParts(path, frontmatter, body) {
+    // yaml.stringify emits a trailing newline. Strip if present so we control framing.
+    const yamlBlock = stringifyYaml(frontmatter).replace(/\n$/, "");
+    const newContent = body
+        ? `---\n${yamlBlock}\n---\n\n${body.replace(/^\n+/, "")}`
+        : `---\n${yamlBlock}\n---\n`;
+    atomicWriteSync(path, newContent, "utf-8");
+}
+function applyDeepWorkflowPreferenceDefaults(frontmatter) {
+    if (frontmatter.commit_policy === undefined) {
+        frontmatter.commit_policy = "per-task";
+    }
+    if (frontmatter.branch_model === undefined) {
+        frontmatter.branch_model = "single";
+    }
+    if (frontmatter.uat_dispatch === undefined) {
+        frontmatter.uat_dispatch = true;
+    }
+    const existingModels = frontmatter.models;
+    const models = existingModels && typeof existingModels === "object" && !Array.isArray(existingModels)
+        ? existingModels
+        : {};
+    if (models.executor_class === undefined) {
+        models.executor_class = "balanced";
+    }
+    frontmatter.models = models;
+    frontmatter.workflow_prefs_captured = true;
+}
+function ensureResearchDecisionDefault(basePath) {
+    const decisionPath = researchDecisionPath(basePath);
+    if (existsSync(decisionPath)) {
+        try {
+            const parsed = JSON.parse(readFileSync(decisionPath, "utf-8"));
+            const source = typeof parsed.source === "string" ? parsed.source : undefined;
+            if (parsed.decision === "research" && (source === "research-decision" || source === "user")) {
+                return;
+            }
+            if (parsed.decision === "skip" && source !== "workflow-preferences")
+                return;
+        }
+        catch {
+            // Invalid runtime marker is replaced with the default decision.
+        }
+    }
+    writeDefaultResearchSkipDecision(basePath);
+}

package/dist/resources/extensions/gsd/preferences-models.js

@@ -8,6 +8,7 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { gsdHome } from "./gsd-home.js";
 import { canonicalModelForTier, defaultRoutingConfig, resolveModelForTier } from "./model-router.js";
 import { loadEffectiveGSDPreferences, getGlobalGSDPreferencesPath } from "./preferences.js";
 /**
@@ -45,8 +46,24 @@ export function resolveModelWithFallbacksForUnit(unitType) {
             break;
         case "discuss-milestone":
         case "discuss-slice":
+        // Deep-mode project-level discussion units route to the same model
+        // bucket as milestone-level discussion (interactive interview style).
+        case "discuss-project":
+        case "discuss-requirements":
+        // Workflow preferences and research-decision are tiny ask_user_questions
+        // style units; they share the discuss bucket because they are
+        // conversational rather than research/execution. Falling back to planning
+        // when no `discuss` bucket is set keeps parity with the milestone units.
+        case "workflow-preferences":
+        case "research-decision":
             phaseConfig = m.discuss ?? m.planning;
             break;
+        // Deep-mode project research orchestrator. Reads PROJECT.md / REQUIREMENTS.md
+        // and fans out research subagents. Routes to the research bucket so it
+        // gets the research-tier model when one is configured.
+        case "research-project":
+            phaseConfig = m.research;
+            break;
         case "execute-task":
         case "reactive-execute":
             phaseConfig = m.execution;
@@ -186,7 +203,7 @@ export function isCustomProvider(provider) {
     if (!provider)
         return false;
     const candidates = [
-        join(homedir(), ".gsd", "agent", "models.json"),
+        join(gsdHome(), "agent", "models.json"),
         join(homedir(), ".pi", "agent", "models.json"),
     ];
     for (const path of candidates) {

package/dist/resources/extensions/gsd/preferences-skills.js

@@ -7,6 +7,7 @@
 import { existsSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
+import { gsdHome } from "./gsd-home.js";
 import { statSync } from "node:fs";
 import { validatePreferences } from "./preferences-validation.js";
 /**
@@ -25,7 +26,7 @@ export function getSkillSearchDirs(cwd) {
         { dir: join(cwd, ".claude", "skills"), method: "project-skill" },
     ];
     // Legacy fallback — read skills from old GSD directory only if migration hasn't completed
-    const legacyDir = join(homedir(), ".gsd", "agent", "skills");
+    const legacyDir = join(gsdHome(), "agent", "skills");
     if (existsSync(legacyDir) && !existsSync(join(legacyDir, ".migrated-to-agents"))) {
         dirs.push({ dir: legacyDir, method: "user-skill" });
     }

package/dist/resources/extensions/gsd/preferences-types.js

@@ -98,6 +98,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set([
     "language",
     "context_window_override",
     "context_mode",
+    "planning_depth",
 ]);
 /** Canonical list of all dispatch unit types. */
 export const KNOWN_UNIT_TYPES = [
@@ -105,6 +106,9 @@ export const KNOWN_UNIT_TYPES = [
     "execute-task", "reactive-execute", "gate-evaluate", "complete-slice", "replan-slice", "reassess-roadmap",
     "run-uat", "complete-milestone", "validate-milestone", "rewrite-docs",
     "discuss-milestone", "discuss-slice", "worktree-merge",
+    // Deep planning mode (project-level) units
+    "workflow-preferences", "discuss-project", "discuss-requirements",
+    "research-decision", "research-project",
 ];
 export const SKILL_ACTIONS = new Set(["use", "prefer", "avoid"]);
 /**

package/dist/resources/extensions/gsd/preferences-validation.js

@@ -251,6 +251,15 @@ export function validatePreferences(preferences) {
             errors.push(`token_profile must be one of: budget, balanced, quality, burn-max`);
         }
     }
+    // ─── Planning Depth (deep planning mode) ─────────────────────────
+    if (preferences.planning_depth !== undefined) {
+        if (preferences.planning_depth === "light" || preferences.planning_depth === "deep") {
+            validated.planning_depth = preferences.planning_depth;
+        }
+        else {
+            errors.push(`planning_depth must be "light" or "deep"`);
+        }
+    }
     // ─── Search Provider ─────────────────────────────────────────────
     if (preferences.search_provider !== undefined) {
         const validSearchProviders = new Set(["brave", "tavily", "ollama", "native", "auto"]);

package/dist/resources/extensions/gsd/preferences.js

@@ -17,8 +17,10 @@ import { parse as parseYaml } from "yaml";
 import { normalizeStringArray } from "../shared/format-utils.js";
 import { logWarning } from "./workflow-logger.js";
 import { resolveProfileDefaults as _resolveProfileDefaults } from "./preferences-models.js";
+import { nativeHasCommittedHead, nativeIsRepo } from "./native-git-bridge.js";
 import { KNOWN_PREFERENCE_KEYS, MODE_DEFAULTS, formatSkillRef, } from "./preferences-types.js";
 import { validatePreferences } from "./preferences-validation.js";
+import { gsdHome } from "./gsd-home.js";
 // ─── Re-exports: validation ─────────────────────────────────────────────────
 export { validatePreferences } from "./preferences-validation.js";
 // ─── Re-exports: skills ─────────────────────────────────────────────────────
@@ -37,9 +39,6 @@ export function resolveSkillStalenessDays(basePath) {
 // ─── Re-exports: models ─────────────────────────────────────────────────────
 export { resolveModelForUnit, resolveModelWithFallbacksForUnit, getNextFallbackModel, isTransientNetworkError, validateModelId, updatePreferencesModels, resolveDynamicRoutingConfig, resolveAutoSupervisorConfig, resolveProfileDefaults, getProfileTierMap, resolveEffectiveProfile, resolveInlineLevel, resolveContextSelection, resolveSearchProviderFromPreferences, resolveDisabledModelProvidersFromPreferences, } from "./preferences-models.js";
 // ─── Path Constants & Getters ───────────────────────────────────────────────
-function gsdHome() {
-    return process.env.GSD_HOME || join(homedir(), ".gsd");
-}
 function globalPreferencesPath() {
     return join(gsdHome(), "PREFERENCES.md");
 }
@@ -79,6 +78,7 @@ export function loadProjectGSDPreferences(basePath) {
 export function loadEffectiveGSDPreferences(basePath, opts) {
     const globalPreferences = loadGlobalGSDPreferences();
     const projectPreferences = loadProjectGSDPreferences(basePath);
+    const projectHasPlanningDepth = projectPreferences?.preferences.planning_depth !== undefined;
     if (!globalPreferences && !projectPreferences)
         return null;
     let result;
@@ -118,8 +118,20 @@ export function loadEffectiveGSDPreferences(basePath, opts) {
             preferences: applyModeDefaults(result.preferences.mode, result.preferences),
         };
     }
+    result = stripInheritedPlanningDepth(result, projectHasPlanningDepth);
     return result;
 }
+function stripInheritedPlanningDepth(loaded, projectHasPlanningDepth) {
+    if (projectHasPlanningDepth || loaded.preferences.planning_depth === undefined) {
+        return loaded;
+    }
+    // planning_depth is a project bootstrap routing flag, not a user-global
+    // preference. A global ~/.gsd/PREFERENCES.md value should not make every
+    // fresh repo behave like `/gsd new-project --deep`.
+    const preferences = { ...loaded.preferences };
+    delete preferences.planning_depth;
+    return { ...loaded, preferences };
+}
 function loadPreferencesFile(path, scope) {
     if (!existsSync(path))
         return null;
@@ -363,6 +375,7 @@ function mergePreferences(base, override) {
             ? { ...(base.slice_parallel ?? {}), ...(override.slice_parallel ?? {}) }
             : undefined,
         language: override.language ?? base.language,
+        planning_depth: override.planning_depth ?? base.planning_depth,
     };
 }
 function mergeStringLists(base, override) {
@@ -493,8 +506,11 @@ export function resolvePreDispatchHooks() {
  */
 export function getIsolationMode(basePath) {
     const prefs = loadEffectiveGSDPreferences(basePath)?.preferences?.git;
-    if (prefs?.isolation === "worktree")
+    if (prefs?.isolation === "worktree") {
+        if (basePath && nativeIsRepo(basePath) && !nativeHasCommittedHead(basePath))
+            return "none";
         return "worktree";
+    }
     if (prefs?.isolation === "branch")
         return "branch";
     return "none"; // default — no isolation, work on current branch

package/dist/resources/extensions/gsd/project-research-policy.js

@@ -0,0 +1,182 @@
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { atomicWriteSync } from "./atomic-write.js";
+import { classifyMilestoneScope, } from "./milestone-scope-classifier.js";
+import { clearParseCache } from "./files.js";
+import { gsdRoot, clearPathCache } from "./paths.js";
+import { parseProject, parseRequirements } from "./schemas/parsers.js";
+export const PROJECT_RESEARCH_DIMENSIONS = ["STACK", "FEATURES", "ARCHITECTURE", "PITFALLS"];
+export const PROJECT_RESEARCH_BLOCKER = "PROJECT-RESEARCH-BLOCKER.md";
+export const PROJECT_RESEARCH_INFLIGHT_MARKER = "research-project-inflight";
+function researchDir(basePath) {
+    return join(gsdRoot(basePath), "research");
+}
+function runtimeDir(basePath) {
+    return join(gsdRoot(basePath), "runtime");
+}
+function researchDecisionPath(basePath) {
+    return join(runtimeDir(basePath), "research-decision.json");
+}
+function clearResearchCaches() {
+    clearPathCache();
+    clearParseCache();
+}
+function isProjectResearchDimensionSatisfied(dir, name) {
+    return existsSync(join(dir, `${name}.md`)) || existsSync(join(dir, `${name}-BLOCKER.md`));
+}
+function writeIfMissing(path, content) {
+    if (existsSync(path))
+        return false;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content, "utf-8");
+    return true;
+}
+function markdownTitle(content) {
+    return content.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? "Project";
+}
+function selectedSections(sections) {
+    return [
+        "What This Is",
+        "Core Value",
+        "Current State",
+        "Architecture / Key Patterns",
+        "Constraints",
+        "Milestone Sequence",
+    ]
+        .map((name) => sections[name] ?? "")
+        .filter(Boolean)
+        .join("\n\n");
+}
+export function classifyProjectResearchScope(projectContent, requirementsContent) {
+    const project = parseProject(projectContent);
+    const requirements = parseRequirements(requirementsContent);
+    const activeRequirements = requirements.requirements.filter((r) => r.status === "active" || r.parentSection === "Active");
+    const activeCapabilities = activeRequirements.filter((r) => r.class !== "constraint" && r.class !== "anti-feature");
+    const requirementCoverage = activeRequirements
+        .map((r) => [
+        r.id,
+        r.title,
+        r.class,
+        r.status,
+        r.description,
+        r.notes,
+    ].filter(Boolean).join(" — "))
+        .join("\n");
+    const result = classifyMilestoneScope({
+        title: markdownTitle(projectContent),
+        vision: selectedSections(project.sections),
+        successCriteria: activeCapabilities.map((r) => `${r.title}: ${r.description}`),
+        definitionOfDone: activeCapabilities.map((r) => r.validation).filter(Boolean),
+        requirementCoverage: [
+            requirementCoverage,
+            Object.entries(requirements.coverageSummary)
+                .map(([key, value]) => `${key}: ${value}`)
+                .join("\n"),
+        ].filter(Boolean).join("\n\n"),
+    });
+    return {
+        ...result,
+        source: "project-research",
+    };
+}
+export function getProjectResearchStatus(basePath) {
+    const dir = researchDir(basePath);
+    const globalBlocker = existsSync(join(dir, PROJECT_RESEARCH_BLOCKER));
+    const completedDimensions = [];
+    const blockerDimensions = [];
+    const missingDimensions = [];
+    for (const name of PROJECT_RESEARCH_DIMENSIONS) {
+        if (existsSync(join(dir, `${name}.md`)))
+            completedDimensions.push(name);
+        else if (existsSync(join(dir, `${name}-BLOCKER.md`)))
+            blockerDimensions.push(name);
+        else
+            missingDimensions.push(name);
+    }
+    const allSatisfied = PROJECT_RESEARCH_DIMENSIONS.every((name) => isProjectResearchDimensionSatisfied(dir, name));
+    const allDimensionBlockers = allSatisfied &&
+        completedDimensions.length === 0 &&
+        blockerDimensions.length === PROJECT_RESEARCH_DIMENSIONS.length;
+    const blocked = globalBlocker || allDimensionBlockers;
+    return {
+        complete: allSatisfied && !blocked,
+        blocked,
+        allDimensionBlockers,
+        globalBlocker,
+        missingDimensions,
+        completedDimensions,
+        blockerDimensions,
+        hasRealResearch: completedDimensions.length > 0,
+    };
+}
+export function writeProjectResearchAutoSkipDecision(basePath, classification) {
+    atomicWriteSync(researchDecisionPath(basePath), JSON.stringify({
+        decision: "skip",
+        decided_at: new Date().toISOString(),
+        source: "project-research-fast-path",
+        previous_source: "workflow-preferences",
+        reason: "trivial-static-local-project",
+        classifier_variant: classification.variant,
+        classifier_reasons: classification.reasons,
+    }, null, 2) + "\n", "utf-8");
+}
+export function clearProjectResearchInflightMarker(basePath) {
+    const marker = join(runtimeDir(basePath), PROJECT_RESEARCH_INFLIGHT_MARKER);
+    if (existsSync(marker))
+        unlinkSync(marker);
+}
+export function finalizeProjectResearchTimeout(basePath, reason) {
+    const dir = researchDir(basePath);
+    mkdirSync(dir, { recursive: true });
+    clearProjectResearchInflightMarker(basePath);
+    const before = getProjectResearchStatus(basePath);
+    const written = [];
+    if (before.complete) {
+        clearResearchCaches();
+        return { kind: "completed", status: before, written };
+    }
+    if (before.blocked) {
+        clearResearchCaches();
+        return { kind: "global-blocker", status: before, written };
+    }
+    if (before.hasRealResearch) {
+        for (const dimension of before.missingDimensions) {
+            const blockerPath = join(dir, `${dimension}-BLOCKER.md`);
+            if (writeIfMissing(blockerPath, [
+                `# ${dimension} research blocker`,
+                ``,
+                `Auto-mode stopped project research before this dimension produced a durable artifact.`,
+                ``,
+                `**Reason**: ${reason}`,
+                ``,
+                `At least one other project research dimension completed, so this blocker satisfies the project research gate without rerunning every scout.`,
+            ].join("\n"))) {
+                written.push(blockerPath);
+            }
+        }
+        clearResearchCaches();
+        return {
+            kind: "partial-blockers",
+            status: getProjectResearchStatus(basePath),
+            written,
+        };
+    }
+    const blockerPath = join(dir, PROJECT_RESEARCH_BLOCKER);
+    if (writeIfMissing(blockerPath, [
+        `# Project research blocker`,
+        ``,
+        `Auto-mode stopped project research before any usable research dimension completed.`,
+        ``,
+        `**Reason**: ${reason}`,
+        ``,
+        `This fail-closed blocker prevents milestone planning from relying on missing project research.`,
+    ].join("\n"))) {
+        written.push(blockerPath);
+    }
+    clearResearchCaches();
+    return {
+        kind: "global-blocker",
+        status: getProjectResearchStatus(basePath),
+        written,
+    };
+}

package/dist/resources/extensions/gsd/prompt-loader.js

@@ -19,8 +19,8 @@ import { readFileSync, readdirSync, existsSync } from "node:fs";
 import { GSDError, GSD_PARSE_ERROR } from "./errors.js";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { homedir } from "node:os";
 import { logWarning } from "./workflow-logger.js";
+import { gsdHome } from "./gsd-home.js";
 function hasRequiredExtensionAssets(rootDir, exists = existsSync) {
     return (exists(join(rootDir, "prompts")) &&
         exists(join(rootDir, "templates", "task-summary.md")));
@@ -54,8 +54,7 @@ export function resolveExtensionDirFromCandidates(moduleDir, agentGsdDir, exists
  */
 function resolveExtensionDir() {
     const moduleDir = dirname(fileURLToPath(import.meta.url));
-    const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-    const agentGsdDir = join(gsdHome, "agent", "extensions", "gsd");
+    const agentGsdDir = join(gsdHome(), "agent", "extensions", "gsd");
     return resolveExtensionDirFromCandidates(moduleDir, agentGsdDir);
 }
 const __extensionDir = resolveExtensionDir();

package/dist/resources/extensions/gsd/prompts/complete-slice.md

@@ -38,7 +38,7 @@ Then:
 5. Address every gate listed in the **Gates to Close** section above — each gate maps to a specific slice-summary section the handler inspects (for example, Q8 maps to **Operational Readiness**: health signal, failure signal, recovery procedure, and monitoring gaps). Leaving a section empty records the gate as `omitted`.
 6. If this slice produced evidence that a requirement changed status (Active → Validated, Active → Deferred, etc.), call `gsd_requirement_update` with the requirement ID, updated `status`, and `validation` evidence. Do NOT write `.gsd/REQUIREMENTS.md` directly — the engine renders it from the database.
 7. Prepare the slice completion content you will pass to `gsd_complete_slice` using the camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`. Do **not** manually write `{{sliceSummaryPath}}`. Do **not** manually write `{{sliceUatPath}}` — the DB-backed tool is the canonical write path for both artifacts.
-8. Draft the UAT content you will pass as `uatContent` — a concrete UAT script with real test cases derived from the slice plan and task summaries. Include preconditions, numbered steps with expected outcomes, and edge cases. This must NOT be a placeholder or generic template — tailor every test case to what this slice actually built.
+8. Draft the UAT content you will pass as `uatContent` — a concrete UAT script with real test cases derived from the slice plan and task summaries. Include preconditions, numbered steps with expected outcomes, and edge cases. This must NOT be a placeholder or generic template — tailor every test case to what this slice actually built. Fill the `UAT Type` and `Not Proven By This UAT` sections explicitly so the artifact states what class of acceptance it covers and what still remains unproven (e.g. live integration paths, performance under load, scenarios deferred to a later slice).
 9. Review task summaries for `key_decisions`. For each significant decision, call `capture_thought` with `category: "architecture"` (or `"pattern"`) and a `structuredFields` payload of `{ scope, decision, choice, rationale, made_by: "agent", revisable }`.
 10. Review task summaries for patterns, gotchas, or non-obvious lessons learned. For each one that would save future agents from repeating investigation, call `capture_thought` with the matching category (`gotcha`, `convention`, `pattern`, `environment`). The memory store is the single source of truth (ADR-013); do not append to `.gsd/DECISIONS.md` or `.gsd/KNOWLEDGE.md` directly.
 11. Call `gsd_complete_slice` with the camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`, plus any optional enrichment fields you have. Do NOT manually mark the roadmap checkbox — the tool writes to the DB, renders `{{sliceSummaryPath}}` and `{{sliceUatPath}}`, and updates the ROADMAP.md projection automatically.