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

package/src/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/src/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/src/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/src/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/src/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;
-}
 

package/src/resources/extensions/gsd/gsd-db.ts

@@ -6,8 +6,7 @@
 // Schema is initialized on first open with WAL mode for file-backed DBs.
 
 import { createRequire } from 'node:module';
-import { copyFileSync, existsSync, mkdirSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { existsSync } from 'node:fs';
 import type { Decision, Requirement } from './types.js';
 import { GSDError, GSD_STALE_STATE } from './errors.js';
 
@@ -565,169 +564,6 @@ export function getActiveRequirements(): Requirement[] {
   }));
 }
 
-// ─── Worktree DB Operations ────────────────────────────────────────────────
-
-/**
- * Copy a gsd.db file to a new worktree location.
- * Copies only the .db file — skips -wal and -shm files so the copy starts clean.
- * Returns true on success, false on failure (never throws).
- */
-export function copyWorktreeDb(srcDbPath: string, destDbPath: string): boolean {
-  try {
-    if (!existsSync(srcDbPath)) {
-      return false; // source doesn't exist — expected when no DB yet
-    }
-    const destDir = dirname(destDbPath);
-    mkdirSync(destDir, { recursive: true });
-    copyFileSync(srcDbPath, destDbPath);
-    return true;
-  } catch (err) {
-    process.stderr.write(`gsd-db: failed to copy DB to worktree: ${(err as Error).message}\n`);
-    return false;
-  }
-}
-
-/**
- * Reconcile rows from a worktree DB back into the main DB using ATTACH DATABASE.
- * Merges all three tables (decisions, requirements, artifacts) via INSERT OR REPLACE.
- * Detects conflicts where both DBs modified the same row.
- *
- * ATTACH must happen outside any transaction. INSERT OR REPLACE runs inside a transaction.
- * DETACH happens after commit (or rollback on error).
- */
-export function reconcileWorktreeDb(
-  mainDbPath: string,
-  worktreeDbPath: string,
-): { decisions: number; requirements: number; artifacts: number; conflicts: string[] } {
-  const zero = { decisions: 0, requirements: 0, artifacts: 0, conflicts: [] as string[] };
-
-  // Validate worktree DB exists
-  if (!existsSync(worktreeDbPath)) {
-    return zero;
-  }
-
-  // Safety: reject single quotes which could break the ATTACH DATABASE '...' SQL literal.
-  // SQLite ATTACH doesn't support parameterized binding. We block the one dangerous char
-  // rather than allowlisting, since OS temp paths vary widely (tildes, parens, unicode).
-  if (worktreeDbPath.includes("'")) {
-    process.stderr.write(`gsd-db: worktree DB reconciliation failed: path contains unsafe characters\n`);
-    return zero;
-  }
-
-  // Ensure main DB is open
-  if (!currentDb) {
-    const opened = openDatabase(mainDbPath);
-    if (!opened) {
-      process.stderr.write(`gsd-db: worktree DB reconciliation failed: cannot open main DB\n`);
-      return zero;
-    }
-  }
-
-  const adapter = currentDb!;
-  const conflicts: string[] = [];
-
-  try {
-    // ATTACH must be outside transaction
-    adapter.exec(`ATTACH DATABASE '${worktreeDbPath}' AS wt`);
-
-    try {
-      // ── Conflict detection phase ──
-      // Decisions: same id, different content
-      const decisionConflicts = adapter.prepare(
-        `SELECT m.id FROM decisions m
-         INNER JOIN wt.decisions w ON m.id = w.id
-         WHERE m.decision != w.decision
-            OR m.choice != w.choice
-            OR m.rationale != w.rationale
-            OR m.superseded_by IS NOT w.superseded_by`,
-      ).all();
-      for (const row of decisionConflicts) {
-        conflicts.push(`decision ${row['id']}: modified in both main and worktree`);
-      }
-
-      // Requirements: same id, different content
-      const reqConflicts = adapter.prepare(
-        `SELECT m.id FROM requirements m
-         INNER JOIN wt.requirements w ON m.id = w.id
-         WHERE m.description != w.description
-            OR m.status != w.status
-            OR m.notes != w.notes
-            OR m.superseded_by IS NOT w.superseded_by`,
-      ).all();
-      for (const row of reqConflicts) {
-        conflicts.push(`requirement ${row['id']}: modified in both main and worktree`);
-      }
-
-      // Artifacts: same path, different content
-      const artifactConflicts = adapter.prepare(
-        `SELECT m.path FROM artifacts m
-         INNER JOIN wt.artifacts w ON m.path = w.path
-         WHERE m.full_content != w.full_content
-            OR m.artifact_type != w.artifact_type`,
-      ).all();
-      for (const row of artifactConflicts) {
-        conflicts.push(`artifact ${row['path']}: modified in both main and worktree`);
-      }
-
-      // ── Merge phase (inside manual transaction) ──
-      adapter.exec('BEGIN');
-      try {
-        // Decisions: exclude seq to let main auto-assign
-        adapter.exec(
-          `INSERT OR REPLACE INTO decisions (id, when_context, scope, decision, choice, rationale, revisable, superseded_by)
-           SELECT id, when_context, scope, decision, choice, rationale, revisable, superseded_by FROM wt.decisions`,
-        );
-        const dCount = adapter.prepare('SELECT changes() as cnt').get();
-
-        // Requirements: full row copy
-        adapter.exec(
-          `INSERT OR REPLACE INTO requirements (id, class, status, description, why, source, primary_owner, supporting_slices, validation, notes, full_content, superseded_by)
-           SELECT id, class, status, description, why, source, primary_owner, supporting_slices, validation, notes, full_content, superseded_by FROM wt.requirements`,
-        );
-        const rCount = adapter.prepare('SELECT changes() as cnt').get();
-
-        // Artifacts: copy with fresh imported_at timestamp
-        adapter.exec(
-          `INSERT OR REPLACE INTO artifacts (path, artifact_type, milestone_id, slice_id, task_id, full_content, imported_at)
-           SELECT path, artifact_type, milestone_id, slice_id, task_id, full_content, datetime('now') FROM wt.artifacts`,
-        );
-        const aCount = adapter.prepare('SELECT changes() as cnt').get();
-
-        adapter.exec('COMMIT');
-
-        const result = {
-          decisions: (dCount?.['cnt'] as number) || 0,
-          requirements: (rCount?.['cnt'] as number) || 0,
-          artifacts: (aCount?.['cnt'] as number) || 0,
-          conflicts,
-        };
-
-        if (conflicts.length > 0) {
-          process.stderr.write(`gsd-db: reconciliation conflicts:\n${conflicts.map(c => `  - ${c}`).join('\n')}\n`);
-        }
-        process.stderr.write(
-          `gsd-db: reconciled ${result.decisions} decisions, ${result.requirements} requirements, ${result.artifacts} artifacts (${conflicts.length} conflicts)\n`,
-        );
-
-        return result;
-      } catch (err) {
-        adapter.exec('ROLLBACK');
-        throw err;
-      }
-    } finally {
-      // DETACH always, even on error
-      try {
-        adapter.exec('DETACH DATABASE wt');
-      } catch {
-        // swallow — may already be detached
-      }
-    }
-  } catch (err) {
-    process.stderr.write(`gsd-db: worktree DB reconciliation failed: ${(err as Error).message}\n`);
-    return zero;
-  }
-}
-
 /**
  * Returns the PID of the process that opened the current DB connection.
  * Returns 0 if no connection is open.

package/src/resources/extensions/gsd/guided-flow.ts

@@ -104,7 +104,7 @@ export function checkAutoStartAfterDiscuss(): boolean {
         const missing = milestoneIds.filter(id => {
           const hasContext = !!resolveMilestoneFile(basePath, id, "CONTEXT");
           const hasDraft = !!resolveMilestoneFile(basePath, id, "CONTEXT-DRAFT");
-          const hasDir = existsSync(join(basePath, ".gsd", "milestones", id));
+          const hasDir = existsSync(join(gsdRoot(basePath), "milestones", id));
           return !hasContext && !hasDraft && !hasDir;
         });
         if (missing.length > 0) {
@@ -122,7 +122,7 @@ export function checkAutoStartAfterDiscuss(): boolean {
   // The LLM writes DISCUSSION-MANIFEST.json after each Phase 3 gate decision.
   // If the manifest exists but gates_completed < total, the LLM hasn't finished
   // presenting all readiness gates to the user — block auto-start.
-  const manifestPath = join(basePath, ".gsd", "DISCUSSION-MANIFEST.json");
+  const manifestPath = join(gsdRoot(basePath), "DISCUSSION-MANIFEST.json");
   if (existsSync(manifestPath)) {
     try {
       const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
@@ -295,7 +295,7 @@ export async function showHeadlessMilestoneCreation(
   const nextId = nextMilestoneId(existingIds, prefs?.preferences?.unique_milestone_ids ?? false);
 
   // Create milestone directory
-  const milestoneDir = join(basePath, ".gsd", "milestones", nextId, "slices");
+  const milestoneDir = join(gsdRoot(basePath), "milestones", nextId, "slices");
   mkdirSync(milestoneDir, { recursive: true });
 
   // Build and dispatch the headless discuss prompt
@@ -410,11 +410,14 @@ export async function showDiscuss(
   basePath: string,
 ): Promise<void> {
   // Guard: no .gsd/ project
-  if (!existsSync(join(basePath, ".gsd"))) {
+  if (!existsSync(gsdRoot(basePath))) {
     ctx.ui.notify("No GSD project found. Run /gsd to start one first.", "warning");
     return;
   }
 
+  // Invalidate caches to pick up artifacts written by a just-completed discuss/plan
+  invalidateAllCaches();
+
   const state = await deriveState(basePath);
 
   // Guard: no active milestone
@@ -750,7 +753,7 @@ export async function showSmartEntry(
   }
 
   // ── Detection preamble — run before any bootstrap ────────────────────
-  if (!existsSync(join(basePath, ".gsd"))) {
+  if (!existsSync(gsdRoot(basePath))) {
     const detection = detectProjectState(basePath);
 
     // v1 .planning/ detected — offer migration before anything else

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

@@ -75,7 +75,7 @@ async function ensureDbAvailable(): Promise<boolean> {
     if (db.isDbAvailable()) return true;
 
     // Auto-initialize: open (and create if needed) the DB at the standard path
-    const gsdDir = join(process.cwd(), ".gsd");
+    const gsdDir = gsdRoot(process.cwd());
     if (!existsSync(gsdDir)) return false; // No GSD project — can't create DB
     const dbPath = join(gsdDir, "gsd.db");
     return db.openDatabase(dbPath);
@@ -629,7 +629,7 @@ export default function (pi: ExtensionAPI) {
     description: shortcutDesc("Open GSD dashboard", "/gsd status"),
     handler: async (ctx) => {
       // Only show if .gsd/ exists
-      if (!existsSync(join(process.cwd(), ".gsd"))) {
+      if (!existsSync(gsdRoot(process.cwd()))) {
         ctx.ui.notify("No .gsd/ directory found. Run /gsd to start.", "info");
         return;
       }
@@ -659,7 +659,7 @@ export default function (pi: ExtensionAPI) {
 
   // ── before_agent_start: inject GSD contract into true system prompt ─────
   pi.on("before_agent_start", async (event, ctx: ExtensionContext) => {
-    if (!existsSync(join(process.cwd(), ".gsd"))) return;
+    if (!existsSync(gsdRoot(process.cwd()))) return;
 
     const stopContextTimer = debugTime("context-inject");
     const systemContent = loadPrompt("system");

package/src/resources/extensions/gsd/md-importer.ts

@@ -18,6 +18,7 @@ import {
 import {
   resolveGsdRootFile,
   milestonesDir,
+  gsdRoot,
   resolveTaskFiles,
 } from './paths.js';
 import { findMilestoneIds } from './guided-flow.js';
@@ -298,7 +299,7 @@ const TASK_SUFFIXES = ['PLAN', 'SUMMARY', 'CONTINUE', 'CONTEXT', 'RESEARCH'];
  */
 function importHierarchyArtifacts(gsdDir: string): number {
   let count = 0;
-  const gsdPath = join(gsdDir, '.gsd');
+  const gsdPath = gsdRoot(gsdDir);
 
   // Root-level artifacts: PROJECT.md, QUEUE.md
   const rootFiles = ['PROJECT.md', 'QUEUE.md', 'SECRETS-MANIFEST.md'];
@@ -487,7 +488,7 @@ export function migrateFromMarkdown(gsdDir: string): {
   requirements: number;
   artifacts: number;
 } {
-  const dbPath = join(gsdDir, '.gsd', 'gsd.db');
+  const dbPath = join(gsdRoot(gsdDir), 'gsd.db');
 
   // Open DB if not already open
   if (!_getAdapter()) {