gsd-pi 2.34.0 → 2.35.0-dev.34ce717

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/commands-inspect-open-db.test.ts

@@ -0,0 +1,46 @@
+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 { handleInspect } from "../commands-inspect.ts";
+import { closeDatabase, openDatabase } from "../gsd-db.ts";
+
+test("/gsd inspect opens existing database when it was not yet opened in session", async () => {
+  closeDatabase();
+
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "gsd-inspect-db-"));
+  const prevCwd = process.cwd();
+
+  try {
+    const gsdDir = path.join(tmp, ".gsd");
+    fs.mkdirSync(gsdDir, { recursive: true });
+    const dbPath = path.join(gsdDir, "gsd.db");
+
+    assert.equal(openDatabase(dbPath), true);
+    closeDatabase();
+
+    process.chdir(tmp);
+
+    const notifications: Array<{ message: string; level: string }> = [];
+    const ctx = {
+      ui: {
+        notify(message: string, level: string) {
+          notifications.push({ message, level });
+        },
+      },
+    } as any;
+
+    await handleInspect(ctx);
+
+    assert.equal(notifications.length, 1);
+    assert.equal(notifications[0].level, "info");
+    assert.match(notifications[0].message, /=== GSD Database Inspect ===/);
+    assert.doesNotMatch(notifications[0].message, /No GSD database available/);
+  } finally {
+    process.chdir(prevCwd);
+    closeDatabase();
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/doctor-git.test.ts

@@ -2,9 +2,10 @@
  * doctor-git.test.ts — Integration tests for doctor git health checks.
  *
  * Creates real temp git repos with deliberate broken state, runs runGSDDoctor,
- * and asserts correct detection and fixing of all 4 git issue codes:
+ * and asserts correct detection and fixing of git issue codes:
  *   orphaned_auto_worktree, stale_milestone_branch,
- *   corrupt_merge_state, tracked_runtime_files
+ *   corrupt_merge_state, tracked_runtime_files,
+ *   integration_branch_missing, worktree_directory_orphaned
  */
 
 import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, realpathSync } from "node:fs";
@@ -299,6 +300,101 @@ async function main(): Promise<void> {
       console.log("\n=== none-mode skips stale branch (skipped on Windows) ===");
     }
 
+    // ─── Test: Integration branch missing ──────────────────────────────
+    if (process.platform !== "win32") {
+    console.log("\n=== integration_branch_missing ===");
+    {
+      const dir = createRepoWithActiveMilestone();
+      cleanups.push(dir);
+
+      // Write integration branch metadata for M001 pointing to a non-existent branch
+      const metaPath = join(dir, ".gsd", "milestones", "M001", "M001-META.json");
+      writeFileSync(metaPath, JSON.stringify({ integrationBranch: "feat/does-not-exist" }, null, 2));
+
+      const detect = await runGSDDoctor(dir);
+      const missingBranchIssues = detect.issues.filter(i => i.code === "integration_branch_missing");
+      assertTrue(missingBranchIssues.length > 0, "detects missing integration branch");
+      assertTrue(
+        missingBranchIssues[0]?.message.includes("feat/does-not-exist"),
+        "message includes the missing branch name",
+      );
+      assertEq(missingBranchIssues[0]?.fixable, false, "integration_branch_missing is not auto-fixable");
+      assertEq(missingBranchIssues[0]?.severity, "error", "severity is error");
+    }
+    } else {
+      console.log("\n=== integration_branch_missing (skipped on Windows) ===");
+    }
+
+    // ─── Test: Integration branch present — no false positive ──────────
+    if (process.platform !== "win32") {
+    console.log("\n=== integration_branch_missing (no false positive) ===");
+    {
+      const dir = createRepoWithActiveMilestone();
+      cleanups.push(dir);
+
+      // Write integration branch metadata for M001 pointing to "main" (which exists)
+      const metaPath = join(dir, ".gsd", "milestones", "M001", "M001-META.json");
+      writeFileSync(metaPath, JSON.stringify({ integrationBranch: "main" }, null, 2));
+
+      const detect = await runGSDDoctor(dir);
+      const missingBranchIssues = detect.issues.filter(i => i.code === "integration_branch_missing");
+      assertEq(missingBranchIssues.length, 0, "existing integration branch NOT flagged");
+    }
+    } else {
+      console.log("\n=== integration_branch_missing (no false positive — skipped on Windows) ===");
+    }
+
+    // ─── Test: Orphaned worktree directory ─────────────────────────────
+    if (process.platform !== "win32") {
+    console.log("\n=== worktree_directory_orphaned ===");
+    {
+      const dir = createRepoWithActiveMilestone();
+      cleanups.push(dir);
+
+      // Create a worktrees/ dir with an entry that is NOT in git worktree list
+      const orphanDir = join(dir, ".gsd", "worktrees", "orphan-feature");
+      mkdirSync(orphanDir, { recursive: true });
+      writeFileSync(join(orphanDir, "some-file.txt"), "leftover content\n");
+
+      const detect = await runGSDDoctor(dir);
+      const orphanDirIssues = detect.issues.filter(i => i.code === "worktree_directory_orphaned");
+      assertTrue(orphanDirIssues.length > 0, "detects orphaned worktree directory");
+      assertTrue(
+        orphanDirIssues[0]?.message.includes("orphan-feature"),
+        "message includes the orphaned directory name",
+      );
+      assertTrue(orphanDirIssues[0]?.fixable === true, "worktree_directory_orphaned is fixable");
+
+      const fixed = await runGSDDoctor(dir, { fix: true });
+      assertTrue(
+        fixed.fixesApplied.some(f => f.includes("removed orphaned worktree directory")),
+        "fix removes orphaned worktree directory",
+      );
+      assertTrue(!existsSync(orphanDir), "orphaned directory removed after fix");
+    }
+    } else {
+      console.log("\n=== worktree_directory_orphaned (skipped on Windows) ===");
+    }
+
+    // ─── Test: Registered worktree NOT flagged as orphaned ─────────────
+    if (process.platform !== "win32") {
+    console.log("\n=== worktree_directory_orphaned (registered worktree not flagged) ===");
+    {
+      const dir = createRepoWithActiveMilestone();
+      cleanups.push(dir);
+
+      // Create a real registered worktree under .gsd/worktrees/
+      mkdirSync(join(dir, ".gsd", "worktrees"), { recursive: true });
+      run("git worktree add -b worktree/feature-1 .gsd/worktrees/feature-1", dir);
+
+      const detect = await runGSDDoctor(dir);
+      const orphanDirIssues = detect.issues.filter(i => i.code === "worktree_directory_orphaned");
+      assertEq(orphanDirIssues.length, 0, "registered worktree NOT flagged as orphaned");
+    }
+    } else {
+      console.log("\n=== worktree_directory_orphaned (registered worktree not flagged — skipped on Windows) ===");
+    }
+
     // ─── Test 9: none-mode still detects corrupt merge state ───────────
     console.log("\n=== none-mode keeps corrupt merge state ===");
     {

package/src/resources/extensions/gsd/tests/doctor-runtime.test.ts

@@ -2,9 +2,9 @@
  * doctor-runtime.test.ts — Tests for doctor runtime health checks.
  *
  * Tests detection and auto-fix of:
- *   stale_crash_lock, orphaned_completed_units, stale_hook_state,
- *   activity_log_bloat, state_file_missing, state_file_stale,
- *   gitignore_missing_patterns
+ *   stale_crash_lock, stranded_lock_directory, orphaned_completed_units,
+ *   stale_hook_state, activity_log_bloat, state_file_missing,
+ *   state_file_stale, gitignore_missing_patterns
  */
 
 import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, readFileSync, realpathSync } from "node:fs";
@@ -290,6 +290,62 @@ node_modules/
       assertEq(content.length, 0, "all orphaned keys removed");
     }
 
+    // ─── Test: Stranded lock directory detection & fix ────────────────
+    // Skip on Windows: proper-lockfile uses advisory file locking on Windows,
+    // not the directory-based mechanism. The .gsd.lock/ directory pattern is
+    // a POSIX-specific lockfile implementation detail.
+    if (process.platform !== "win32") {
+    console.log("\n=== stranded_lock_directory ===");
+    {
+      const dir = createMinimalProject();
+      cleanups.push(dir);
+
+      // Create the proper-lockfile lock directory without a live lock holder.
+      // The lock dir sits at <parent of .gsd>/.gsd.lock (i.e., <basePath>/.gsd.lock).
+      const lockDir = join(dir, ".gsd.lock");
+      mkdirSync(lockDir, { recursive: true });
+
+      const detect = await runGSDDoctor(dir);
+      const strandedIssues = detect.issues.filter(i => i.code === "stranded_lock_directory");
+      assertTrue(strandedIssues.length > 0, "detects stranded lock directory");
+      assertTrue(strandedIssues[0]?.message.includes("lock directory"), "message describes stranded lock directory");
+      assertTrue(strandedIssues[0]?.fixable === true, "stranded lock dir is fixable");
+
+      const fixed = await runGSDDoctor(dir, { fix: true });
+      assertTrue(
+        fixed.fixesApplied.some(f => f.includes("removed stranded lock directory")),
+        "fix removes stranded lock directory",
+      );
+      assertTrue(!existsSync(lockDir), "lock directory removed after fix");
+    }
+
+    // ─── Test: Stranded lock dir with live lock holder — NOT flagged ───
+    console.log("\n=== stranded_lock_directory (live holder not flagged) ===");
+    {
+      const dir = createMinimalProject();
+      cleanups.push(dir);
+
+      // Create lock dir + auto.lock with PID 1 (init/launchd — always alive, never our own PID)
+      const lockDir = join(dir, ".gsd.lock");
+      mkdirSync(lockDir, { recursive: true });
+      const liveLockData = {
+        pid: 1,
+        startedAt: new Date().toISOString(),
+        unitType: "execute-task",
+        unitId: "M001/S01/T01",
+        unitStartedAt: new Date().toISOString(),
+        completedUnits: 1,
+      };
+      writeFileSync(join(dir, ".gsd", "auto.lock"), JSON.stringify(liveLockData, null, 2));
+
+      const detect = await runGSDDoctor(dir);
+      const strandedIssues = detect.issues.filter(i => i.code === "stranded_lock_directory");
+      assertEq(strandedIssues.length, 0, "live lock holder: stranded_lock_directory NOT detected");
+    }
+    } else {
+      console.log("\n=== stranded_lock_directory (skipped on Windows) ===");
+    }
+
   } finally {
     for (const dir of cleanups) {
       try { rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }

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