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

package/dist/resources/extensions/gsd/delegation-policy.js

@@ -34,6 +34,7 @@
 // Adding a `unitType` mapping (or a future `unitTypes: string[]`) to an
 // 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";
 const POLICY = {
     gsd_plan_slice: {
         toolName: "gsd_plan_slice",
@@ -96,17 +97,8 @@ const POLICY = {
         rationale: "plan-slice prompt explicitly forbids calling gsd_plan_task separately; per-task granularity multiplies manifest writes and projection re-renders with no payoff.",
     },
 };
-// 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 = {
-    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) {
-    return ALIASES[name] ?? name;
+    return canonicalWorkflowSurfaceToolName(name);
 }
 export function getDelegationVerdict(toolName) {
     return POLICY[resolveCanonical(toolName)] ?? null;

package/dist/resources/extensions/gsd/discussion-handoff.js

@@ -0,0 +1,218 @@
+// Project/App: gsd-pi
+// File Purpose: Owns the guided-discuss to auto-mode handoff.
+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 } from "./pending-auto-start.js";
+import { logWarning } from "./workflow-logger.js";
+import { readManifest } from "./workflow-manifest.js";
+// 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, pi, basePath, verboseMode, options, launch = startAutoDetached) {
+    const waitForIdle = typeof ctx.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, milestoneId) {
+    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.message}`);
+        return false;
+    }
+}
+function notifyDbRowRecoveryFailed(entry) {
+    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) {
+    entry.r3bRecoveryCount += 1;
+    if (entry.r3bRecoveryCount >= MAX_DB_ROW_RECOVERIES) {
+        notifyDbRowRecoveryFailed(entry);
+    }
+}
+function ensureMilestoneRowForAcceptedHandoff(entry, contextFile) {
+    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.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) {
+    const ids = [];
+    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) {
+    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) {
+    return join(entry.scope.workspace.contract.projectGsd, "DISCUSSION-MANIFEST.json");
+}
+function warnForMissingProjectMilestones(entry) {
+    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.message}`);
+        return [];
+    }
+}
+function discussionManifestIsComplete(entry, projectIds) {
+    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.message}`);
+    }
+    return true;
+}
+function cleanupAcceptedHandoffArtifacts(entry) {
+    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.message}`);
+    }
+    const manifestPath = discussionManifestPath(entry);
+    if (existsSync(manifestPath)) {
+        try {
+            unlinkSync(manifestPath);
+        }
+        catch (e) {
+            logWarning("guided", `manifest unlink failed: ${e.message}`);
+        }
+    }
+}
+/** Called from agent_end to check if auto-mode should start after discuss. */
+export function checkAutoStartAfterDiscuss(lookupBasePath) {
+    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/dist/resources/extensions/gsd/dispatch-guard.js

@@ -2,9 +2,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";
 const SLICE_DISPATCH_TYPES = new Set([
@@ -97,38 +96,14 @@ export function getPriorSliceCompletionBlocker(base, _mainBranch, unitType, unit
                 continue;
             }
         }
-        let slices = 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;
-            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);
             if (incomplete) {

package/dist/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/dist/resources/extensions/gsd/doctor-engine-checks.js

@@ -1,11 +1,11 @@
 import { existsSync, statSync } from "node:fs";
-import { join } from "node:path";
 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, issues, fixesApplied) {
     const dbPath = resolveGsdPathContract(basePath).projectDb;
     if (!isDbAvailable() && existsSync(dbPath)) {
@@ -228,7 +228,7 @@ export async function checkEngineHealth(basePath, issues, fixesApplied) {
     // 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();
@@ -239,7 +239,7 @@ export async function checkEngineHealth(basePath, issues, fixesApplied) {
                     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 {
@@ -250,7 +250,7 @@ export async function checkEngineHealth(basePath, issues, fixesApplied) {
                     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 {

package/dist/resources/extensions/gsd/doctor-environment.js

@@ -12,6 +12,7 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { execSync } from "node:child_process";
 import { join } from "node:path";
 import { detectPythonExecutable } from "./python-resolver.js";
+import { projectRootFromWorktreePath } from "./worktree-root.js";
 // ── Constants ──────────────────────────────────────────────────────────────
 /** Default dev server ports to scan for conflicts. */
 const DEFAULT_DEV_PORTS = [3000, 3001, 4000, 5000, 5173, 8000, 8080, 8888];
@@ -20,26 +21,19 @@ const MIN_DISK_BYTES = 500 * 1024 * 1024;
 /** Timeout for external commands (ms). */
 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) {
     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, cwd) {
     try {

package/dist/resources/extensions/gsd/doctor-format.js

@@ -1,3 +1,7 @@
+import { doctorFixHint } from "./guidance.js";
+function severityTag(severity) {
+    return severity === "error" ? "ERROR" : severity === "warning" ? "WARN" : "INFO";
+}
 function matchesScope(unitId, scope) {
     if (!scope)
         return true;
@@ -47,8 +51,10 @@ export function formatDoctorReport(report, options) {
     if (scopedIssues.length > 0) {
         lines.push("Priority issues:");
         for (const issue of scopedIssues.slice(0, maxIssues)) {
-            const prefix = issue.severity === "error" ? "ERROR" : issue.severity === "warning" ? "WARN" : "INFO";
-            lines.push(`- [${prefix}] ${issue.unitId}: ${issue.message}${issue.file ? ` (${issue.file})` : ""}`);
+            lines.push(`- [${severityTag(issue.severity)}] ${issue.unitId}: ${issue.message}${issue.file ? ` (${issue.file})` : ""}`);
+            const hint = doctorFixHint(issue.code);
+            if (hint && issue.severity !== "info")
+                lines.push(`  Fix: ${hint}`);
         }
         if (scopedIssues.length > maxIssues) {
             lines.push(`- ...and ${scopedIssues.length - maxIssues} more in scope`);
@@ -66,10 +72,7 @@ export function formatDoctorReport(report, options) {
 export function formatDoctorIssuesForPrompt(issues) {
     if (issues.length === 0)
         return "- No remaining issues in scope.";
-    return issues.map(issue => {
-        const prefix = issue.severity === "error" ? "ERROR" : issue.severity === "warning" ? "WARN" : "INFO";
-        return `- [${prefix}] ${issue.unitId} | ${issue.code} | ${issue.message}${issue.file ? ` | file: ${issue.file}` : ""} | fixable: ${issue.fixable ? "yes" : "no"}`;
-    }).join("\n");
+    return issues.map(issue => `- [${severityTag(issue.severity)}] ${issue.unitId} | ${issue.code} | ${issue.message}${issue.file ? ` | file: ${issue.file}` : ""} | fixable: ${issue.fixable ? "yes" : "no"}`).join("\n");
 }
 /**
  * Serialize a doctor report to JSON — suitable for CI/tooling integration.

package/dist/resources/extensions/gsd/doctor-git-checks.js

@@ -3,11 +3,10 @@ import { spawnSync } from "node:child_process";
 import { cpSync, existsSync, mkdirSync, readdirSync, realpathSync, rmSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { loadFile } from "./files.js";
-import { parseRoadmap as parseLegacyRoadmap } from "./parsers-legacy.js";
-import { isDbAvailable, getMilestone } from "./gsd-db.js";
 import { resolveMilestoneFile } from "./paths.js";
-import { deriveState, isMilestoneComplete } from "./state.js";
-import { createWorktree, listWorktrees, resolveGitDir, worktreesDir } from "./worktree-manager.js";
+import { isCompletedMilestoneTerminal } from "./milestone-closeout.js";
+import { deriveState } from "./state.js";
+import { allWorktreesDirs, createWorktree, listWorktrees, resolveGitDir } from "./worktree-manager.js";
 import { abortAndReset } from "./git-self-heal.js";
 import { RUNTIME_EXCLUSION_PATHS, resolveMilestoneIntegrationBranch, writeIntegrationBranch } from "./git-service.js";
 import { nativeIsRepo, nativeWorktreeList, nativeWorktreeRemove, nativeBranchList, nativeBranchDelete, nativeLsFiles, nativeRmCached, nativeHasChanges, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeAddTracked, nativeCommit } from "./native-git-bridge.js";
@@ -141,21 +140,6 @@ function getSnapshotDiffCheckFailure(basePath) {
     }
     return failures.length > 0 ? failures.join("\n") : null;
 }
-async function isCompletedMilestoneTerminal(basePath, milestoneId) {
-    const summaryPath = resolveMilestoneFile(basePath, milestoneId, "SUMMARY");
-    if (!summaryPath)
-        return false;
-    if (isDbAvailable()) {
-        const milestone = getMilestone(milestoneId);
-        return !!milestone && milestone.status === "complete";
-    }
-    const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
-    const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
-    if (!roadmapContent)
-        return false;
-    const roadmap = parseLegacyRoadmap(roadmapContent);
-    return isMilestoneComplete(roadmap);
-}
 export async function checkGitHealth(basePath, issues, fixesApplied, shouldFix, isolationMode = "none") {
     // Degrade gracefully if not a git repo
     if (!nativeIsRepo(basePath)) {
@@ -478,8 +462,9 @@ export async function checkGitHealth(basePath, issues, fixesApplied, shouldFix,
     // that is no longer registered with git. These orphaned dirs cause
     // "already exists" errors when re-creating the same worktree name.
     try {
-        const wtDir = worktreesDir(basePath);
-        if (existsSync(wtDir)) {
+        for (const wtDir of allWorktreesDirs(basePath)) {
+            if (!existsSync(wtDir))
+                continue;
             // Resolve symlinks and normalize separators so that symlinked .gsd
             // paths (e.g. ~/.gsd/projects/<hash>/worktrees/…) match the paths
             // returned by `git worktree list`.

package/dist/resources/extensions/gsd/doctor-proactive.js

@@ -205,12 +205,17 @@ export async function preDispatchHealthGate(basePath) {
     catch {
         // Non-fatal — dispatch continues without STATE.md if rebuild fails
     }
+    // #442 Phase 1.7: resolve repo-ness once per gate. ensureWorkspaceGitReady
+    // has already run, and nothing below initializes/deinitializes the repo, so
+    // the two downstream blocks (integration-branch check, stale-changes
+    // snapshot) can share one nativeIsRepo result instead of querying twice.
+    const isRepo = nativeIsRepo(basePath);
     // ── Integration branch existence check ──
     // If the active milestone's recorded integration branch no longer exists in
     // git, the merge-back at the end of the milestone will fail. Block dispatch
     // now to surface this before work is lost.
     try {
-        if (nativeIsRepo(basePath)) {
+        if (isRepo) {
             const state = await deriveState(basePath);
             if (state.activeMilestone) {
                 const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git ?? {};
@@ -231,7 +236,7 @@ export async function preDispatchHealthGate(basePath) {
     // If the working tree is dirty and no commit has happened recently,
     // create a safety snapshot so work isn't lost if the next unit crashes.
     try {
-        if (nativeIsRepo(basePath)) {
+        if (isRepo) {
             const prefs = loadEffectiveGSDPreferences()?.preferences ?? {};
             // `git.snapshots: false` is the canonical toggle that disables WIP
             // snapshot commits — honour it before touching the threshold path (#4420).

package/dist/resources/extensions/gsd/doctor-runtime-checks.js

@@ -391,24 +391,29 @@ export async function checkRuntimeHealth(basePath, issues, fixesApplied, shouldF
                 ".gsd/completed-units*.json",
                 ".gsd/event-log.jsonl",
             ];
-            // If blanket .gsd/ or .gsd is present, all patterns are covered
+            // If blanket .gsd/ or .gsd is present, all .gsd/* patterns are covered —
+            // but NOT the .gsd-worktrees/ sibling, which always needs its own entry.
             const hasBlanketIgnore = existingLines.has(".gsd/") || existingLines.has(".gsd");
+            const missing = [];
+            if (!existingLines.has(".gsd-worktrees/") && !existingLines.has(".gsd-worktrees")) {
+                missing.push(".gsd-worktrees/");
+            }
             if (!hasBlanketIgnore) {
-                const missing = criticalPatterns.filter(p => !existingLines.has(p));
-                if (missing.length > 0) {
-                    issues.push({
-                        severity: "warning",
-                        code: "gitignore_missing_patterns",
-                        scope: "project",
-                        unitId: "project",
-                        message: `${missing.length} critical GSD runtime pattern(s) missing from .gitignore: ${missing.join(", ")}`,
-                        file: ".gitignore",
-                        fixable: true,
-                    });
-                    if (shouldFix("gitignore_missing_patterns")) {
-                        ensureGitignore(basePath, { manageGitignore });
-                        fixesApplied.push("added missing GSD runtime patterns to .gitignore");
-                    }
+                missing.push(...criticalPatterns.filter(p => !existingLines.has(p)));
+            }
+            if (missing.length > 0) {
+                issues.push({
+                    severity: "warning",
+                    code: "gitignore_missing_patterns",
+                    scope: "project",
+                    unitId: "project",
+                    message: `${missing.length} critical GSD runtime pattern(s) missing from .gitignore: ${missing.join(", ")}`,
+                    file: ".gitignore",
+                    fixable: true,
+                });
+                if (shouldFix("gitignore_missing_patterns")) {
+                    ensureGitignore(basePath, { manageGitignore });
+                    fixesApplied.push("added missing GSD runtime patterns to .gitignore");
                 }
             }
         }

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

@@ -2,11 +2,13 @@ import { existsSync, mkdirSync, lstatSync, readdirSync, readFileSync } from "nod
 import { join } from "node:path";
 import { loadFile, parseSummary, saveFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.js";
 import { parseRoadmap as parseLegacyRoadmap, parsePlan as parseLegacyPlan } from "./parsers-legacy.js";
-import { isDbAvailable, openDatabase, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
-import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, milestonesDir, gsdRoot, relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relGsdRootFile, resolveGsdRootFile, relMilestonePath, resolveGsdPathContract } from "./paths.js";
+import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
+import { openExistingWorkflowDatabase } from "./db-workspace.js";
+import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, milestonesDir, gsdRoot, relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relGsdRootFile, resolveGsdRootFile, relMilestonePath } from "./paths.js";
 import { deriveState, isMilestoneComplete } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { collectPreferenceDiagnostics, formatPreferenceDiagnosticDetail } from "./preferences-diagnostics.js";
 import { isClosedStatus } from "./status-guards.js";
 import { GLOBAL_STATE_CODES } from "./doctor-types.js";
 import { checkGitHealth, checkRuntimeHealth, checkGlobalHealth, checkEngineHealth } from "./doctor-checks.js";
@@ -286,13 +288,7 @@ export async function runGSDDoctor(basePath, options) {
     // CLI doctor can run before any tool handler has opened the DB. Runtime
     // health checks need the existing project DB to surface DB-backed crash
     // locks, paused sessions, and coordination rows.
-    const dbPath = resolveGsdPathContract(basePath).projectDb;
-    if (existsSync(dbPath)) {
-        try {
-            openDatabase(dbPath);
-        }
-        catch { /* surfaced later as db_unavailable */ }
-    }
+    openExistingWorkflowDatabase(basePath);
     // Issue codes that represent completion state transitions — creating summary
     // stubs, marking slices/milestones done in the roadmap. These belong to the
     // dispatch lifecycle (complete-slice, complete-milestone units), not to
@@ -307,6 +303,17 @@ export async function runGSDDoctor(basePath, options) {
         return true;
     };
     const prefs = loadEffectiveGSDPreferences(basePath);
+    for (const diagnostic of collectPreferenceDiagnostics(basePath)) {
+        issues.push({
+            severity: diagnostic.severity,
+            code: "invalid_preferences",
+            scope: "project",
+            unitId: "project",
+            message: `GSD preferences ${diagnostic.kind}: ${formatPreferenceDiagnosticDetail(diagnostic)}`,
+            file: diagnostic.path,
+            fixable: false,
+        });
+    }
     if (prefs) {
         const prefIssues = validatePreferenceShape(prefs.preferences);
         for (const issue of prefIssues) {