gsd-pi 2.78.1-dev.b0759e59b → 2.78.1-dev.e9d88a536

package/src/resources/extensions/gsd/bootstrap/dynamic-tools.ts

@@ -1,11 +1,12 @@
 import { existsSync } from "node:fs";
-import { join, sep } from "node:path";
+import { dirname } from "node:path";
 
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@gsd/pi-coding-agent";
 
 import { DEFAULT_BASH_TIMEOUT_SECS } from "../constants.js";
 import { setLogBasePath, logWarning } from "../workflow-logger.js";
+import { resolveGsdPathContract } from "../paths.js";
 
 /**
  * Resolve the correct DB path for the current working directory.
@@ -14,75 +15,16 @@ import { setLogBasePath, logWarning } from "../workflow-logger.js";
  * returns `<basePath>/.gsd/gsd.db`.
  */
 export function resolveProjectRootDbPath(basePath: string): string {
-  // Detect worktree: look for `.gsd/worktrees/` in the path segments.
-  // A worktree path looks like: /project/root/.gsd/worktrees/M001/...
-  // We need to resolve back to /project/root/.gsd/gsd.db
-  const marker = `${sep}.gsd${sep}worktrees${sep}`;
-  const idx = basePath.indexOf(marker);
-  if (idx !== -1) {
-    const projectRoot = basePath.slice(0, idx);
-    return join(projectRoot, ".gsd", "gsd.db");
-  }
-
-  // Also handle forward-slash paths on all platforms
-  const fwdMarker = "/.gsd/worktrees/";
-  const fwdIdx = basePath.indexOf(fwdMarker);
-  if (fwdIdx !== -1) {
-    const projectRoot = basePath.slice(0, fwdIdx);
-    return join(projectRoot, ".gsd", "gsd.db");
-  }
-
-  // External-state layout: ~/.gsd/projects/<hash>/worktrees/<MID>/...
-  // Resolve to ~/.gsd/projects/<hash>/gsd.db (the canonical project DB) (#2952).
-  // Must be checked before the generic symlink-resolved handler: both match
-  // /.gsd/projects/<hash>/worktrees/ but require different resolution targets.
-  const extRe = /[/\\]\.gsd[/\\]projects[/\\][a-f0-9]+[/\\]worktrees(?:[/\\]|$)/;
-  const extMatch = extRe.exec(basePath);
-  if (extMatch) {
-    const matchStr = extMatch[0];
-    // Find the "/worktrees" portion within the match and slice up to it
-    const wtIdx = matchStr.search(/[/\\]worktrees(?:[/\\]|$)/);
-    const projectStateRoot = basePath.slice(0, extMatch.index + wtIdx);
-    return join(projectStateRoot, "gsd.db");
-  }
-
-  // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/M001/...
-  // The project root is everything before /.gsd/projects/ (#2517)
-  const symlinkMarker = `${sep}.gsd${sep}projects${sep}`;
-  const symlinkIdx = basePath.indexOf(symlinkMarker);
-  if (symlinkIdx !== -1) {
-    const afterProjects = basePath.slice(symlinkIdx + symlinkMarker.length);
-    // Expect: <hash>/worktrees/...
-    const worktreeSeg = `${sep}worktrees${sep}`;
-    if (afterProjects.includes(worktreeSeg)) {
-      const projectRoot = basePath.slice(0, symlinkIdx);
-      return join(projectRoot, ".gsd", "gsd.db");
-    }
-  }
-
-  // Forward-slash variant for symlink-resolved layout
-  const fwdSymlinkMarker = "/.gsd/projects/";
-  const fwdSymlinkIdx = basePath.indexOf(fwdSymlinkMarker);
-  if (fwdSymlinkIdx !== -1) {
-    const afterProjects = basePath.slice(fwdSymlinkIdx + fwdSymlinkMarker.length);
-    if (afterProjects.includes("/worktrees/")) {
-      const projectRoot = basePath.slice(0, fwdSymlinkIdx);
-      return join(projectRoot, ".gsd", "gsd.db");
-    }
-  }
-
-
-  return join(basePath, ".gsd", "gsd.db");
+  return resolveGsdPathContract(basePath).projectDb;
 }
 
 export async function ensureDbOpen(basePath: string = process.cwd()): Promise<boolean> {
   try {
     const db = await import("../gsd-db.js");
-    const dbPath = resolveProjectRootDbPath(basePath);
-    const gsdDir = join(basePath, ".gsd");
-
-    // Derive the project root from the DB path (strip .gsd/gsd.db)
-    const projectRoot = join(dbPath, "..", "..");
+    const contract = resolveGsdPathContract(basePath);
+    const dbPath = contract.projectDb;
+    const gsdDir = contract.projectGsd;
+    const projectRoot = dirname(dirname(dbPath));
 
     // Open existing DB file (may be at project root for worktrees)
     if (existsSync(dbPath)) {
@@ -91,26 +33,9 @@ export async function ensureDbOpen(basePath: string = process.cwd()): Promise<bo
       return opened;
     }
 
-    // No DB file — create + migrate from Markdown if .gsd/ has content
+    // No DB file — create an empty authoritative DB. Markdown migration is
+    // explicit-only; runtime startup must not import projections into state.
     if (existsSync(gsdDir)) {
-      const hasDecisions = existsSync(join(gsdDir, "DECISIONS.md"));
-      const hasRequirements = existsSync(join(gsdDir, "REQUIREMENTS.md"));
-      const hasMilestones = existsSync(join(gsdDir, "milestones"));
-      if (hasDecisions || hasRequirements || hasMilestones) {
-        const opened = db.openDatabase(dbPath);
-        if (opened) {
-          setLogBasePath(projectRoot);
-          try {
-            const { migrateFromMarkdown } = await import("../md-importer.js");
-            migrateFromMarkdown(basePath);
-          } catch (err) {
-            logWarning("bootstrap", `ensureDbOpen auto-migration failed: ${(err as Error).message}`);
-          }
-        }
-        return opened;
-      }
-
-      // .gsd/ exists but has no Markdown content (fresh project) — create empty DB
       const opened = db.openDatabase(dbPath);
       if (opened) setLogBasePath(projectRoot);
       return opened;

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

@@ -16,7 +16,7 @@ import {
 } from "./codebase-generator.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import type { CodebaseMapOptions } from "./codebase-generator.js";
-import { projectRoot } from "./commands/context.js";
+import { currentDirectoryRoot } from "./commands/context.js";
 
 const USAGE =
   "Usage: /gsd codebase [generate|update|stats]\n\n" +
@@ -37,7 +37,7 @@ export async function handleCodebase(
   ctx: ExtensionCommandContext,
   _pi: ExtensionAPI,
 ): Promise<void> {
-  const basePath = projectRoot();
+  const basePath = currentDirectoryRoot();
   const parts = args.trim().split(/\s+/);
   const sub = parts[0] ?? "";
 

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

@@ -24,7 +24,7 @@ import {
 } from "./doctor.js";
 import { isAutoActive, checkRemoteAutoSession } from "./auto.js";
 import { getAutoWorktreePath } from "./auto-worktree.js";
-import { projectRoot } from "./commands/context.js";
+import { currentDirectoryRoot, projectRoot } from "./commands/context.js";
 import { loadPrompt } from "./prompt-loader.js";
 
 const UPDATE_REGISTRY_URL = "https://registry.npmjs.org/gsd-pi/latest";
@@ -203,7 +203,7 @@ export async function handleCapture(args: string, ctx: ExtensionCommandContext):
     return;
   }
 
-  const basePath = projectRoot();
+  const basePath = currentDirectoryRoot();
 
   // Ensure .gsd/ exists — capture should work even without a milestone
   const gsdDir = gsdRoot(basePath);
@@ -270,7 +270,7 @@ export async function handleTriage(ctx: ExtensionCommandContext, pi: ExtensionAP
 }
 
 export async function handleSteer(change: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
-  const basePath = projectRoot();
+  const basePath = currentDirectoryRoot();
   const state = await deriveState(basePath);
   const mid = state.activeMilestone?.id ?? "none";
   const sid = state.activeSlice?.id ?? "none";
@@ -343,7 +343,7 @@ export async function handleKnowledge(args: string, ctx: ExtensionCommandContext
   }
 
   const type = typeArg as "rule" | "pattern" | "lesson";
-  const basePath = projectRoot();
+  const basePath = currentDirectoryRoot();
   const state = await deriveState(basePath);
   const scope = state.activeMilestone?.id
     ? `${state.activeMilestone.id}${state.activeSlice ? `/${state.activeSlice.id}` : ""}`
@@ -372,7 +372,7 @@ Examples:
   }
 
   const [hookName, unitType, unitId] = parts;
-  const basePath = projectRoot();
+  const basePath = currentDirectoryRoot();
 
   // Import the hook trigger function
   const { triggerHookManually, formatHookStatus, getHookStatus } = await import("./post-unit-hooks.js");

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

@@ -15,7 +15,7 @@ import { existsSync, readdirSync, readFileSync, statSync, unlinkSync } from "nod
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { loadJsonFileOrNull } from "./json-persistence.js";
-import { projectRoot } from "./commands/context.js";
+import { currentDirectoryRoot } from "./commands/context.js";
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -244,7 +244,7 @@ function summarizeDebugLog(filePath: string): {
 // ─── Main Handler ───────────────────────────────────────────────────────────
 
 export async function handleLogs(args: string, ctx: ExtensionCommandContext): Promise<void> {
-  const basePath = projectRoot();
+  const basePath = currentDirectoryRoot();
   const parts = args.trim().split(/\s+/).filter(Boolean);
   const subCmd = parts[0] ?? "";
 

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

@@ -20,7 +20,7 @@ import { existsSync, mkdirSync } from "node:fs";
 import { join, relative } from "node:path";
 
 import { loadPrompt } from "./prompt-loader.js";
-import { projectRoot } from "./commands/context.js";
+import { currentDirectoryRoot } from "./commands/context.js";
 
 // ─── Constants ────────────────────────────────────────────────────────────────
 
@@ -87,7 +87,7 @@ export async function handleScan(
   ctx: ExtensionCommandContext,
   pi: ExtensionAPI,
 ): Promise<void> {
-  const basePath = projectRoot();
+  const basePath = currentDirectoryRoot();
   const { focus } = parseScanArgs(args);
   const outputDir = join(basePath, ".gsd", "codebase");
   const outputPaths = buildScanOutputPaths(focus, basePath);

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

@@ -17,7 +17,7 @@ import { getLedger, getProjectTotals, aggregateByModel, formatCost, formatTokenC
 import { nativeGetCurrentBranch, nativeDetectMainBranch } from "./native-git-bridge.js";
 import { formatDuration } from "../shared/format-utils.js";
 import { parseEvalReviewFrontmatter, type Verdict } from "./eval-review-schema.js";
-import { projectRoot } from "./commands/context.js";
+import { currentDirectoryRoot } from "./commands/context.js";
 
 function git(basePath: string, args: readonly string[]): string {
   return execFileSync("git", args, { cwd: basePath, encoding: "utf-8" }).trim();
@@ -223,7 +223,7 @@ export async function handleShip(
   ctx: ExtensionCommandContext,
   _pi: ExtensionAPI,
 ): Promise<void> {
-  const basePath = projectRoot();
+  const basePath = currentDirectoryRoot();
   const dryRun = args.includes("--dry-run");
   const draft = args.includes("--draft");
   const force = args.includes("--force");

package/src/resources/extensions/gsd/commands-workflow-templates.ts

@@ -23,7 +23,7 @@ import { createGitService, runGit } from "./git-service.js";
 import { isAutoActive, isAutoPaused } from "./auto.js";
 import { getErrorMessage } from "./error-utils.js";
 import { resolvePlugin, type WorkflowPlugin } from "./workflow-plugins.js";
-import { projectRoot } from "./commands/context.js";
+import { currentDirectoryRoot } from "./commands/context.js";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -197,7 +197,7 @@ export async function handleStart(
   // ─── Resume detection ───────────────────────────────────────────────────
   // /gsd start --resume or /gsd start resume → resume in-progress workflow
   if (trimmed === "--resume" || trimmed === "resume") {
-    const basePath = projectRoot();
+    const basePath = currentDirectoryRoot();
     const inProgress = findInProgressWorkflows(basePath);
     if (inProgress.length === 0) {
       ctx.ui.notify("No in-progress workflows found.", "info");
@@ -248,7 +248,7 @@ export async function handleStart(
 
   // Show in-progress workflows when /gsd start is called with no args
   if (!trimmed) {
-    const basePath = projectRoot();
+    const basePath = currentDirectoryRoot();
     const inProgress = findInProgressWorkflows(basePath);
     if (inProgress.length > 0) {
       const wf = inProgress[0];
@@ -347,7 +347,7 @@ export async function handleStart(
 
   const templateId = match.id;
   const template = match.template;
-  const basePath = projectRoot();
+  const basePath = currentDirectoryRoot();
   const date = new Date().toISOString().split("T")[0];
 
   // Load the workflow template content — prefer a project/global plugin
@@ -582,7 +582,7 @@ export function dispatchMarkdownPhasePlugin(
   }
 
   const templateId = plugin.name;
-  const basePath = projectRoot();
+  const basePath = currentDirectoryRoot();
   const date = new Date().toISOString().split("T")[0];
   let workflowContent: string;
   try {

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

@@ -318,23 +318,6 @@ export async function saveRequirementToDb(
            LIMIT 1`,
         )
         .get({ ':description': fields.description });
-      const previousRow: Requirement | null = existingRow
-        ? {
-            id: existingRow['id'] as string,
-            class: existingRow['class'] as string,
-            status: existingRow['status'] as string,
-            description: existingRow['description'] as string,
-            why: existingRow['why'] as string,
-            source: existingRow['source'] as string,
-            primary_owner: existingRow['primary_owner'] as string,
-            supporting_slices: existingRow['supporting_slices'] as string,
-            validation: existingRow['validation'] as string,
-            notes: existingRow['notes'] as string,
-            full_content: existingRow['full_content'] as string,
-            superseded_by: (existingRow['superseded_by'] as string) ?? null,
-          }
-        : null;
-
       const row = adapter
         .prepare('SELECT MAX(CAST(SUBSTR(id, 2) AS INTEGER)) as max_num FROM requirements')
         .get();
@@ -361,9 +344,9 @@ export async function saveRequirementToDb(
       };
 
       db.upsertRequirement(requirement);
-      return { id: nextId, isNew: !existingRow, previousRow };
+      return { id: nextId };
     });
-    const { id, isNew, previousRow } = txResult;
+    const { id } = txResult;
 
     // Fetch all requirements for full file regeneration
     const adapter = db._getAdapter();
@@ -392,17 +375,7 @@ export async function saveRequirementToDb(
     try {
       await saveFile(filePath, md);
     } catch (diskErr) {
-      logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveRequirementToDb', error: String((diskErr as Error).message) });
-      try {
-        if (isNew) {
-          db.deleteRequirementById(id);
-        } else if (previousRow) {
-          db.upsertRequirement(previousRow);
-        }
-      } catch (rollbackErr) {
-        logError('manifest', 'SPLIT BRAIN: disk write failed AND DB rollback failed — DB has orphaned row', { fn: 'saveRequirementToDb', id, error: String((rollbackErr as Error).message) });
-      }
-      throw diskErr;
+      logWarning('projection', 'REQUIREMENTS.md projection write failed; DB requirement remains committed', { fn: 'saveRequirementToDb', id, error: String((diskErr as Error).message) });
     }
     invalidateStateCache();
     clearPathCache();
@@ -538,13 +511,7 @@ export async function saveDecisionToDb(
     try {
       await saveFile(filePath, md);
     } catch (diskErr) {
-      logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveDecisionToDb', error: String((diskErr as Error).message) });
-      try {
-        db.deleteDecisionById(id);
-      } catch (rollbackErr) {
-        logError('manifest', 'SPLIT BRAIN: disk write failed AND DB rollback failed — DB has orphaned row', { fn: 'saveDecisionToDb', id, error: String((rollbackErr as Error).message) });
-      }
-      throw diskErr;
+      logWarning('projection', 'DECISIONS.md projection write failed; DB decision remains committed', { fn: 'saveDecisionToDb', id, error: String((diskErr as Error).message) });
     }
     // #2661: When a decision defers a slice, update the slice status in the DB
     // so the dispatcher skips it. Without this, STATE.md and DECISIONS.md are
@@ -667,34 +634,7 @@ export async function updateRequirementInDb(
   try {
     const db = await import('./gsd-db.js');
 
-    let existing = db.getRequirementById(id);
-
-    // If requirement doesn't exist in DB, seed the entire requirements table
-    // from REQUIREMENTS.md first (#3346). This handles the standard workflow
-    // where requirements are authored in markdown during discussion but never
-    // imported into the database — making gsd_requirement_update always fail
-    // with "not_found" at milestone completion.
-    if (!existing) {
-      const reqFilePath = resolveGsdRootFile(basePath, 'REQUIREMENTS');
-      try {
-        const content = readFileSync(reqFilePath, 'utf-8');
-        const { parseRequirementsSections } = await import('./md-importer.js');
-        const parsed = parseRequirementsSections(content);
-        if (parsed.length > 0) {
-          logWarning('manifest', `Seeding ${parsed.length} requirements from REQUIREMENTS.md into DB (first update triggers import)`, { fn: 'updateRequirementInDb' });
-          for (const req of parsed) {
-            // Only seed if not already in DB (avoid overwriting concurrent inserts)
-            if (!db.getRequirementById(req.id)) {
-              db.upsertRequirement(req);
-            }
-          }
-          // Re-check after seeding
-          existing = db.getRequirementById(id);
-        }
-      } catch {
-        // REQUIREMENTS.md missing or unparseable — fall through to skeleton
-      }
-    }
+    const existing = db.getRequirementById(id);
 
     const base: Requirement = existing ?? {
       id,
@@ -750,11 +690,7 @@ export async function updateRequirementInDb(
     try {
       await saveFile(filePath, md);
     } catch (diskErr) {
-      logError('manifest', 'disk write failed, reverting DB row', { fn: 'updateRequirementInDb', error: String((diskErr as Error).message) });
-      if (existing) {
-        db.upsertRequirement(existing);
-      }
-      throw diskErr;
+      logWarning('projection', 'REQUIREMENTS.md projection write failed; DB requirement update remains committed', { fn: 'updateRequirementInDb', id, error: String((diskErr as Error).message) });
     }
     // Invalidate file-read caches so deriveState() sees the updated markdown.
     // Do NOT clear the artifacts table — we just wrote to it intentionally.
@@ -805,20 +741,19 @@ export async function saveArtifactToDb(
       contentToPersist = generateRequirementsMd(activeRequirements);
     }
 
-    // Shrinkage guard: if the file already exists and the new content is
-    // significantly smaller (<50%), preserve the richer file on disk and
-    // store its content in the DB instead of the abbreviated version. Root
-    // canonical artifacts are exempt because their content is rendered from
-    // canonical DB state, and cleanup/consolidation is often intentionally much
-    // smaller than a malformed accumulated file.
-    let dbContent = contentToPersist;
+    // Shrinkage guard: if the projection file already exists and the new
+    // content is significantly smaller (<50%), preserve the richer file on
+    // disk, but keep the DB row authoritative with the caller-provided content.
+    // The disk file is a stale projection until the next explicit render.
+    // Root canonical artifacts are exempt because their content is rendered
+    // from canonical DB state, and cleanup/consolidation is often intentionally
+    // much smaller than a malformed accumulated file.
     let skipDiskWrite = false;
     if (!isRootCanonicalArtifact(opts) && existsSync(fullPath)) {
       const existingSize = statSync(fullPath).size;
       const newSize = Buffer.byteLength(contentToPersist, 'utf-8');
       if (existingSize > 0 && newSize < existingSize * 0.5) {
-        logWarning('manifest', `new content (${newSize}B) is <50% of existing file (${existingSize}B), preserving disk file`, { fn: 'saveArtifactToDb', path: opts.path });
-        dbContent = readFileSync(fullPath, 'utf-8');
+        logWarning('projection', `new content (${newSize}B) is <50% of existing projection (${existingSize}B), preserving disk file while DB remains authoritative`, { fn: 'saveArtifactToDb', path: opts.path });
         skipDiskWrite = true;
       }
     }
@@ -829,7 +764,7 @@ export async function saveArtifactToDb(
       milestone_id: opts.milestone_id ?? null,
       slice_id: opts.slice_id ?? null,
       task_id: opts.task_id ?? null,
-      full_content: dbContent,
+      full_content: contentToPersist,
     });
 
     // Write the file to disk (only if we're not preserving a richer existing file)
@@ -837,9 +772,7 @@ export async function saveArtifactToDb(
       try {
         await saveFile(fullPath, contentToPersist);
       } catch (diskErr) {
-        logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveArtifactToDb', error: String((diskErr as Error).message) });
-        db.deleteArtifactByPath(opts.path);
-        throw diskErr;
+        logWarning('projection', 'artifact projection write failed; DB artifact remains committed', { fn: 'saveArtifactToDb', path: opts.path, error: String((diskErr as Error).message) });
       }
     }
     // Invalidate file-read caches so deriveState() sees the updated markdown.

package/src/resources/extensions/gsd/dispatch-guard.ts

@@ -54,21 +54,16 @@ export function getPriorSliceCompletionBlocker(
     // completion, which is wrong when the SUMMARY is a failure-path report
     // (verification FAILED, blocker placeholder, etc.). Resolve as follows:
     //   1. When DB is available and status is closed → skip (authoritative).
-    //   2. When SUMMARY exists but looks like a failure/blocker report →
-    //      do not short-circuit; fall through to the slice-level check so
-    //      the guard can still block dependents of an active milestone.
-    //   3. Otherwise (SUMMARY without failure markers) → skip. Preserves
-    //      the #1716 contract where a completed milestone with unchecked
-    //      remediation slices is still treated as done.
-    const summaryPath = resolveMilestoneFile(base, mid, "SUMMARY");
+    //   2. When DB is unavailable, legacy SUMMARY.md fallback may skip.
+    //      DB-backed projects must not treat SUMMARY.md as authoritative.
     if (isDbAvailable()) {
       const milestoneRow = getMilestone(mid);
       if (milestoneRow && isClosedStatus(milestoneRow.status)) continue;
-    }
-    if (summaryPath) {
+    } else {
+      const summaryPath = resolveMilestoneFile(base, mid, "SUMMARY");
       let summaryContent: string | null = null;
-      try { summaryContent = readFileSync(summaryPath, "utf-8"); } catch { /* ignore */ }
-      if (!summaryContent || classifyMilestoneSummaryContent(summaryContent) !== "failure") {
+      try { summaryContent = summaryPath ? readFileSync(summaryPath, "utf-8") : null; } catch { /* ignore */ }
+      if (summaryContent && classifyMilestoneSummaryContent(summaryContent) !== "failure") {
         continue;
       }
     }

package/src/resources/extensions/gsd/doctor-engine-checks.ts

@@ -3,7 +3,7 @@ import { join } from "node:path";
 
 import type { DoctorIssue } from "./doctor-types.js";
 import { isDbAvailable, _getAdapter } from "./gsd-db.js";
-import { resolveMilestoneFile } from "./paths.js";
+import { resolveGsdPathContract, resolveMilestoneFile } from "./paths.js";
 import { deriveState } from "./state.js";
 import { readEvents } from "./workflow-events.js";
 import { renderAllProjections } from "./workflow-projections.js";
@@ -13,7 +13,7 @@ export async function checkEngineHealth(
   issues: DoctorIssue[],
   fixesApplied: string[],
 ): Promise<void> {
-  const dbPath = join(basePath, ".gsd", "gsd.db");
+  const dbPath = resolveGsdPathContract(basePath).projectDb;
 
   if (!isDbAvailable() && existsSync(dbPath)) {
     issues.push({