@opengsd/gsd-pi 1.2.0-dev.5457a158 → 1.2.0-dev.6ccd27b3

package/src/resources/extensions/gsd/health-widget.ts

@@ -4,7 +4,7 @@
 import type { ExtensionContext } from "@gsd/pi-coding-agent";
 import type { GSDState } from "./types.js";
 import { runProviderChecks, summariseProviderIssues } from "./doctor-providers.js";
-import { runEnvironmentChecks } from "./doctor-environment.js";
+import { runEnvironmentChecks, runEnvironmentChecksAsync } from "./doctor-environment.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { nativeIsRepo, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeCommitSubject } from "./native-git-bridge.js";
 import { loadLedgerFromDisk, getProjectTotals } from "./metrics.js";
@@ -22,7 +22,31 @@ export const HEALTH_WIDGET_ACTIVE_HINTS =
 
 // ── Data loader ────────────────────────────────────────────────────────────────
 
-function loadHealthWidgetData(basePath: string): HealthWidgetData {
+// Last-commit lookup is subprocess-backed (native-git-bridge → git spawns),
+// so it is treated like the other expensive checks: skipped on first paint,
+// run only by the background refresh.
+function loadLastCommitInfo(basePath: string): { epoch: number | null; message: string | null } {
+  try {
+    if (nativeIsRepo(basePath)) {
+      const branch = nativeGetCurrentBranch(basePath);
+      const epoch = nativeLastCommitEpoch(basePath, branch || "HEAD");
+      if (epoch > 0) {
+        return { epoch, message: nativeCommitSubject(basePath, branch || "HEAD") || null };
+      }
+    }
+  } catch { /* non-fatal */ }
+  return { epoch: null, message: null };
+}
+
+function loadHealthWidgetData(
+  basePath: string,
+  options?: { includeChecks?: boolean },
+): HealthWidgetData {
+  // `includeChecks` gates the expensive subprocess-backed checks (provider +
+  // environment doctor: `lsof`, `docker`, `node --version`, ...). The initial
+  // synchronous render passes `false` so first paint is never blocked on them;
+  // the async refresh (off the first-paint path) runs the full suite.
+  const includeChecks = options?.includeChecks ?? true;
   let budgetCeiling: number | undefined;
   let budgetSpent = 0;
   let providerIssue: string | null = null;
@@ -44,40 +68,73 @@ function loadHealthWidgetData(basePath: string): HealthWidgetData {
     }
   } catch { /* non-fatal */ }
 
+  if (includeChecks) {
+    try {
+      const providerResults = runProviderChecks();
+      providerIssue = summariseProviderIssues(providerResults);
+    } catch { /* non-fatal */ }
+
+    try {
+      const envResults = runEnvironmentChecks(basePath);
+      for (const r of envResults) {
+        if (r.status === "error") environmentErrorCount++;
+        else if (r.status === "warning") environmentWarningCount++;
+      }
+    } catch { /* non-fatal */ }
+  }
+
+  // ── Last commit info ── (git spawns — gated like the other expensive checks)
+  if (includeChecks) {
+    const commit = loadLastCommitInfo(basePath);
+    lastCommitEpoch = commit.epoch;
+    lastCommitMessage = commit.message;
+  }
+
+  return {
+    projectState,
+    budgetCeiling,
+    budgetSpent,
+    providerIssue,
+    environmentErrorCount,
+    environmentWarningCount,
+    lastCommitEpoch,
+    lastCommitMessage,
+    lastRefreshed: Date.now(),
+  };
+}
+
+// Non-blocking variant used by the widget's background refresh: the cheap fields
+// come from the synchronous snapshot, then provider + environment checks are
+// layered in off the event-loop critical path (env checks run concurrently via
+// runEnvironmentChecksAsync). Keeps the always-on widget from stalling the UI on
+// its initial enrichment or its 60s refresh.
+async function loadHealthWidgetDataAsync(basePath: string): Promise<HealthWidgetData> {
+  const data = loadHealthWidgetData(basePath, { includeChecks: false });
+  let providerIssue = data.providerIssue;
+  let environmentErrorCount = 0;
+  let environmentWarningCount = 0;
+
   try {
-    const providerResults = runProviderChecks();
-    providerIssue = summariseProviderIssues(providerResults);
+    providerIssue = summariseProviderIssues(runProviderChecks());
   } catch { /* non-fatal */ }
 
   try {
-    const envResults = runEnvironmentChecks(basePath);
+    const envResults = await runEnvironmentChecksAsync(basePath);
     for (const r of envResults) {
       if (r.status === "error") environmentErrorCount++;
       else if (r.status === "warning") environmentWarningCount++;
     }
   } catch { /* non-fatal */ }
 
-  // ── Last commit info ──
-  try {
-    if (nativeIsRepo(basePath)) {
-      const branch = nativeGetCurrentBranch(basePath);
-      const epoch = nativeLastCommitEpoch(basePath, branch || "HEAD");
-      if (epoch > 0) {
-        lastCommitEpoch = epoch;
-        lastCommitMessage = nativeCommitSubject(basePath, branch || "HEAD") || null;
-      }
-    }
-  } catch { /* non-fatal */ }
+  const commit = loadLastCommitInfo(basePath);
 
   return {
-    projectState,
-    budgetCeiling,
-    budgetSpent,
+    ...data,
     providerIssue,
     environmentErrorCount,
     environmentWarningCount,
-    lastCommitEpoch,
-    lastCommitMessage,
+    lastCommitEpoch: commit.epoch,
+    lastCommitMessage: commit.message,
     lastRefreshed: Date.now(),
   };
 }
@@ -95,8 +152,13 @@ export function initHealthWidget(ctx: ExtensionContext): void {
 
   const basePath = projectRoot();
 
-  // String-array fallback — used in RPC mode (factory is a no-op there)
-  const initialData = loadHealthWidgetData(basePath);
+  // String-array fallback — used in RPC mode (factory is a no-op there).
+  // Skip the expensive provider/environment doctor checks here: this runs
+  // synchronously on the interactive-startup path, where running them would
+  // block first paint by ~0.9s (lsof/docker probes, otherwise run again
+  // immediately by the factory below). The factory's async refresh fills in
+  // real health once the screen is up.
+  const initialData = loadHealthWidgetData(basePath, { includeChecks: false });
   ctx.ui.setWidget("gsd-health", buildHealthLines(initialData), { placement: "belowEditor" });
 
   // Factory-based widget for TUI mode — replaces the string-array above
@@ -110,7 +172,7 @@ export function initHealthWidget(ctx: ExtensionContext): void {
       if (refreshInFlight) return;
       refreshInFlight = true;
       try {
-        data = loadHealthWidgetData(basePath);
+        data = await loadHealthWidgetDataAsync(basePath);
         cachedLines = undefined;
         if (!isDisposed) _tui.requestRender();
       } catch { /* non-fatal */ } finally {
@@ -118,9 +180,11 @@ export function initHealthWidget(ctx: ExtensionContext): void {
       }
     };
 
-    // Fire first enrichment immediately. requestRender() inside is a no-op
-    // if the widget has not yet rendered, so this is safe before factory return.
-    void refresh();
+    // Fire the first full enrichment off the first-paint path. setTimeout(0)
+    // yields to the initial render + input loop, so the expensive doctor checks
+    // (provider + environment) never delay the moment the user sees the UI.
+    // requestRender() inside refresh repaints the widget once data is ready.
+    setTimeout(() => { void refresh(); }, 0);
 
     const refreshTimer = setInterval(() => {
       void refresh();

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

@@ -911,6 +911,17 @@ export function detectStaleRenders(basePath: string): StaleEntry[] {
   return stale;
 }
 
+/**
+ * Render-verification helper: does the rendered ROADMAP markdown mark a slice
+ * as done? Used by completion code to verify/repair the *projection* after a
+ * DB write — never as a source of truth for dispatch or completion decisions
+ * (ADR-017). Lives here so decision-path modules need not import
+ * parsers-legacy directly.
+ */
+export function roadmapRenderMarksSliceDone(roadmapContent: string, sliceId: string): boolean {
+  return parseRoadmap(roadmapContent).slices.some((slice) => slice.id === sliceId && slice.done);
+}
+
 // ─── Stale Repair ─────────────────────────────────────────────────────────
 // Body relocated to state-reconciliation/drift/stale-render.ts (ADR-017 #5702).
 // detectStaleRenders above stays as a useful diagnostic primitive; the

package/src/resources/extensions/gsd/mcp-bridge.ts

@@ -0,0 +1,39 @@
+// mcp-bridge.ts — stable runtime seam for MCP server consumption (phase 1).
+export {
+  loadWriteGateSnapshot,
+  shouldBlockPendingGateInSnapshot,
+  shouldBlockQueueExecutionInSnapshot,
+} from "./bootstrap/write-gate.js";
+export { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
+export {
+  _getAdapter,
+  checkpointDatabase,
+  closeDatabase,
+  getAllMilestones,
+  getDb,
+  getGateResults,
+  getMilestoneSlices,
+  getPendingGates,
+  getSliceTasks,
+  insertDecision,
+  insertMilestone,
+  insertSlice,
+  openDatabase,
+  upsertMilestonePlanning,
+} from "./gsd-db.js";
+export { invalidateStateCache, isReusableGhostMilestone } from "./state.js";
+export { loadEffectiveGSDPreferences } from "./preferences.js";
+export {
+  saveDecisionToDb,
+  saveRequirementToDb,
+  updateRequirementInDb,
+} from "./db-writer.js";
+export { rebuildState } from "./doctor.js";
+export { queryJournal } from "./journal.js";
+export {
+  claimReservedId,
+  findMilestoneIds,
+  getReservedMilestoneIds,
+  milestoneIdSort,
+  nextMilestoneId,
+} from "./milestone-ids.js";

package/src/resources/extensions/gsd/mcp-filter.ts

@@ -3,6 +3,7 @@ import { homedir } from "node:os";
 import { resolve } from "node:path";
 
 import type { ClaudeCodeMcpConfig } from "./preferences-types.js";
+import { isGsdBrowserMcpServerConfig } from "../shared/gsd-browser-cli.js";
 import { toMcpWildcardToolName } from "./mcp-tool-name.js";
 import { resolveModelMcpConfig } from "./preferences-mcp.js";
 
@@ -83,34 +84,12 @@ function isWorkflowMcpServerConfig(config: unknown): boolean {
   return args.some((arg) => arg.includes("gsd-mcp-server") || arg.includes("packages/mcp-server"));
 }
 
-function isBrowserMcpServerConfig(config: unknown): boolean {
-  if (!isRecord(config)) return false;
-  const command = typeof config.command === "string" ? config.command : "";
-  if (command.includes("gsd-browser") || command.includes("@opengsd/gsd-browser")) {
-    return true;
-  }
-
-  const env = config.env;
-  if (isRecord(env)) {
-    if (
-      typeof env.GSD_BROWSER_CLI_PATH === "string"
-      || typeof env.GSD_BROWSER_BIN_PATH === "string"
-      || typeof env.GSD_BROWSER_MCP_COMMAND === "string"
-    ) {
-      return true;
-    }
-  }
-
-  const args = Array.isArray(config.args) ? config.args.filter((arg): arg is string => typeof arg === "string") : [];
-  return args.some((arg) => arg.includes("gsd-browser") || arg.includes("@opengsd/gsd-browser"));
-}
-
 export function discoverWorkflowMcpServerName(projectDir: string): string | undefined {
   return discoverMcpServers(projectDir).find((server) => isWorkflowMcpServerConfig(server.config))?.name;
 }
 
 export function discoverBrowserMcpServerName(projectDir: string): string | undefined {
-  return discoverMcpServers(projectDir).find((server) => isBrowserMcpServerConfig(server.config))?.name;
+  return discoverMcpServers(projectDir).find((server) => isGsdBrowserMcpServerConfig(server.config))?.name;
 }
 
 export function discoverMcpServerNames(projectDir: string): string[] {

package/src/resources/extensions/gsd/milestone-closeout.ts

@@ -5,13 +5,23 @@
 // - postUnit: git commit, artifact verify, DB settle, then GitHub finalize
 // - recovery: DB repair from artifacts, then GitHub finalize
 
+import { existsSync } from "node:fs";
+
 import { loadFile } from "./files.js";
-import { parseRoadmap } from "./parsers-legacy.js";
 import { resolveMilestoneFile } from "./paths.js";
-import { getMilestone, getMilestoneSlices, isDbAvailable } from "./gsd-db.js";
+import {
+  getMilestone,
+  getClosedSliceIds,
+  getLatestAssessmentByScope,
+  getMilestoneSlices,
+  isDbAvailable,
+} from "./gsd-db.js";
 import { isClosedStatus } from "./status-guards.js";
+import { resolveExpectedArtifactPath } from "./auto-artifact-paths.js";
+import { handleCompleteMilestone } from "./tools/complete-milestone.js";
 import { runSafely } from "./auto-utils.js";
 import { extractVerdict, isAcceptableUatVerdict } from "./verdict-parser.js";
+import { uatSignoffBlockerGuidance } from "./guidance.js";
 import { logWarning } from "./workflow-logger.js";
 import { hasImplementationArtifacts } from "./milestone-implementation-evidence.js";
 import { buildCompleteMilestonePrompt } from "./auto-prompts.js";
@@ -28,6 +38,76 @@ import {
 const COMPLETE_MILESTONE_DB_SETTLE_MS = 1500;
 const COMPLETE_MILESTONE_DB_SETTLE_POLL_MS = 100;
 
+/**
+ * True when a milestone is terminal for git cleanup (orphaned worktrees, stale branches).
+ * DB-authoritative (ADR-017): closed status, or validation-pass with all slices closed.
+ * When the DB is unavailable we cannot make this decision and conservatively
+ * return false so callers leave the worktree/branch alone instead of cleaning
+ * up based on parsed projections.
+ */
+export async function isCompletedMilestoneTerminal(
+  _basePath: string,
+  milestoneId: string,
+): Promise<boolean> {
+  if (!isDbAvailable()) return false;
+
+  const milestone = getMilestone(milestoneId);
+  if (!milestone) return false;
+
+  if (isClosedStatus(milestone.status)) {
+    return true;
+  }
+
+  const validation = getLatestAssessmentByScope(milestoneId, "milestone-validation");
+  if (validation?.status !== "pass") {
+    return false;
+  }
+
+  const slices = getMilestoneSlices(milestoneId);
+  if (slices.length === 0) return false;
+  return slices.every((slice) => isClosedStatus(slice.status));
+}
+
+/** Write a missing milestone SUMMARY projection when canonical DB closeout already settled. */
+export async function repairMissingMilestoneSummaryProjection(
+  basePath: string,
+  milestoneId: string,
+): Promise<{ ok: true } | { ok: false; error: string }> {
+  const milestone = getMilestone(milestoneId);
+  if (!milestone) {
+    return { ok: false, error: `milestone not found: ${milestoneId}` };
+  }
+
+  const artifactBasePath = resolveCanonicalMilestoneRoot(basePath, milestoneId);
+  const summaryPath = resolveExpectedArtifactPath("complete-milestone", milestoneId, artifactBasePath);
+  if (summaryPath && existsSync(summaryPath)) {
+    return { ok: true };
+  }
+
+  const result = await handleCompleteMilestone(
+    {
+      milestoneId,
+      title: milestone.title,
+      oneLiner: "Canonical closeout completed; summary projection repaired automatically.",
+      narrative:
+        "The workflow database recorded this milestone as complete, but the milestone SUMMARY artifact was missing on disk. " +
+        "Dispatch policy repaired the projection so closeout proof and cleanup can proceed.",
+      verificationPassed: true,
+      triggerReason: "closeout-projection-repair",
+    },
+    basePath,
+  );
+
+  if ("error" in result) {
+    return { ok: false, error: result.error };
+  }
+  const writtenSummaryPath = result.summaryPath;
+  if (result.stale || !writtenSummaryPath || !existsSync(writtenSummaryPath)) {
+    return { ok: false, error: "milestone SUMMARY projection write failed" };
+  }
+  return { ok: true };
+}
+
 /**
  * True when the milestone is closed in the DB and the completion summary artifact exists.
  * Polls briefly so post-unit verification can observe the tool's DB write.
@@ -78,7 +158,22 @@ export async function evaluateCompleteMilestoneDispatch(
   if (isDbAvailable()) {
     const milestone = getMilestone(mid);
     if (milestone && isClosedStatus(milestone.status)) {
-      return { action: "skip" };
+      const artifactBasePath = resolveCanonicalMilestoneRoot(basePath, mid);
+      const summaryPath = resolveExpectedArtifactPath("complete-milestone", mid, artifactBasePath);
+      const summaryMissing = !summaryPath || !existsSync(summaryPath);
+      if (summaryMissing) {
+        const repair = await repairMissingMilestoneSummaryProjection(basePath, mid);
+        if (!repair.ok) {
+          logWarning(
+            "dispatch",
+            `Milestone ${mid} is closed in DB but SUMMARY repair failed: ${repair.error}. Dispatching complete-milestone to retry.`,
+          );
+        } else {
+          return { action: "skip" };
+        }
+      } else {
+        return { action: "skip" };
+      }
     }
   }
 
@@ -86,31 +181,21 @@ export async function evaluateCompleteMilestoneDispatch(
   if (closeoutGitStop) return closeoutGitStop;
 
   if (prefs?.uat_dispatch) {
-    let closedSliceIds: string[];
-    if (isDbAvailable()) {
-      closedSliceIds = getMilestoneSlices(mid)
-        .filter((slice) => isClosedStatus(slice.status))
-        .map((slice) => slice.id);
-    } else {
-      const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
-      const roadmapContent = roadmapFile ? await loadFile(roadmapFile) : null;
-      if (!roadmapContent) {
-        return {
-          action: "stop",
-          reason: `Cannot complete milestone ${mid}: unable to verify UAT verdicts because ROADMAP is unavailable while DB is not accessible.`,
-          level: "warning",
-        };
-      }
-      const roadmap = parseRoadmap(roadmapContent);
-      closedSliceIds = roadmap.slices.filter((slice) => slice.done).map((slice) => slice.id);
+    // DB-authoritative (ADR-017): UAT sign-off gating never parses the
+    // ROADMAP projection. Without a DB we cannot verify — stop conservatively.
+    if (!isDbAvailable()) {
+      return {
+        action: "stop",
+        reason: `Cannot complete milestone ${mid}: unable to verify UAT verdicts because the workflow DB is not accessible.`,
+        level: "warning",
+      };
     }
-
-    for (const sliceId of closedSliceIds) {
+    for (const sliceId of getClosedSliceIds(mid)) {
       const result = await readUatGateVerdict(basePath, mid, sliceId);
       if (!result) {
         return {
           action: "stop",
-          reason: `Cannot complete milestone ${mid}: missing UAT PASS verdict for ${sliceId}. Manual UAT sign-off (PASS) is required before milestone closure.`,
+          reason: uatSignoffBlockerGuidance(mid, sliceId),
           level: "warning",
         };
       }
@@ -118,7 +203,7 @@ export async function evaluateCompleteMilestoneDispatch(
       if (!isAcceptableUatVerdict(verdict, uatType)) {
         return {
           action: "stop",
-          reason: `Cannot complete milestone ${mid}: UAT verdict for ${sliceId} is "${verdict}". Manual UAT sign-off (PASS) is required before milestone closure.`,
+          reason: uatSignoffBlockerGuidance(mid, sliceId, verdict),
           level: "warning",
         };
       }

package/src/resources/extensions/gsd/milestone-planning-persistence.ts

@@ -15,7 +15,7 @@ import {
 } from "./gsd-db.js";
 import { invalidateStateCache } from "./state.js";
 import { renderRoadmapFromDb } from "./markdown-renderer.js";
-import { renderAllProjections } from "./workflow-projections.js";
+import { flushWorkflowProjections } from "./projection-flush.js";
 import { writeManifest } from "./workflow-manifest.js";
 import { appendEvent } from "./workflow-events.js";
 import { logWarning } from "./workflow-logger.js";
@@ -171,7 +171,7 @@ async function renderPlanArtifacts(
 
 async function runPostPlanHooks(basePath: string, params: PersistMilestonePlanParams): Promise<void> {
   try {
-    await renderAllProjections(basePath, params.milestoneId);
+    await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
     writeManifest(basePath);
     appendEvent(basePath, {
       cmd: "plan-milestone",

package/src/resources/extensions/gsd/milestone-reopen-events.ts

@@ -1,13 +1,10 @@
-import { join } from "node:path";
-
-import { gsdRoot } from "./paths.js";
+import { workflowEventArchivePath, workflowEventLogPath } from "./workflow-event-ledger.js";
 import { readEvents } from "./workflow-events.js";
 
 export function latestExplicitReopenAt(basePath: string, milestoneId: string): string | null {
-  const root = gsdRoot(basePath);
   const candidates = [
-    join(root, "event-log.jsonl"),
-    join(root, `event-log-${milestoneId}.jsonl.archived`),
+    workflowEventLogPath(basePath),
+    workflowEventArchivePath(basePath, milestoneId),
   ];
 
   let latest: string | null = null;

package/src/resources/extensions/gsd/milestone-settlement.ts

@@ -74,8 +74,8 @@ export function evaluateAllCompleteSettlement(
     action: "pause",
     message:
       `Milestone ${milestoneId} is complete, but its worktree branch has not been merged to main. ` +
-      `Retry with \`/gsd dispatch complete-milestone ${milestoneId}\` or merge manually.`,
-    nextAction: `Retry \`/gsd dispatch complete-milestone ${milestoneId}\` or merge manually.`,
+      `Retry with \`/gsd dispatch complete-milestone ${milestoneId}\` to finish the system-owned merge.`,
+    nextAction: `Retry \`/gsd dispatch complete-milestone ${milestoneId}\`.`,
     milestoneId,
   };
 }

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

@@ -4,7 +4,12 @@
 import { execFileSync } from "node:child_process";
 import type { NotificationPreferences } from "./types.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { sendRemoteNotification } from "../remote-questions/notify.js";
+import { sendRemoteNotification as _sendRemoteNotification } from "../remote-questions/notify.js";
+
+/** Swappable dispatcher for remote notifications — exported so tests can mock it. */
+export const remoteNotificationDispatcher = {
+  send: _sendRemoteNotification,
+};
 
 export type NotifyLevel = "info" | "success" | "warning" | "error";
 export type NotificationKind = "complete" | "error" | "budget" | "milestone" | "attention";
@@ -30,28 +35,30 @@ export function sendDesktopNotification(
   level: NotifyLevel = "info",
   kind: NotificationKind = "complete",
   projectName?: string,
+  deps: { notifications?: NotificationPreferences } = {},
 ): void {
   // When a projectName is provided and the title is the default "GSD",
   // replace it with a project-qualified title for multi-project clarity.
   if (projectName && title === "GSD") {
     title = formatNotificationTitle(projectName);
   }
-  const loaded = loadEffectiveGSDPreferences()?.preferences;
+  const loadedPreferences = loadEffectiveGSDPreferences()?.preferences;
+  const notifications = deps.notifications ?? loadedPreferences?.notifications;
 
   // Remote notifications fire independently of desktop preferences.
   // sendRemoteNotification handles "not configured" gracefully (early return).
-  void sendRemoteNotification(title, message).catch(() => {});
+  void remoteNotificationDispatcher.send(title, message).catch(() => {});
 
-  if (!shouldSendDesktopNotification(kind, loaded?.notifications)) return;
+  if (!shouldSendDesktopNotification(kind, notifications)) return;
 
   // cmux delivery and desktop delivery are independent — if cmux import or
   // delivery fails, we must still attempt the native desktop notification.
   const runCmux = async () => {
     try {
       const { CmuxClient, emitOsc777Notification, resolveCmuxConfig } = await import("../cmux/index.js");
-      const cmux = resolveCmuxConfig(loaded);
+      const cmux = resolveCmuxConfig(loadedPreferences);
       if (cmux.notifications) {
-        const delivered = CmuxClient.fromPreferences(loaded).notify(title, message);
+        const delivered = CmuxClient.fromPreferences(loadedPreferences).notify(title, message);
         if (delivered) return true;
         emitOsc777Notification(title, message);
       }

package/src/resources/extensions/gsd/parsers-legacy.ts

@@ -1,10 +1,22 @@
 // GSD Extension - Legacy Parsers
 // parseRoadmap() and parsePlan() extracted from files.ts.
-// Used only by: md-importer.ts (migration), state.ts (pre-migration fallback),
-// markdown-renderer.ts (detectStaleRenders disk-vs-DB comparison),
-// commands-maintenance.ts (cold-path branch cleanup), and tests.
 //
-// NOT used in the dispatch loop or any hot-path runtime code.
+// ADR-017: the DB is the single source of truth; `.gsd/*.md` files are
+// projections. These parsers may be imported ONLY for:
+//   - migration/import (md-importer, workflow-migration, migration-auto-check)
+//   - drift detection that compares both sources by design
+//     (state-reconciliation/drift, markdown-renderer stale-render detection)
+//   - explicit pre-migration / DB-unavailable fallbacks (state.ts,
+//     reactive-graph.ts, auto-recovery.ts)
+//   - diagnostics and display/telemetry-only surfaces (doctor,
+//     doctor-git-checks, workspace-index, visualizer-data, auto-prompts
+//     context text, commands-maintenance, milestone-closeout, github-sync)
+//   - tests
+//
+// Dispatch/gate/completion DECISION paths must NOT import this module — they
+// read the DB via gsd-db queries (e.g. getMilestoneSliceSummaries). Enforced
+// by tests/parsers-legacy-importers.test.ts; new importers must be added to
+// its allowlist with a one-line justification.
 
 import { extractSection, parseBullets, extractBoldField, extractAllSections, registerCacheClearCallback } from './files.js';
 import { splitFrontmatter } from '../shared/frontmatter.js';

package/src/resources/extensions/gsd/preferences-models.ts

@@ -185,8 +185,9 @@ export function resolveThinkingLevelForUnit(unitType: string): GSDThinkingLevel
  */
 export function resolveDefaultSessionModel(
   sessionProvider?: string,
+  basePath?: string,
 ): { provider: string; id: string } | undefined {
-  const prefs = loadEffectiveGSDPreferences(undefined, { availableModelIds: [] });
+  const prefs = loadEffectiveGSDPreferences(basePath, { availableModelIds: [] });
   const models = prefs?.preferences?.models;
   if (!models) return undefined;
 

package/src/resources/extensions/gsd/projection-flush.ts

@@ -0,0 +1,20 @@
+// Project/App: gsd-pi
+// File Purpose: Single workflow projection flush seam for mutation exits.
+
+import { renderAllProjections } from "./workflow-projections.js";
+
+export interface ProjectionFlushScope {
+  milestoneId: string;
+}
+
+export interface ProjectionFlushResult {
+  milestoneId: string;
+}
+
+export async function flushWorkflowProjections(
+  basePath: string,
+  scope: ProjectionFlushScope,
+): Promise<ProjectionFlushResult> {
+  await renderAllProjections(basePath, scope.milestoneId);
+  return { milestoneId: scope.milestoneId };
+}

package/src/resources/extensions/gsd/prompts/complete-slice.md

@@ -24,7 +24,7 @@ Use `subagent` only when useful: reviewer, security, or tester. Apply findings b
 
 1. Use the inlined Slice Summary and UAT templates.
 2. {{skillActivation}}
-3. Run all slice-level verification through `gsd_exec` / Context Mode evidence; refresh current state if needed. Do not use direct `bash` for verification commands.
+3. Run all slice-level verification through `gsd_exec` / Context Mode evidence; refresh current state if needed. Do not use direct `bash` for verification commands. See the prepended **Tool Surface** block for unavailable tools.
 4. Complete only when every required check passes. If verification fails or source changes are needed, do **not** edit source files in this unit and do **not** call `gsd_slice_complete`.
 5. If verification fails:
    - Task-specific regressions: if the failure is in files the task touched and pre-task verification evidence shows it was absent before that task ran, call `gsd_task_reopen` with that task and reason.
@@ -36,9 +36,9 @@ Use `subagent` only when useful: reviewer, security, or tester. Apply findings b
 8. Address every Gate to Close. Q8 = **Operational Readiness**: health signal, failure signal, recovery, monitoring gaps. Omit empty sections.
 9. If requirement status changed, call `gsd_requirement_update`; do not write `.gsd/REQUIREMENTS.md` directly.
 10. Prepare `gsd_slice_complete` content with camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`.
-11. Draft concrete UAT with preconditions, steps, expected outcomes, edge cases, and UAT Type.
+11. Draft concrete UAT with preconditions, steps, expected outcomes, edge cases, and UAT Type. Declare the type as a bullet under a `## UAT Type` heading, exactly like `- UAT mode: browser-executable`.
     **Web apps:** when inlined Web App UAT guidance is present, declare `browser-executable` or `runtime-executable` (not `artifact-driven`) for localhost/browser/screenshot steps; include dev-server preconditions and name Playwright specs when they exist.
-12. Review the inlined task-summary excerpts for DECISIONS.md/KNOWLEDGE.md-worthy decisions and gotchas. Read full `*-SUMMARY.md` only if needed. Capture with `capture_thought`; do not append knowledge files.
+12. Review the inlined task-summary excerpts for DECISIONS.md/KNOWLEDGE.md-worthy decisions and gotchas. Read full `*-SUMMARY.md` only if needed. Capture with `gsd_capture_thought` (MCP-scoped `mcp__...__gsd_capture_thought`), not bare `capture_thought`; do not append knowledge files.
 13. When verification passes, call `gsd_slice_complete`. The DB-backed tool is the canonical write path. Do **not** manually write `{{sliceSummaryPath}}`. Do **not** manually write `{{sliceUatPath}}`. Do not edit roadmap checkboxes.
 14. Do not run git commands.
 15. If the current project state needs refresh, call `gsd_summary_save` with `artifact_type: "PROJECT"` and the full updated project markdown as `content`; omit `milestone_id`. Do not write or edit `.gsd/PROJECT.md` directly.
@@ -49,4 +49,4 @@ Use `subagent` only when useful: reviewer, security, or tester. Apply findings b
 
 **You MUST call `gsd_slice_complete` with summary and UAT content only after verification passes.**
 
-When done, say: "Slice {{sliceId}} complete."
+When done, say: "Slice {{sliceId}} complete." Say this exactly once — if you already said it in a prior message, do not repeat it.