@opengsd/gsd-pi 1.1.1-dev.b2556262 → 1.2.0-dev.0b870afa

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

@@ -0,0 +1,170 @@
+// Project/App: gsd-pi
+// File Purpose: Workspace-facing Interface for opening and maintaining the workflow database.
+
+import { existsSync } from "node:fs";
+import { dirname } from "node:path";
+
+import type { GsdWorkspace, MilestoneScope } from "./workspace.js";
+import {
+  backupDatabaseSnapshot,
+  checkpointDatabase,
+  closeAllDatabases,
+  closeDatabase,
+  closeDatabaseByWorkspace,
+  getDbPath,
+  getDbStatus,
+  getDbProvider,
+  isDbAvailable,
+  openDatabase,
+  openDatabaseByScope,
+  openDatabaseByWorkspace,
+  refreshOpenDatabaseFromDisk,
+  vacuumDatabase,
+  wasDbOpenAttempted,
+} from "./gsd-db.js";
+import { resolveGsdPathContract } from "./paths.js";
+import { setLogBasePath } from "./workflow-logger.js";
+
+export interface WorkflowDatabaseLocation {
+  projectRoot: string;
+  projectGsd: string;
+  projectDb: string;
+}
+
+export type WorkflowDatabaseOpenReason =
+  | "opened-existing"
+  | "created-empty"
+  | "missing-database"
+  | "missing-gsd-dir"
+  | "open-failed";
+
+export type WorkflowDatabaseOpenResult =
+  | {
+      ok: true;
+      reason: "opened-existing" | "created-empty";
+      location: WorkflowDatabaseLocation;
+    }
+  | {
+      ok: false;
+      reason: "missing-database" | "missing-gsd-dir" | "open-failed";
+      location: WorkflowDatabaseLocation;
+      error?: Error;
+    };
+
+export type WorkflowDatabaseStatus = ReturnType<typeof getDbStatus>;
+export type WorkflowDatabaseProvider = ReturnType<typeof getDbProvider>;
+
+export function resolveWorkflowDatabaseLocation(basePath: string): WorkflowDatabaseLocation {
+  const contract = resolveGsdPathContract(basePath);
+  return {
+    projectRoot: dirname(dirname(contract.projectDb)),
+    projectGsd: contract.projectGsd,
+    projectDb: contract.projectDb,
+  };
+}
+
+/**
+ * Resolve the correct DB path for the current working directory.
+ * If `basePath` is inside a `.gsd/worktrees/<MID>/` directory, returns
+ * the project root's `.gsd/gsd.db` (shared WAL — R012). Otherwise returns
+ * `<basePath>/.gsd/gsd.db`.
+ */
+export function resolveProjectRootDbPath(basePath: string): string {
+  return resolveWorkflowDatabaseLocation(basePath).projectDb;
+}
+
+export function openWorkflowDatabase(basePath: string): WorkflowDatabaseOpenResult {
+  const location = resolveWorkflowDatabaseLocation(basePath);
+  if (!existsSync(location.projectGsd)) {
+    return { ok: false, reason: "missing-gsd-dir", location };
+  }
+
+  const existed = existsSync(location.projectDb);
+  try {
+    const opened = openDatabase(location.projectDb);
+    if (!opened) {
+      return { ok: false, reason: "open-failed", location };
+    }
+    setLogBasePath(location.projectRoot);
+    return {
+      ok: true,
+      reason: existed ? "opened-existing" : "created-empty",
+      location,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      reason: "open-failed",
+      location,
+      error: err instanceof Error ? err : new Error(String(err)),
+    };
+  }
+}
+
+export function openExistingWorkflowDatabase(basePath: string): WorkflowDatabaseOpenResult {
+  const location = resolveWorkflowDatabaseLocation(basePath);
+  if (!existsSync(location.projectDb)) {
+    return { ok: false, reason: "missing-database", location };
+  }
+  return openWorkflowDatabase(basePath);
+}
+
+export function openWorkflowDatabasePath(path: string): boolean {
+  return openDatabase(path);
+}
+
+export function openWorkflowDatabaseByWorkspace(workspace: GsdWorkspace): boolean {
+  return openDatabaseByWorkspace(workspace);
+}
+
+export function openWorkflowDatabaseByScope(scope: MilestoneScope): boolean {
+  return openDatabaseByScope(scope);
+}
+
+export function closeWorkflowDatabase(): void {
+  closeDatabase();
+}
+
+export function closeWorkflowDatabaseByWorkspace(workspace: GsdWorkspace): void {
+  closeDatabaseByWorkspace(workspace);
+}
+
+export function closeAllWorkflowDatabases(): void {
+  closeAllDatabases();
+}
+
+export function isWorkflowDatabaseOpen(): boolean {
+  return isDbAvailable();
+}
+
+export function wasWorkflowDatabaseOpenAttempted(): boolean {
+  return wasDbOpenAttempted();
+}
+
+export function getWorkflowDatabaseStatus(): WorkflowDatabaseStatus {
+  return getDbStatus();
+}
+
+export function getWorkflowDatabaseProvider(): WorkflowDatabaseProvider {
+  return getDbProvider();
+}
+
+export function getWorkflowDatabasePath(): string | null {
+  return getDbPath();
+}
+
+export function refreshWorkflowDatabaseFromDisk(): boolean {
+  return refreshOpenDatabaseFromDisk();
+}
+
+export function checkpointWorkflowDatabase(): void {
+  checkpointDatabase();
+}
+
+export function vacuumWorkflowDatabase(): void {
+  vacuumDatabase();
+}
+
+export function backupWorkflowDatabaseSnapshot(label: string): string | null {
+  return backupDatabaseSnapshot(label);
+}

package/src/resources/extensions/gsd/debug-logger.ts

@@ -25,6 +25,7 @@ const _counters = {
   parsePlanTotalMs: 0,
   dispatches: 0,
   renders: 0,
+  gitInvocations: 0,
 };
 
 /** Max debug log files to keep. Older ones are pruned on enable. */
@@ -131,6 +132,15 @@ export function debugCount(counter: keyof typeof _counters, value = 1): void {
   _counters[counter] += value;
 }
 
+/**
+ * Snapshot the current debug counters. Used by the per-dispatch benchmark
+ * harness (#442) to read counts without disabling debug (which is what
+ * writeDebugSummary does). Returns a copy so callers can't mutate internal state.
+ */
+export function getDebugCounters(): Readonly<typeof _counters> {
+  return { ..._counters };
+}
+
 /** Record a peak value (only updates if new value is higher). */
 export function debugPeak(counter: keyof typeof _counters, value: number): void {
   if (!_enabled) return;
@@ -168,6 +178,7 @@ export function writeDebugSummary(): string | null {
     avgTtsrCheck_ms,
     ttsrPeakBuffer: _counters.ttsrPeakBuffer,
     renders: _counters.renders,
+    gitInvocations: _counters.gitInvocations,
   });
 
   return disableDebug();

package/src/resources/extensions/gsd/delegation-policy.ts

@@ -35,6 +35,8 @@
 // existing entry is the place to lift any of these out of default-deny
 // when the analysis has been done.
 
+import { canonicalWorkflowSurfaceToolName } from "./workflow-tool-surface.js";
+
 export type BackgroundabilityVerdict = "good" | "risky" | "no";
 
 export interface DelegationPolicyEntry {
@@ -123,18 +125,8 @@ const POLICY: Record<string, DelegationPolicyEntry> = {
   },
 };
 
-// Alias map keyed on the secondary name; resolves to the canonical entry above.
-// Sourced from packages/mcp-server/src/workflow-tools.ts alias registrations
-// (gsd_milestone_validate, gsd_roadmap_reassess, gsd_slice_replan, gsd_task_plan).
-const ALIASES: Record<string, string> = {
-  gsd_milestone_validate: "gsd_validate_milestone",
-  gsd_roadmap_reassess: "gsd_reassess_roadmap",
-  gsd_slice_replan: "gsd_replan_slice",
-  gsd_task_plan: "gsd_plan_task",
-};
-
 function resolveCanonical(name: string): string {
-  return ALIASES[name] ?? name;
+  return canonicalWorkflowSurfaceToolName(name);
 }
 
 export function getDelegationVerdict(toolName: string): DelegationPolicyEntry | null {

package/src/resources/extensions/gsd/discussion-handoff.ts

@@ -0,0 +1,276 @@
+// Project/App: gsd-pi
+// File Purpose: Owns the guided-discuss to auto-mode handoff.
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { startAutoDetached } from "./auto.js";
+import { extractDepthVerificationMilestoneId, getPendingGate } from "./bootstrap/write-gate.js";
+import { getMilestone, insertMilestone, isDbAvailable } from "./gsd-db.js";
+import {
+  assessMilestoneHandoffReadiness,
+  formatAcceptedDiscussHandoffMessage,
+} from "./milestone-readiness.js";
+import { gsdRoot, resolveGsdRootFile, resolveMilestoneFile } from "./paths.js";
+import { _getPendingAutoStart, deletePendingAutoStart, type PendingAutoStartEntry } from "./pending-auto-start.js";
+import { logWarning } from "./workflow-logger.js";
+import { readManifest } from "./workflow-manifest.js";
+
+type AutoStartOptions = Parameters<typeof startAutoDetached>[4];
+type AutoStartLauncher = typeof startAutoDetached;
+
+// Cap failed in-flight DB row repair attempts before escalating to the user.
+const MAX_DB_ROW_RECOVERIES = 3;
+const PROJECT_DEPTH_GATE_IDS = new Set([
+  "depth_verification_project_confirm",
+  "depth_verification_requirements_confirm",
+  "depth_verification_research_decision_confirm",
+]);
+
+export function scheduleAutoStartAfterIdle(
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+  basePath: string,
+  verboseMode: boolean,
+  options?: AutoStartOptions,
+  launch: AutoStartLauncher = startAutoDetached,
+): void {
+  const waitForIdle =
+    typeof (ctx as { waitForIdle?: unknown }).waitForIdle === "function"
+      ? ctx.waitForIdle.bind(ctx)
+      : async () => {};
+  void waitForIdle()
+    .then(() => {
+      setTimeout(() => launch(ctx, pi, basePath, verboseMode, options), 0);
+    })
+    .catch((err) => {
+      const message = err instanceof Error ? err.message : String(err);
+      ctx.ui.notify(`Auto-start failed while waiting for the prior turn to settle: ${message}`, "error");
+      logWarning("guided", `auto-start idle wait failed: ${message}`);
+    });
+}
+
+function manifestContainsMilestone(basePath: string, milestoneId: string): boolean {
+  try {
+    const manifest = readManifest(basePath);
+    return (
+      Array.isArray(manifest?.milestones) &&
+      manifest.milestones.some(m => m.id === milestoneId)
+    );
+  } catch (e) {
+    logWarning("guided", `R3b: failed to read state manifest: ${(e as Error).message}`);
+    return false;
+  }
+}
+
+function notifyDbRowRecoveryFailed(entry: PendingAutoStartEntry): void {
+  entry.ctx.ui.notify(
+    `Milestone ${entry.milestoneId}: DB row recovery failed ${entry.r3bRecoveryCount} times. ` +
+    `Re-run /gsd to reset the recovery counter, or run /gsd-debug to diagnose without resetting.`,
+    "error",
+  );
+}
+
+function noteDbRowRecoveryMiss(entry: PendingAutoStartEntry): void {
+  entry.r3bRecoveryCount += 1;
+  if (entry.r3bRecoveryCount >= MAX_DB_ROW_RECOVERIES) {
+    notifyDbRowRecoveryFailed(entry);
+  }
+}
+
+function ensureMilestoneRowForAcceptedHandoff(
+  entry: PendingAutoStartEntry,
+  contextFile: string | null,
+): boolean {
+  if (!isDbAvailable()) return true;
+
+  const { basePath, milestoneId } = entry;
+  const milestoneRow = getMilestone(milestoneId);
+  if (milestoneRow) return true;
+
+  if (manifestContainsMilestone(basePath, milestoneId)) {
+    logWarning(
+      "guided",
+      `R3b: getMilestone(${milestoneId}) returned null but manifest has the row — treating as stale read`,
+    );
+    return true;
+  }
+
+  if (!contextFile) {
+    entry.ctx.ui.notify(
+      `Milestone ${milestoneId}: discuss artifacts on disk but no DB row exists. ` +
+      `PROJECT.md may have failed to register milestones. ` +
+      `Re-save PROJECT.md with canonical "- [ ] M001: Title — One-liner" lines, ` +
+      `then re-run /gsd to recover.`,
+      "error",
+    );
+    return false;
+  }
+
+  if (entry.r3bRecoveryCount >= MAX_DB_ROW_RECOVERIES) {
+    logWarning(
+      "guided",
+      `R3b: milestone ${milestoneId} DB-row recovery limit reached ` +
+      `(${entry.r3bRecoveryCount}/${MAX_DB_ROW_RECOVERIES}); user already notified`,
+    );
+    return false;
+  }
+
+  logWarning(
+    "guided",
+    `R3b: ${milestoneId} has CONTEXT.md but no DB row — inserting placeholder "queued" row ` +
+    `(attempt ${entry.r3bRecoveryCount + 1}/${MAX_DB_ROW_RECOVERIES})`,
+  );
+
+  try {
+    insertMilestone({ id: milestoneId, title: milestoneId, status: "queued" });
+  } catch (e) {
+    logWarning("guided", `R3b: insertMilestone failed: ${(e as Error).message}`);
+  }
+
+  if (getMilestone(milestoneId)) return true;
+
+  noteDbRowRecoveryMiss(entry);
+  return false;
+}
+
+/**
+ * Extract milestone IDs from PROJECT.md milestone sequence table.
+ * Looks for rows like "| M001 | Name | Status |" and extracts the ID column.
+ */
+function parseMilestoneSequenceFromProject(content: string): string[] {
+  const ids: string[] = [];
+  const lines = content.split(/\r?\n/);
+  for (const line of lines) {
+    const match = line.match(/^\|\s*(M\d{3}[A-Z0-9-]*)\s*\|/);
+    if (match) ids.push(match[1]);
+  }
+  return ids;
+}
+
+function hasBlockingDepthGate(entry: PendingAutoStartEntry): boolean {
+  const basePathForGate = entry.scope.workspace.projectRoot;
+  const pendingGateId = getPendingGate(basePathForGate);
+  if (!pendingGateId) return false;
+
+  const pendingMilestoneId = extractDepthVerificationMilestoneId(pendingGateId);
+  return pendingMilestoneId === entry.milestoneId || PROJECT_DEPTH_GATE_IDS.has(pendingGateId);
+}
+
+function discussionManifestPath(entry: PendingAutoStartEntry): string {
+  return join(entry.scope.workspace.contract.projectGsd, "DISCUSSION-MANIFEST.json");
+}
+
+function warnForMissingProjectMilestones(entry: PendingAutoStartEntry): string[] {
+  const { ctx, basePath } = entry;
+  const projectFile = resolveGsdRootFile(basePath, "PROJECT");
+  if (!projectFile) return [];
+
+  try {
+    const projectContent = readFileSync(projectFile, "utf-8");
+    const projectIds = parseMilestoneSequenceFromProject(projectContent);
+    if (projectIds.length <= 1) return projectIds;
+
+    const missing = projectIds.filter(id => {
+      const hasContext = !!resolveMilestoneFile(basePath, id, "CONTEXT");
+      const hasDraft = !!resolveMilestoneFile(basePath, id, "CONTEXT-DRAFT");
+      const hasDir = existsSync(join(gsdRoot(basePath), "milestones", id));
+      return !hasContext && !hasDraft && !hasDir;
+    });
+    if (missing.length > 0) {
+      ctx.ui.notify(
+        `Multi-milestone validation: ${missing.join(", ")} not found in filesystem. ` +
+        `Discussion may not have completed all readiness gates.`,
+        "warning",
+      );
+    }
+    return projectIds;
+  } catch (e) {
+    logWarning("guided", `PROJECT.md parsing failed: ${(e as Error).message}`);
+    return [];
+  }
+}
+
+function discussionManifestIsComplete(entry: PendingAutoStartEntry, projectIds: string[]): boolean {
+  const manifestPath = discussionManifestPath(entry);
+  if (!existsSync(manifestPath)) return true;
+
+  try {
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    const total = typeof manifest.total === "number" ? manifest.total : 0;
+    const completed = typeof manifest.gates_completed === "number" ? manifest.gates_completed : 0;
+
+    if (total > 1 && completed < total) {
+      return false;
+    }
+
+    if (projectIds.length > 0) {
+      const manifestIds = Object.keys(manifest.milestones ?? {});
+      const untracked = projectIds.filter(id => !manifestIds.includes(id));
+      if (untracked.length > 0) {
+        entry.ctx.ui.notify(
+          `Discussion manifest missing gates for: ${untracked.join(", ")}`,
+          "warning",
+        );
+      }
+    }
+  } catch (e) {
+    logWarning("guided", `discussion manifest verification failed: ${(e as Error).message}`);
+  }
+  return true;
+}
+
+function cleanupAcceptedHandoffArtifacts(entry: PendingAutoStartEntry): void {
+  const { basePath, milestoneId } = entry;
+  try {
+    const draftFile = resolveMilestoneFile(basePath, milestoneId, "CONTEXT-DRAFT");
+    if (draftFile) unlinkSync(draftFile);
+  } catch (e) {
+    logWarning("guided", `CONTEXT-DRAFT.md unlink failed: ${(e as Error).message}`);
+  }
+
+  const manifestPath = discussionManifestPath(entry);
+  if (existsSync(manifestPath)) {
+    try {
+      unlinkSync(manifestPath);
+    } catch (e) {
+      logWarning("guided", `manifest unlink failed: ${(e as Error).message}`);
+    }
+  }
+}
+
+/** Called from agent_end to check if auto-mode should start after discuss. */
+export function checkAutoStartAfterDiscuss(lookupBasePath?: string): boolean {
+  const entry = _getPendingAutoStart(lookupBasePath);
+  if (!entry) return false;
+
+  const { ctx, pi, basePath, milestoneId, step } = entry;
+  const contextFilePath = entry.scope.contextFile();
+  const roadmapFilePath = entry.scope.roadmapFile();
+  const contextFile = existsSync(contextFilePath) ? contextFilePath : null;
+  const roadmapFile = existsSync(roadmapFilePath) ? roadmapFilePath : null;
+  if (!contextFile && !roadmapFile) return false;
+
+  if (hasBlockingDepthGate(entry)) return false;
+  if (!ensureMilestoneRowForAcceptedHandoff(entry, contextFile)) return false;
+
+  const projectIds = warnForMissingProjectMilestones(entry);
+  if (!discussionManifestIsComplete(entry, projectIds)) return false;
+
+  cleanupAcceptedHandoffArtifacts(entry);
+  deletePendingAutoStart(basePath);
+
+  const readiness = assessMilestoneHandoffReadiness({
+    milestoneId,
+    contextFile,
+    roadmapFile,
+  });
+  ctx.ui.notify(
+    formatAcceptedDiscussHandoffMessage(milestoneId, readiness),
+    "success",
+  );
+  if (entry.startAuto !== false) {
+    scheduleAutoStartAfterIdle(ctx, pi, basePath, false, { step: step ?? true });
+  }
+  return true;
+}

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

@@ -3,9 +3,8 @@
 import { resolveMilestoneFile } from "./paths.js";
 import { findMilestoneIds } from "./guided-flow.js";
 import { parseUnitId } from "./unit-id.js";
-import { isDbAvailable, getMilestoneSlices, getMilestone } from "./gsd-db.js";
-import { parseRoadmap } from "./parsers-legacy.js";
-import { isClosedStatus, isSkippedForDispatch } from "./status-guards.js";
+import { isDbAvailable, getMilestoneSliceSummaries, getMilestone } from "./gsd-db.js";
+import { isSkippedForDispatch } from "./status-guards.js";
 import { classifyMilestoneSummaryContent } from "./milestone-summary-classifier.js";
 import { readFileSync } from "node:fs";
 import type { LoopState } from "./auto/types.js";
@@ -117,34 +116,12 @@ export function getPriorSliceCompletionBlocker(
       }
     }
 
-    // Normalised slice list from DB or file fallback
-    type NormSlice = { id: string; done: boolean; depends: string[] };
-    let slices: NormSlice[] | null = null;
-
-    if (isDbAvailable()) {
-      const rows = getMilestoneSlices(mid);
-      if (rows.length > 0) {
-        slices = rows.map((r) => ({
-          id: r.id,
-          done: isClosedStatus(r.status),
-          depends: r.depends ?? [],
-        }));
-      }
-    }
-    if (!slices) {
-      // File-based fallback: parse roadmap checkboxes
-      const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
-      if (!roadmapPath) continue;
-      let roadmapContent: string;
-      try { roadmapContent = readFileSync(roadmapPath, "utf-8"); } catch { continue; }
-      const parsed = parseRoadmap(roadmapContent);
-      if (parsed.slices.length === 0) continue;
-      slices = parsed.slices.map((s) => ({
-        id: s.id,
-        done: s.done,
-        depends: s.depends ?? [],
-      }));
-    }
+    // DB-authoritative eligibility list (ADR-017) — markdown projections are
+    // never parsed for dispatch decisions. No DB / no rows → skip this
+    // milestone's check (unknown is not a blocker).
+    if (!isDbAvailable()) continue;
+    const slices = getMilestoneSliceSummaries(mid);
+    if (slices.length === 0) continue;
 
     if (mid !== targetMid) {
       const incomplete = slices.find((slice) => !slice.done);

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -73,6 +73,15 @@ These are **separate concerns**:
 
 Setting `prefer_skills: []` does **not** disable skill discovery — it just means you have no preference overrides. Use `skill_discovery: off` to disable discovery entirely.
 
+### Parse & Validation Diagnostics
+
+Preference loading never throws. When a file is malformed or contains invalid settings, GSD falls back to safe defaults but attaches structured diagnostics (see `collectPreferenceDiagnostics()` in `preferences-diagnostics.ts`) so the problem is reported instead of silently ignored:
+
+- **Parse failures** (missing closing `---` delimiter, YAML syntax error, or an unrecognized file format) cause the whole file to be ignored. Loading continues to the next candidate — a valid global or legacy preferences file is still used, and a malformed project file never becomes the effective wrapper or blocks fallback.
+- **Validation problems** (unknown keys, type mismatches) are sanitized or dropped per-field; the remaining valid settings in the file still apply.
+
+Diagnostics record the file path, scope (global/project), severity (error/warning), kind (parse/validation), and — for YAML parse errors — the line and column. They surface through session-start notifications, `/gsd doctor`, and auto-mode preflight, with each surface deduping repeated diagnostics.
+
 ---
 
 ## Field Guide

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

@@ -6,8 +6,9 @@ import { isDbAvailable, _getAdapter } from "./gsd-db.js";
 import { isAfter, latestExplicitReopenAt } from "./milestone-reopen-events.js";
 import { resolveGsdPathContract, resolveMilestoneFile } from "./paths.js";
 import { deriveState } from "./state.js";
+import { workflowEventLogPath } from "./workflow-event-ledger.js";
 import { readEvents } from "./workflow-events.js";
-import { renderAllProjections } from "./workflow-projections.js";
+import { flushWorkflowProjections } from "./projection-flush.js";
 
 export async function checkEngineHealth(
   basePath: string,
@@ -260,7 +261,7 @@ export async function checkEngineHealth(
   // relative to the event log and re-render them.
   try {
     if (isDbAvailable()) {
-      const eventLogPath = join(basePath, ".gsd", "event-log.jsonl");
+      const eventLogPath = workflowEventLogPath(basePath);
       const events = readEvents(eventLogPath);
       if (events.length > 0) {
         const lastEventTs = new Date(events[events.length - 1]!.ts).getTime();
@@ -270,7 +271,7 @@ export async function checkEngineHealth(
           const roadmapPath = resolveMilestoneFile(basePath, milestone.id, "ROADMAP");
           if (!roadmapPath || !existsSync(roadmapPath)) {
             try {
-              await renderAllProjections(basePath, milestone.id);
+              await flushWorkflowProjections(basePath, { milestoneId: milestone.id });
               fixesApplied.push(`re-rendered missing projections for ${milestone.id}`);
             } catch {
               // Non-fatal — projection re-render failed
@@ -280,7 +281,7 @@ export async function checkEngineHealth(
           const projectionMtime = statSync(roadmapPath).mtimeMs;
           if (lastEventTs > projectionMtime) {
             try {
-              await renderAllProjections(basePath, milestone.id);
+              await flushWorkflowProjections(basePath, { milestoneId: milestone.id });
               fixesApplied.push(`re-rendered stale projections for ${milestone.id}`);
             } catch {
               // Non-fatal — projection re-render failed

package/src/resources/extensions/gsd/doctor-environment.ts

@@ -15,6 +15,7 @@ import { join } from "node:path";
 
 import type { DoctorIssue, DoctorIssueCode } from "./doctor-types.js";
 import { detectPythonExecutable } from "./python-resolver.js";
+import { projectRootFromWorktreePath } from "./worktree-root.js";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -38,27 +39,18 @@ const CMD_TIMEOUT = 5_000;
 
 // ── Helpers ────────────────────────────────────────────────────────────────
 
-/** Worktree sentinel — path segment that marks an auto-worktree directory. */
-const WORKTREE_PATH_SEGMENT = `${join(".gsd", "worktrees")}/`;
-
 /**
- * Resolve the project root when running inside a `.gsd/worktrees/<name>/`
- * auto-worktree. Returns `null` if not in a worktree.
+ * Resolve the project root when running inside a GSD auto-worktree.
+ * Returns `null` if not in a worktree.
  *
  * Detection order:
  *   1. `GSD_WORKTREE` env var (set by the worktree launcher)
- *   2. `.gsd/worktrees/` segment in basePath
+ *   2. worktree segment in basePath (via worktree-root's layout matching)
  */
 function resolveWorktreeProjectRoot(basePath: string): string | null {
   const envRoot = process.env.GSD_WORKTREE;
   if (envRoot) return envRoot;
-
-  const normalised = basePath.replace(/\\/g, "/");
-  const idx = normalised.indexOf(WORKTREE_PATH_SEGMENT.replace(/\\/g, "/"));
-  if (idx === -1) return null;
-
-  // Everything before `.gsd/worktrees/` is the project root
-  return basePath.slice(0, idx);
+  return projectRootFromWorktreePath(basePath);
 }
 
 function tryExec(cmd: string, cwd: string): string | null {