@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.b1abb545

package/src/resources/extensions/gsd/closeout-consistency-gate.ts

@@ -1,17 +1,22 @@
 // Project/App: gsd-pi
 // File Purpose: Shared DB-backed guard for milestone closeout finalization.
 
+import { dirname } from "node:path";
+
 import {
-  getDbPath,
   getLatestAssessmentByScope,
   getMilestone,
   getMilestoneSlices,
   getPendingGates,
   getSliceTasks,
   isDbAvailable,
-  refreshOpenDatabaseFromDisk,
 } from "./gsd-db.js";
+import {
+  getWorkflowDatabasePath,
+  refreshWorkflowDatabaseFromDisk,
+} from "./db-workspace.js";
 import { isClosedStatus } from "./status-guards.js";
+import { closeQualityGatesFromEvidence } from "./quality-gate-closure.js";
 
 export const CLOSEOUT_CONSISTENCY_BLOCKED_REASON = "closeout-consistency-blocked";
 
@@ -37,6 +42,8 @@ export type CloseoutConsistencyResult =
 
 export interface CloseoutConsistencyOptions {
   refreshFromDisk?: boolean;
+  allowOpenMilestone?: boolean;
+  artifactBasePath?: string;
 }
 
 function blocked(reason: CloseoutConsistencyFailureReason, message: string): CloseoutConsistencyResult {
@@ -52,6 +59,12 @@ function isFileBackedDbPath(path: string | null): boolean {
   return Boolean(path && path !== ":memory:");
 }
 
+function artifactBasePathFromDb(): string | undefined {
+  const dbPath = getWorkflowDatabasePath();
+  if (!isFileBackedDbPath(dbPath)) return undefined;
+  return dirname(dirname(dbPath!));
+}
+
 export function checkCloseoutConsistencyGate(
   milestoneId: string,
   options: CloseoutConsistencyOptions = {},
@@ -63,7 +76,7 @@ export function checkCloseoutConsistencyGate(
     );
   }
 
-  if (options.refreshFromDisk && isFileBackedDbPath(getDbPath()) && !refreshOpenDatabaseFromDisk()) {
+  if (options.refreshFromDisk && isFileBackedDbPath(getWorkflowDatabasePath()) && !refreshWorkflowDatabaseFromDisk()) {
     return blocked(
       "db-refresh-failed",
       `Closeout consistency blocked for ${milestoneId}: canonical DB refresh failed.`,
@@ -77,15 +90,17 @@ export function checkCloseoutConsistencyGate(
       `Closeout consistency blocked for ${milestoneId}: milestone is missing from canonical DB.`,
     );
   }
-  if (!isClosedStatus(milestone.status)) {
+  if (!isClosedStatus(milestone.status) && !options.allowOpenMilestone) {
     return blocked(
       "milestone-open",
       `Closeout consistency blocked for ${milestoneId}: canonical DB milestone status is "${milestone.status}".`,
     );
   }
 
+  const validation = milestone.status === "skipped"
+    ? null
+    : getLatestAssessmentByScope(milestoneId, "milestone-validation");
   if (milestone.status !== "skipped") {
-    const validation = getLatestAssessmentByScope(milestoneId, "milestone-validation");
     if (validation?.status !== "pass") {
       return blocked(
         "validation-not-pass",
@@ -102,6 +117,13 @@ export function checkCloseoutConsistencyGate(
     );
   }
 
+  if (milestone.status !== "skipped") {
+    closeQualityGatesFromEvidence(milestoneId, {
+      artifactBasePath: options.artifactBasePath ?? artifactBasePathFromDb(),
+      milestoneValidationPassed: validation?.status === "pass",
+    });
+  }
+
   for (const slice of slices) {
     if (!isClosedStatus(slice.status)) {
       return blocked(

package/src/resources/extensions/gsd/codebase-generator.ts

@@ -472,17 +472,21 @@ export function ensureCodebaseMapFresh(
   const force = ensureOptions?.force === true;
   const now = Date.now();
 
+  // Enumerate files and compute fingerprint before the TTL check so that
+  // file changes are always detected, even within the TTL window.
+  const existing = readCodebaseMap(basePath);
+  const listed = enumerateFiles(basePath, resolved.excludes, resolved.maxFiles);
+  const fingerprint = computeCodebaseFingerprint(listed.files, resolved, listed.truncated);
+
+  // TTL short-circuit: only bypass regeneration when the fingerprint matches,
+  // confirming that no tracked files changed since the last check.
   if (!force && ttlMs > 0) {
     const cached = freshnessCache.get(cacheKey);
-    if (cached && now - cached.checkedAt < ttlMs) {
+    if (cached && now - cached.checkedAt < ttlMs && cached.result.fingerprint === fingerprint) {
       return cached.result;
     }
   }
 
-  const existing = readCodebaseMap(basePath);
-  const listed = enumerateFiles(basePath, resolved.excludes, resolved.maxFiles);
-  const fingerprint = computeCodebaseFingerprint(listed.files, resolved, listed.truncated);
-
   const cacheAndReturn = (result: EnsureCodebaseMapResult): EnsureCodebaseMapResult => {
     freshnessCache.set(cacheKey, { checkedAt: now, result });
     return result;

package/src/resources/extensions/gsd/commands/handlers/auto.ts

@@ -6,6 +6,7 @@ import { resolve } from "node:path";
 import { enableDebug } from "../../debug-logger.js";
 import { getAutoDashboardData, isAutoActive, isAutoPaused, pauseAuto, startAutoDetached, stopAuto, stopAutoRemote } from "../../auto.js";
 import { handleRate } from "../../commands-rate.js";
+import { notifyPreferenceDiagnostics } from "../../preferences-diagnostics.js";
 import { setSessionModelOverride } from "../../session-model-override.js";
 import { guardRemoteSession, projectRoot } from "../context.js";
 import { findMilestoneIds } from "../../milestone-id-utils.js";
@@ -91,6 +92,7 @@ export async function handleAutoCommand(trimmed: string, ctx: ExtensionCommandCo
     if (!(await guardRemoteSession(ctx, pi))) return true;
     const basePath = projectRoot();
     if (await hasUnresolvedCloseoutBlocker(ctx, basePath)) return true;
+    notifyPreferenceDiagnostics(ctx, basePath, { surface: "auto-preflight" });
 
     // Validate the milestone target exists and is not already complete.
     if (milestoneId) {
@@ -118,6 +120,7 @@ export async function handleAutoCommand(trimmed: string, ctx: ExtensionCommandCo
     if (!(await guardRemoteSession(ctx, pi))) return true;
     const basePath = projectRoot();
     if (await hasUnresolvedCloseoutBlocker(ctx, basePath)) return true;
+    notifyPreferenceDiagnostics(ctx, basePath, { surface: "auto-preflight" });
 
     // Validate the milestone target exists and is not already complete.
     if (milestoneId) {

package/src/resources/extensions/gsd/commands-handlers.ts

@@ -28,6 +28,7 @@ import { isAutoActive, checkRemoteAutoSession } from "./auto.js";
 import { getAutoWorktreePath } from "./auto-worktree.js";
 import { currentDirectoryRoot, projectRoot } from "./commands/context.js";
 import { loadPrompt } from "./prompt-loader.js";
+import { buildClaudeRuntimeFloorAdvisory } from "../../shared/claude-runtime-floor.js";
 import { isPnpmInstall } from "../../shared/package-manager-detection.js";
 import {
   buildDoctorHealIssuePayload,
@@ -67,6 +68,21 @@ function resolveInstallCommand(pkg: string): string {
   return `npm install -g ${pkg}`;
 }
 
+function notifyClaudeRuntimeFloorAdvisory(ctx: ExtensionCommandContext): void {
+  let advisory: string | null = null;
+  try {
+    advisory = buildClaudeRuntimeFloorAdvisory({
+      agentDir: join(gsdHome(), "agent"),
+      cwd: process.cwd(),
+    });
+  } catch {
+    return;
+  }
+  if (advisory) {
+    ctx.ui.notify(advisory, "warning");
+  }
+}
+
 async function fetchLatestVersionForCommand(registryUrl: string = UPDATE_REGISTRY_URL): Promise<string | null> {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), UPDATE_FETCH_TIMEOUT_MS);
@@ -549,6 +565,7 @@ export async function handleUpdate(ctx: ExtensionCommandContext, args = ""): Pro
 
   if (current && compareSemverLocal(latest, current) <= 0) {
     ctx.ui.notify(`Already up to date (${formatCommandVersion(current)}).`, "info");
+    if (!browserUpdate) notifyClaudeRuntimeFloorAdvisory(ctx);
     return;
   }
 
@@ -568,6 +585,7 @@ export async function handleUpdate(ctx: ExtensionCommandContext, args = ""): Pro
         : `Updated to v${latest}. Restart your GSD session to use the new version.`,
       "info",
     );
+    if (!browserUpdate) notifyClaudeRuntimeFloorAdvisory(ctx);
   } catch {
     ctx.ui.notify(
       `Update failed. Try manually: ${installCmd}`,

package/src/resources/extensions/gsd/commands-inspect.ts

@@ -5,9 +5,10 @@
  */
 
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import { gsdRoot } from "./paths.js";
+import {
+  isWorkflowDatabaseOpen,
+  openExistingWorkflowDatabase,
+} from "./db-workspace.js";
 import { logWarning } from "./workflow-logger.js";
 import { getErrorMessage } from "./error-utils.js";
 
@@ -48,12 +49,10 @@ export function formatInspectOutput(data: InspectData): string {
 
 export async function handleInspect(ctx: ExtensionCommandContext): Promise<void> {
   try {
-    const { isDbAvailable, _getAdapter, openDatabase } = await import("./gsd-db.js");
+    const { _getAdapter } = await import("./gsd-db.js");
 
-    if (!isDbAvailable()) {
-      const gsdDir = gsdRoot(process.cwd());
-      const dbPath = join(gsdDir, "gsd.db");
-      if (!existsSync(gsdDir) || !existsSync(dbPath) || !openDatabase(dbPath)) {
+    if (!isWorkflowDatabaseOpen()) {
+      if (!openExistingWorkflowDatabase(process.cwd()).ok) {
         ctx.ui.notify("No GSD database available. Run /gsd auto to create one.", "info");
         return;
       }

package/src/resources/extensions/gsd/commands-maintenance.ts

@@ -11,6 +11,7 @@ import { deriveState } from "./state.js";
 import { gsdProjectionRoot, gsdRoot } from "./paths.js";
 import { nativeBranchList, nativeDetectMainBranch, nativeBranchListMerged, nativeBranchDelete, nativeForEachRef, nativeUpdateRef } from "./native-git-bridge.js";
 import { logWarning } from "./workflow-logger.js";
+import { backupWorkflowDatabaseSnapshot, refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 
 export async function handleCleanupBranches(ctx: ExtensionCommandContext, basePath: string): Promise<void> {
   let branches: string[];
@@ -581,7 +582,7 @@ async function confirmRecover(
  * Prints counts of recovered items and the resulting project phase.
  */
 export async function handleRecover(ctx: ExtensionCommandContext, basePath: string, args = ""): Promise<void> {
-  const { isDbAvailable: dbAvailable, clearEngineHierarchy, transaction: dbTransaction, backupDatabaseSnapshot } = await import("./gsd-db.js");
+  const { isDbAvailable: dbAvailable, clearEngineHierarchy, transaction: dbTransaction } = await import("./gsd-db.js");
   const { migrateHierarchyToDb } = await import("./md-importer.js");
   const { invalidateStateCache } = await import("./state.js");
   const { countDbHierarchy, countMarkdownHierarchy, recoverWouldDeleteDbRows } = await import("./migration-auto-check.js");
@@ -604,7 +605,7 @@ export async function handleRecover(ctx: ExtensionCommandContext, basePath: stri
 
   try {
     // 0. Snapshot the DB before the destructive clear so recover is reversible.
-    const backupPath = backupDatabaseSnapshot("pre-recover");
+    const backupPath = backupWorkflowDatabaseSnapshot("pre-recover");
 
     // 1. Delete + re-populate inside a single transaction for atomicity.
     //    clearEngineHierarchy() uses transaction() internally but transaction()
@@ -749,6 +750,62 @@ function parseRebuildTarget(args: string): RebuildTarget {
   return "usage";
 }
 
+export interface RebuildMarkdownProjectionsResult {
+  rendered: number;
+  skipped: number;
+  errors: string[];
+  quarantined: number;
+  quarantinedPaths: string[];
+}
+
+/**
+ * Re-render markdown planning projections from the authoritative DB.
+ *
+ * Quarantines open-unit SUMMARY files that contradict DB status before
+ * rendering. Safe to call after milestone merge/transition or during startup
+ * self-heal when the DB holds rows markdown lacks.
+ */
+export async function rebuildMarkdownProjectionsFromDb(
+  basePath: string,
+): Promise<RebuildMarkdownProjectionsResult> {
+  const { deleteArtifactByPath } = await import("./gsd-db.js");
+  const { detectArtifactDbDrift } = await import("./state-reconciliation/drift/artifact-db.js");
+  const { renderAllFromDb } = await import("./markdown-renderer.js");
+  const { invalidateStateCache } = await import("./state.js");
+
+  invalidateStateCache();
+  refreshWorkflowDatabaseFromDisk();
+
+  const state = await deriveState(basePath);
+  const drifts = detectArtifactDbDrift(state, { basePath, state });
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const quarantined: string[] = [];
+  const seen = new Set<string>();
+
+  for (const drift of drifts) {
+    if (drift.kind !== "artifact-db-status-divergence") continue;
+    if (drift.artifactType !== "SUMMARY" || !drift.artifactPath) continue;
+    const absPath = resolveDiskArtifactPath(basePath, drift.artifactPath);
+    if (seen.has(absPath) || !existsSync(absPath)) continue;
+    seen.add(absPath);
+    const artifactDbPath = artifactPathForDb(basePath, absPath);
+    const target = quarantineProjectionFile(basePath, absPath, stamp);
+    deleteArtifactByPath(artifactDbPath);
+    quarantined.push(target);
+  }
+
+  const rendered = await renderAllFromDb(basePath);
+  invalidateStateCache();
+
+  return {
+    rendered: rendered.rendered,
+    skipped: rendered.skipped,
+    errors: rendered.errors,
+    quarantined: quarantined.length,
+    quarantinedPaths: quarantined,
+  };
+}
+
 /**
  * `gsd rebuild markdown` — Re-render markdown projections from the authoritative DB.
  *
@@ -757,10 +814,7 @@ function parseRebuildTarget(args: string): RebuildTarget {
  * under `.gsd/quarantine/projections/` before DB projections are rendered.
  */
 export async function handleRebuild(ctx: ExtensionCommandContext, basePath: string, args = ""): Promise<void> {
-  const { isDbAvailable: dbAvailable, deleteArtifactByPath } = await import("./gsd-db.js");
-  const { detectArtifactDbDrift } = await import("./state-reconciliation/drift/artifact-db.js");
-  const { renderAllFromDb } = await import("./markdown-renderer.js");
-  const { invalidateStateCache } = await import("./state.js");
+  const { isDbAvailable: dbAvailable } = await import("./gsd-db.js");
 
   const target = parseRebuildTarget(args);
   if (target === "usage") {
@@ -794,54 +848,34 @@ export async function handleRebuild(ctx: ExtensionCommandContext, basePath: stri
   }
 
   try {
-    invalidateStateCache();
-    const state = await deriveState(basePath);
-    const drifts = detectArtifactDbDrift(state, { basePath, state });
-    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-    const quarantined: string[] = [];
-    const seen = new Set<string>();
-
-    for (const drift of drifts) {
-      if (drift.kind !== "artifact-db-status-divergence") continue;
-      if (drift.artifactType !== "SUMMARY" || !drift.artifactPath) continue;
-      const absPath = resolveDiskArtifactPath(basePath, drift.artifactPath);
-      if (seen.has(absPath) || !existsSync(absPath)) continue;
-      seen.add(absPath);
-      const artifactDbPath = artifactPathForDb(basePath, absPath);
-      const target = quarantineProjectionFile(basePath, absPath, stamp);
-      deleteArtifactByPath(artifactDbPath);
-      quarantined.push(target);
-    }
-
-    const rendered = await renderAllFromDb(basePath);
-    invalidateStateCache();
+    const result = await rebuildMarkdownProjectionsFromDb(basePath);
 
     const lines = [
       "gsd rebuild markdown: rebuilt markdown projections from the canonical DB",
-      `  Rendered:    ${rendered.rendered}`,
-      `  Skipped:     ${rendered.skipped}`,
-      `  Quarantined: ${quarantined.length}`,
+      `  Rendered:    ${result.rendered}`,
+      `  Skipped:     ${result.skipped}`,
+      `  Quarantined: ${result.quarantined}`,
     ];
-    if (rendered.errors.length > 0) {
-      lines.push(`  Errors:      ${rendered.errors.length}`);
-      for (const err of rendered.errors.slice(0, 5)) {
+    if (result.errors.length > 0) {
+      lines.push(`  Errors:      ${result.errors.length}`);
+      for (const err of result.errors.slice(0, 5)) {
         lines.push(`    - ${err}`);
       }
-      if (rendered.errors.length > 5) {
-        lines.push(`    - ${rendered.errors.length - 5} more`);
+      if (result.errors.length > 5) {
+        lines.push(`    - ${result.errors.length - 5} more`);
       }
     }
-    if (quarantined.length > 0) {
+    if (result.quarantined > 0) {
       lines.push("", "  Quarantine:");
-      for (const target of quarantined.slice(0, 5)) {
+      for (const target of result.quarantinedPaths.slice(0, 5)) {
         lines.push(`    - ${target}`);
       }
-      if (quarantined.length > 5) {
-        lines.push(`    - ${quarantined.length - 5} more`);
+      if (result.quarantined > 5) {
+        lines.push(`    - ${result.quarantined - 5} more`);
       }
     }
 
-    ctx.ui.notify(lines.join("\n"), rendered.errors.length > 0 ? "warning" : "success");
+    ctx.ui.notify(lines.join("\n"), result.errors.length > 0 ? "warning" : "success");
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     logWarning("command", `rebuild failed: ${msg}`);

package/src/resources/extensions/gsd/commands-ship.ts

@@ -21,7 +21,7 @@ import { nativeGetCurrentBranch, nativeDetectMainBranch } from "./native-git-bri
 import { formatDuration } from "../shared/format-utils.js";
 import { parseEvalReviewFrontmatter, type Verdict } from "./eval-review-schema.js";
 import { currentDirectoryRoot } from "./commands/context.js";
-import { buildPrEvidence } from "./pr-evidence.js";
+import { buildPullRequestEvidence } from "./pull-request-process.js";
 
 function git(basePath: string, args: readonly string[]): string {
   return execFileSync("git", args, { cwd: basePath, encoding: "utf-8" }).trim();
@@ -178,7 +178,7 @@ function generatePRContent(basePath: string, milestoneId: string, milestoneTitle
     }
   }
 
-  return buildPrEvidence({
+  return buildPullRequestEvidence({
     milestoneId,
     milestoneTitle,
     changeType: "feat",

package/src/resources/extensions/gsd/commands-verdict.ts

@@ -4,11 +4,14 @@
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
 
 import { loadFile } from "./files.js";
-import { resolveMilestoneFile } from "./paths.js";
+import { gsdProjectionRoot, resolveMilestoneFile } from "./paths.js";
+import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
+import { join } from "node:path";
 import { deriveState } from "./state.js";
 import { executeValidateMilestone } from "./tools/workflow-tool-executors.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import { getLatestAssessmentByScope } from "./gsd-db.js";
+import { checkpointWorkflowDatabase } from "./db-workspace.js";
 import {
   VALIDATION_VERDICTS,
   extractVerdict,
@@ -122,8 +125,20 @@ async function loadExistingValidation(
   basePath: string,
   milestoneId: string,
 ): Promise<ExistingValidation | null> {
+  const canonicalBase = resolveCanonicalMilestoneRoot(basePath, milestoneId);
+  const canonicalValidationPath = join(
+    gsdProjectionRoot(canonicalBase),
+    "milestones",
+    milestoneId,
+    `${milestoneId}-VALIDATION.md`,
+  );
+  const canonicalContent = await loadFile(canonicalValidationPath);
+  if (canonicalContent) {
+    return { content: canonicalContent, source: canonicalValidationPath };
+  }
+
   const validationPath = resolveMilestoneFile(basePath, milestoneId, "VALIDATION");
-  if (validationPath) {
+  if (validationPath && validationPath !== canonicalValidationPath) {
     const content = await loadFile(validationPath);
     if (content) return { content, source: validationPath };
   }
@@ -222,6 +237,8 @@ export async function handleVerdict(
     return;
   }
 
+  checkpointWorkflowDatabase();
+
   const prevVerdict = current.verdict ?? "unknown";
   const effectiveVerdict = extractEffectiveVerdict(result.details, parsed.verdict);
   if (effectiveVerdict !== parsed.verdict) {

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/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 {