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

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

@@ -181,7 +181,7 @@ function openRawDb(path: string): unknown {
   return new Database(path);
 }
 
-export const SCHEMA_VERSION = 22;
+export const SCHEMA_VERSION = 23;
 
 function indexExists(db: DbAdapter, name: string): boolean {
   return !!db.prepare(
@@ -354,7 +354,8 @@ function initSchema(db: DbAdapter, fileBacked: boolean): void {
         verification_uat TEXT NOT NULL DEFAULT '',
         definition_of_done TEXT NOT NULL DEFAULT '[]',
         requirement_coverage TEXT NOT NULL DEFAULT '',
-        boundary_map_markdown TEXT NOT NULL DEFAULT ''
+        boundary_map_markdown TEXT NOT NULL DEFAULT '',
+        sequence INTEGER DEFAULT 0
       )
     `);
 
@@ -1233,6 +1234,17 @@ function migrateSchema(db: DbAdapter): void {
       });
     }
 
+    if (currentVersion < 23) {
+      // v23: milestone queue ordering moves into the canonical DB. The
+      // historical QUEUE-ORDER.json file remains a projection, but runtime
+      // derivation must not read it as authoritative state.
+      ensureColumn(db, "milestones", "sequence", "ALTER TABLE milestones ADD COLUMN sequence INTEGER DEFAULT 0");
+      db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
+        ":version": 23,
+        ":applied_at": new Date().toISOString(),
+      });
+    }
+
     db.exec("COMMIT");
   } catch (err) {
     db.exec("ROLLBACK");
@@ -1602,6 +1614,34 @@ export function getActiveRequirements(): Requirement[] {
   }));
 }
 
+export function getRequirementCounts(): {
+  active: number;
+  validated: number;
+  deferred: number;
+  outOfScope: number;
+  blocked: number;
+  total: number;
+} {
+  if (!currentDb) {
+    return { active: 0, validated: 0, deferred: 0, outOfScope: 0, blocked: 0, total: 0 };
+  }
+  const rows = currentDb
+    .prepare("SELECT lower(status) as status, COUNT(*) as count FROM requirements GROUP BY lower(status)")
+    .all();
+  const counts = { active: 0, validated: 0, deferred: 0, outOfScope: 0, blocked: 0, total: 0 };
+  for (const row of rows) {
+    const status = String(row["status"] ?? "");
+    const count = Number(row["count"] ?? 0);
+    counts.total += count;
+    if (status === "active") counts.active += count;
+    else if (status === "validated") counts.validated += count;
+    else if (status === "deferred") counts.deferred += count;
+    else if (status === "out-of-scope" || status === "out_of_scope") counts.outOfScope += count;
+    else if (status === "blocked") counts.blocked += count;
+  }
+  return counts;
+}
+
 export function getDbOwnerPid(): number {
   return currentPid;
 }
@@ -2469,6 +2509,7 @@ export interface MilestoneRow {
   definition_of_done: string[];
   requirement_coverage: string;
   boundary_map_markdown: string;
+  sequence: number;
 }
 
 function rowToMilestone(row: Record<string, unknown>): MilestoneRow {
@@ -2490,6 +2531,7 @@ function rowToMilestone(row: Record<string, unknown>): MilestoneRow {
     definition_of_done: JSON.parse((row["definition_of_done"] as string) || "[]"),
     requirement_coverage: (row["requirement_coverage"] as string) ?? "",
     boundary_map_markdown: (row["boundary_map_markdown"] as string) ?? "",
+    sequence: Number(row["sequence"] ?? 0),
   };
 }
 
@@ -2517,7 +2559,9 @@ function rowToArtifact(row: Record<string, unknown>): ArtifactRow {
 
 export function getAllMilestones(): MilestoneRow[] {
   if (!currentDb) return [];
-  const rows = currentDb.prepare("SELECT * FROM milestones ORDER BY id").all();
+  const rows = currentDb.prepare(
+    "SELECT * FROM milestones ORDER BY CASE WHEN sequence > 0 THEN 0 ELSE 1 END, sequence, id",
+  ).all();
   return rows.map(rowToMilestone);
 }
 
@@ -2528,6 +2572,22 @@ export function getMilestone(id: string): MilestoneRow | null {
   return rowToMilestone(row);
 }
 
+export function setMilestoneQueueOrder(order: string[]): void {
+  if (!currentDb) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+  currentDb.exec("BEGIN IMMEDIATE");
+  try {
+    currentDb.prepare("UPDATE milestones SET sequence = 0").run();
+    const stmt = currentDb.prepare("UPDATE milestones SET sequence = :sequence WHERE id = :id");
+    order.forEach((id, index) => {
+      stmt.run({ ":id": id, ":sequence": index + 1 });
+    });
+    currentDb.exec("COMMIT");
+  } catch (err) {
+    currentDb.exec("ROLLBACK");
+    throw err;
+  }
+}
+
 /**
  * Update a milestone's status in the database.
  * Used by park/unpark to keep the DB in sync with the filesystem marker.
@@ -2723,6 +2783,8 @@ export function reconcileWorktreeDb(
       // fall through to the main DB's existing value (not a literal default)
       // so reconcile never silently clears state the main tree has recorded.
       const hasDecisionSource = wtInfo.some((col) => col["name"] === "source");
+      const wtMilestoneInfo = adapter.prepare("PRAGMA wt.table_info('milestones')").all();
+      const hasMilestoneSequence = wtMilestoneInfo.some((col) => col["name"] === "sequence");
       const wtSliceInfo = adapter.prepare("PRAGMA wt.table_info('slices')").all();
       const hasIsSketch = wtSliceInfo.some((col) => col["name"] === "is_sketch");
       const hasSketchScope = wtSliceInfo.some((col) => col["name"] === "sketch_scope");
@@ -2796,7 +2858,7 @@ export function reconcileWorktreeDb(
             id, title, status, depends_on, created_at, completed_at,
             vision, success_criteria, key_risks, proof_strategy,
             verification_contract, verification_integration, verification_operational, verification_uat,
-            definition_of_done, requirement_coverage, boundary_map_markdown
+            definition_of_done, requirement_coverage, boundary_map_markdown, sequence
           )
           SELECT w.id, w.title,
                  CASE
@@ -2814,7 +2876,8 @@ export function reconcileWorktreeDb(
                  END,
                  w.vision, w.success_criteria, w.key_risks, w.proof_strategy,
                  w.verification_contract, w.verification_integration, w.verification_operational, w.verification_uat,
-                 w.definition_of_done, w.requirement_coverage, w.boundary_map_markdown
+                 w.definition_of_done, w.requirement_coverage, w.boundary_map_markdown,
+                 ${hasMilestoneSequence ? "COALESCE(w.sequence, 0)" : "COALESCE(m.sequence, 0)"}
           FROM wt.milestones w
           LEFT JOIN milestones m ON m.id = w.id
         `).run());
@@ -3104,6 +3167,20 @@ export function getAssessment(path: string): Record<string, unknown> | null {
   return row ?? null;
 }
 
+export function getLatestAssessmentByScope(
+  milestoneId: string,
+  scope: string,
+): Record<string, unknown> | null {
+  if (!currentDb) return null;
+  const row = currentDb.prepare(
+    `SELECT * FROM assessments
+      WHERE milestone_id = :mid AND scope = :scope
+      ORDER BY created_at DESC
+      LIMIT 1`,
+  ).get({ ":mid": milestoneId, ":scope": scope });
+  return row ?? null;
+}
+
 // ─── Quality Gates ───────────────────────────────────────────────────────
 
 function rowToGate(row: Record<string, unknown>): GateRow {
@@ -3591,8 +3668,8 @@ export function restoreManifest(manifest: StateManifest): void {
       `INSERT INTO milestones (id, title, status, depends_on, created_at, completed_at,
         vision, success_criteria, key_risks, proof_strategy,
         verification_contract, verification_integration, verification_operational, verification_uat,
-        definition_of_done, requirement_coverage, boundary_map_markdown)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        definition_of_done, requirement_coverage, boundary_map_markdown, sequence)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
     );
     for (const m of manifest.milestones) {
       msStmt.run(
@@ -3601,7 +3678,7 @@ export function restoreManifest(manifest: StateManifest): void {
         m.vision, JSON.stringify(m.success_criteria), JSON.stringify(m.key_risks),
         JSON.stringify(m.proof_strategy),
         m.verification_contract, m.verification_integration, m.verification_operational, m.verification_uat,
-        JSON.stringify(m.definition_of_done), m.requirement_coverage, m.boundary_map_markdown,
+        JSON.stringify(m.definition_of_done), m.requirement_coverage, m.boundary_map_markdown, m.sequence ?? 0,
       );
     }
 

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

@@ -36,7 +36,7 @@ import { gsdHome } from "./gsd-home.js";
 import {
   gsdRoot, milestonesDir, resolveMilestoneFile, resolveMilestonePath,
   resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile,
-  relMilestoneFile, relSliceFile,
+  relMilestoneFile, relSliceFile, clearPathCache,
 } from "./paths.js";
 import { join } from "node:path";
 import { readFileSync, existsSync, mkdirSync, readdirSync, rmSync, unlinkSync } from "node:fs";
@@ -588,12 +588,39 @@ export function maybeHandleReadyPhraseWithoutFiles(event: { messages: any[] }):
   const text = extractAssistantText(lastMsg);
   if (!READY_PHRASE_RE.test(text)) return false;
 
+  // Bust paths.ts cached dir listings before checking for fresh writes. The
+  // LLM's Write tool calls do not invalidate paths.ts caches, so a stale
+  // listing taken before the milestone dir or its CONTEXT/ROADMAP files
+  // existed would falsely report the artifacts as missing and trigger the
+  // 3-strike "ready without files" abort even though the writes succeeded.
+  clearPathCache();
+
   // Gate: artifacts must still be missing — if they exist, the happy path
   // already fired and we have nothing to do.
   const contextFile = resolveMilestoneFile(basePath, milestoneId, "CONTEXT");
   const roadmapFile = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
   if (contextFile || roadmapFile) return false;
 
+  // Diagnostic: when the cached resolver reports both files missing, also probe
+  // the canonical paths with uncached existsSync so we can tell whether the
+  // recovery is firing on real-missing files or a path-resolution miss
+  // (basePath/symlink mismatch, stale cache despite agent-end-recovery flush,
+  // legacy descriptor dir not matching, etc.).
+  try {
+    const mDir = resolveMilestonePath(basePath, milestoneId);
+    const canonicalCtx = mDir ? join(mDir, `${milestoneId}-CONTEXT.md`) : null;
+    const canonicalRoadmap = mDir ? join(mDir, `${milestoneId}-ROADMAP.md`) : null;
+    logWarning(
+      "guided",
+      `ready-phrase-reject diagnostic mid=${milestoneId} basePath=${basePath} ` +
+      `mDir=${mDir ?? "null"} ` +
+      `canonical-ctx=${canonicalCtx ?? "null"} ctx-exists=${canonicalCtx ? existsSync(canonicalCtx) : "n/a"} ` +
+      `canonical-roadmap=${canonicalRoadmap ?? "null"} roadmap-exists=${canonicalRoadmap ? existsSync(canonicalRoadmap) : "n/a"}`,
+    );
+  } catch (e) {
+    logWarning("guided", `ready-phrase-reject diagnostic failed: ${(e as Error).message}`);
+  }
+
   entry.readyRejectCount = (entry.readyRejectCount ?? 0) + 1;
 
   if (entry.readyRejectCount > MAX_READY_REJECTS) {
@@ -696,14 +723,14 @@ export function maybeHandleEmptyIntentTurn(
   // path, handled by maybeHandleReadyPhraseWithoutFiles.
   if (READY_PHRASE_RE.test(text)) return false;
 
-  // Skip if the LLM is clearly handing back to the user. Last-line `?` is
-  // the strongest signal, but discuss flows often end with a freeform
-  // question followed by a closing remark ("…what should we build? I'll
-  // pick one if you don't care."). Treat ANY non-empty line ending in `?`
-  // as a question-asked signal — false negatives here auto-reply to the
+  // Skip if the LLM is clearly handing back to the user. Discuss flows
+  // often pose a question and follow it with a conditional intent on the
+  // same line ("Did I capture that correctly? If so, I'll write the
+  // requirements."). A line-trailing `?` check misses these because the
+  // line ends in `.`. Match any sentence-terminating `?` (followed by
+  // whitespace or end-of-text) — false negatives here auto-reply to the
   // user, which is a much worse failure mode than a missed nudge.
-  const lines = text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
-  if (lines.some((l) => l.endsWith("?"))) return false;
+  if (/\?(?:\s|$)/.test(text)) return false;
 
   // Must contain a commit-intent phrase — this is the stall we care about.
   if (!COMMIT_INTENT_RE.test(text)) return false;

package/src/resources/extensions/gsd/markdown-renderer.ts

@@ -1,9 +1,8 @@
 // GSD Markdown Renderer — DB → Markdown file generation
 //
 // Transforms DB state into correct markdown files on disk.
-// Each render function reads from DB (with disk fallback),
-// patches content to match DB status, writes atomically to disk,
-// stores updated content in the artifacts table, and invalidates caches.
+// Each render function reads from DB, writes a markdown projection to disk,
+// stores generated content in the artifacts table, and invalidates caches.
 //
 // Critical invariant: rendered markdown must round-trip through
 // parseRoadmap(), parsePlan(), parseSummary() in files.ts.
@@ -85,58 +84,19 @@ function taskSummaryForSlicePlan(description: string): string {
 }
 
 /**
- * Load artifact content from DB first, falling back to reading from disk.
- * On disk fallback, stores the content in the artifacts table for future use.
- * Returns null if content is unavailable from both sources.
+ * Load artifact content from the DB. Markdown projections are not authoritative
+ * during runtime; when the artifact row is missing, callers regenerate from DB
+ * rows instead of patching disk fallback content and storing it back.
  */
 function loadArtifactContent(
   artifactPath: string,
-  absPath: string | null,
-  opts: {
-    artifact_type: string;
-    milestone_id: string;
-    slice_id?: string;
-    task_id?: string;
-  },
 ): string | null {
-  // Try DB first
   const artifact = getArtifact(artifactPath);
   if (artifact && artifact.full_content) {
     return artifact.full_content;
   }
 
-  // Fall back to disk
-  if (!absPath) {
-    process.stderr.write(
-      `markdown-renderer: artifact not found in DB or on disk: ${artifactPath}\n`,
-    );
-    return null;
-  }
-
-  let content: string;
-  try {
-    content = readFileSync(absPath, "utf-8");
-  } catch {
-    logWarning("renderer", `cannot read file from disk: ${absPath}`);
-    return null;
-  }
-
-  // Store in DB for future use (graceful degradation path)
-  try {
-    insertArtifact({
-      path: artifactPath,
-      artifact_type: opts.artifact_type,
-      milestone_id: opts.milestone_id,
-      slice_id: opts.slice_id ?? null,
-      task_id: opts.task_id ?? null,
-      full_content: content,
-    });
-  } catch {
-    // Non-fatal: we have the content, DB storage is best-effort
-    logWarning("renderer", `failed to store disk fallback in DB: ${artifactPath}`);
-  }
-
-  return content;
+  return null;
 }
 
 /**
@@ -507,20 +467,15 @@ export async function renderRoadmapCheckboxes(
   const absPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
   const artifactPath = absPath ? toArtifactPath(absPath, basePath) : null;
 
-  // Load content from DB (with disk fallback)
+  // Load content from DB; regenerate from DB rows when the artifact is absent.
   let content: string | null = null;
   if (artifactPath) {
-    content = loadArtifactContent(artifactPath, absPath, {
-      artifact_type: "ROADMAP",
-      milestone_id: milestoneId,
-    });
+    content = loadArtifactContent(artifactPath);
   }
 
   if (!content) {
-    process.stderr.write(
-      `markdown-renderer: no roadmap content available for ${milestoneId}\n`,
-    );
-    return false;
+    await renderRoadmapFromDb(basePath, milestoneId);
+    return true;
   }
 
   // Apply checkbox patches for each slice
@@ -582,18 +537,12 @@ export async function renderPlanCheckboxes(
 
   let content: string | null = null;
   if (artifactPath) {
-    content = loadArtifactContent(artifactPath, absPath, {
-      artifact_type: "PLAN",
-      milestone_id: milestoneId,
-      slice_id: sliceId,
-    });
+    content = loadArtifactContent(artifactPath);
   }
 
   if (!content) {
-    process.stderr.write(
-      `markdown-renderer: no plan content available for ${milestoneId}/${sliceId}\n`,
-    );
-    return false;
+    await renderPlanFromDb(basePath, milestoneId, sliceId);
+    return true;
   }
 
   // Apply checkbox patches for each task

package/src/resources/extensions/gsd/parallel-merge.ts

@@ -9,7 +9,7 @@ import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { loadFile } from "./files.js";
-import { resolveMilestoneFile } from "./paths.js";
+import { resolveGsdPathContract, resolveMilestoneFile } from "./paths.js";
 import { mergeMilestoneToMain } from "./auto-worktree.js";
 import { MergeConflictError } from "./git-service.js";
 import { removeSessionStatus } from "./session-status-io.js";
@@ -33,12 +33,13 @@ export type MergeOrder = "sequential" | "by-completion";
 // ─── Merge Queue ───────────────────────────────────────────────────────────
 
 /**
- * Check whether a milestone is complete by querying its worktree SQLite DB.
+ * Check whether a milestone is complete by querying the canonical project DB.
  * Uses a subprocess to avoid disrupting the global DB singleton.
- * Returns true when milestones.status = 'complete' in the worktree's gsd.db.
+ * Returns true when milestones.status = 'complete' in project gsd.db.
  */
-export function isMilestoneCompleteInWorktreeDb(basePath: string, mid: string): boolean {
-  const dbPath = join(basePath, ".gsd", "worktrees", mid, ".gsd", "gsd.db");
+export function isMilestoneCompleteInProjectDb(basePath: string, mid: string): boolean {
+  const workRoot = join(basePath, ".gsd", "worktrees", mid);
+  const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
   if (!existsSync(dbPath)) return false;
 
   try {
@@ -55,15 +56,15 @@ export function isMilestoneCompleteInWorktreeDb(basePath: string, mid: string):
 }
 
 /**
- * Discover milestone IDs with status='complete' in their worktree DB,
- * scanning .gsd/worktrees/<MID>/.gsd/gsd.db for each worktree directory.
+ * Discover milestone IDs with status='complete' in the canonical DB,
+ * using worktree directories only to enumerate active parallel workers.
  */
 function discoverDbCompletedMilestones(basePath: string): Set<string> {
   const completed = new Set<string>();
   const worktreeDir = join(basePath, ".gsd", "worktrees");
   try {
     for (const entry of readdirSync(worktreeDir)) {
-      if (entry.startsWith("M") && isMilestoneCompleteInWorktreeDb(basePath, entry)) {
+      if (entry.startsWith("M") && isMilestoneCompleteInProjectDb(basePath, entry)) {
         completed.add(entry);
       }
     }
@@ -78,9 +79,9 @@ function discoverDbCompletedMilestones(basePath: string): Set<string> {
  * Sequential: merge in milestone ID order (M001 before M002).
  * By-completion: merge in the order milestones finished.
  *
- * When basePath is provided, also checks worktree SQLite DBs as the
- * source of truth — workers with stale orchestrator state (e.g. "error")
- * are included if their worktree DB shows status='complete'.
+ * When basePath is provided, also checks the canonical project DB as the
+ * source of truth. Workers with stale orchestrator state (e.g. "error")
+ * are included if their project DB row shows status='complete'.
  * See: https://github.com/gsd-build/gsd-2/issues/2812
  */
 export function determineMergeOrder(
@@ -93,7 +94,7 @@ export function determineMergeOrder(
     workers.filter(w => w.state === "stopped").map(w => w.milestoneId),
   );
 
-  // When basePath is available, also check worktree DBs for milestones
+  // When basePath is available, also check the project DB for milestones
   // whose orchestrator state is stale but are actually complete (#2812)
   const dbCompleted = basePath ? discoverDbCompletedMilestones(basePath) : new Set<string>();
 
@@ -109,7 +110,7 @@ export function determineMergeOrder(
     if (w) {
       allMergeable.push(w);
     } else {
-      // Milestone discovered from worktree DB but not in workers list
+      // Milestone discovered from project DB but not in workers list
       allMergeable.push({
         milestoneId: mid,
         title: mid,

package/src/resources/extensions/gsd/parallel-monitor-overlay.ts

@@ -17,6 +17,7 @@ import { truncateToWidth, visibleWidth, matchesKey, Key } from "@gsd/pi-tui";
 
 import { formatDuration, STATUS_GLYPH, STATUS_COLOR } from "../shared/mod.js";
 import { formattedShortcutPair } from "./shortcut-defs.js";
+import { resolveGsdPathContract } from "./paths.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -126,7 +127,8 @@ function discoverWorkers(basePath: string): string[] {
 }
 
 function querySliceProgress(basePath: string, mid: string): SliceProgress[] {
-  const dbPath = join(basePath, ".gsd", "worktrees", mid, ".gsd", "gsd.db");
+  const workRoot = join(basePath, ".gsd", "worktrees", mid);
+  const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
   if (!existsSync(dbPath)) return [];
 
   try {
@@ -166,7 +168,8 @@ function extractCostFromNdjson(basePath: string, mid: string): number {
 }
 
 function queryRecentCompletions(basePath: string, mid: string): string[] {
-  const dbPath = join(basePath, ".gsd", "worktrees", mid, ".gsd", "gsd.db");
+  const workRoot = join(basePath, ".gsd", "worktrees", mid);
+  const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
   if (!existsSync(dbPath)) return [];
   try {
     const sql = `SELECT id, slice_id, one_liner FROM tasks WHERE milestone_id='${mid}' AND status='complete' AND completed_at IS NOT NULL ORDER BY completed_at DESC LIMIT 5`;

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

@@ -10,12 +10,13 @@
  */
 
 import { readdirSync, existsSync, realpathSync, Dirent } from "node:fs";
-import { join, dirname, normalize } from "node:path";
+import { join, dirname, normalize, resolve } from "node:path";
 import { homedir } from "node:os";
 import { spawnSync } from "node:child_process";
 import { nativeScanGsdTree, type GsdTreeEntry } from "./native-parser-bridge.js";
 import { DIR_CACHE_MAX } from "./constants.js";
 import { gsdHome } from "./gsd-home.js";
+import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
 
 // ─── Directory Listing Cache ──────────────────────────────────────────────────
 
@@ -286,6 +287,56 @@ const LEGACY_GSD_ROOT_FILES: Record<GSDRootFileKey, string> = {
 
 const gsdRootCache = new Map<string, string>();
 
+export interface GsdPathContract {
+  /** Canonical repo/project root where authoritative state lives. */
+  projectRoot: string;
+  /** Current execution root, which may be an auto-worktree. */
+  workRoot: string;
+  /** Canonical authoritative .gsd directory. */
+  projectGsd: string;
+  /** Legacy worktree-local .gsd projection directory, when applicable. */
+  worktreeGsd: string | null;
+  /** Canonical authoritative SQLite DB path. */
+  projectDb: string;
+  /** True when workRoot is inside a GSD worktree layout. */
+  isWorktree: boolean;
+}
+
+export function resolveGsdPathContract(
+  workRoot: string,
+  originalProjectRoot?: string | null,
+): GsdPathContract {
+  const resolvedWorkRoot = resolve(workRoot || process.cwd());
+  const isWorktree = isGsdWorktreePath(resolvedWorkRoot);
+  if (isWorktree && !originalProjectRoot?.trim()) {
+    const externalMatch = /[/\\]\.gsd[/\\]projects[/\\][^/\\]+[/\\]worktrees(?:[/\\]|$)/.exec(resolvedWorkRoot);
+    if (externalMatch) {
+      const worktreesIdx = externalMatch[0].search(/[/\\]worktrees(?:[/\\]|$)/);
+      const projectGsd = resolvedWorkRoot.slice(0, externalMatch.index + worktreesIdx);
+      return {
+        projectRoot: dirname(dirname(projectGsd)),
+        workRoot: resolvedWorkRoot,
+        projectGsd,
+        worktreeGsd: join(resolvedWorkRoot, ".gsd"),
+        projectDb: join(projectGsd, "gsd.db"),
+        isWorktree,
+      };
+    }
+  }
+  const projectRoot = resolve(resolveWorktreeProjectRoot(resolvedWorkRoot, originalProjectRoot));
+  const projectGsd = join(projectRoot, ".gsd");
+  const worktreeGsd = isWorktree ? join(resolvedWorkRoot, ".gsd") : null;
+
+  return {
+    projectRoot,
+    workRoot: resolvedWorkRoot,
+    projectGsd,
+    worktreeGsd,
+    projectDb: join(projectGsd, "gsd.db"),
+    isWorktree,
+  };
+}
+
 /** Exported for tests only — do not call in production code. */
 export function _clearGsdRootCache(): void {
   gsdRootCache.clear();
@@ -378,6 +429,9 @@ function isInsideGsdWorktree(p: string): boolean {
 }
 
 function probeGsdRoot(rawBasePath: string): string {
+  const contract = resolveGsdPathContract(rawBasePath);
+  if (contract.isWorktree) return contract.projectGsd;
+
   // 1. Fast path — check the input path directly
   const local = join(rawBasePath, ".gsd");
   if (existsSync(local)) return local;

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

@@ -10,6 +10,12 @@ All relevant context has been preloaded below — start working immediately with
 
 {{inlinedContext}}
 
+## Already Planned? Soft Brake
+
+If `{{outputPath}}` already exists on disk with at least one slice line (e.g. `- [ ] **S01:`) AND `gsd_query` reports slice rows for this milestone, a prior `gsd_plan_milestone` call already persisted the plan. Do **not** re-call `gsd_plan_milestone` — its UPSERT would overwrite the existing plan with whatever you reconstruct, which is unsafe when you don't have the original decomposition reasoning. Skip directly to the ready phrase at the end of this prompt.
+
+If only the file exists (no DB rows) or only DB rows exist (no file), the prior write was incomplete — proceed with planning as normal so the tool reconciles both.
+
 ## Your Role in the Pipeline
 
 You are the first deep look at this milestone. You have full tool access — explore the codebase, look up docs, investigate technology choices. Your job is to understand the landscape and then strategically decompose the work into demoable slices.

package/src/resources/extensions/gsd/queue-order.ts

@@ -13,6 +13,7 @@ import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { milestoneIdSort } from "./milestone-ids.js";
 import { loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
+import { isDbAvailable, setMilestoneQueueOrder } from "./gsd-db.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -63,9 +64,13 @@ export function loadQueueOrder(basePath: string): string[] | null {
 }
 
 /**
- * Save a custom queue order to disk.
+ * Save a custom queue order. The DB sequence is canonical when a DB
+ * connection is open; QUEUE-ORDER.json remains a compatibility projection.
  */
 export function saveQueueOrder(basePath: string, order: string[]): void {
+  if (isDbAvailable()) {
+    setMilestoneQueueOrder(order);
+  }
   const data: QueueOrderFile = {
     order,
     updatedAt: new Date().toISOString(),

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

@@ -20,7 +20,7 @@ import { getMilestoneSlices, isDbAvailable } from "./gsd-db.js";
 import { buildExistingMilestonesContext } from "./guided-flow-queue.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { isGsdGitignored } from "./gitignore.js";
-import { projectRoot } from "./commands/context.js";
+import { currentDirectoryRoot } from "./commands/context.js";
 
 // ─── Entry Point ──────────────────────────────────────────────────────────────
 
@@ -34,7 +34,7 @@ export async function handleRethink(
     return;
   }
 
-  const basePath = projectRoot();
+  const basePath = currentDirectoryRoot();
   const root = gsdRoot(basePath);
   if (!existsSync(root)) {
     ctx.ui.notify("No GSD project found. Run /gsd init first.", "warning");