gsd-pi 2.29.0-dev.2ccf3fb → 2.29.0-dev.4c155ee

package/src/resources/extensions/gsd/auto-prompts.ts

@@ -530,11 +530,21 @@ export async function checkNeedsRunUat(
   const uatContent = await loadFile(uatFile);
   if (!uatContent) return null;
 
-  // If UAT result already exists, skip (idempotent)
+  // If UAT result already exists with a PASS verdict, skip (idempotent).
+  // Non-PASS verdicts (FAIL, surfaced-for-human-review) should block slice
+  // progression — return the slice for re-evaluation (#1231).
   const uatResultFile = resolveSliceFile(base, mid, sid, "UAT-RESULT");
   if (uatResultFile) {
-    const hasResult = !!(await loadFile(uatResultFile));
-    if (hasResult) return null;
+    const resultContent = await loadFile(uatResultFile);
+    if (resultContent) {
+      const verdictMatch = resultContent.match(/verdict:\s*([\w-]+)/i);
+      const verdict = verdictMatch?.[1]?.toLowerCase();
+      if (verdict === "pass" || verdict === "passed") return null; // PASS — skip
+      // Non-PASS verdict exists — don't re-run UAT, but don't advance either.
+      // Return null here since the UAT already ran; the dispatch table's
+      // complete-slice rule should check the verdict before advancing.
+      // For now, returning the slice signals it still needs attention.
+    }
   }
 
   // Classify UAT type; unknown type → treat as human-experience (human review)
@@ -589,14 +599,18 @@ export async function buildPlanMilestonePrompt(mid: string, midTitle: string, ba
   const { inlinePriorMilestoneSummary } = await import("./files.js");
   const priorSummaryInline = await inlinePriorMilestoneSummary(mid, base);
   if (priorSummaryInline) inlined.push(priorSummaryInline);
-  if (inlineLevel !== "minimal") {
-    const projectInline = await inlineProjectFromDb(base);
-    if (projectInline) inlined.push(projectInline);
-    const requirementsInline = await inlineRequirementsFromDb(base, undefined, inlineLevel);
-    if (requirementsInline) inlined.push(requirementsInline);
-    const decisionsInline = await inlineDecisionsFromDb(base, mid, undefined, inlineLevel);
-    if (decisionsInline) inlined.push(decisionsInline);
-  }
+  // Build source file paths for the planner to read on demand (reduces inlining)
+  const sourcePaths: string[] = [];
+  if (existsSync(resolveGsdRootFile(base, "PROJECT")))
+    sourcePaths.push(`- **Project**: \`${relGsdRootFile("PROJECT")}\``);
+  if (existsSync(resolveGsdRootFile(base, "REQUIREMENTS")))
+    sourcePaths.push(`- **Requirements**: \`${relGsdRootFile("REQUIREMENTS")}\``);
+  if (existsSync(resolveGsdRootFile(base, "DECISIONS")))
+    sourcePaths.push(`- **Decisions**: \`${relGsdRootFile("DECISIONS")}\``);
+  const sourceFilePaths = sourcePaths.length > 0
+    ? sourcePaths.join("\n")
+    : "_No project/requirements/decisions files found._";
+
   const knowledgeInlinePM = await inlineGsdRootFile(base, "knowledge.md", "Project Knowledge");
   if (knowledgeInlinePM) inlined.push(knowledgeInlinePM);
   inlined.push(inlineTemplate("roadmap", "Roadmap"));
@@ -615,6 +629,7 @@ export async function buildPlanMilestonePrompt(mid: string, midTitle: string, ba
 
   const outputRelPath = relMilestoneFile(base, mid, "ROADMAP");
   const secretsOutputPath = join(base, relMilestoneFile(base, mid, "SECRETS"));
+  const researchOutputRelPath = relMilestoneFile(base, mid, "RESEARCH");
   return loadPrompt("plan-milestone", {
     workingDirectory: base,
     milestoneId: mid, milestoneTitle: midTitle,
@@ -624,6 +639,9 @@ export async function buildPlanMilestonePrompt(mid: string, midTitle: string, ba
     outputPath: join(base, outputRelPath),
     secretsOutputPath,
     inlinedContext,
+    sourceFilePaths,
+    researchOutputPath: join(base, researchOutputRelPath),
+    ...buildSkillDiscoveryVars(),
   });
 }
 
@@ -686,12 +704,16 @@ export async function buildPlanSlicePrompt(
   inlined.push(await inlineFile(roadmapPath, roadmapRel, "Milestone Roadmap"));
   const researchInline = await inlineFileOptional(researchPath, researchRel, "Slice Research");
   if (researchInline) inlined.push(researchInline);
-  if (inlineLevel !== "minimal") {
-    const decisionsInline = await inlineDecisionsFromDb(base, mid, undefined, inlineLevel);
-    if (decisionsInline) inlined.push(decisionsInline);
-    const requirementsInline = await inlineRequirementsFromDb(base, sid, inlineLevel);
-    if (requirementsInline) inlined.push(requirementsInline);
-  }
+  // Build source file paths for the planner to read on demand (reduces inlining)
+  const sliceSourcePaths: string[] = [];
+  if (existsSync(resolveGsdRootFile(base, "REQUIREMENTS")))
+    sliceSourcePaths.push(`- **Requirements**: \`${relGsdRootFile("REQUIREMENTS")}\``);
+  if (existsSync(resolveGsdRootFile(base, "DECISIONS")))
+    sliceSourcePaths.push(`- **Decisions**: \`${relGsdRootFile("DECISIONS")}\``);
+  const sliceSourceFilePaths = sliceSourcePaths.length > 0
+    ? sliceSourcePaths.join("\n")
+    : "_No requirements/decisions files found._";
+
   const knowledgeInlinePS = await inlineGsdRootFile(base, "knowledge.md", "Project Knowledge");
   if (knowledgeInlinePS) inlined.push(knowledgeInlinePS);
   inlined.push(inlineTemplate("plan", "Slice Plan"));
@@ -726,6 +748,7 @@ export async function buildPlanSlicePrompt(
     dependencySummaries: depContent,
     executorContextConstraints,
     commitInstruction,
+    sourceFilePaths: sliceSourceFilePaths,
   });
 }
 

package/src/resources/extensions/gsd/auto-recovery.ts

@@ -35,6 +35,7 @@ import {
   resolveMilestoneFile,
   clearPathCache,
   resolveGsdRootFile,
+  gsdRoot,
 } from "./paths.js";
 import { isValidationTerminal } from "./state.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
@@ -361,7 +362,7 @@ function isStringArray(data: unknown): data is string[] {
 
 /** Path to the persisted completed-unit keys file. */
 export function completedKeysPath(base: string): string {
-  return join(base, ".gsd", "completed-units.json");
+  return join(gsdRoot(base), "completed-units.json");
 }
 
 /** Write a completed unit key to disk (read-modify-write append to set). */

package/src/resources/extensions/gsd/auto-start.ts

@@ -16,6 +16,8 @@ import type {
 import { deriveState } from "./state.js";
 import { loadFile, getManifestStatus } from "./files.js";
 import { loadEffectiveGSDPreferences, resolveSkillDiscoveryMode, getIsolationMode } from "./preferences.js";
+import { isInsideWorktree, ensureGsdSymlink } from "./repo-identity.js";
+import { migrateToExternalState, recoverFailedMigration } from "./migrate-external.js";
 import { sendDesktopNotification } from "./notifications.js";
 import { sendRemoteNotification } from "../remote-questions/notify.js";
 import {
@@ -48,7 +50,7 @@ import {
   getAutoWorktreePath,
   isInAutoWorktree,
 } from "./auto-worktree.js";
-import { readResourceVersion } from "./auto-worktree-sync.js";
+import { readResourceVersion } from "./resource-version.js";
 import { initMetrics, getLedger } from "./metrics.js";
 import { initRoutingHistory } from "./routing-history.js";
 import { restoreHookState, resetHookState, clearPersistedHookState } from "./post-unit-hooks.js";
@@ -61,7 +63,6 @@ import { debugLog, enableDebug, isDebugEnabled, getDebugLogPath } from "./debug-
 import type { AutoSession } from "./auto/session.js";
 import { existsSync, mkdirSync, readdirSync, statSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
-import { sep as pathSep } from "node:path";
 
 export interface BootstrapDeps {
   shouldUseWorktreeIsolation: () => boolean;
@@ -113,8 +114,17 @@ export async function bootstrapAutoSession(
   ensureGitignore(base, { commitDocs, manageGitignore });
   if (manageGitignore !== false) untrackRuntimeFiles(base);
 
+  // Migrate legacy in-project .gsd/ to external state directory
+  recoverFailedMigration(base);
+  const migration = migrateToExternalState(base);
+  if (migration.error) {
+    ctx.ui.notify(`External state migration warning: ${migration.error}`, "warning");
+  }
+  // Ensure symlink exists (handles fresh projects and post-migration)
+  ensureGsdSymlink(base);
+
   // Bootstrap .gsd/ if it doesn't exist
-  const gsdDir = join(base, ".gsd");
+  const gsdDir = gsdRoot(base);
   if (!existsSync(gsdDir)) {
     mkdirSync(join(gsdDir, "milestones"), { recursive: true });
     if (commitDocs !== false) {
@@ -204,18 +214,6 @@ export async function bootstrapAutoSession(
 
   let state = await deriveState(base);
 
-  // Stale worktree state recovery (#654)
-  if (
-    state.activeMilestone &&
-    shouldUseWorktreeIsolation() &&
-    !detectWorktreeName(base)
-  ) {
-    const wtPath = getAutoWorktreePath(base, state.activeMilestone.id);
-    if (wtPath) {
-      state = await deriveState(wtPath);
-    }
-  }
-
   // Milestone branch recovery (#601)
   let hasSurvivorBranch = false;
   if (
@@ -223,7 +221,7 @@ export async function bootstrapAutoSession(
     (state.phase === "pre-planning" || state.phase === "needs-discussion") &&
     shouldUseWorktreeIsolation() &&
     !detectWorktreeName(base) &&
-    !base.includes(`${pathSep}.gsd${pathSep}worktrees${pathSep}`)
+    !isInsideWorktree(base)
   ) {
     const milestoneBranch = `milestone/${state.activeMilestone.id}`;
     const { nativeBranchExists } = await import("./native-git-bridge.js");
@@ -333,14 +331,7 @@ export async function bootstrapAutoSession(
   // ── Auto-worktree setup ──
   s.originalBasePath = base;
 
-  const isUnderGsdWorktrees = (p: string): boolean => {
-    const marker = `${pathSep}.gsd${pathSep}worktrees${pathSep}`;
-    if (p.includes(marker)) return true;
-    const worktreesSuffix = `${pathSep}.gsd${pathSep}worktrees`;
-    return p.endsWith(worktreesSuffix);
-  };
-
-  if (s.currentMilestoneId && shouldUseWorktreeIsolation() && !detectWorktreeName(base) && !isUnderGsdWorktrees(base)) {
+  if (s.currentMilestoneId && shouldUseWorktreeIsolation() && !detectWorktreeName(base) && !isInsideWorktree(base)) {
     try {
       const existingWtPath = getAutoWorktreePath(base, s.currentMilestoneId);
       if (existingWtPath) {
@@ -355,11 +346,6 @@ export async function bootstrapAutoSession(
         ctx.ui.notify(`Created auto-worktree at ${wtPath}`, "info");
       }
       registerSigtermHandler(s.originalBasePath);
-
-      // Load completed keys from BOTH locations
-      if (s.basePath !== s.originalBasePath) {
-        loadPersistedKeys(s.basePath, s.completedKeySet);
-      }
     } catch (err) {
       ctx.ui.notify(
         `Auto-worktree setup failed: ${err instanceof Error ? err.message : String(err)}. Continuing in project root.`,
@@ -369,8 +355,8 @@ export async function bootstrapAutoSession(
   }
 
   // ── DB lifecycle ──
-  const gsdDbPath = join(s.basePath, ".gsd", "gsd.db");
-  const gsdDirPath = join(s.basePath, ".gsd");
+  const gsdDbPath = join(gsdRoot(s.basePath), "gsd.db");
+  const gsdDirPath = gsdRoot(s.basePath);
   if (existsSync(gsdDirPath) && !existsSync(gsdDbPath)) {
     const hasDecisions = existsSync(join(gsdDirPath, "DECISIONS.md"));
     const hasRequirements = existsSync(join(gsdDirPath, "REQUIREMENTS.md"));
@@ -476,7 +462,7 @@ export async function bootstrapAutoSession(
 
   // Pre-flight: validate milestone queue
   try {
-    const msDir = join(base, ".gsd", "milestones");
+    const msDir = join(gsdRoot(base), "milestones");
     if (existsSync(msDir)) {
       const milestoneIds = readdirSync(msDir, { withFileTypes: true })
         .filter(d => d.isDirectory() && /^M\d{3}/.test(d.name))

package/src/resources/extensions/gsd/auto-worktree.ts

@@ -6,25 +6,24 @@
  * manages create, enter, detect, and teardown for auto-mode worktrees.
  */
 
-import { existsSync, cpSync, readFileSync, readdirSync, mkdirSync, realpathSync, unlinkSync, statSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, unlinkSync, statSync } from "node:fs";
 import { isAbsolute, join, sep } from "node:path";
 import { GSDError, GSD_IO_ERROR, GSD_GIT_ERROR } from "./errors.js";
-import { copyWorktreeDb, reconcileWorktreeDb, isDbAvailable } from "./gsd-db.js";
-import { atomicWriteSync } from "./atomic-write.js";
 import { execSync, execFileSync } from "node:child_process";
-import { safeCopy, safeCopyRecursive } from "./safe-fs.js";
 import {
   createWorktree,
   removeWorktree,
   worktreePath,
 } from "./worktree-manager.js";
 import { detectWorktreeName, resolveGitHeadPath, nudgeGitBranchCache } from "./worktree.js";
+import { ensureGsdSymlink } from "./repo-identity.js";
 import {
   MergeConflictError,
   readIntegrationBranch,
 } from "./git-service.js";
 import { parseRoadmap } from "./files.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { gsdRoot } from "./paths.js";
 import {
   nativeGetCurrentBranch,
   nativeWorkingTreeStatus,
@@ -103,111 +102,6 @@ export function autoWorktreeBranch(milestoneId: string): string {
  * to prevent split-brain.
  */
 
-/**
- * Forward-merge plan checkbox state from the project root into a freshly
- * re-attached worktree (#778).
- *
- * When auto-mode stops via crash (not graceful stop), the milestone branch
- * HEAD may be behind the filesystem state at the project root because
- * syncStateToProjectRoot() runs after every task completion but the final
- * git commit may not have happened before the crash. On restart the worktree
- * is re-attached to the branch HEAD, which has [ ] for the crashed task,
- * causing verifyExpectedArtifact() to fail and triggering an infinite
- * dispatch/skip loop.
- *
- * Fix: after re-attaching, read every *.md plan file in the milestone
- * directory at the project root and apply any [x] checkbox states that are
- * ahead of the worktree version (forward-only: never downgrade [x] → [ ]).
- *
- * This is safe because syncStateToProjectRoot() is the authoritative source
- * of post-task state at the project root — it writes the same [x] the LLM
- * produced, then the auto-commit follows. If the commit never happened, the
- * filesystem copy is still valid and correct.
- */
-function reconcilePlanCheckboxes(projectRoot: string, wtPath: string, milestoneId: string): void {
-  const srcMilestone = join(projectRoot, ".gsd", "milestones", milestoneId);
-  const dstMilestone = join(wtPath, ".gsd", "milestones", milestoneId);
-  if (!existsSync(srcMilestone) || !existsSync(dstMilestone)) return;
-
-  // Walk all markdown files in the milestone directory (plans, summaries, etc.)
-  function walkMd(dir: string): string[] {
-    const results: string[] = [];
-    try {
-      for (const entry of readdirSync(dir, { withFileTypes: true })) {
-        const full = join(dir, entry.name);
-        if (entry.isDirectory()) {
-          results.push(...walkMd(full));
-        } else if (entry.isFile() && entry.name.endsWith(".md")) {
-          results.push(full);
-        }
-      }
-    } catch { /* non-fatal */ }
-    return results;
-  }
-
-  for (const srcFile of walkMd(srcMilestone)) {
-    const rel = srcFile.slice(srcMilestone.length);
-    const dstFile = dstMilestone + rel;
-    if (!existsSync(dstFile)) continue; // only reconcile existing files
-
-    let srcContent: string;
-    let dstContent: string;
-    try {
-      srcContent = readFileSync(srcFile, "utf-8");
-      dstContent = readFileSync(dstFile, "utf-8");
-    } catch { continue; }
-
-    if (srcContent === dstContent) continue;
-
-    // Extract all checked task IDs from the source (project root)
-    // Pattern: - [x] **T<id>: or - [x] **S<id>: (case-insensitive x)
-    const checkedRe = /^- \[[xX]\] \*\*([TS]\d+):/gm;
-    const srcChecked = new Set<string>();
-    for (const m of srcContent.matchAll(checkedRe)) srcChecked.add(m[1]);
-
-    if (srcChecked.size === 0) continue;
-
-    // Forward-apply: replace [ ] → [x] for any IDs that are checked in src
-    let updated = dstContent;
-    let changed = false;
-    for (const id of srcChecked) {
-      const escapedId = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-      const uncheckedRe = new RegExp(`^(- )\\[ \\]( \\*\\*${escapedId}:)`, "gm");
-      if (uncheckedRe.test(updated)) {
-        updated = updated.replace(
-          new RegExp(`^(- )\\[ \\]( \\*\\*${escapedId}:)`, "gm"),
-          "$1[x]$2",
-        );
-        changed = true;
-      }
-    }
-
-    if (changed) {
-      try {
-        atomicWriteSync(dstFile, updated, "utf-8");
-      } catch { /* non-fatal */ }
-    }
-  }
-
-  // Also forward-merge completed-units.json (set-union)
-  const srcKeys = join(projectRoot, ".gsd", "completed-units.json");
-  const dstKeys = join(wtPath, ".gsd", "completed-units.json");
-  if (existsSync(srcKeys)) {
-    try {
-      const src: string[] = JSON.parse(readFileSync(srcKeys, "utf-8"));
-      let dst: string[] = [];
-      if (existsSync(dstKeys)) {
-        try { dst = JSON.parse(readFileSync(dstKeys, "utf-8")); } catch { /* ignore corrupt */ }
-      }
-      const merged = [...new Set([...dst, ...src])];
-      if (merged.length > dst.length) {
-        mkdirSync(join(wtPath, ".gsd"), { recursive: true });
-        atomicWriteSync(dstKeys, JSON.stringify(merged), "utf-8");
-      }
-    } catch { /* non-fatal */ }
-  }
-}
-
 export function createAutoWorktree(basePath: string, milestoneId: string): string {
   const branch = autoWorktreeBranch(milestoneId);
 
@@ -227,32 +121,8 @@ export function createAutoWorktree(basePath: string, milestoneId: string): strin
     info = createWorktree(basePath, milestoneId, { branch, startPoint: integrationBranch });
   }
 
-  // Copy .gsd/ planning artifacts from the source repo into the new worktree.
-  // Worktrees are fresh git checkouts — untracked files don't carry over.
-  // Planning artifacts may be untracked if the project's .gitignore had a
-  // blanket .gsd/ rule (pre-v2.14.0). Without this copy, auto-mode loops
-  // on plan-slice because the plan file doesn't exist in the worktree.
-  //
-  // IMPORTANT: Skip when re-attaching to an existing branch (#759).
-  // The branch checkout already has committed artifacts with correct state
-  // (e.g. [x] for completed slices). Copying from the project root would
-  // overwrite them with stale data ([ ] checkboxes) because the root is
-  // not always fully synced.
-  if (!branchExists) {
-    copyPlanningArtifacts(basePath, info.path);
-  } else {
-    // Re-attaching to an existing branch: forward-merge any plan checkpoint
-    // state from the project root into the worktree (#778).
-    //
-    // If auto-mode stopped via crash, the milestone branch HEAD may lag behind
-    // the project root filesystem because syncStateToProjectRoot() ran after
-    // task completion but the auto-commit never fired. On restart the worktree
-    // is re-created from the branch HEAD (which has [ ] for the crashed task),
-    // causing verifyExpectedArtifact() to return false → stale-key eviction →
-    // infinite dispatch/skip loop. Reconciling here ensures the worktree sees
-    // the same [x] state that syncStateToProjectRoot() wrote to the root.
-    reconcilePlanCheckboxes(basePath, info.path, milestoneId);
-  }
+  // Ensure worktree shares external state via symlink
+  ensureGsdSymlink(info.path);
 
   // Run user-configured post-create hook (#597) — e.g. copy .env, symlink assets
   const hookError = runWorktreePostCreateHook(basePath, info.path);
@@ -279,36 +149,6 @@ export function createAutoWorktree(basePath: string, milestoneId: string): strin
   return info.path;
 }
 
-/**
- * Copy .gsd/ planning artifacts from source repo to a new worktree.
- * Copies milestones/, DECISIONS.md, REQUIREMENTS.md, PROJECT.md, QUEUE.md,
- * STATE.md, KNOWLEDGE.md, and OVERRIDES.md.
- * Skips runtime files (auto.lock, metrics.json, etc.) and the worktrees/ dir.
- * Best-effort — failures are non-fatal since auto-mode can recreate artifacts.
- */
-function copyPlanningArtifacts(srcBase: string, wtPath: string): void {
-  const srcGsd = join(srcBase, ".gsd");
-  const dstGsd = join(wtPath, ".gsd");
-  if (!existsSync(srcGsd)) return;
-
-  // Copy milestones/ directory (planning files, roadmaps, plans, research)
-  safeCopyRecursive(join(srcGsd, "milestones"), join(dstGsd, "milestones"), { force: true });
-
-  // Copy top-level planning files
-  for (const file of ["DECISIONS.md", "REQUIREMENTS.md", "PROJECT.md", "QUEUE.md", "STATE.md", "KNOWLEDGE.md", "OVERRIDES.md"]) {
-    safeCopy(join(srcGsd, file), join(dstGsd, file), { force: true });
-  }
-
-  // Copy gsd.db if present in source
-  const srcDb = join(srcGsd, "gsd.db");
-  const destDb = join(dstGsd, "gsd.db");
-  if (existsSync(srcDb)) {
-    try {
-      copyWorktreeDb(srcDb, destDb);
-    } catch { /* non-fatal */ }
-  }
-}
-
 /**
  * Teardown an auto-worktree: chdir back to original base, then remove
  * the worktree and its branch.
@@ -346,7 +186,7 @@ export function isInAutoWorktree(basePath: string): boolean {
   // Primary check: use originalBase if available (fast path)
   if (originalBase) {
     const resolvedBase = existsSync(basePath) ? realpathSync(basePath) : basePath;
-    const wtDir = join(resolvedBase, ".gsd", "worktrees");
+    const wtDir = join(gsdRoot(resolvedBase), "worktrees");
     if (!cwd.startsWith(wtDir)) return false;
     const branch = nativeGetCurrentBranch(cwd);
     return branch.startsWith("milestone/");
@@ -364,8 +204,8 @@ export function isInAutoWorktree(basePath: string): boolean {
     // Worktrees have a .git file with "gitdir: ..." pointing to the main repo
     const gitContent = readFileSync(worktreeMarker, "utf-8").trim();
     if (!gitContent.startsWith("gitdir:")) return false;
-    // Verify cwd path contains .gsd/worktrees/
-    if (!cwd.includes(`${sep}.gsd${sep}worktrees${sep}`) && !cwd.includes("/.gsd/worktrees/")) return false;
+    // Verify we're inside a GSD-managed worktree
+    if (!detectWorktreeName(cwd)) return false;
     const branch = nativeGetCurrentBranch(cwd);
     return branch.startsWith("milestone/");
   } catch {
@@ -458,7 +298,7 @@ export function getActiveAutoWorktreeContext(): {
   if (!originalBase) return null;
   const cwd = process.cwd();
   const resolvedBase = existsSync(originalBase) ? realpathSync(originalBase) : originalBase;
-  const wtDir = join(resolvedBase, ".gsd", "worktrees");
+  const wtDir = join(gsdRoot(resolvedBase), "worktrees");
   if (!cwd.startsWith(wtDir)) return null;
   const worktreeName = detectWorktreeName(cwd);
   if (!worktreeName) return null;
@@ -518,15 +358,6 @@ export function mergeMilestoneToMain(
   // 1. Auto-commit dirty state in worktree before leaving
   autoCommitDirtyState(worktreeCwd);
 
-  // Reconcile worktree DB into main DB before leaving worktree context
-  if (isDbAvailable()) {
-    try {
-      const worktreeDbPath = join(worktreeCwd, ".gsd", "gsd.db");
-      const mainDbPath = join(originalBasePath_, ".gsd", "gsd.db");
-      reconcileWorktreeDb(mainDbPath, worktreeDbPath);
-    } catch { /* non-fatal */ }
-  }
-
   // 2. Parse roadmap for slice listing
   const roadmap = parseRoadmap(roadmapContent);
   const completedSlices = roadmap.slices.filter(s => s.done);
@@ -535,11 +366,19 @@ export function mergeMilestoneToMain(
   const previousCwd = process.cwd();
   process.chdir(originalBasePath_);
 
-  // 3a. Auto-commit any dirty state in the project root that syncStateToProjectRoot
-  // wrote during execution. Without this, the squash merge can fail with
-  // "Your local changes to the following files would be overwritten by merge" (#1127).
+  // 3a. Auto-commit any dirty state in the project root. Without this, the
+  // squash merge can fail with "Your local changes would be overwritten" (#1127).
   autoCommitDirtyState(originalBasePath_);
 
+  // 3b. Remove untracked .gsd/ files that syncStateToProjectRoot copied.
+  // autoCommitDirtyState stages and commits everything (git add -A), but if
+  // the project root branch has no .gsd/ tracking (e.g., .gsd/ is gitignored),
+  // these files remain untracked and cause "untracked working tree files would
+  // be overwritten by merge" during squash-merge (#1237).
+  try {
+    execFileSync("git", ["clean", "-fd", ".gsd/"], { cwd: originalBasePath_, stdio: "pipe" });
+  } catch { /* non-fatal — clean failure shouldn't block merge attempt */ }
+
   // 4. Resolve integration branch — prefer milestone metadata, fall back to preferences / "main"
   const prefs = loadEffectiveGSDPreferences()?.preferences?.git ?? {};
   const integrationBranch = readIntegrationBranch(originalBasePath_, milestoneId);
@@ -556,7 +395,7 @@ export function mergeMilestoneToMain(
     // "Your local changes would be overwritten" (#827).
     const gsdStateFiles = ["STATE.md", "completed-units.json", "auto.lock"];
     for (const f of gsdStateFiles) {
-      const p = join(originalBasePath_, ".gsd", f);
+      const p = join(gsdRoot(originalBasePath_), f);
       try { unlinkSync(p); } catch { /* non-fatal — file may not exist */ }
     }
     nativeCheckoutBranch(originalBasePath_, mainBranch);

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

@@ -69,12 +69,10 @@ import { closeoutUnit } from "./auto-unit-closeout.js";
 import { recoverTimedOutUnit } from "./auto-timeout-recovery.js";
 import { selectAndApplyModel } from "./auto-model-selection.js";
 import {
-  syncProjectRootToWorktree,
-  syncStateToProjectRoot,
   readResourceVersion,
   checkResourcesStale,
   escapeStaleWorktree,
-} from "./auto-worktree-sync.js";
+} from "./resource-version.js";
 import { initRoutingHistory, resetRoutingHistory, recordOutcome } from "./routing-history.js";
 import {
   checkPostUnitHooks,
@@ -180,7 +178,7 @@ import { runPostUnitVerification, type VerificationContext } from "./auto-verifi
 import { postUnitPreVerification, postUnitPostVerification, type PostUnitContext } from "./auto-post-unit.js";
 import { bootstrapAutoSession, type BootstrapDeps } from "./auto-start.js";
 
-// Worktree sync, resource staleness, stale worktree escape → auto-worktree-sync.ts
+// Resource staleness, stale worktree escape → resource-version.ts
 
 // ─── Session State ─────────────────────────────────────────────────────────
 
@@ -1018,11 +1016,6 @@ async function dispatchNextUnit(
     // Non-fatal
   }
 
-  // ── Sync project root artifacts into worktree ──
-  if (s.originalBasePath && s.basePath !== s.originalBasePath && s.currentMilestoneId) {
-    syncProjectRootToWorktree(s.originalBasePath, s.basePath, s.currentMilestoneId);
-  }
-
   const stopDeriveTimer = debugTime("derive-state");
   let state = await deriveState(s.basePath);
   stopDeriveTimer({

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

@@ -9,9 +9,10 @@
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { join, resolve, sep } from "node:path";
+import { join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import { gsdRoot } from "./paths.js";
+import { resolveProjectRoot } from "./worktree.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -58,15 +59,8 @@ const VALID_CLASSIFICATIONS: readonly string[] = [
  * directory that contains `.gsd/worktrees/` — that's the project root.
  */
 export function resolveCapturesPath(basePath: string): string {
-  const resolved = resolve(basePath);
-  const worktreeMarker = `${sep}.gsd${sep}worktrees${sep}`;
-  const idx = resolved.indexOf(worktreeMarker);
-  if (idx !== -1) {
-    // basePath is inside a worktree — resolve to project root
-    const projectRoot = resolved.slice(0, idx);
-    return join(projectRoot, ".gsd", CAPTURES_FILENAME);
-  }
-  return join(gsdRoot(basePath), CAPTURES_FILENAME);
+  const projectRoot = resolveProjectRoot(resolve(basePath));
+  return join(gsdRoot(projectRoot), CAPTURES_FILENAME);
 }
 
 // ─── File I/O ─────────────────────────────────────────────────────────────────

package/src/resources/extensions/gsd/commands-handlers.ts

@@ -9,6 +9,7 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent
 import { existsSync, readFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { deriveState } from "./state.js";
+import { gsdRoot } from "./paths.js";
 import { appendCapture, hasPendingCaptures, loadPendingCaptures } from "./captures.js";
 import { appendOverride, appendKnowledge } from "./files.js";
 import {
@@ -136,7 +137,7 @@ export async function handleCapture(args: string, ctx: ExtensionCommandContext):
   const basePath = process.cwd();
 
   // Ensure .gsd/ exists — capture should work even without a milestone
-  const gsdDir = join(basePath, ".gsd");
+  const gsdDir = gsdRoot(basePath);
   if (!existsSync(gsdDir)) {
     mkdirSync(gsdDir, { recursive: true });
   }

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

@@ -8,6 +8,7 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent
 import type { GSDState } from "./types.js";
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
+import { gsdRoot } from "./paths.js";
 import { enableDebug } from "./debug-logger.js";
 import { deriveState } from "./state.js";
 import { GSDDashboardOverlay } from "./dashboard-overlay.js";
@@ -698,7 +699,7 @@ export function registerGSDCommand(pi: ExtensionAPI): void {
 
       if (trimmed === "new-milestone") {
         const basePath = projectRoot();
-        const headlessContextPath = join(basePath, ".gsd", "runtime", "headless-context.md");
+        const headlessContextPath = join(gsdRoot(basePath), "runtime", "headless-context.md");
         if (existsSync(headlessContextPath)) {
           const seedContext = readFileSync(headlessContextPath, "utf-8");
           try { unlinkSync(headlessContextPath); } catch { /* non-fatal */ }

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

@@ -9,6 +9,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+import { gsdRoot } from "./paths.js";
 
 // ─── Types ──────────────────────────────────────────────────────────────────────
 
@@ -214,7 +215,7 @@ export function detectV1Planning(basePath: string): V1Detection | null {
 // ─── V2 GSD Detection ──────────────────────────────────────────────────────────
 
 function detectV2Gsd(basePath: string): V2Detection | null {
-  const gsdPath = join(basePath, ".gsd");
+  const gsdPath = gsdRoot(basePath);
 
   if (!existsSync(gsdPath)) return null;