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

package/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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;
 

package/dist/resources/extensions/gsd/doctor-checks.ts

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { join, sep } from "node:path";
 
 import type { DoctorIssue, DoctorIssueCode } from "./doctor-types.js";
@@ -13,6 +13,7 @@ import { nativeIsRepo, nativeWorktreeRemove, nativeBranchList, nativeBranchDelet
 import { readCrashLock, isLockProcessAlive, clearLock } from "./crash-recovery.js";
 import { ensureGitignore } from "./gitignore.js";
 import { readAllSessionStatuses, isSessionStale, removeSessionStatus } from "./session-status-io.js";
+import { recoverFailedMigration } from "./migrate-external.js";
 
 export async function checkGitHealth(
   basePath: string,
@@ -508,6 +509,53 @@ export async function checkRuntimeHealth(
   } catch {
     // Non-fatal — gitignore check failed
   }
+
+  // ── External state symlink health ──────────────────────────────────────
+  try {
+    const localGsd = join(basePath, ".gsd");
+    if (existsSync(localGsd)) {
+      const stat = lstatSync(localGsd);
+
+      // Check for .gsd.migrating (failed migration)
+      const migratingPath = join(basePath, ".gsd.migrating");
+      if (existsSync(migratingPath)) {
+        issues.push({
+          severity: "error",
+          code: "failed_migration",
+          scope: "project",
+          unitId: "project",
+          message: "Found .gsd.migrating — a previous external state migration failed. State may be incomplete.",
+          file: ".gsd.migrating",
+          fixable: true,
+        });
+
+        if (shouldFix("failed_migration")) {
+          if (recoverFailedMigration(basePath)) {
+            fixesApplied.push("recovered failed migration (.gsd.migrating → .gsd)");
+          }
+        }
+      }
+
+      // Check symlink target exists
+      if (stat.isSymbolicLink()) {
+        try {
+          realpathSync(localGsd);
+        } catch {
+          issues.push({
+            severity: "error",
+            code: "broken_symlink",
+            scope: "project",
+            unitId: "project",
+            message: ".gsd symlink target does not exist. External state directory may have been deleted.",
+            file: ".gsd",
+            fixable: false,
+          });
+        }
+      }
+    }
+  } catch {
+    // Non-fatal — external state check failed
+  }
 }
 
 /**

package/dist/resources/extensions/gsd/doctor-types.ts

@@ -30,7 +30,9 @@ export type DoctorIssueCode =
   | "state_file_stale"
   | "state_file_missing"
   | "gitignore_missing_patterns"
-  | "unresolvable_dependency";
+  | "unresolvable_dependency"
+  | "failed_migration"
+  | "broken_symlink";
 
 /**
  * Issue codes that represent expected completion-transition states.

package/dist/resources/extensions/gsd/forensics.ts

@@ -268,7 +268,7 @@ function resolveActivityDirs(basePath: string, activeMilestone?: string | null):
   if (activeMilestone) {
     const wtPath = getAutoWorktreePath(basePath, activeMilestone);
     if (wtPath) {
-      const wtActivityDir = join(wtPath, ".gsd", "activity");
+      const wtActivityDir = join(gsdRoot(wtPath), "activity");
       if (existsSync(wtActivityDir)) {
         dirs.push(wtActivityDir);
       }
@@ -285,7 +285,7 @@ function resolveActivityDirs(basePath: string, activeMilestone?: string | null):
 // ─── Completed Keys Loader ────────────────────────────────────────────────────
 
 function loadCompletedKeys(basePath: string): string[] {
-  const file = join(basePath, ".gsd", "completed-units.json");
+  const file = join(gsdRoot(basePath), "completed-units.json");
   try {
     if (existsSync(file)) {
       return JSON.parse(readFileSync(file, "utf-8"));

package/dist/resources/extensions/gsd/git-service.ts

@@ -11,6 +11,7 @@
 import { execFileSync, execSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { gsdRoot } from "./paths.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 
 import {
@@ -193,7 +194,7 @@ export const RUNTIME_EXCLUSION_PATHS: readonly string[] = [
  * Format: .gsd/milestones/<MID>/<MID>-META.json
  */
 function milestoneMetaPath(basePath: string, milestoneId: string): string {
-  return join(basePath, ".gsd", "milestones", milestoneId, `${milestoneId}-META.json`);
+  return join(gsdRoot(basePath), "milestones", milestoneId, `${milestoneId}-META.json`);
 }
 
 /**
@@ -237,7 +238,7 @@ export function writeIntegrationBranch(basePath: string, milestoneId: string, br
   if (existingBranch === branch) return;
 
   const metaFile = milestoneMetaPath(basePath, milestoneId);
-  mkdirSync(join(basePath, ".gsd", "milestones", milestoneId), { recursive: true });
+  mkdirSync(join(gsdRoot(basePath), "milestones", milestoneId), { recursive: true });
 
   // Merge with existing metadata if present
   let existing: Record<string, unknown> = {};

package/dist/resources/extensions/gsd/gitignore.ts

@@ -9,10 +9,12 @@
 import { join } from "node:path";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { nativeRmCached } from "./native-git-bridge.js";
+import { gsdRoot } from "./paths.js";
 
 /**
- * Patterns that are always correct regardless of project type.
- * No one ever wants these tracked.
+ * GSD runtime patterns for git index cleanup.
+ * With external state (symlink), these are a no-op in most cases,
+ * but retained for backwards compatibility during migration.
  */
 const GSD_RUNTIME_PATTERNS = [
   ".gsd/activity/",
@@ -31,8 +33,8 @@ const GSD_RUNTIME_PATTERNS = [
 ] as const;
 
 const BASELINE_PATTERNS = [
-  // ── GSD runtime (not source artifacts — planning files are tracked) ──
-  ...GSD_RUNTIME_PATTERNS,
+  // ── GSD state directory (symlink to external storage) ──
+  ".gsd",
 
   // ── OS junk ──
   ".DS_Store",
@@ -90,41 +92,12 @@ export function ensureGitignore(basePath: string, options?: { commitDocs?: boole
   if (options?.manageGitignore === false) return false;
 
   const gitignorePath = join(basePath, ".gitignore");
-  const commitDocs = options?.commitDocs !== false; // default true
 
   let existing = "";
   if (existsSync(gitignorePath)) {
     existing = readFileSync(gitignorePath, "utf-8");
   }
 
-  // When commit_docs is false, ensure blanket ".gsd/" is in .gitignore
-  // and skip the self-heal that would remove it.
-  if (!commitDocs) {
-    return ensureBlanketGsdIgnore(gitignorePath, existing);
-  }
-
-  // Self-heal: remove blanket ".gsd/" lines from pre-v2.14.0 projects.
-  // The blanket ignore prevented planning artifacts (.gsd/milestones/) from
-  // being tracked in git, causing artifacts to vanish in worktrees and
-  // triggering loop detection failures. Replace with explicit runtime-only
-  // ignores so planning files are tracked naturally.
-  let modified = false;
-  const lines = existing.split("\n");
-  const filteredLines = lines.filter(line => {
-    const trimmed = line.trim();
-    // Remove standalone ".gsd/" lines (blanket ignore) but keep specific
-    // .gsd/ subpath patterns like ".gsd/activity/" or ".gsd/auto.lock"
-    if (trimmed === ".gsd/" || trimmed === ".gsd") {
-      modified = true;
-      return false;
-    }
-    return true;
-  });
-  if (modified) {
-    existing = filteredLines.join("\n");
-    writeFileSync(gitignorePath, existing, "utf-8");
-  }
-
   // Parse existing lines (trimmed, ignoring comments and blanks)
   const existingLines = new Set(
     existing
@@ -136,7 +109,7 @@ export function ensureGitignore(basePath: string, options?: { commitDocs?: boole
   // Find patterns not yet present
   const missing = BASELINE_PATTERNS.filter((p) => !existingLines.has(p));
 
-  if (missing.length === 0) return modified;
+  if (missing.length === 0) return false;
 
   // Build the block to append
   const block = [
@@ -184,8 +157,8 @@ export function untrackRuntimeFiles(basePath: string): void {
  * creating a duplicate when an uppercase file already exists.
  */
 export function ensurePreferences(basePath: string): boolean {
-  const preferencesPath = join(basePath, ".gsd", "preferences.md");
-  const legacyPath = join(basePath, ".gsd", "PREFERENCES.md");
+  const preferencesPath = join(gsdRoot(basePath), "preferences.md");
+  const legacyPath = join(gsdRoot(basePath), "PREFERENCES.md");
 
   if (existsSync(preferencesPath) || existsSync(legacyPath)) {
     return false;
@@ -240,31 +213,4 @@ custom_instructions:
   return true;
 }
 
-/**
- * When commit_docs is false, ensure `.gsd/` is in .gitignore as a blanket
- * pattern. This keeps all GSD artifacts local-only.
- * Returns true if the file was modified, false if already complete.
- */
-function ensureBlanketGsdIgnore(gitignorePath: string, existing: string): boolean {
-  const existingLines = new Set(
-    existing
-      .split("\n")
-      .map((l) => l.trim())
-      .filter((l) => l && !l.startsWith("#")),
-  );
-
-  // Already has blanket .gsd/ ignore
-  if (existingLines.has(".gsd/") || existingLines.has(".gsd")) return false;
-
-  const block = [
-    "",
-    "# ── GSD (local-only, commit_docs: false) ──",
-    ".gsd/",
-    "",
-  ].join("\n");
-
-  const prefix = existing && !existing.endsWith("\n") ? "\n" : "";
-  writeFileSync(gitignorePath, existing + prefix + block, "utf-8");
-  return true;
-}