gsd-pi 2.78.0 → 2.78.1-dev.0fdacd524

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

@@ -655,14 +655,25 @@ export const DISPATCH_RULES = [
                 return null;
             if (!state.activeSlice)
                 return null; // fall through
-            // Only activate when reactive_execution is explicitly enabled
+            // Reactive dispatch is on by default when there are enough ready tasks to
+            // benefit from parallelism. Users opt out explicitly via
+            // `reactive_execution.enabled: false`. The downstream safety checks
+            // (graph ambiguity, ready-task count, conflict-free selection) still gate
+            // every actual dispatch, so the worst-case "default-on" outcome is the
+            // same fall-through to sequential execution as before.
             const reactiveConfig = prefs?.reactive_execution;
-            if (!reactiveConfig?.enabled)
+            if (reactiveConfig?.enabled === false)
                 return null;
             const sid = state.activeSlice.id;
             const sTitle = state.activeSlice.title;
-            const maxParallel = reactiveConfig.max_parallel ?? 2;
-            const subagentModel = reactiveConfig.subagent_model ?? resolveModelWithFallbacksForUnit("subagent")?.primary;
+            const maxParallel = reactiveConfig?.max_parallel ?? 2;
+            const subagentModel = reactiveConfig?.subagent_model ?? resolveModelWithFallbacksForUnit("subagent")?.primary;
+            // Default-on safety threshold: only activate reactive dispatch when at
+            // least N tasks are ready. Users who explicitly enabled reactive_execution
+            // keep the legacy threshold of 2 (matches the prior "any parallelism is
+            // better than none" intent). Default-on installs require >=3 to avoid
+            // surprising users with parallelism on small slices.
+            const minReadyTasksForReactive = reactiveConfig?.enabled === true ? 2 : 3;
             // Dry-run mode: max_parallel=1 means graph is derived and logged but
             // execution remains sequential
             if (maxParallel <= 1)
@@ -678,8 +689,9 @@ export const DISPATCH_RULES = [
                     return null;
                 const completed = new Set(graph.filter((n) => n.done).map((n) => n.id));
                 const readyIds = getReadyTasks(graph, completed, new Set());
-                // Only activate reactive dispatch when >1 task is ready
-                if (readyIds.length <= 1)
+                // Only activate reactive dispatch when enough tasks are ready.
+                // Threshold is 2 when explicitly opted in, 3 when default-on.
+                if (readyIds.length < minReadyTasksForReactive)
                     return null;
                 const uokFlags = resolveUokFlags(prefs);
                 const selected = uokFlags.executionGraph

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
@@ -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,
@@ -2262,6 +2324,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 +2352,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 +2467,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";
@@ -168,8 +169,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 +241,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");

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, {

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));
 }

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

@@ -16,6 +16,7 @@ import { safeCopy, safeCopyRecursive } from "./safe-fs.js";
 import { gsdRoot } from "./paths.js";
 import { createWorktree, removeWorktree, resolveGitDir, worktreePath, isInsideWorktreesDir, } from "./worktree-manager.js";
 import { detectWorktreeName, nudgeGitBranchCache, } from "./worktree.js";
+import { isGsdWorktreePath, normalizeWorktreePathForCompare, resolveWorktreeProjectRoot, } from "./worktree-root.js";
 import { MergeConflictError, readIntegrationBranch, RUNTIME_EXCLUSION_PATHS } from "./git-service.js";
 import { debugLog } from "./debug-logger.js";
 import { logWarning, logError } from "./workflow-logger.js";
@@ -857,6 +858,11 @@ export function runWorktreePostCreateHook(sourceDir, worktreeDir, hookPath) {
 export function autoWorktreeBranch(milestoneId) {
     return `milestone/${milestoneId}`;
 }
+function normalizeLocalBranchRef(branch) {
+    return branch.startsWith("refs/heads/")
+        ? branch.slice("refs/heads/".length)
+        : branch;
+}
 // ─── Branch-mode Entry ─────────────────────────────────────────────────────
 /**
  * Enter branch isolation mode for a milestone.
@@ -1033,6 +1039,14 @@ function reconcilePlanCheckboxes(projectRoot, wtPath, milestoneId) {
     }
 }
 export function createAutoWorktree(basePath, milestoneId) {
+    basePath = resolveWorktreeProjectRoot(basePath);
+    // Check if repo has commits — git worktree requires a valid HEAD
+    try {
+        execFileSync("git", ["rev-parse", "--verify", "HEAD"], { cwd: basePath, stdio: "pipe" });
+    }
+    catch {
+        throw new GSDError(GSD_GIT_ERROR, `Cannot create worktree: repository has no commits yet. Worktree isolation requires at least one commit.`);
+    }
     const branch = autoWorktreeBranch(milestoneId);
     // Check if the milestone branch already exists — it survives auto-mode
     // stop/pause and contains committed work from prior sessions. If it exists,
@@ -1159,6 +1173,7 @@ function copyPlanningArtifacts(srcBase, wtPath) {
  * the worktree and its branch.
  */
 export function teardownAutoWorktree(originalBasePath, milestoneId, opts = {}) {
+    originalBasePath = resolveWorktreeProjectRoot(originalBasePath);
     const branch = autoWorktreeBranch(milestoneId);
     const { preserveBranch = false } = opts;
     const previousCwd = process.cwd();
@@ -1200,18 +1215,26 @@ export function teardownAutoWorktree(originalBasePath, milestoneId, opts = {}) {
 }
 /**
  * Detect if the process is currently inside an auto-worktree.
- * Checks both module state and git branch prefix.
+ * Uses the current directory structure plus git branch prefix so detection
+ * still works after process restart when module state has been reset.
  */
 export function isInAutoWorktree(basePath) {
-    if (!originalBase)
-        return false;
     const cwd = process.cwd();
-    const resolvedBase = existsSync(basePath) ? realpathSync(basePath) : basePath;
-    const wtDir = join(resolvedBase, ".gsd", "worktrees");
-    if (!cwd.startsWith(wtDir))
+    if (!isGsdWorktreePath(cwd))
         return false;
-    const branch = nativeGetCurrentBranch(cwd);
-    return branch.startsWith("milestone/");
+    const projectRoot = resolveWorktreeProjectRoot(basePath, originalBase);
+    const cwdProjectRoot = resolveWorktreeProjectRoot(cwd, originalBase);
+    if (normalizeWorktreePathForCompare(projectRoot) !==
+        normalizeWorktreePathForCompare(cwdProjectRoot)) {
+        return false;
+    }
+    try {
+        const branch = nativeGetCurrentBranch(cwd);
+        return branch.startsWith("milestone/");
+    }
+    catch {
+        return false;
+    }
 }
 /**
  * Get the filesystem path for an auto-worktree, or null if it doesn't exist
@@ -1222,6 +1245,7 @@ export function isInAutoWorktree(basePath) {
  * mis-detection of leftover directories as active worktrees (#695).
  */
 export function getAutoWorktreePath(basePath, milestoneId) {
+    basePath = resolveWorktreeProjectRoot(basePath);
     const p = worktreePath(basePath, milestoneId);
     if (!existsSync(p))
         return null;
@@ -1248,6 +1272,7 @@ export function getAutoWorktreePath(basePath, milestoneId) {
  * Atomic: chdir + originalBase update in same try block.
  */
 export function enterAutoWorktree(basePath, milestoneId) {
+    basePath = resolveWorktreeProjectRoot(basePath);
     const p = worktreePath(basePath, milestoneId);
     if (!existsSync(p)) {
         throw new GSDError(GSD_IO_ERROR, `Auto-worktree for ${milestoneId} does not exist at ${p}`);
@@ -1286,16 +1311,20 @@ export function enterAutoWorktree(basePath, milestoneId) {
 export function getAutoWorktreeOriginalBase() {
     return originalBase;
 }
+export function _resetAutoWorktreeOriginalBaseForTests() {
+    originalBase = null;
+}
 export function getActiveAutoWorktreeContext() {
     if (!originalBase)
         return null;
     const cwd = process.cwd();
-    const resolvedBase = existsSync(originalBase)
-        ? realpathSync(originalBase)
-        : originalBase;
-    const wtDir = join(resolvedBase, ".gsd", "worktrees");
-    if (!cwd.startsWith(wtDir))
+    if (!isGsdWorktreePath(cwd))
         return null;
+    const cwdProjectRoot = resolveWorktreeProjectRoot(cwd, originalBase);
+    if (normalizeWorktreePathForCompare(cwdProjectRoot) !==
+        normalizeWorktreePathForCompare(originalBase)) {
+        return null;
+    }
     const worktreeName = detectWorktreeName(cwd);
     if (!worktreeName)
         return null;
@@ -1408,6 +1437,10 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
         }
     }
     // 3. chdir to original base
+    // Note: previousCwd captures the cwd at this point — i.e. the worktree cwd
+    // entering the function. Subsequent throws restore to previousCwd, leaving
+    // the caller in worktree-cwd; callers (worktree-resolver) are responsible
+    // for any further cwd movement on the error path.
     const previousCwd = process.cwd();
     process.chdir(originalBasePath_);
     // 4. Resolve integration branch — prefer milestone metadata, then preferences,
@@ -1422,6 +1455,20 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
         ? prefs.main_branch
         : undefined;
     const mainBranch = integrationBranch ?? validatedPrefBranch ?? nativeDetectMainBranch(originalBasePath_);
+    // Fail closed when the resolved integration branch is the milestone branch
+    // itself (#5024). Stale or corrupt metadata (e.g. integrationBranch recorded
+    // as "milestone/<MID>") would otherwise let the squash merge resolve to a
+    // self-merge: nothing-to-commit + empty self-diff in the post-merge safety
+    // check (#1792) collapse to a false success, and the worktree-resolver
+    // emits worktree-merged for work that never landed on a distinct
+    // integration branch.
+    if (normalizeLocalBranchRef(mainBranch) === milestoneBranch) {
+        process.chdir(previousCwd);
+        throw new GSDError(GSD_GIT_ERROR, `Resolved integration branch "${mainBranch}" is the same ref as milestone branch ` +
+            `"${milestoneBranch}" — refusing to self-merge. Integration branch metadata is invalid; ` +
+            `set a distinct main_branch in GSD preferences or repair the milestone integration record ` +
+            `before retrying milestone completion.`);
+    }
     // Remove transient project-root state files before any branch or merge
     // operation. Untracked milestone metadata can otherwise block squash merges.
     clearProjectRootStateFiles(originalBasePath_, milestoneId);

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

@@ -80,13 +80,12 @@ import { runAutoLoopWithUok } from "./uok/kernel.js";
 import { resolveUokFlags } from "./uok/flags.js";
 import { WorktreeResolver, } from "./worktree-resolver.js";
 import { reorderForCaching } from "./prompt-ordering.js";
-// ─── Session State ─────────────────────────────────────────────────────────
-import { AutoSession, } from "./auto/session.js";
 export { STUB_RECOVERY_THRESHOLD, NEW_SESSION_TIMEOUT_MS, } from "./auto/session.js";
+import { autoSession as s } from "./auto-runtime-state.js";
 // ── ENCAPSULATION INVARIANT ─────────────────────────────────────────────────
 // ALL mutable auto-mode state lives in the AutoSession class (auto/session.ts).
 // This file must NOT declare module-level `let` or `var` variables for state.
-// The single `s` instance below is the only mutable module-level binding.
+// The single shared `s` instance below is the only mutable AutoSession binding.
 //
 // When adding features or fixing bugs:
 //   - New mutable state → add a property to AutoSession, not a module-level variable
@@ -95,7 +94,6 @@ export { STUB_RECOVERY_THRESHOLD, NEW_SESSION_TIMEOUT_MS, } from "./auto/session
 //
 // Tests in auto-session-encapsulation.test.ts enforce this invariant.
 // ─────────────────────────────────────────────────────────────────────────────
-const s = new AutoSession();
 /** Throttle STATE.md rebuilds — at most once per 30 seconds */
 const STATE_REBUILD_MIN_INTERVAL_MS = 30_000;
 function captureProjectRootEnv(projectRoot) {
@@ -1408,10 +1406,21 @@ const widgetStateAccessors = {
  * Ensure directories, branches, and other prerequisites exist before
  * dispatching a unit. The LLM should never need to mkdir or git checkout.
  */
-function ensurePreconditions(unitType, unitId, base, state) {
+export function ensurePreconditions(unitType, unitId, base, state) {
     const { milestone: mid, slice: sid } = parseUnitId(unitId);
     const mDir = resolveMilestonePath(base, mid);
     if (!mDir) {
+        // Fix #4996: When dispatching a slice unit against an unrecognised milestone,
+        // only create the directory if the milestone has a DB row.
+        // Without this guard, forward-referenced unit IDs (e.g. from REQUIREMENTS.md)
+        // silently scaffold empty stub directories that later skew nextMilestoneId.
+        if (sid !== undefined) {
+            const hasDbRow = isDbAvailable() && getMilestone(mid) != null;
+            if (!hasDbRow) {
+                logWarning("engine", `ensurePreconditions: skipping mkdir for unrecognised milestone ${mid} referenced by slice unit ${unitId} — no DB row exists`, { file: "auto.ts" });
+                return;
+            }
+        }
         const newDir = join(milestonesDir(base), mid);
         mkdirSync(join(newDir, "slices"), { recursive: true });
     }
@@ -1432,15 +1441,18 @@ function ensurePreconditions(unitType, unitId, base, state) {
     }
 }
 export async function dispatchHookUnit(ctx, pi, hookName, triggerUnitType, triggerUnitId, hookPrompt, hookModel, targetBasePath) {
+    const wasActive = s.active;
+    const previousBasePath = s.basePath;
+    const previousCurrentUnit = s.currentUnit ? { ...s.currentUnit } : null;
     if (!s.active) {
         s.active = true;
         s.stepMode = true;
         s.cmdCtx = ctx;
-        s.basePath = targetBasePath;
         s.autoStartTime = Date.now();
         s.currentUnit = null;
         s.pendingQuickTasks = [];
     }
+    s.basePath = targetBasePath;
     const hookUnitType = `hook/${hookName}`;
     const hookStartedAt = Date.now();
     s.currentUnit = {
@@ -1448,6 +1460,27 @@ export async function dispatchHookUnit(ctx, pi, hookName, triggerUnitType, trigg
         id: triggerUnitId,
         startedAt: hookStartedAt,
     };
+    // Ensure cwd matches basePath BEFORE newSession() captures it (#1389).
+    // newSession() snapshots process.cwd() during construction; chdir-ing
+    // afterward leaves the session rooted to whatever cwd was when the call
+    // was made. Must be synchronous — no awaits between chdir and newSession.
+    try {
+        if (process.cwd() !== s.basePath)
+            process.chdir(s.basePath);
+    }
+    catch (err) {
+        const msg = `Failed to chdir before hook newSession (basePath: ${s.basePath}): ${err instanceof Error ? err.message : String(err)}`;
+        logWarning("engine", msg, { file: "auto.ts", basePath: s.basePath, error: err instanceof Error ? err.message : String(err) });
+        ctx.ui.notify(`${msg}. Cancelling hook dispatch to avoid running in the wrong directory.`, "error");
+        if (wasActive) {
+            s.basePath = previousBasePath;
+            s.currentUnit = previousCurrentUnit;
+        }
+        else {
+            s.reset();
+        }
+        return false;
+    }
     const result = await s.cmdCtx.newSession();
     if (result.cancelled) {
         await stopAuto(ctx, pi);
@@ -1490,14 +1523,6 @@ export async function dispatchHookUnit(ctx, pi, hookName, triggerUnitType, trigg
     }, hookHardTimeoutMs);
     ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
     ctx.ui.notify(`Running post-unit hook: ${hookName}`, "info");
-    // Ensure cwd matches basePath before hook dispatch (#1389)
-    try {
-        if (process.cwd() !== s.basePath)
-            process.chdir(s.basePath);
-    }
-    catch (err) {
-        logWarning("engine", `chdir failed before hook dispatch: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
-    }
     debugLog("dispatchHookUnit", {
         phase: "send-message",
         promptLength: hookPrompt.length,

package/dist/resources/extensions/gsd/bootstrap/db-tools.js

@@ -1,11 +1,12 @@
 import { Type } from "@sinclair/typebox";
 import { Text } from "@gsd/pi-tui";
-import { findMilestoneIds, nextMilestoneId, claimReservedId, getReservedMilestoneIds } from "../guided-flow.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { ensureDbOpen } from "./dynamic-tools.js";
 import { StringEnum } from "@gsd/pi-ai";
 import { logError } from "../workflow-logger.js";
-import { executeCompleteMilestone, executePlanMilestone, executePlanSlice, executeReplanSlice, executeReassessRoadmap, executeSaveGateResult, executeSliceComplete, executeSummarySave, executeTaskComplete, executeValidateMilestone, } from "../tools/workflow-tool-executors.js";
+async function loadWorkflowExecutors() {
+    return import("../tools/workflow-tool-executors.js");
+}
 /**
  * Register an alias tool that shares the same execute function as its canonical counterpart.
  * The alias description and promptGuidelines direct the LLM to prefer the canonical name.
@@ -280,6 +281,7 @@ export function registerDbTools(pi) {
     registerAlias(pi, requirementSaveTool, "gsd_save_requirement", "gsd_requirement_save");
     // ─── gsd_summary_save (formerly gsd_save_summary) ──────────────────────
     const summarySaveExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const { executeSummarySave } = await loadWorkflowExecutors();
         return executeSummarySave(params, process.cwd());
     };
     const summarySaveTool = {
@@ -330,6 +332,7 @@ export function registerDbTools(pi) {
         try {
             // Claim a reserved ID if the guided-flow already previewed one to the user.
             // This guarantees the ID shown in the UI matches the one materialised on disk.
+            const { claimReservedId, findMilestoneIds, getReservedMilestoneIds, nextMilestoneId } = await import("../guided-flow.js");
             const reserved = claimReservedId();
             if (reserved) {
                 await ensureMilestoneDbRow(reserved);
@@ -408,6 +411,7 @@ export function registerDbTools(pi) {
     registerAlias(pi, milestoneGenerateIdTool, "gsd_generate_milestone_id", "gsd_milestone_generate_id");
     // ─── gsd_plan_milestone (gsd_milestone_plan alias) ─────────────────────
     const planMilestoneExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const { executePlanMilestone } = await loadWorkflowExecutors();
         return executePlanMilestone(params, process.cwd());
     };
     const planMilestoneTool = {
@@ -472,6 +476,7 @@ export function registerDbTools(pi) {
     registerAlias(pi, planMilestoneTool, "gsd_milestone_plan", "gsd_plan_milestone");
     // ─── gsd_plan_slice (gsd_slice_plan alias) ─────────────────────────────
     const planSliceExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const { executePlanSlice } = await loadWorkflowExecutors();
         return executePlanSlice(params, process.cwd());
     };
     const planSliceTool = {
@@ -585,6 +590,7 @@ export function registerDbTools(pi) {
     registerAlias(pi, planTaskTool, "gsd_task_plan", "gsd_plan_task");
     // ─── gsd_task_complete (gsd_complete_task alias) ────────────────────────
     const taskCompleteExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const { executeTaskComplete } = await loadWorkflowExecutors();
         return executeTaskComplete(params, process.cwd());
     };
     const taskCompleteTool = {
@@ -647,6 +653,7 @@ export function registerDbTools(pi) {
     registerAlias(pi, taskCompleteTool, "gsd_complete_task", "gsd_task_complete");
     // ─── gsd_slice_complete (gsd_complete_slice alias) ─────────────────────
     const sliceCompleteExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const { executeSliceComplete } = await loadWorkflowExecutors();
         return executeSliceComplete(params, process.cwd());
     };
     const sliceCompleteTool = {
@@ -811,6 +818,7 @@ export function registerDbTools(pi) {
     });
     // ─── gsd_complete_milestone ────────────────────────────────────────────
     const milestoneCompleteExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const { executeCompleteMilestone } = await loadWorkflowExecutors();
         return executeCompleteMilestone(params, process.cwd());
     };
     const milestoneCompleteTool = {
@@ -851,6 +859,7 @@ export function registerDbTools(pi) {
     registerAlias(pi, milestoneCompleteTool, "gsd_milestone_complete", "gsd_complete_milestone");
     // ─── gsd_validate_milestone (gsd_milestone_validate alias) ─────────────
     const milestoneValidateExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const { executeValidateMilestone } = await loadWorkflowExecutors();
         return executeValidateMilestone(params, process.cwd());
     };
     const milestoneValidateTool = {
@@ -883,6 +892,7 @@ export function registerDbTools(pi) {
     registerAlias(pi, milestoneValidateTool, "gsd_milestone_validate", "gsd_validate_milestone");
     // ─── gsd_replan_slice (gsd_slice_replan alias) ─────────────────────────
     const replanSliceExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const { executeReplanSlice } = await loadWorkflowExecutors();
         return executeReplanSlice(params, process.cwd());
     };
     const replanSliceTool = {
@@ -925,6 +935,7 @@ export function registerDbTools(pi) {
     registerAlias(pi, replanSliceTool, "gsd_slice_replan", "gsd_replan_slice");
     // ─── gsd_reassess_roadmap (gsd_roadmap_reassess alias) ─────────────────
     const reassessRoadmapExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const { executeReassessRoadmap } = await loadWorkflowExecutors();
         return executeReassessRoadmap(params, process.cwd());
     };
     const reassessRoadmapTool = {
@@ -1157,6 +1168,7 @@ export function registerDbTools(pi) {
     registerAlias(pi, reopenMilestoneTool, "gsd_reopen_milestone", "gsd_milestone_reopen");
     // ─── gsd_save_gate_result ──────────────────────────────────────────────
     const saveGateResultExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const { executeSaveGateResult } = await loadWorkflowExecutors();
         return executeSaveGateResult(params, process.cwd());
     };
     const saveGateResultTool = {