gsd-pi 2.35.0-dev.55dcc60 → 2.35.0-dev.6179610

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

@@ -10,7 +10,8 @@
  */
 
 import { readdirSync, existsSync, realpathSync, Dirent } from "node:fs";
-import { join } from "node:path";
+import { join, dirname, normalize } from "node:path";
+import { spawnSync } from "node:child_process";
 import { nativeScanGsdTree, type GsdTreeEntry } from "./native-parser-bridge.js";
 import { DIR_CACHE_MAX } from "./constants.js";
 
@@ -277,15 +278,80 @@ const LEGACY_GSD_ROOT_FILES: Record<GSDRootFileKey, string> = {
   KNOWLEDGE: "knowledge.md",
 };
 
+// ─── GSD Root Discovery ───────────────────────────────────────────────────────
+
+const gsdRootCache = new Map<string, string>();
+
+/** Exported for tests only — do not call in production code. */
+export function _clearGsdRootCache(): void {
+  gsdRootCache.clear();
+}
+
+/**
+ * Resolve the `.gsd` directory for a given project base path.
+ *
+ * Probe order:
+ *   1. basePath/.gsd         — fast path (common case)
+ *   2. git rev-parse root    — handles cwd-is-a-subdirectory
+ *   3. Walk up from basePath — handles moved .gsd in an ancestor (bounded by git root)
+ *   4. basePath/.gsd         — creation fallback (init scenario)
+ *
+ * Result is cached per basePath for the process lifetime.
+ */
 export function gsdRoot(basePath: string): string {
-  const local = join(basePath, ".gsd");
-  try {
-    const resolved = realpathSync(local);
-    if (resolved !== local) return resolved; // symlink resolved
-  } catch { /* doesn't exist yet — fall through */ }
-  return local; // backwards compat: unmigrated projects
+  const cached = gsdRootCache.get(basePath);
+  if (cached) return cached;
+
+  const result = probeGsdRoot(basePath);
+  gsdRootCache.set(basePath, result);
+  return result;
 }
 
+function probeGsdRoot(rawBasePath: string): string {
+  // 1. Fast path — check the input path directly
+  const local = join(rawBasePath, ".gsd");
+  if (existsSync(local)) return local;
+
+  // Resolve symlinks so path comparisons work correctly across platforms
+  // (e.g. macOS /var → /private/var). Use rawBasePath as fallback if not resolvable.
+  let basePath: string;
+  try { basePath = realpathSync.native(rawBasePath); } catch { basePath = rawBasePath; }
+
+  // 2. Git root anchor — used as both probe target and walk-up boundary
+  //    Only walk if we're inside a git project — prevents escaping into
+  //    unrelated filesystem territory when running outside any repo.
+  let gitRoot: string | null = null;
+  try {
+    const out = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd: basePath,
+      encoding: "utf-8",
+    });
+    if (out.status === 0) {
+      const r = out.stdout.trim();
+      if (r) gitRoot = normalize(r);
+    }
+  } catch { /* git not available */ }
+
+  if (gitRoot) {
+    const candidate = join(gitRoot, ".gsd");
+    if (existsSync(candidate)) return candidate;
+  }
+
+  // 3. Walk up from basePath to the git root (only if we are in a subdirectory)
+  if (gitRoot && basePath !== gitRoot) {
+    let cur = dirname(basePath);
+    while (cur !== basePath) {
+      const candidate = join(cur, ".gsd");
+      if (existsSync(candidate)) return candidate;
+      if (cur === gitRoot) break;
+      basePath = cur;
+      cur = dirname(cur);
+    }
+  }
+
+  // 4. Fallback for init/creation
+  return local;
+}
 export function milestonesDir(basePath: string): string {
   return join(gsdRoot(basePath), "milestones");
 }

package/src/resources/extensions/gsd/post-unit-hooks.ts

@@ -149,11 +149,15 @@ function dequeueNextHook(basePath: string): HookDispatchResult | null {
 
     // Build the prompt with variable substitution
     const [mid, sid, tid] = triggerUnitId.split("/");
-    const prompt = config.prompt
+    let prompt = config.prompt
       .replace(/\{milestoneId\}/g, mid ?? "")
       .replace(/\{sliceId\}/g, sid ?? "")
       .replace(/\{taskId\}/g, tid ?? "");
 
+    // Inject browser safety instruction for hooks that may use browser tools (#1345).
+    // Vite HMR and other persistent connections prevent networkidle from resolving.
+    prompt += "\n\n**Browser tool safety:** Do NOT use `browser_wait_for` with `condition: \"network_idle\"` — it hangs indefinitely when dev servers keep persistent connections (Vite HMR, WebSocket). Use `selector_visible`, `text_visible`, or `delay` instead.";
+
     return {
       hookName: config.name,
       prompt,

package/src/resources/extensions/gsd/preferences-validation.ts

@@ -33,9 +33,24 @@ export function validatePreferences(preferences: GSDPreferences): {
   const validated: GSDPreferences = {};
 
   // ─── Unknown Key Detection ──────────────────────────────────────────
+  // Common key migration hints for pi-level settings that don't map to GSD prefs
+  const KEY_MIGRATION_HINTS: Record<string, string> = {
+    taskIsolation: 'use "git.isolation" instead (values: worktree, branch, none)',
+    task_isolation: 'use "git.isolation" instead (values: worktree, branch, none)',
+    isolation: 'use "git.isolation" instead (values: worktree, branch, none)',
+    manage_gitignore: 'use "git.manage_gitignore" instead',
+    auto_push: 'use "git.auto_push" instead',
+    main_branch: 'use "git.main_branch" instead',
+  };
+
   for (const key of Object.keys(preferences)) {
     if (!KNOWN_PREFERENCE_KEYS.has(key)) {
-      warnings.push(`unknown preference key "${key}" — ignored`);
+      const hint = KEY_MIGRATION_HINTS[key];
+      if (hint) {
+        warnings.push(`unknown preference key "${key}" — ${hint}`);
+      } else {
+        warnings.push(`unknown preference key "${key}" — ignored`);
+      }
     }
   }
 

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

@@ -15,9 +15,10 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { parse as parseYaml } from "yaml";
-import type { PostUnitHookConfig, PreDispatchHookConfig } from "./types.js";
+import type { PostUnitHookConfig, PreDispatchHookConfig, TokenProfile } from "./types.js";
 import type { DynamicRoutingConfig } from "./model-router.js";
 import { normalizeStringArray } from "../shared/mod.js";
+import { resolveProfileDefaults as _resolveProfileDefaults } from "./preferences-models.js";
 
 import {
   MODE_DEFAULTS,
@@ -141,6 +142,18 @@ export function loadEffectiveGSDPreferences(): LoadedGSDPreferences | null {
     };
   }
 
+  // Apply token-profile defaults as the lowest-priority layer so that
+  // `token_profile: budget` sets models and phase-skips automatically.
+  // Explicit user preferences always override profile defaults.
+  const profile = result.preferences.token_profile as TokenProfile | undefined;
+  if (profile) {
+    const profileDefaults = _resolveProfileDefaults(profile);
+    result = {
+      ...result,
+      preferences: mergePreferences(profileDefaults as GSDPreferences, result.preferences),
+    };
+  }
+
   // Apply mode defaults as the lowest-priority layer
   if (result.preferences.mode) {
     result = {

package/src/resources/extensions/gsd/prompts/complete-milestone.md

@@ -28,6 +28,8 @@ Then:
 
 **Important:** Do NOT skip the success criteria and definition of done verification (steps 3-4). The milestone summary must reflect actual verified outcomes, not assumed success. If any criterion was not met, document it clearly in the summary and do not mark the milestone as passing verification.
 
+**File system safety:** When scanning milestone directories for evidence, use `ls` or `find` to list directory contents first — never pass a directory path (e.g. `tasks/`, `slices/`) directly to the `read` tool. The `read` tool only accepts file paths, not directories.
+
 **You MUST write `{{milestoneSummaryPath}}` AND update PROJECT.md before finishing.**
 
 When done, say: "Milestone {{milestoneId}} complete."

package/src/resources/extensions/gsd/prompts/validate-milestone.md

@@ -67,4 +67,6 @@ If verdict is `needs-remediation`:
 
 **You MUST write `{{validationPath}}` before finishing.**
 
+**File system safety:** When scanning milestone directories for evidence, use `ls` or `find` to list directory contents first — never pass a directory path (e.g. `tasks/`, `slices/`) directly to the `read` tool. The `read` tool only accepts file paths, not directories.
+
 When done, say: "Milestone {{milestoneId}} validation complete — verdict: <verdict>."

package/src/resources/extensions/gsd/roadmap-mutations.ts

@@ -0,0 +1,66 @@
+/**
+ * Roadmap Mutations — shared utilities for modifying roadmap checkbox state.
+ *
+ * Extracts the duplicated "flip slice checkbox" pattern that existed in
+ * doctor.ts, mechanical-completion.ts, and auto-recovery.ts.
+ */
+
+import { readFileSync } from "node:fs";
+import { atomicWriteSync } from "./atomic-write.js";
+import { resolveMilestoneFile } from "./paths.js";
+import { clearParseCache } from "./files.js";
+
+/**
+ * Mark a slice as done ([x]) in the milestone roadmap.
+ * Idempotent — no-op if already checked or if the slice isn't found.
+ *
+ * @returns true if the roadmap was modified, false if no change was needed
+ */
+export function markSliceDoneInRoadmap(basePath: string, mid: string, sid: string): boolean {
+  const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
+  if (!roadmapFile) return false;
+
+  let content: string;
+  try {
+    content = readFileSync(roadmapFile, "utf-8");
+  } catch {
+    return false;
+  }
+
+  const updated = content.replace(
+    new RegExp(`^(\\s*-\\s+)\\[ \\]\\s+\\*\\*${sid}:`, "m"),
+    `$1[x] **${sid}:`,
+  );
+
+  if (updated === content) return false;
+
+  atomicWriteSync(roadmapFile, updated);
+  clearParseCache();
+  return true;
+}
+
+/**
+ * Mark a task as done ([x]) in the slice plan.
+ * Idempotent — no-op if already checked or if the task isn't found.
+ *
+ * @returns true if the plan was modified, false if no change was needed
+ */
+export function markTaskDoneInPlan(basePath: string, planPath: string, tid: string): boolean {
+  let content: string;
+  try {
+    content = readFileSync(planPath, "utf-8");
+  } catch {
+    return false;
+  }
+
+  const updated = content.replace(
+    new RegExp(`^(\\s*-\\s+)\\[ \\]\\s+\\*\\*${tid}:`, "m"),
+    `$1[x] **${tid}:`,
+  );
+
+  if (updated === content) return false;
+
+  atomicWriteSync(planPath, updated);
+  clearParseCache();
+  return true;
+}

package/src/resources/extensions/gsd/session-lock.ts

@@ -57,9 +57,19 @@ let _lockCompromised: boolean = false;
 /** Whether we've already registered a process.on('exit') handler. */
 let _exitHandlerRegistered: boolean = false;
 
+/** Snapshotted lock file path — captured at acquireSessionLock time to avoid
+ *  gsdRoot() resolving differently in worktree vs project root contexts (#1363). */
+let _snapshotLockPath: string | null = null;
+
+/** Timestamp when the session lock was acquired — used to detect false-positive
+ *  onCompromised events from event loop stalls within the stale window (#1362). */
+let _lockAcquiredAt: number = 0;
+
 const LOCK_FILE = "auto.lock";
 
 function lockPath(basePath: string): string {
+  // If we have a snapshotted path from acquisition, use it for consistency
+  if (_snapshotLockPath) return _snapshotLockPath;
   return join(gsdRoot(basePath), LOCK_FILE);
 }
 
@@ -198,8 +208,19 @@ export function acquireSessionLock(basePath: string): SessionLockResult {
       onCompromised: () => {
         // proper-lockfile detected mtime drift (system sleep, event loop stall, etc.).
         // Default handler throws inside setTimeout — an uncaught exception that crashes
-        // or corrupts process state. Instead, set a flag so validateSessionLock() can
-        // detect the compromise gracefully on the next dispatch cycle.
+        // or corrupts process state.
+        //
+        // False-positive suppression (#1362): If we're still within the stale window
+        // (30 min since acquisition), the mtime mismatch is from an event loop stall
+        // during a long LLM call — not a real takeover. Log and continue.
+        const elapsed = Date.now() - _lockAcquiredAt;
+        if (elapsed < 1_800_000) {
+          process.stderr.write(
+            `[gsd] Lock heartbeat mismatch after ${Math.round(elapsed / 1000)}s — event loop stall, continuing.\n`,
+          );
+          return; // Suppress false positive
+        }
+        // Past the stale window — this is a real compromise
         _lockCompromised = true;
         _releaseFunction = null;
       },
@@ -209,6 +230,8 @@ export function acquireSessionLock(basePath: string): SessionLockResult {
     _lockedPath = basePath;
     _lockPid = process.pid;
     _lockCompromised = false;
+    _lockAcquiredAt = Date.now();
+    _snapshotLockPath = lp; // Snapshot the resolved path for consistent access (#1363)
 
     // Safety net: clean up lock dir on process exit if _releaseFunction
     // wasn't called (e.g., normal exit after clean completion) (#1245).
@@ -237,6 +260,16 @@ export function acquireSessionLock(basePath: string): SessionLockResult {
           stale: 1_800_000, // 30 minutes — match primary lock settings
           update: 10_000,
           onCompromised: () => {
+            // Same false-positive suppression as the primary lock (#1512).
+            // Without this, the retry path fires _lockCompromised unconditionally
+            // on benign mtime drift (laptop sleep, heavy LLM event loop stalls).
+            const elapsed = Date.now() - _lockAcquiredAt;
+            if (elapsed < 1_800_000) {
+              process.stderr.write(
+                `[gsd] Lock heartbeat mismatch after ${Math.round(elapsed / 1000)}s — event loop stall, continuing.\n`,
+              );
+              return;
+            }
             _lockCompromised = true;
             _releaseFunction = null;
           },
@@ -245,6 +278,8 @@ export function acquireSessionLock(basePath: string): SessionLockResult {
         _lockedPath = basePath;
         _lockPid = process.pid;
         _lockCompromised = false;
+        _lockAcquiredAt = Date.now();
+        _snapshotLockPath = lp; // Snapshot for retry path too (#1363)
 
         // Safety net — uses centralized handler to avoid double-registration
         ensureExitHandler(gsdDir);
@@ -336,6 +371,26 @@ export function updateSessionLock(
 export function validateSessionLock(basePath: string): boolean {
   // Lock was compromised by proper-lockfile (mtime drift from sleep, stall, etc.)
   if (_lockCompromised) {
+    // Recovery gate (#1512): Before declaring the lock lost, check if the lock
+    // file still contains our PID. If it does, no other process took over — the
+    // onCompromised fired from benign mtime drift (laptop sleep, event loop stall
+    // beyond the stale window). Attempt re-acquisition instead of giving up.
+    const lp = lockPath(basePath);
+    const existing = readExistingLockData(lp);
+    if (existing && existing.pid === process.pid) {
+      // Lock file still ours — try to re-acquire the OS lock
+      try {
+        const result = acquireSessionLock(basePath);
+        if (result.acquired) {
+          process.stderr.write(
+            `[gsd] Lock recovered after onCompromised — lock file PID matched, re-acquired.\n`,
+          );
+          return true;
+        }
+      } catch {
+        // Re-acquisition failed — fall through to return false
+      }
+    }
     return false;
   }
 
@@ -394,6 +449,8 @@ export function releaseSessionLock(basePath: string): void {
   _lockedPath = null;
   _lockPid = 0;
   _lockCompromised = false;
+  _lockAcquiredAt = 0;
+  _snapshotLockPath = null;
 }
 
 /**

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

@@ -64,11 +64,12 @@ export function isValidationTerminal(validationContent: string): boolean {
   if (!match) return false;
   const verdict = match[1].match(/verdict:\s*(\S+)/);
   if (!verdict) return false;
+  const v = verdict[1] === 'passed' ? 'pass' : verdict[1];
   // 'pass' and 'needs-attention' are always terminal.
   // 'needs-remediation' is treated as terminal to prevent infinite loops
   // when no remediation slices exist in the roadmap (#832). The validation
   // report is preserved on disk for manual review.
-  return verdict[1] === 'pass' || verdict[1] === 'needs-attention' || verdict[1] === 'needs-remediation';
+  return v === 'pass' || v === 'needs-attention' || v === 'needs-remediation';
 }
 
 // ─── State Derivation ──────────────────────────────────────────────────────

package/src/resources/extensions/gsd/templates/plan.md

@@ -113,6 +113,14 @@
   - Tasks execute sequentially in order (T01, T02, T03, ...)
   - est: is informational (e.g. 30m, 1h, 2h) and optional
 
+  Verify field rules:
+  - MUST be a mechanically executable command: `npm test`, `grep -q "pattern" file`, `test -f path`
+  - For content/document tasks: verify file existence, section count, YAML validity, or word count
+    NOT exact phrasing, specific formulas, or "zero TBD" aspirational criteria
+  - If no command can verify the output, write: "Manual review — file exists and is non-empty"
+  - BAD: "Sections 3.1 and 3.2 exist with exact formulas. Zero TBD/TODO."
+  - GOOD: `grep -c "^## " doc.md` returns >= 4 (4+ sections), `! grep -q "TBD\|TODO" doc.md`
+
   Integration closure rule:
   - At least one slice in any multi-boundary milestone should perform real composition/wiring, not just contract hardening
   - For the final assembly slice, verification must exercise the real entrypoint or runtime path

package/src/resources/extensions/gsd/tests/files-loadfile-eisdir.test.ts

@@ -0,0 +1,20 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs";
+
+import { loadFile } from "../files.ts";
+
+test("loadFile returns null for directory paths instead of throwing EISDIR", async () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "gsd-loadfile-eisdir-"));
+  const dirPath = path.join(tmp, "tasks");
+  fs.mkdirSync(dirPath);
+
+  try {
+    const result = await loadFile(dirPath);
+    assert.equal(result, null);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/gitignore-tracked-gsd.test.ts

@@ -0,0 +1,214 @@
+/**
+ * gitignore-tracked-gsd.test.ts — Regression tests for #1364.
+ *
+ * Verifies that ensureGitignore() does NOT add ".gsd" to .gitignore
+ * when .gsd/ contains git-tracked files, and that migrateToExternalState()
+ * aborts migration for tracked .gsd/ directories.
+ *
+ * Uses real temporary git repos — no mocks.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { ensureGitignore, hasGitTrackedGsdFiles } from "../gitignore.ts";
+import { migrateToExternalState } from "../migrate-external.ts";
+
+// ─── Helpers ─────────────────────────────────────────────────────────
+
+function git(dir: string, ...args: string[]): string {
+  return execFileSync("git", args, { cwd: dir, stdio: "pipe", encoding: "utf-8" }).trim();
+}
+
+function makeTempRepo(): string {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-gitignore-test-"));
+  git(dir, "init");
+  git(dir, "config", "user.email", "test@test.com");
+  git(dir, "config", "user.name", "Test");
+  writeFileSync(join(dir, "README.md"), "# init\n");
+  git(dir, "add", "-A");
+  git(dir, "commit", "-m", "init");
+  git(dir, "branch", "-M", "main");
+  return dir;
+}
+
+function cleanup(dir: string): void {
+  try {
+    rmSync(dir, { recursive: true, force: true });
+  } catch {
+    // ignore
+  }
+}
+
+// ─── hasGitTrackedGsdFiles ───────────────────────────────────────────
+
+test("hasGitTrackedGsdFiles returns false when .gsd/ does not exist", () => {
+  const dir = makeTempRepo();
+  try {
+    assert.equal(hasGitTrackedGsdFiles(dir), false);
+  } finally {
+    cleanup(dir);
+  }
+});
+
+test("hasGitTrackedGsdFiles returns true when .gsd/ has tracked files", () => {
+  const dir = makeTempRepo();
+  try {
+    mkdirSync(join(dir, ".gsd", "milestones"), { recursive: true });
+    writeFileSync(join(dir, ".gsd", "PROJECT.md"), "# Test Project\n");
+    git(dir, "add", ".gsd/PROJECT.md");
+    git(dir, "commit", "-m", "add gsd");
+    assert.equal(hasGitTrackedGsdFiles(dir), true);
+  } finally {
+    cleanup(dir);
+  }
+});
+
+test("hasGitTrackedGsdFiles returns false when .gsd/ exists but is untracked", () => {
+  const dir = makeTempRepo();
+  try {
+    mkdirSync(join(dir, ".gsd"), { recursive: true });
+    writeFileSync(join(dir, ".gsd", "STATE.md"), "state\n");
+    // Not git-added — should return false
+    assert.equal(hasGitTrackedGsdFiles(dir), false);
+  } finally {
+    cleanup(dir);
+  }
+});
+
+// ─── ensureGitignore — tracked .gsd/ protection ─────────────────────
+
+test("ensureGitignore does NOT add .gsd when .gsd/ has tracked files (#1364)", () => {
+  const dir = makeTempRepo();
+  try {
+    // Set up .gsd/ with tracked files
+    mkdirSync(join(dir, ".gsd", "milestones"), { recursive: true });
+    writeFileSync(join(dir, ".gsd", "PROJECT.md"), "# Test Project\n");
+    writeFileSync(join(dir, ".gsd", "DECISIONS.md"), "# Decisions\n");
+    git(dir, "add", ".gsd/");
+    git(dir, "commit", "-m", "track gsd state");
+
+    // Run ensureGitignore
+    ensureGitignore(dir);
+
+    // Verify .gsd is NOT in .gitignore
+    const gitignore = readFileSync(join(dir, ".gitignore"), "utf-8");
+    const lines = gitignore.split("\n").map((l) => l.trim());
+    assert.ok(
+      !lines.includes(".gsd"),
+      `Expected .gsd NOT to appear in .gitignore, but it does:\n${gitignore}`,
+    );
+
+    // Other baseline patterns should still be present
+    assert.ok(lines.includes(".DS_Store"), "Expected .DS_Store in .gitignore");
+    assert.ok(lines.includes("node_modules/"), "Expected node_modules/ in .gitignore");
+  } finally {
+    cleanup(dir);
+  }
+});
+
+test("ensureGitignore adds .gsd when .gsd/ has NO tracked files", () => {
+  const dir = makeTempRepo();
+  try {
+    // Run ensureGitignore (no .gsd/ at all)
+    ensureGitignore(dir);
+
+    // Verify .gsd IS in .gitignore
+    const gitignore = readFileSync(join(dir, ".gitignore"), "utf-8");
+    const lines = gitignore.split("\n").map((l) => l.trim());
+    assert.ok(
+      lines.includes(".gsd"),
+      `Expected .gsd in .gitignore, but it's missing:\n${gitignore}`,
+    );
+  } finally {
+    cleanup(dir);
+  }
+});
+
+test("ensureGitignore respects manageGitignore: false", () => {
+  const dir = makeTempRepo();
+  try {
+    const result = ensureGitignore(dir, { manageGitignore: false });
+    assert.equal(result, false);
+    assert.ok(!existsSync(join(dir, ".gitignore")), "Should not create .gitignore");
+  } finally {
+    cleanup(dir);
+  }
+});
+
+// ─── ensureGitignore — verify no tracked files become invisible ─────
+
+test("ensureGitignore with tracked .gsd/ does not cause git to see files as deleted", () => {
+  const dir = makeTempRepo();
+  try {
+    // Create tracked .gsd/ files
+    mkdirSync(join(dir, ".gsd", "milestones", "M001"), { recursive: true });
+    writeFileSync(join(dir, ".gsd", "PROJECT.md"), "# Project\n");
+    writeFileSync(
+      join(dir, ".gsd", "milestones", "M001", "M001-CONTEXT.md"),
+      "# M001\n",
+    );
+    git(dir, "add", ".gsd/");
+    git(dir, "commit", "-m", "track gsd state");
+
+    // Run ensureGitignore
+    ensureGitignore(dir);
+
+    // git status should show NO deleted files under .gsd/
+    const status = git(dir, "status", "--porcelain", ".gsd/");
+
+    // Filter for deletions (lines starting with " D" or "D ")
+    const deletions = status
+      .split("\n")
+      .filter((l) => l.match(/^\s*D\s/) || l.match(/^D\s/));
+
+    assert.equal(
+      deletions.length,
+      0,
+      `Expected no deleted .gsd/ files, but found:\n${deletions.join("\n")}`,
+    );
+  } finally {
+    cleanup(dir);
+  }
+});
+
+// ─── migrateToExternalState — tracked .gsd/ protection ──────────────
+
+test("migrateToExternalState aborts when .gsd/ has tracked files (#1364)", () => {
+  const dir = makeTempRepo();
+  try {
+    // Create tracked .gsd/ files
+    mkdirSync(join(dir, ".gsd", "milestones"), { recursive: true });
+    writeFileSync(join(dir, ".gsd", "PROJECT.md"), "# Project\n");
+    git(dir, "add", ".gsd/");
+    git(dir, "commit", "-m", "track gsd state");
+
+    // Attempt migration — should abort without moving anything
+    const result = migrateToExternalState(dir);
+
+    assert.equal(result.migrated, false, "Should NOT migrate tracked .gsd/");
+    assert.equal(result.error, undefined, "Should not report an error — just skip");
+
+    // .gsd/ should still be a real directory, not a symlink
+    assert.ok(existsSync(join(dir, ".gsd", "PROJECT.md")), ".gsd/PROJECT.md should still exist");
+
+    // No .gsd.migrating should exist
+    assert.ok(
+      !existsSync(join(dir, ".gsd.migrating")),
+      ".gsd.migrating should not exist",
+    );
+  } finally {
+    cleanup(dir);
+  }
+});