gsd-pi 2.78.0 → 2.78.1-dev.42ef05fbe

package/dist/resources/extensions/gsd/auto-prompts.js

@@ -23,7 +23,7 @@ import { composeInlinedContext } from "./unit-context-composer.js";
 import { logWarning } from "./workflow-logger.js";
 import { inlineGraphSubgraph } from "./graph-context.js";
 import { buildExtractionStepsBlock } from "./commands-extract-learnings.js";
-import { warnIfManifestHasMissingSkills } from "./skill-manifest.js";
+import { resolveSkillManifest, warnIfManifestHasMissingSkills } from "./skill-manifest.js";
 // ─── Preamble Cap ─────────────────────────────────────────────────────────────
 /**
  * Historical static ceiling for the preamble cap. Kept as an upper bound even
@@ -77,17 +77,17 @@ function capPreamble(preamble) {
  * Uses the budget engine to compute task count ranges and inline context budgets
  * based on the configured executor model's context window.
  */
-function formatExecutorConstraints(sessionContextWindow, modelRegistry) {
+function formatExecutorConstraints(sessionContextWindow, modelRegistry, sessionProvider) {
     let windowTokens;
     try {
         const prefs = loadEffectiveGSDPreferences();
-        windowTokens = resolveExecutorContextWindow(modelRegistry, prefs?.preferences, sessionContextWindow);
+        windowTokens = resolveExecutorContextWindow(modelRegistry, prefs?.preferences, sessionContextWindow, sessionProvider);
     }
     catch (e) {
         logWarning("prompt", `resolveExecutorContextWindow failed: ${e.message}`);
         // Delegate to the budget engine without prefs (the path that just threw)
         // so DEFAULT_CONTEXT_WINDOW stays the single source of truth.
-        windowTokens = resolveExecutorContextWindow(undefined, undefined, sessionContextWindow);
+        windowTokens = resolveExecutorContextWindow(undefined, undefined, sessionContextWindow, sessionProvider);
     }
     const budgets = computeBudgets(windowTokens);
     const { min, max } = budgets.taskCountRange;
@@ -675,6 +675,26 @@ function formatSkillActivationBlock(skillNames) {
     const calls = safe.map(name => `Call Skill({ skill: '${name}' })`).join('. ');
     return `<skill_activation>${calls}.</skill_activation>`;
 }
+/**
+ * Manifest-driven recommendations block — informational only, does NOT
+ * auto-invoke. Lists per-unit-type skills that are installed but not already
+ * activated by explicit user intent (always_use_skills / prefer_skills /
+ * skill_rules / task-plan skills_used). Surfaces relevant skills to the
+ * model so they can be invoked when the model judges them useful.
+ *
+ * This is the additive complement to the existing activation directive:
+ * activation force-invokes (explicit intent), recommendations remind
+ * (manifest defaults). User intent is preserved as the stronger signal
+ * (RFC #4779 design principle); this block only adds visibility.
+ */
+function formatSkillRecommendationsBlock(unitType, skillNames) {
+    if (!unitType)
+        return "";
+    const safe = skillNames.filter(name => SAFE_SKILL_NAME.test(name));
+    if (safe.length === 0)
+        return "";
+    return `<skill_recommendations unit="${unitType}">For this unit type, also consider invoking: ${safe.join(", ")}. Use Skill({ skill: 'name' }) when relevant — these are recommendations, not requirements.</skill_recommendations>`;
+}
 export function buildSkillActivationBlock(params) {
     const prefs = params.preferences ?? loadEffectiveGSDPreferences(params.base)?.preferences;
     const contextTokens = tokenizeSkillContext(params.milestoneId, params.milestoneTitle, params.sliceId, params.sliceTitle, params.taskId, params.taskTitle);
@@ -717,10 +737,51 @@ export function buildSkillActivationBlock(params) {
             logWarning("prompt", `parseTaskPlanFile failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    // Heuristic auto-match (gated on skill_discovery: "auto").
+    // For each installed skill, check if its name or description appears in the
+    // unit's context tokens (milestone/slice/task titles). Only consider skills
+    // already on the unit-type manifest allowlist — this keeps the heuristic
+    // narrow and avoids wildly off-topic activations.
+    // Users who set `skill_discovery: "off"` or "suggest" do not get
+    // auto-matched skills (the recommendations block still surfaces manifest
+    // skills passively); only "auto" actually adds them to the activation
+    // directive set. Default `skill_discovery` is "suggest", so this is opt-in.
+    if ((prefs?.skill_discovery ?? "suggest") === "auto") {
+        const manifestAllow = resolveSkillManifest(params.unitType);
+        const allowSet = manifestAllow ? new Set(manifestAllow) : null;
+        for (const skill of visibleSkills) {
+            const normalized = normalizeSkillReference(skill.name);
+            if (matched.has(normalized) || avoided.has(normalized))
+                continue;
+            // Respect the manifest allowlist when present; wildcard (null) lets all
+            // installed skills compete for keyword match.
+            if (allowSet && !allowSet.has(normalized))
+                continue;
+            if (skillMatchesContext(skill, contextTokens)) {
+                matched.add(normalized);
+            }
+        }
+    }
     const ordered = [...matched]
         .filter(name => installedNames.has(name) && !avoided.has(name))
         .sort();
-    return formatSkillActivationBlock(ordered);
+    const activationBlock = formatSkillActivationBlock(ordered);
+    // Manifest-driven recommendations (additive, does not override explicit intent).
+    // Only surface skills the manifest declares for this unit type that are
+    // installed and not already in matched/avoided.
+    const matchedSet = new Set(ordered);
+    const manifestList = resolveSkillManifest(params.unitType);
+    const recommendations = (manifestList ?? [])
+        .filter(name => installedNames.has(name) && !avoided.has(name) && !matchedSet.has(name))
+        .sort();
+    const recommendationsBlock = formatSkillRecommendationsBlock(params.unitType, recommendations);
+    if (!activationBlock && !recommendationsBlock)
+        return "";
+    if (!activationBlock)
+        return recommendationsBlock;
+    if (!recommendationsBlock)
+        return activationBlock;
+    return `${activationBlock}\n${recommendationsBlock}`;
 }
 /**
  * Build the skill discovery template variables for research prompts.
@@ -1059,6 +1120,7 @@ export async function checkNeedsRunUat(base, mid, state, prefs) {
 export async function buildDiscussMilestonePrompt(mid, midTitle, base, structuredQuestionsAvailable = "false") {
     const discussTemplates = inlineTemplate("context", "Context");
     const basePrompt = loadPrompt("guided-discuss-milestone", {
+        workingDirectory: base,
         milestoneId: mid,
         milestoneTitle: midTitle,
         inlinedTemplates: discussTemplates,
@@ -1074,6 +1136,73 @@ export async function buildDiscussMilestonePrompt(mid, midTitle, base, structure
     }
     return basePrompt;
 }
+/**
+ * Build a prompt for the workflow-preferences unit type (deep mode).
+ * Default-writing stage: records high-impact workflow defaults in
+ * .gsd/PREFERENCES.md. Runs ONCE per project, early
+ * in deep-mode bootstrap before discuss-project.
+ */
+export async function buildWorkflowPreferencesPrompt(base, structuredQuestionsAvailable = "false") {
+    return loadPrompt("guided-workflow-preferences", {
+        workingDirectory: base,
+        structuredQuestionsAvailable,
+    });
+}
+/**
+ * Build a prompt for the research-project (parallel) unit type (deep mode).
+ * Orchestrator that spawns 4 parallel Task() calls covering stack, features,
+ * architecture, and pitfalls. Each subagent writes its findings to .gsd/research/.
+ * Fires after research-decision marker says "research" and project research files
+ * are missing. Skipped entirely if user picked "skip".
+ */
+export async function buildResearchProjectPrompt(base, structuredQuestionsAvailable = "false") {
+    return loadPrompt("guided-research-project", {
+        workingDirectory: base,
+        structuredQuestionsAvailable,
+    });
+}
+/**
+ * Build a prompt for the research-decision unit type (deep mode).
+ * Fixed-question stage: asks "research first or skip?" via ask_user_questions
+ * and writes .gsd/runtime/research-decision.json. Fires after discuss-requirements
+ * and before research-project-parallel.
+ */
+export async function buildResearchDecisionPrompt(base, structuredQuestionsAvailable = "false") {
+    return loadPrompt("guided-research-decision", {
+        workingDirectory: base,
+        structuredQuestionsAvailable,
+    });
+}
+/**
+ * Build a prompt for the discuss-project unit type (deep mode).
+ * Project-level interview: produces .gsd/PROJECT.md.
+ * Fires before any milestone-level work when planning_depth === "deep" and
+ * PROJECT.md is missing.
+ */
+export async function buildDiscussProjectPrompt(base, structuredQuestionsAvailable = "false") {
+    const inlinedTemplates = inlineTemplate("project", "Project");
+    return loadPrompt("guided-discuss-project", {
+        workingDirectory: base,
+        inlinedTemplates,
+        structuredQuestionsAvailable,
+        commitInstruction: "Do not commit planning artifacts — .gsd/ is managed externally.",
+    });
+}
+/**
+ * Build a prompt for the discuss-requirements unit type (deep mode).
+ * Requirements-level interview: produces .gsd/REQUIREMENTS.md using the
+ * structured R### format. Reads PROJECT.md as authoritative context.
+ * Fires when planning_depth === "deep", PROJECT.md exists, and REQUIREMENTS.md is missing.
+ */
+export async function buildDiscussRequirementsPrompt(base, structuredQuestionsAvailable = "false") {
+    const inlinedTemplates = inlineTemplate("requirements", "Requirements");
+    return loadPrompt("guided-discuss-requirements", {
+        workingDirectory: base,
+        inlinedTemplates,
+        structuredQuestionsAvailable,
+        commitInstruction: "Do not commit planning artifacts — .gsd/ is managed externally.",
+    });
+}
 export async function buildResearchMilestonePrompt(mid, midTitle, base) {
     // #4782 phase 3: research-milestone migrated through the composer.
     // Declared inline order: milestone-context, project, requirements,
@@ -1305,7 +1434,7 @@ export async function buildResearchSlicePrompt(mid, _midTitle, sid, sTitle, base
  * sketch-scope constraint).
  */
 async function renderSlicePrompt(options) {
-    const { mid, sid, sTitle, base, level, promptTemplate, prependBlocks = [], extraVars = {}, sessionContextWindow, modelRegistry, } = options;
+    const { mid, sid, sTitle, base, level, promptTemplate, prependBlocks = [], extraVars = {}, sessionContextWindow, modelRegistry, sessionProvider, } = options;
     const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
     const roadmapRel = relMilestoneFile(base, mid, "ROADMAP");
     const researchPath = resolveSliceFile(base, mid, sid, "RESEARCH");
@@ -1355,7 +1484,7 @@ async function renderSlicePrompt(options) {
     if (overridesInline)
         inlined.unshift(overridesInline);
     const inlinedContext = capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`);
-    const executorContextConstraints = formatExecutorConstraints(sessionContextWindow, modelRegistry);
+    const executorContextConstraints = formatExecutorConstraints(sessionContextWindow, modelRegistry, sessionProvider);
     const outputRelPath = relSliceFile(base, mid, sid, "PLAN");
     const commitInstruction = "Do not commit — .gsd/ planning docs are managed externally and not tracked in git.";
     return loadPrompt(promptTemplate, {
@@ -1412,6 +1541,7 @@ export async function buildPlanSlicePrompt(mid, _midTitle, sid, sTitle, base, le
         prependBlocks,
         sessionContextWindow: options?.sessionContextWindow,
         modelRegistry: options?.modelRegistry,
+        sessionProvider: options?.sessionProvider,
     });
 }
 /**
@@ -1446,6 +1576,7 @@ export async function buildRefineSlicePrompt(mid, _midTitle, sid, sTitle, base,
         extraVars: { sketchScope },
         sessionContextWindow: options?.sessionContextWindow,
         modelRegistry: options?.modelRegistry,
+        sessionProvider: options?.sessionProvider,
     });
 }
 export async function buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, base, level) {
@@ -1511,7 +1642,7 @@ export async function buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, base
     const overridesSection = formatOverridesSection(activeOverrides);
     // Compute verification budget for the executor's context window (issue #707)
     const prefs = loadEffectiveGSDPreferences();
-    const contextWindow = resolveExecutorContextWindow(opts.modelRegistry, prefs?.preferences, opts.sessionContextWindow);
+    const contextWindow = resolveExecutorContextWindow(opts.modelRegistry, prefs?.preferences, opts.sessionContextWindow, opts.sessionProvider);
     const budgets = computeBudgets(contextWindow);
     const verificationBudget = `~${Math.round(budgets.verificationBudgetChars / 1000)}K chars`;
     // Truncate carry-forward section when it exceeds 40% of inline context budget.
@@ -2181,6 +2312,7 @@ export async function buildReactiveExecutePrompt(mid, midTitle, sid, sTitle, rea
             carryForwardPaths: depPaths,
             sessionContextWindow: opts?.sessionContextWindow,
             modelRegistry: opts?.modelRegistry,
+            sessionProvider: opts?.sessionProvider,
         });
         const modelSuffix = subagentModel ? ` with model: "${subagentModel}"` : "";
         subagentSections.push([
@@ -2262,6 +2394,7 @@ export async function buildParallelResearchSlicesPrompt(mid, midTitle, slices, b
         ].join("\n"));
     }
     return loadPrompt("parallel-research-slices", {
+        workingDirectory: basePath,
         mid,
         midTitle,
         sliceCount: String(slices.length),
@@ -2289,11 +2422,14 @@ export async function buildGateEvaluatePrompt(mid, midTitle, sid, sTitle, base,
     const gateDefs = getGatesForTurn("gate-evaluate").filter((def) => pendingIds.has(def.id));
     const subagentSections = [];
     const gateListLines = [];
+    const normalizedBase = base.replaceAll("\\", "/");
     for (const def of gateDefs) {
         gateListLines.push(`- **${def.id}**: ${def.question}`);
         const subPrompt = [
             `You are evaluating quality gate **${def.id}** for slice ${sid} (${sTitle}).`,
             "",
+            `**Working directory:** \`${normalizedBase}\`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT \`cd\` to any other directory.`,
+            "",
             `## Question: ${def.question}`,
             "",
             def.guidance,
@@ -2401,6 +2537,7 @@ export async function buildRewriteDocsPrompt(mid, midTitle, activeSlice, base, o
     ].join("\n")).join("\n\n");
     const documentList = docList.length > 0 ? docList.join("\n") : "- No active plan documents found.";
     return loadPrompt("rewrite-docs", {
+        workingDirectory: base,
         milestoneId: mid,
         milestoneTitle: midTitle,
         sliceId: sid ?? "none",

package/dist/resources/extensions/gsd/auto-recovery.js

@@ -7,6 +7,7 @@
  * globals or AutoContext dependency.
  */
 import { parseUnitId } from "./unit-id.js";
+import { MILESTONE_ID_RE } from "./milestone-ids.js";
 import { appendEvent } from "./workflow-events.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { clearParseCache } from "./files.js";
@@ -24,10 +25,35 @@ import { execFileSync } from "node:child_process";
 import { dirname, join } from "node:path";
 import { resolveExpectedArtifactPath, diagnoseExpectedArtifact, } from "./auto-artifact-paths.js";
 import { classifyMilestoneSummaryContent } from "./milestone-summary-classifier.js";
+import { validateArtifact } from "./schemas/validate.js";
+import { getProjectResearchStatus } from "./project-research-policy.js";
 // Re-export so existing consumers of auto-recovery.ts keep working.
 export { resolveExpectedArtifactPath, diagnoseExpectedArtifact };
 export { classifyMilestoneSummaryContent, } from "./milestone-summary-classifier.js";
 // ─── Artifact Resolution & Verification ───────────────────────────────────────
+function hasCapturedWorkflowPrefs(base) {
+    const prefsPath = resolveExpectedArtifactPath("workflow-preferences", "WORKFLOW-PREFS", base);
+    if (!prefsPath || !existsSync(prefsPath))
+        return false;
+    const content = readFileSync(prefsPath, "utf-8");
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    return !!match && /^workflow_prefs_captured:\s*true\s*$/m.test(match[1]);
+}
+function hasValidResearchDecision(base) {
+    const decisionPath = resolveExpectedArtifactPath("research-decision", "RESEARCH-DECISION", base);
+    if (!decisionPath || !existsSync(decisionPath))
+        return false;
+    try {
+        const cfg = JSON.parse(readFileSync(decisionPath, "utf-8"));
+        return cfg.decision === "research" || cfg.decision === "skip";
+    }
+    catch {
+        return false;
+    }
+}
+function hasCompleteProjectResearch(base) {
+    return getProjectResearchStatus(base).complete;
+}
 /**
  * Check whether a milestone produced implementation artifacts (non-`.gsd/`
  * files) in git history. The primary signal is the branch diff against the
@@ -168,8 +194,35 @@ function getChangedFilesSinceBranch(basePath, targetBranch) {
     }
 }
 function getChangedFilesFromMilestoneTaggedCommits(basePath, milestoneId) {
+    // Primary: path-scoped log against .gsd/milestones/<id>. Fast and unbounded
+    // by depth when .gsd/ is tracked in git.
+    const scoped = scanGsdTaggedCommits(basePath, milestoneId, [
+        "log", "--format=%H%x1f%B%x1e", "HEAD", "--", `.gsd/milestones/${milestoneId}`,
+    ]);
+    if (!scoped.ok)
+        return scoped;
+    if (scoped.matched)
+        return scoped;
+    // Fallback (#5033): when .gsd/ is gitignored / external / untracked, the
+    // path-scoped scan matches no commits even though GSD-tagged commits
+    // referencing the milestone exist on the integration branch. Re-scan all
+    // of HEAD's history and rely on commitMatchesMilestone to bind by
+    // explicit milestone mention in the message body.
+    //
+    // Intentionally unbounded — symmetric with the primary scan, and avoids
+    // reintroducing the rolling-depth failure class removed in #4699 where
+    // milestone evidence aged out behind unrelated activity.
+    return scanGsdTaggedCommits(basePath, milestoneId, [
+        "log", "--format=%H%x1f%B%x1e", "HEAD",
+    ]);
+}
+function scanGsdTaggedCommits(basePath, milestoneId, gitArgs) {
     try {
-        const logOutput = execFileSync("git", ["log", "--format=%H%x1f%B%x1e", "HEAD", "--", `.gsd/milestones/${milestoneId}`], { cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" });
+        const logOutput = execFileSync("git", [...gitArgs], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        });
         const records = logOutput
             .split("\x1e")
             .map((record) => record.trim())
@@ -213,13 +266,24 @@ function commitMatchesMilestone(message, milestoneId, files) {
     if (commitTrailerStartsWithMilestone(message, milestoneId))
         return true;
     // Meaningful execute-task commits currently store task scope as Sxx/Tyy
-    // rather than Mxx/Sxx/Tyy. Bind those commits back to the milestone only
-    // when the commit also touched this milestone's artifacts.
+    // rather than Mxx/Sxx/Tyy. Bind those commits back to the milestone when
+    // either the commit touched this milestone's artifacts, or — for projects
+    // where .gsd/ is gitignored/external (#5033) — the message explicitly
+    // names the milestone.
     if (/^GSD-Task:\s*S[^/\s]+\/T\S+/m.test(message)) {
-        return files.some((file) => isMilestoneArtifactPath(file, milestoneId));
+        if (files.some((file) => isMilestoneArtifactPath(file, milestoneId)))
+            return true;
+        if (commitMessageMentionsMilestone(message, milestoneId))
+            return true;
     }
     return false;
 }
+function commitMessageMentionsMilestone(message, milestoneId) {
+    if (!MILESTONE_ID_RE.test(milestoneId))
+        return false;
+    const escapedMilestone = milestoneId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`\\b${escapedMilestone}\\b`).test(message);
+}
 function commitTrailerStartsWithMilestone(message, milestoneId) {
     const escapedMilestone = milestoneId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     const trailerPattern = new RegExp(`^GSD-(?:Task|Unit):\\s*${escapedMilestone}(?:$|[\\s/])`, "m");
@@ -257,6 +321,23 @@ export function verifyExpectedArtifact(unitType, unitId, base) {
         const content = readFileSync(overridesPath, "utf-8");
         return !content.includes("**Scope:** active");
     }
+    if (unitType === "workflow-preferences") {
+        return hasCapturedWorkflowPrefs(base);
+    }
+    if (unitType === "discuss-project") {
+        const projectPath = resolveExpectedArtifactPath(unitType, unitId, base);
+        return !!projectPath && existsSync(projectPath) && validateArtifact(projectPath, "project").ok;
+    }
+    if (unitType === "discuss-requirements") {
+        const requirementsPath = resolveExpectedArtifactPath(unitType, unitId, base);
+        return !!requirementsPath && existsSync(requirementsPath) && validateArtifact(requirementsPath, "requirements").ok;
+    }
+    if (unitType === "research-decision") {
+        return hasValidResearchDecision(base);
+    }
+    if (unitType === "research-project") {
+        return hasCompleteProjectResearch(base);
+    }
     // Reactive-execute: verify that each dispatched task's summary exists.
     // The unitId encodes the batch: "{mid}/{sid}/reactive+T02,T03"
     if (unitType === "reactive-execute") {
@@ -560,6 +641,9 @@ export function writeBlockerPlaceholder(unitType, unitId, base, reason) {
     const dir = dirname(absPath);
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true });
+    const recoveryLine = unitType === "research-project"
+        ? "This placeholder was written by auto-mode so the project research gate can stop fail-closed."
+        : "This placeholder was written by auto-mode so the pipeline can advance.";
     const content = [
         `# BLOCKER — auto-mode recovery failed`,
         ``,
@@ -567,7 +651,7 @@ export function writeBlockerPlaceholder(unitType, unitId, base, reason) {
         ``,
         `**Reason**: ${reason}`,
         ``,
-        `This placeholder was written by auto-mode so the pipeline can advance.`,
+        recoveryLine,
         `Review and replace this file before relying on downstream artifacts.`,
     ].join("\n");
     writeFileSync(absPath, content, "utf-8");

package/dist/resources/extensions/gsd/auto-runtime-state.js

@@ -0,0 +1,31 @@
+// GSD auto-mode runtime state
+import { AutoSession } from "./auto/session.js";
+import { isDeterministicPolicyError, isQueuedUserMessageSkip, isToolInvocationError, markToolEnd as markTrackedToolEnd, markToolStart as markTrackedToolStart, } from "./auto-tool-tracking.js";
+export const autoSession = new AutoSession();
+export function getAutoRuntimeSnapshot() {
+    return {
+        active: autoSession.active,
+        paused: autoSession.paused,
+        currentUnit: autoSession.currentUnit ? { ...autoSession.currentUnit } : null,
+        basePath: autoSession.basePath,
+    };
+}
+export function isAutoActive() {
+    return autoSession.active;
+}
+export function isAutoPaused() {
+    return autoSession.paused;
+}
+export function markToolStart(toolCallId, toolName) {
+    markTrackedToolStart(toolCallId, autoSession.active, toolName);
+}
+export function markToolEnd(toolCallId) {
+    markTrackedToolEnd(toolCallId);
+}
+export function recordToolInvocationError(toolName, errorMsg) {
+    if (!autoSession.active)
+        return;
+    if (isToolInvocationError(errorMsg) || isQueuedUserMessageSkip(errorMsg) || isDeterministicPolicyError(errorMsg)) {
+        autoSession.lastToolInvocationError = `${toolName}: ${errorMsg}`;
+    }
+}

package/dist/resources/extensions/gsd/auto-start.js

@@ -208,7 +208,7 @@ export function auditOrphanedMilestoneBranches(basePath, isolationMode) {
         else {
             // Branch is NOT merged — preserve for safety, warn the user
             warnings.push(`Branch ${branch} exists for completed milestone ${milestoneId} but is NOT merged into ${mainBranch}. ` +
-                `This may contain unmerged work. Merge manually or run \`/gsd health --fix\` to resolve.`);
+                `This may contain unmerged work. Merge manually or run \`/gsd doctor fix\` to resolve.`);
             // #4764 telemetry
             try {
                 emitWorktreeOrphaned(basePath, milestoneId, {
@@ -474,7 +474,17 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
             // Clear survivor flag — finalization is done
             hasSurvivorBranch = false;
         }
-        if (!hasSurvivorBranch) {
+        const deepProjectStagePending = !hasSurvivorBranch
+            ? (await import("./auto-dispatch.js")).hasPendingDeepStage(loadEffectiveGSDPreferences(base)?.preferences, base)
+            : false;
+        if (deepProjectStagePending) {
+            // Deep project-level setup runs before the first milestone exists. Let
+            // the auto loop dispatch workflow-preferences / project / requirements
+            // units instead of recursing back through showSmartEntry while this
+            // bootstrap still holds the session lock.
+            s.currentMilestoneId = null;
+        }
+        if (!hasSurvivorBranch && !deepProjectStagePending) {
             // No active work — start a new milestone via discuss flow
             if (!state.activeMilestone || state.phase === "complete") {
                 // Guard against recursive dialog loop (#1348):
@@ -536,7 +546,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
             }
         }
         // Unreachable safety check
-        if (!state.activeMilestone) {
+        if (!state.activeMilestone && !deepProjectStagePending) {
             const { showSmartEntry } = await import("./guided-flow.js");
             await showSmartEntry(ctx, pi, base, { step: requestedStepMode });
             return releaseLockAndReturn();
@@ -568,7 +578,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         s.resourceVersionOnStart = readResourceVersion();
         s.pendingQuickTasks = [];
         s.currentUnit = null;
-        s.currentMilestoneId = state.activeMilestone?.id ?? null;
+        s.currentMilestoneId = deepProjectStagePending ? null : state.activeMilestone?.id ?? null;
         s.originalModelId = startModelSnapshot?.id ?? ctx.model?.id ?? null;
         s.originalModelProvider = startModelSnapshot?.provider ?? ctx.model?.provider ?? null;
         s.originalThinkingLevel = startThinkingSnapshot ?? null;
@@ -713,10 +723,17 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         ctx.ui.setWidget("gsd-health", undefined);
         const modeLabel = s.stepMode ? "Step-mode" : "Auto-mode";
         const pendingCount = (state.registry ?? []).filter((m) => m.status !== "complete" && m.status !== "parked").length;
-        const scopeMsg = pendingCount > 1
-            ? `Will loop through ${pendingCount} milestones.`
-            : "Will loop until milestone complete.";
+        const scopeMsg = deepProjectStagePending
+            ? "Will run project setup before milestone planning."
+            : pendingCount > 1
+                ? `Will loop through ${pendingCount} milestones.`
+                : "Will loop until milestone complete.";
         ctx.ui.notify(`${modeLabel} started. ${scopeMsg}`, "info");
+        const providerReportedWindow = ctx.model?.contextWindow ?? 0;
+        const contextOverride = loadEffectiveGSDPreferences(base)?.preferences.context_window_override;
+        if (providerReportedWindow > 500_000 && contextOverride === undefined) {
+            ctx.ui.notify(`Model reports a ${Math.round(providerReportedWindow / 1000)}K context window. If the provider's real API limit is lower, set context_window_override in .gsd/PREFERENCES.md so wrap-up signals fire before context overflow.`, "warning");
+        }
         // Show dynamic routing status so users know upfront if models will be
         // downgraded for simple tasks (#3962).
         // Use the same effective logic as selectAndApplyModel: check flat-rate
@@ -749,24 +766,26 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         updateSessionLock(lockBase(), "starting", s.currentMilestoneId ?? "unknown");
         writeLock(lockBase(), "starting", s.currentMilestoneId ?? "unknown");
         // Secrets collection gate
-        const mid = state.activeMilestone.id;
-        try {
-            const manifestStatus = await getManifestStatus(base, mid, s.originalBasePath || base);
-            if (manifestStatus && manifestStatus.pending.length > 0) {
-                const result = await collectSecretsFromManifest(base, mid, ctx);
-                if (result &&
-                    result.applied &&
-                    result.skipped &&
-                    result.existingSkipped) {
-                    ctx.ui.notify(`Secrets collected: ${result.applied.length} applied, ${result.skipped.length} skipped, ${result.existingSkipped.length} already set.`, "info");
-                }
-                else {
-                    ctx.ui.notify("Secrets collection skipped.", "info");
+        const mid = state.activeMilestone?.id;
+        if (mid) {
+            try {
+                const manifestStatus = await getManifestStatus(base, mid, s.originalBasePath || base);
+                if (manifestStatus && manifestStatus.pending.length > 0) {
+                    const result = await collectSecretsFromManifest(base, mid, ctx);
+                    if (result &&
+                        result.applied &&
+                        result.skipped &&
+                        result.existingSkipped) {
+                        ctx.ui.notify(`Secrets collected: ${result.applied.length} applied, ${result.skipped.length} skipped, ${result.existingSkipped.length} already set.`, "info");
+                    }
+                    else {
+                        ctx.ui.notify("Secrets collection skipped.", "info");
+                    }
                 }
             }
-        }
-        catch (err) {
-            ctx.ui.notify(`Secrets collection error: ${err instanceof Error ? err.message : String(err)}. Continuing with next task.`, "warning");
+            catch (err) {
+                ctx.ui.notify(`Secrets collection error: ${err instanceof Error ? err.message : String(err)}. Continuing with next task.`, "warning");
+            }
         }
         // Self-heal: remove stale .git/index.lock.
         //

package/dist/resources/extensions/gsd/auto-timeout-recovery.js

@@ -7,6 +7,7 @@ import { readUnitRuntimeRecord, writeUnitRuntimeRecord, formatExecuteTaskRecover
 import { resolveExpectedArtifactPath, diagnoseExpectedArtifact, writeBlockerPlaceholder, } from "./auto-recovery.js";
 import { existsSync } from "node:fs";
 import { bumpAndResolveSynthetic } from "./auto/resolve.js";
+import { finalizeProjectResearchTimeout } from "./project-research-policy.js";
 export async function recoverTimedOutUnit(ctx, pi, unitType, unitId, reason, rctx) {
     // Note on turn epoch: the bump is intentionally NOT unconditional at
     // function entry. Two branches below (the "steering retry" paths) keep
@@ -110,6 +111,23 @@ export async function recoverTimedOutUnit(ctx, pi, unitType, unitId, reason, rct
         return "paused";
     }
     const expected = diagnoseExpectedArtifact(unitType, unitId, basePath) ?? "required durable artifact";
+    if (unitType === "research-project") {
+        const outcome = finalizeProjectResearchTimeout(basePath, `${reason} timeout recovery finalized project research before all dimensions completed.`);
+        writeUnitRuntimeRecord(basePath, unitType, unitId, currentUnitStartedAt, {
+            phase: outcome.kind === "global-blocker" ? "skipped" : "finalized",
+            recoveryAttempts: recoveryAttempts + 1,
+            lastRecoveryReason: reason,
+        });
+        const message = outcome.kind === "completed"
+            ? `Project research ${reason} timeout: research artifacts are already terminal; advancing.`
+            : outcome.kind === "partial-blockers"
+                ? `Project research ${reason} timeout: wrote blocker files for missing dimensions and advancing with partial research.`
+                : `Project research ${reason} timeout: wrote PROJECT-RESEARCH-BLOCKER.md and stopping fail-closed.`;
+        ctx.ui.notify(message, outcome.kind === "global-blocker" ? "error" : "warning");
+        unitRecoveryCount.delete(recoveryKey);
+        bumpAndResolveSynthetic(`timeout-recovery:${reason}:${unitType}/${unitId}`);
+        return "recovered";
+    }
     // Check if the artifact already exists on disk — agent may have written it
     // without signaling completion.
     const artifactPath = resolveExpectedArtifactPath(unitType, unitId, basePath);

package/dist/resources/extensions/gsd/auto-timers.js

@@ -16,6 +16,25 @@ import { saveActivityLog } from "./activity-log.js";
 import { recoverTimedOutUnit } from "./auto-timeout-recovery.js";
 import { resolveAgentEndCancelled } from "./auto/resolve.js";
 import { logWarning, logError } from "./workflow-logger.js";
+export const PROJECT_RESEARCH_SOFT_TIMEOUT_MINUTES = 3;
+export const PROJECT_RESEARCH_HARD_TIMEOUT_MINUTES = 5;
+export function resolveUnitSupervisionTimeouts(unitType, supervisor, timeoutScale) {
+    const softMinutes = supervisor.soft_timeout_minutes ?? 0;
+    const idleMinutes = supervisor.idle_timeout_minutes ?? 0;
+    const hardMinutes = supervisor.hard_timeout_minutes ?? 0;
+    if (unitType === "research-project") {
+        return {
+            softTimeoutMs: Math.min(softMinutes, PROJECT_RESEARCH_SOFT_TIMEOUT_MINUTES) * 60 * 1000,
+            idleTimeoutMs: idleMinutes * 60 * 1000,
+            hardTimeoutMs: Math.min(hardMinutes, PROJECT_RESEARCH_HARD_TIMEOUT_MINUTES) * 60 * 1000,
+        };
+    }
+    return {
+        softTimeoutMs: softMinutes * 60 * 1000 * timeoutScale,
+        idleTimeoutMs: idleMinutes * 60 * 1000,
+        hardTimeoutMs: hardMinutes * 60 * 1000 * timeoutScale,
+    };
+}
 /**
  * Set up all four supervision timers for the current unit:
  * 1. Soft timeout warning (wrapup)
@@ -81,9 +100,10 @@ export function startUnitSupervision(sctx) {
     const timeoutScale = estimateMinutes && estimateMinutes > 0
         ? Math.min(MAX_TIMEOUT_SCALE, Math.max(1, estimateMinutes / 10))
         : 1;
-    const softTimeoutMs = (supervisor.soft_timeout_minutes ?? 0) * 60 * 1000 * timeoutScale;
-    const idleTimeoutMs = (supervisor.idle_timeout_minutes ?? 0) * 60 * 1000; // idle not scaled — idle is idle
-    const hardTimeoutMs = (supervisor.hard_timeout_minutes ?? 0) * 60 * 1000 * timeoutScale;
+    const supervisionTimeouts = resolveUnitSupervisionTimeouts(unitType, supervisor, timeoutScale);
+    const softTimeoutMs = supervisionTimeouts.softTimeoutMs;
+    const idleTimeoutMs = supervisionTimeouts.idleTimeoutMs;
+    const hardTimeoutMs = supervisionTimeouts.hardTimeoutMs;
     // ── 1. Soft timeout warning ──
     s.wrapupWarningHandle = setTimeout(() => {
         s.wrapupWarningHandle = null;
@@ -233,7 +253,7 @@ export function startUnitSupervision(sctx) {
         clearInterval(s.continueHereHandle);
         s.continueHereHandle = null;
     }
-    const executorContextWindow = resolveExecutorContextWindow(ctx.modelRegistry, prefs, ctx.model?.contextWindow);
+    const executorContextWindow = resolveExecutorContextWindow(ctx.modelRegistry, prefs, ctx.model?.contextWindow, ctx.model?.provider);
     const continueHereThreshold = computeBudgets(executorContextWindow).continueThresholdPercent;
     s.continueHereHandle = setInterval(() => {
         if (!s.active || !s.currentUnit || !s.cmdCtx)

package/dist/resources/extensions/gsd/auto-tool-tracking.js

@@ -139,6 +139,6 @@ export const DETERMINISTIC_POLICY_ERROR_STRINGS = [
 export function isDeterministicPolicyError(errorMsg) {
     if (!errorMsg)
         return false;
-    return (DETERMINISTIC_POLICY_ERROR_RE.test(errorMsg) ||
-        DETERMINISTIC_POLICY_ERROR_STRINGS.some(s => errorMsg.includes(s)));
+    return DETERMINISTIC_POLICY_ERROR_RE.test(errorMsg)
+        || DETERMINISTIC_POLICY_ERROR_STRINGS.some(s => errorMsg.includes(s));
 }