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

package/dist/resources/extensions/gsd/auto-worktree.js

@@ -12,7 +12,7 @@ import { reconcileWorktreeDb, isDbAvailable, getMilestone, getMilestoneSlices, c
 import { atomicWriteSync } from "./atomic-write.js";
 import { execFileSync } from "node:child_process";
 import { safeCopy, safeCopyRecursive } from "./safe-fs.js";
-import { gsdRoot } from "./paths.js";
+import { gsdRoot, resolveGsdPathContract } from "./paths.js";
 import { createWorktree, removeWorktree, resolveGitDir, worktreePath, isInsideWorktreesDir, } from "./worktree-manager.js";
 import { detectWorktreeName, nudgeGitBranchCache, } from "./worktree.js";
 import { isGsdWorktreePath, normalizeWorktreePathForCompare, resolveWorktreeProjectRoot, } from "./worktree-root.js";
@@ -34,9 +34,8 @@ const LEGACY_DEEP_SETUP_RUNTIME_UNIT_FILES = new Set([
 ]);
 // ─── Shared Constants & Helpers ─────────────────────────────────────────────
 /**
- * Root-level .gsd/ state files synced between worktree and project root.
- * Single source of truth — used by syncGsdStateToWorktree, syncWorktreeStateBack,
- * and the dispatch-level sync functions.
+ * Root-level .gsd/ projections copied from project root into worktrees for
+ * compatibility. Project root remains the canonical state/projection root.
  */
 const ROOT_STATE_FILES = [
     "DECISIONS.md",
@@ -53,6 +52,10 @@ const ROOT_STATE_FILES = [
     // Back-sync (worktree → main) must NEVER overwrite the project root's copy
     // because the project root is authoritative for preferences (#2684).
 ];
+const ROOT_DIAGNOSTIC_FILES = [
+    "completed-units.json",
+    "metrics.json",
+];
 /**
  * Pop a stash entry by tracking the unique marker embedded in its message so
  * concurrent stash operations against the same project root cannot cause us to
@@ -137,7 +140,7 @@ const VERDICT_RE = /verdict:\s*[\w-]+/i;
  * destination when the source copy contains a `verdict:` field.
  *
  * This is the targeted fix for the UAT stuck-loop (#2821): the main
- * safeCopyRecursive uses force:false to protect worktree-authoritative
+ * safeCopyRecursive uses force:false to protect worktree-local projection
  * files (#1886), but ASSESSMENT files written by run-uat must be
  * forward-synced when the project root has a verdict. Without this,
  * the worktree retains a stale FAIL or missing ASSESSMENT and
@@ -212,9 +215,9 @@ function clearProjectRootStateFiles(basePath, milestoneId) {
             }
         }
     }
-    // Clean up entire synced milestone directory and runtime/units.
-    // syncStateToProjectRoot() copies these into the project root during
-    // execution.  If they remain as untracked files when we attempt
+    // Clean up legacy synced milestone directories and runtime/units.
+    // Older versions copied these into the project root during execution.
+    // If they remain as untracked files when we attempt
     // `git merge --squash`, git rejects the merge with "local changes would
     // be overwritten", causing silent data loss (#1738).
     const syncedDirs = [
@@ -277,8 +280,9 @@ export function syncProjectRootToWorktree(projectRoot, worktreePath_, milestoneI
         return;
     if (!milestoneId)
         return;
-    const prGsd = join(projectRoot, ".gsd");
-    const wtGsd = join(worktreePath_, ".gsd");
+    const contract = resolveGsdPathContract(worktreePath_, projectRoot);
+    const prGsd = contract.projectGsd;
+    const wtGsd = contract.worktreeGsd ?? join(worktreePath_, ".gsd");
     // When .gsd is a symlink to the same external directory in both locations,
     // cpSync rejects the copy because source === destination (ERR_FS_CP_EINVAL).
     // Compare realpaths and skip when they resolve to the same physical path (#2184).
@@ -286,12 +290,12 @@ export function syncProjectRootToWorktree(projectRoot, worktreePath_, milestoneI
         return;
     // Copy milestone directory from project root to worktree — additive only.
     // force:false prevents cpSync from overwriting existing worktree files.
-    // Without this, worktree-authoritative files (e.g. VALIDATION.md written
+    // Without this, worktree-local files (e.g. VALIDATION.md written
     // by validate-milestone) get clobbered by stale project root copies,
     // causing an infinite re-validation loop (#1886).
     safeCopyRecursive(join(prGsd, "milestones", milestoneId), join(wtGsd, "milestones", milestoneId), { force: false });
     // Force-sync ASSESSMENT files that have a verdict from project root (#2821).
-    // The additive-only copy above preserves worktree-authoritative files, but
+    // The additive-only copy above preserves worktree-local files, but
     // ASSESSMENT files are special: after run-uat writes a verdict and post-unit
     // syncs it to the project root, the worktree may retain a stale copy (e.g.
     // verdict:fail while the project root has verdict:pass from a retry). On
@@ -303,11 +307,9 @@ export function syncProjectRootToWorktree(projectRoot, worktreePath_, milestoneI
     // Project root is authoritative for completion state after crash recovery;
     // without this, the worktree re-dispatches already-completed units (#1886).
     safeCopy(join(prGsd, "completed-units.json"), join(wtGsd, "completed-units.json"), { force: true });
-    // Delete worktree gsd.db ONLY if it is empty (0 bytes).
-    // An empty DB is stale/corrupt and should be rebuilt (#853).
-    // A non-empty DB was populated by gsd-migrate on respawn and must be
-    // preserved — deleting it truncates the file to 0 bytes when
-    // openDatabase re-creates it, causing "no such table" failures (#2815).
+    // Delete a legacy worktree-local gsd.db ONLY if it is empty (0 bytes).
+    // Runtime opens contract.projectDb; this cleanup only removes corrupt
+    // pre-upgrade local DB projections.
     try {
         const wtDb = join(wtGsd, "gsd.db");
         let deleteSidecars = false;
@@ -342,9 +344,10 @@ export function syncProjectRootToWorktree(projectRoot, worktreePath_, milestoneI
     }
 }
 /**
- * Sync dispatch-critical .gsd/ state files from worktree to project root.
+ * Sync worktree diagnostics from worktree to project root.
  * Only runs when inside an auto-worktree (worktreePath differs from projectRoot).
- * Copies: STATE.md + active milestone directory (roadmap, slice plans, task summaries).
+ * DB/project-root state remains authoritative; markdown projections are not
+ * copied from the worktree back to the project root.
  * Non-fatal — sync failure should never block dispatch.
  */
 export function syncStateToProjectRoot(worktreePath_, projectRoot, milestoneId) {
@@ -352,23 +355,22 @@ export function syncStateToProjectRoot(worktreePath_, projectRoot, milestoneId)
         return;
     if (!milestoneId)
         return;
-    const wtGsd = join(worktreePath_, ".gsd");
-    const prGsd = join(projectRoot, ".gsd");
+    const contract = resolveGsdPathContract(worktreePath_, projectRoot);
+    const wtGsd = contract.worktreeGsd ?? join(worktreePath_, ".gsd");
+    const prGsd = contract.projectGsd;
     // When .gsd is a symlink to the same external directory in both locations,
     // cpSync rejects the copy because source === destination (ERR_FS_CP_EINVAL).
     // Compare realpaths and skip when they resolve to the same physical path (#2184).
     if (isSamePath(wtGsd, prGsd))
         return;
-    // 1. STATE.md — the quick-glance status used by initial deriveState()
-    safeCopy(join(wtGsd, "STATE.md"), join(prGsd, "STATE.md"), { force: true });
-    // 2. Milestone directory — ROADMAP, slice PLANs, task summaries
-    // Copy the entire milestone .gsd subtree so deriveState reads current checkboxes
-    safeCopyRecursive(join(wtGsd, "milestones", milestoneId), join(prGsd, "milestones", milestoneId), { force: true });
-    // 3. metrics.json — session cost/token tracking (#2313).
+    // metrics.json — session cost/token tracking (#2313).
     // Without this, metrics accumulated in the worktree are invisible from the
     // project root and never appear in the dashboard or skill-health reports.
     safeCopy(join(wtGsd, "metrics.json"), join(prGsd, "metrics.json"), { force: true });
-    // 4. Runtime records — unit dispatch state used by selfHealRuntimeRecords().
+    // completed-units.json — runtime completion diagnostics used to avoid
+    // re-dispatching work already completed in an isolated worktree.
+    safeCopy(join(wtGsd, "completed-units.json"), join(prGsd, "completed-units.json"), { force: true });
+    // Runtime records — unit dispatch diagnostics used by selfHealRuntimeRecords().
     // Without this, a crash during a unit leaves the runtime record only in the
     // worktree. If the next session resolves basePath before worktree re-entry,
     // selfHeal can't find or clear the stale record (#769).
@@ -529,12 +531,14 @@ export function cleanStaleRuntimeUnits(gsdRootPath, hasMilestoneSummary) {
  * missing milestones, CONTEXT, ROADMAP, DECISIONS, REQUIREMENTS, and
  * PROJECT files from the main repo's .gsd/ into the worktree's .gsd/.
  *
- * Only adds missing content — never overwrites existing files in the worktree
- * (the worktree's execution state is authoritative for in-progress work).
+ * Only adds missing content — never overwrites existing files in the worktree.
+ * Worktree files are compatibility projections; DB/project root remains
+ * authoritative for runtime state.
  */
 export function syncGsdStateToWorktree(mainBasePath, worktreePath_) {
-    const mainGsd = gsdRoot(mainBasePath);
-    const wtGsd = gsdRoot(worktreePath_);
+    const contract = resolveGsdPathContract(worktreePath_, mainBasePath);
+    const mainGsd = contract.projectGsd;
+    const wtGsd = contract.worktreeGsd ?? join(worktreePath_, ".gsd");
     const synced = [];
     // If both resolve to the same directory (symlink), no sync needed
     if (isSamePath(mainGsd, wtGsd))
@@ -678,28 +682,22 @@ export function syncGsdStateToWorktree(mainBasePath, worktreePath_) {
     return { synced };
 }
 /**
- * Sync milestone artifacts from worktree back to the main external state directory.
- * Called before milestone merge to ensure completion artifacts (SUMMARY, VALIDATION,
- * updated ROADMAP) are visible from the project root (#1412).
+ * Sync compatibility artifacts from worktree back to the main external state
+ * directory. Canonical workflow state lives in the project DB; worktree .gsd
+ * content is legacy projection/diagnostic data only.
  *
  * Syncs:
- *   1. Root-level .gsd/ files (REQUIREMENTS, PROJECT, DECISIONS, KNOWLEDGE,
- *      OVERRIDES) — the worktree's versions overwrite main's because the
- *      worktree is the authoritative execution context.
- *   2. ALL milestone directories found in the worktree — not just the
- *      current milestoneId. The complete-milestone unit may create artifacts
- *      for the *next* milestone (CONTEXT, ROADMAP, new requirements) which
- *      must survive worktree teardown.
+ *   1. Legacy worktree DBs are reconciled into the canonical project DB.
+ *   2. Runtime diagnostic files may be copied for operator visibility.
  *
- * History: Originally only synced milestones/<milestoneId>/ and assumed
- * root-level files would be carried by the squash merge. In practice,
- * .gsd/ files are often untracked (gitignored or never committed), so the
- * squash merge carries nothing. This caused next-milestone artifacts and
- * updated REQUIREMENTS/PROJECT to be silently lost on teardown.
+ * Markdown milestone directories are projections and are not copied from
+ * worktrees into the project root. Current workflow state must arrive through
+ * the shared project DB or the pre-upgrade DB reconciliation path above.
  */
 export function syncWorktreeStateBack(mainBasePath, worktreePath, milestoneId) {
-    const mainGsd = gsdRoot(mainBasePath);
-    const wtGsd = gsdRoot(worktreePath);
+    const contract = resolveGsdPathContract(worktreePath, mainBasePath);
+    const mainGsd = contract.projectGsd;
+    const wtGsd = contract.worktreeGsd ?? join(worktreePath, ".gsd");
     const synced = [];
     // If both resolve to the same directory (symlink), no sync needed
     if (isSamePath(mainGsd, wtGsd))
@@ -712,7 +710,7 @@ export function syncWorktreeStateBack(mainBasePath, worktreePath, milestoneId) {
     // files. This handles in-flight worktrees that were created before the
     // upgrade to shared WAL mode.
     const wtLocalDb = join(wtGsd, "gsd.db");
-    const mainDb = join(mainGsd, "gsd.db");
+    const mainDb = contract.projectDb;
     if (existsSync(wtLocalDb) && existsSync(mainDb)) {
         try {
             reconcileWorktreeDb(mainDb, wtLocalDb);
@@ -723,13 +721,10 @@ export function syncWorktreeStateBack(mainBasePath, worktreePath, milestoneId) {
             logError("worktree", `DB reconciliation failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
-    // ── 1. Sync root-level .gsd/ files back ──────────────────────────────
-    // The worktree is authoritative — complete-milestone updates REQUIREMENTS,
-    // PROJECT, etc. These must overwrite main's copies so they survive teardown.
-    // Also includes QUEUE.md, completed-units.json, and metrics.json which are
-    // written during milestone closeout and lost on teardown without explicit sync
-    // (#1787, #2313).
-    for (const f of ROOT_STATE_FILES) {
+    // ── 1. Sync root-level diagnostic files back ─────────────────────────
+    // Markdown/JSON state projections remain project-root/DB authoritative.
+    // These diagnostic files are copied for observability only.
+    for (const f of ROOT_DIAGNOSTIC_FILES) {
         const src = join(wtGsd, f);
         const dst = join(mainGsd, f);
         if (existsSync(src)) {
@@ -743,103 +738,8 @@ export function syncWorktreeStateBack(mainBasePath, worktreePath, milestoneId) {
             }
         }
     }
-    // ── 2. Sync ALL milestone directories ────────────────────────────────
-    // The complete-milestone unit may create next-milestone artifacts (e.g.
-    // M007 setup while closing M006). We must sync every milestone directory
-    // in the worktree, not just the current one.
-    const wtMilestonesDir = join(wtGsd, "milestones");
-    if (!existsSync(wtMilestonesDir))
-        return { synced };
-    try {
-        const wtMilestones = readdirSync(wtMilestonesDir, { withFileTypes: true })
-            .filter((d) => d.isDirectory())
-            .map((d) => d.name);
-        for (const mid of wtMilestones) {
-            // Skip the current milestone being merged — its files are already in the
-            // milestone branch and would conflict with the squash merge (#3641).
-            if (mid === milestoneId)
-                continue;
-            syncMilestoneDir(wtGsd, mainGsd, mid, synced);
-        }
-    }
-    catch (err) {
-        /* non-fatal */
-        logWarning("worktree", `milestone sync-back failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
     return { synced };
 }
-function syncCurrentMilestoneStateAfterMerge(mainBasePath, worktreePath, milestoneId) {
-    const mainGsd = gsdRoot(mainBasePath);
-    const wtGsd = gsdRoot(worktreePath);
-    const synced = [];
-    if (isSamePath(mainGsd, wtGsd))
-        return { synced };
-    if (!existsSync(wtGsd) || !existsSync(mainGsd))
-        return { synced };
-    syncMilestoneDir(wtGsd, mainGsd, milestoneId, synced);
-    return { synced };
-}
-/**
- * Sync a single milestone directory from worktree to main.
- * Copies milestone-level .md files, slice-level files, and task summaries.
- */
-/** Copy matching files from srcDir to dstDir (non-fatal per file). */
-function syncDirFiles(srcDir, dstDir, filter, synced, prefix) {
-    try {
-        for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
-            if (!entry.isFile() || !filter(entry.name))
-                continue;
-            try {
-                cpSync(join(srcDir, entry.name), join(dstDir, entry.name), { force: true });
-                synced.push(`${prefix}${entry.name}`);
-            }
-            catch (err) {
-                /* non-fatal */
-                logWarning("worktree", `file copy failed (${prefix}${entry.name}): ${err instanceof Error ? err.message : String(err)}`);
-            }
-        }
-    }
-    catch (err) {
-        /* non-fatal — srcDir may not be readable */
-        logWarning("worktree", `directory read failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
-}
-function syncMilestoneDir(wtGsd, mainGsd, mid, synced) {
-    const wtMilestoneDir = join(wtGsd, "milestones", mid);
-    const mainMilestoneDir = join(mainGsd, "milestones", mid);
-    if (!existsSync(wtMilestoneDir))
-        return;
-    mkdirSync(mainMilestoneDir, { recursive: true });
-    const isMd = (name) => name.endsWith(".md");
-    // Sync milestone-level files (SUMMARY, VALIDATION, ROADMAP, CONTEXT)
-    syncDirFiles(wtMilestoneDir, mainMilestoneDir, isMd, synced, `milestones/${mid}/`);
-    // Sync slice-level files (summaries, UATs) and task summaries (#1678)
-    const wtSlicesDir = join(wtMilestoneDir, "slices");
-    const mainSlicesDir = join(mainMilestoneDir, "slices");
-    if (!existsSync(wtSlicesDir))
-        return;
-    try {
-        for (const sliceEntry of readdirSync(wtSlicesDir, { withFileTypes: true })) {
-            if (!sliceEntry.isDirectory())
-                continue;
-            const sid = sliceEntry.name;
-            const wtSliceDir = join(wtSlicesDir, sid);
-            const mainSliceDir = join(mainSlicesDir, sid);
-            mkdirSync(mainSliceDir, { recursive: true });
-            syncDirFiles(wtSliceDir, mainSliceDir, isMd, synced, `milestones/${mid}/slices/${sid}/`);
-            const wtTasksDir = join(wtSliceDir, "tasks");
-            const mainTasksDir = join(mainSliceDir, "tasks");
-            if (existsSync(wtTasksDir)) {
-                mkdirSync(mainTasksDir, { recursive: true });
-                syncDirFiles(wtTasksDir, mainTasksDir, isMd, synced, `milestones/${mid}/slices/${sid}/tasks/`);
-            }
-        }
-    }
-    catch (err) {
-        /* non-fatal */
-        logWarning("worktree", `milestone slice sync failed (${mid}): ${err instanceof Error ? err.message : String(err)}`);
-    }
-}
 // ─── Worktree Post-Create Hook (#597) ────────────────────────────────────────
 /**
  * Run the user-configured post-create hook script after worktree creation.
@@ -1002,10 +902,9 @@ export function enterBranchModeForMilestone(basePath, milestoneId) {
  * directory at the project root and apply any [x] checkbox states that are
  * ahead of the worktree version (forward-only: never downgrade [x] → [ ]).
  *
- * This is safe because syncStateToProjectRoot() is the authoritative source
- * of post-task state at the project root — it writes the same [x] the LLM
- * produced, then the auto-commit follows. If the commit never happened, the
- * filesystem copy is still valid and correct.
+ * This is forward-only compatibility for legacy projection copies. The DB
+ * remains authoritative; this never downgrades checked boxes in a local
+ * worktree projection.
  */
 function reconcilePlanCheckboxes(projectRoot, wtPath, milestoneId) {
     const srcMilestone = join(projectRoot, ".gsd", "milestones", milestoneId);
@@ -1457,9 +1356,10 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     // database (#2823).
     if (isDbAvailable()) {
         try {
-            const worktreeDbPath = join(worktreeCwd, ".gsd", "gsd.db");
-            const mainDbPath = join(originalBasePath_, ".gsd", "gsd.db");
-            if (!isSamePath(worktreeDbPath, mainDbPath)) {
+            const contract = resolveGsdPathContract(worktreeCwd, originalBasePath_);
+            const worktreeDbPath = join(contract.worktreeGsd ?? join(worktreeCwd, ".gsd"), "gsd.db");
+            const mainDbPath = contract.projectDb;
+            if (existsSync(worktreeDbPath) && !isSamePath(worktreeDbPath, mainDbPath)) {
                 reconcileWorktreeDb(mainDbPath, worktreeDbPath);
             }
         }
@@ -1964,23 +1864,6 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
     }
     // 9a-iii. Restore sheltered queued milestone directories (#2505).
     restoreShelter();
-    // 9a-iv. Preserve current milestone artifacts that may be untracked in git.
-    // syncWorktreeStateBack intentionally skips the current milestone before the
-    // squash merge to avoid conflicting with the merge content. Once the squash
-    // commit is complete, copy those files back so summaries, validation, and
-    // task outputs survive worktree teardown in external/.gitignored .gsd setups.
-    try {
-        const { synced } = syncCurrentMilestoneStateAfterMerge(originalBasePath_, worktreeCwd, milestoneId);
-        if (synced.length > 0) {
-            debugLog("mergeMilestoneToMain", {
-                phase: "current-milestone-sync-after-merge",
-                synced: synced.length,
-            });
-        }
-    }
-    catch (err) {
-        logWarning("worktree", `current milestone sync after merge failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
     // 9b. Safety check (#1792): if nothing was committed, verify the milestone
     // work is already on the integration branch before allowing teardown.
     // Compare only non-.gsd/ paths — .gsd/ state files diverge normally and

package/dist/resources/extensions/gsd/auto.js

@@ -56,11 +56,13 @@ import { getErrorMessage } from "./error-utils.js";
 import { recoverFailedMigration } from "./migrate-external.js";
 import { initRegistry, convertDispatchRules } from "./rule-registry.js";
 import { emitJournalEvent as _emitJournalEvent } from "./journal.js";
+import { isClosedStatus } from "./status-guards.js";
 import { updateProgressWidget as _updateProgressWidget, updateSliceProgressCache, clearSliceProgressCache, } from "./auto-dashboard.js";
 import { registerSigtermHandler as _registerSigtermHandler, deregisterSigtermHandler as _deregisterSigtermHandler, } from "./auto-supervisor.js";
 import { isDbAvailable, getMilestone } from "./gsd-db.js";
 import { countPendingCaptures } from "./captures.js";
 import { CMUX_CHANNELS } from "../shared/cmux-events.js";
+import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 function makeCmuxEmitters(pi) {
     return {
         syncCmuxSidebar: (preferences, state) => pi.events.emit(CMUX_CHANNELS.SIDEBAR, { action: "sync", preferences, state }),
@@ -1154,15 +1156,31 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
                         || !!freshStartAssessment.lock);
                 if (shouldResumePausedSession) {
                     // Validate the milestone still exists and isn't already complete (#1664).
+                    // DB status is authoritative when available; SUMMARY.md is a legacy
+                    // fallback only for unmigrated/offline projects.
                     const mDir = resolveMilestonePath(base, meta.milestoneId);
-                    const summaryFile = resolveMilestoneFile(base, meta.milestoneId, "SUMMARY");
                     let summaryIsTerminal = false;
-                    if (summaryFile) {
-                        try {
-                            summaryIsTerminal = classifyMilestoneSummaryContent(readFileSync(summaryFile, "utf-8")) !== "failure";
+                    let dbAvailable = isDbAvailable();
+                    let milestoneRow = dbAvailable ? getMilestone(meta.milestoneId) : null;
+                    if (!milestoneRow) {
+                        const opened = await ensureDbOpen(base);
+                        dbAvailable = opened || isDbAvailable();
+                        if (dbAvailable) {
+                            milestoneRow = getMilestone(meta.milestoneId);
                         }
-                        catch {
-                            summaryIsTerminal = false;
+                    }
+                    if (dbAvailable) {
+                        summaryIsTerminal = !!milestoneRow && isClosedStatus(milestoneRow.status);
+                    }
+                    else {
+                        const summaryFile = resolveMilestoneFile(base, meta.milestoneId, "SUMMARY");
+                        if (summaryFile) {
+                            try {
+                                summaryIsTerminal = classifyMilestoneSummaryContent(readFileSync(summaryFile, "utf-8")) !== "failure";
+                            }
+                            catch {
+                                summaryIsTerminal = false;
+                            }
                         }
                     }
                     if (!mDir || summaryIsTerminal) {

package/dist/resources/extensions/gsd/bootstrap/dynamic-tools.js

@@ -1,8 +1,9 @@
 import { existsSync } from "node:fs";
-import { join, sep } from "node:path";
+import { dirname } from "node:path";
 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.
  * If `basePath` is inside a `.gsd/worktrees/<MID>/` directory, returns
@@ -10,67 +11,15 @@ import { setLogBasePath, logWarning } from "../workflow-logger.js";
  * returns `<basePath>/.gsd/gsd.db`.
  */
 export function resolveProjectRootDbPath(basePath) {
-    // 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 = process.cwd()) {
     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)) {
             const opened = db.openDatabase(dbPath);
@@ -78,26 +27,9 @@ export async function ensureDbOpen(basePath = process.cwd()) {
                 setLogBasePath(projectRoot);
             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.message}`);
-                    }
-                }
-                return opened;
-            }
-            // .gsd/ exists but has no Markdown content (fresh project) — create empty DB
             const opened = db.openDatabase(dbPath);
             if (opened)
                 setLogBasePath(projectRoot);

package/dist/resources/extensions/gsd/commands-codebase.js

@@ -6,7 +6,7 @@
  */
 import { generateCodebaseMap, updateCodebaseMap, writeCodebaseMap, getCodebaseMapStats, readCodebaseMap, } from "./codebase-generator.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { projectRoot } from "./commands/context.js";
+import { currentDirectoryRoot } from "./commands/context.js";
 const USAGE = "Usage: /gsd codebase [generate|update|stats]\n\n" +
     "  generate [--max-files N] [--collapse-threshold N]  — Generate or regenerate CODEBASE.md\n" +
     "  update [--max-files N] [--collapse-threshold N]    — Refresh the CODEBASE.md cache immediately\n" +
@@ -20,7 +20,7 @@ const USAGE = "Usage: /gsd codebase [generate|update|stats]\n\n" +
     "    max_files: 1000\n" +
     "    collapse_threshold: 15";
 export async function handleCodebase(args, ctx, _pi) {
-    const basePath = projectRoot();
+    const basePath = currentDirectoryRoot();
     const parts = args.trim().split(/\s+/);
     const sub = parts[0] ?? "";
     switch (sub) {

package/dist/resources/extensions/gsd/commands-handlers.js

@@ -15,7 +15,7 @@ import { appendOverride, appendKnowledge } from "./files.js";
 import { formatDoctorIssuesForPrompt, formatDoctorReport, formatDoctorReportJson, runGSDDoctor, selectDoctorScope, filterDoctorIssues, } 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";
 const UPDATE_FETCH_TIMEOUT_MS = 5000;
@@ -169,7 +169,7 @@ export async function handleCapture(args, ctx) {
         ctx.ui.notify('Usage: /gsd capture "your thought here"', "warning");
         return;
     }
-    const basePath = projectRoot();
+    const basePath = currentDirectoryRoot();
     // Ensure .gsd/ exists — capture should work even without a milestone
     const gsdDir = gsdRoot(basePath);
     if (!existsSync(gsdDir)) {
@@ -220,7 +220,7 @@ export async function handleTriage(ctx, pi, basePath) {
     }, { triggerTurn: true });
 }
 export async function handleSteer(change, ctx, pi) {
-    const basePath = projectRoot();
+    const basePath = currentDirectoryRoot();
     const state = await deriveState(basePath);
     const mid = state.activeMilestone?.id ?? "none";
     const sid = state.activeSlice?.id ?? "none";
@@ -284,7 +284,7 @@ export async function handleKnowledge(args, ctx) {
         return;
     }
     const type = typeArg;
-    const basePath = projectRoot();
+    const basePath = currentDirectoryRoot();
     const state = await deriveState(basePath);
     const scope = state.activeMilestone?.id
         ? `${state.activeMilestone.id}${state.activeSlice ? `/${state.activeSlice.id}` : ""}`
@@ -310,7 +310,7 @@ Examples:
         return;
     }
     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");
     const { dispatchHookUnit } = await import("./auto.js");

package/dist/resources/extensions/gsd/commands-logs.js

@@ -13,7 +13,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";
 // ─── Helpers ────────────────────────────────────────────────────────────────
 function activityDir(basePath) {
     return join(gsdRoot(basePath), "activity");
@@ -227,7 +227,7 @@ function summarizeDebugLog(filePath) {
 }
 // ─── Main Handler ───────────────────────────────────────────────────────────
 export async function handleLogs(args, ctx) {
-    const basePath = projectRoot();
+    const basePath = currentDirectoryRoot();
     const parts = args.trim().split(/\s+/).filter(Boolean);
     const subCmd = parts[0] ?? "";
     // /gsd logs clear