@opengsd/gsd-pi 1.2.0-dev.955e4da0 → 1.2.0-dev.a6376d75

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/mcp-tool-name.ts

@@ -1,5 +1,7 @@
 // Project/App: gsd-pi
-// File Purpose: Shared parsing and formatting helpers for MCP-scoped tool names.
+// File Purpose: GSD-facing face over the shared @gsd/pi-ai MCP tool-name helpers.
+
+import { parseMcpToolName as parsePiAiMcpToolName, stripMcpToolPrefix } from "@gsd/pi-ai";
 
 const MCP_TOOL_PREFIX = "mcp__";
 
@@ -9,18 +11,11 @@ export interface ParsedMcpToolName {
 }
 
 export function parseMcpToolName(toolName: string): ParsedMcpToolName | null {
-  if (!toolName.startsWith(MCP_TOOL_PREFIX)) return null;
-  const toolSeparator = toolName.indexOf("__", MCP_TOOL_PREFIX.length);
-  if (toolSeparator < 0) return null;
-  return {
-    serverName: toolName.slice(MCP_TOOL_PREFIX.length, toolSeparator),
-    toolName: toolName.slice(toolSeparator + 2),
-  };
+  const parsed = parsePiAiMcpToolName(toolName);
+  return parsed ? { serverName: parsed.server, toolName: parsed.tool } : null;
 }
 
-export function stripMcpToolPrefix(toolName: string): string {
-  return parseMcpToolName(toolName)?.toolName ?? toolName;
-}
+export { stripMcpToolPrefix };
 
 export function toMcpToolName(serverName: string, toolName: string): string {
   return `${MCP_TOOL_PREFIX}${serverName}__${toolName}`;

package/src/resources/extensions/gsd/memory-consolidation-scanner.ts

@@ -264,7 +264,7 @@ export function reportConsolidationGaps(basePath: string): ConsolidationGapRepor
   try {
     const report = scanConsolidationGaps(basePath);
     if (report.totalGaps === 0) return report;
-    appendNotification(report.summary, "warning", "workflow-logger");
+    appendNotification(report.summary, "warning", "workflow-logger", { kind: "memory-consolidation" });
     logWarning("memory-consolidation", report.summary);
     return report;
   } catch (e) {

package/src/resources/extensions/gsd/migrate/safety.ts

@@ -10,6 +10,7 @@ import { readCrashLock, isLockProcessAlive } from "../crash-recovery.js";
 import { closeWorkflowDatabase } from "../db-workspace.js";
 import { readPausedSessionMetadata } from "../interrupted-session.js";
 import { gsdRoot } from "../paths.js";
+import { canonicalWorktreesDir } from "../worktree-placement.js";
 import type { MigrationPreview } from "./writer.js";
 
 export interface MigrationPaths {
@@ -106,8 +107,10 @@ export function assertMigrationHasSlices(preview: MigrationPreview): void {
 }
 
 function hasWorktreeState(targetRoot: string): boolean {
+  // Legacy container is probed via gsdRoot() (symlink-resolved) on purpose —
+  // migration targets may have .gsd in the external-state layout.
   const containers = [
-    join(targetRoot, ".gsd-worktrees"),
+    canonicalWorktreesDir(targetRoot),
     join(gsdRoot(targetRoot), "worktrees"),
   ];
   for (const worktreesDir of containers) {

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/notification-store.ts

@@ -12,6 +12,17 @@ import { randomUUID } from "node:crypto";
 export type NotifySeverity = "info" | "success" | "warning" | "error";
 export type NotificationSource = "notify" | "workflow-logger";
 
+/**
+ * Optional structured identity for a notification. When present, `kind`
+ * (a stable machine name like "auto-stop" or "provider-error-pause") plus
+ * `scope` (e.g. a milestone/slice id) — not the prose — key deduplication,
+ * and consumers can filter without parsing message text.
+ */
+export interface NotificationMeta {
+  kind?: string;
+  scope?: string;
+}
+
 export interface NotificationEntry {
   id: string;
   ts: string;
@@ -19,6 +30,8 @@ export interface NotificationEntry {
   message: string;
   source: NotificationSource;
   read: boolean;
+  kind?: string;
+  scope?: string;
 }
 
 // ─── Constants ──────────────────────────────────────────────────────────
@@ -60,11 +73,15 @@ export function appendNotification(
   message: string,
   severity: NotifySeverity,
   source: NotificationSource = "notify",
+  meta?: NotificationMeta,
 ): void {
   if (!_basePath) return;
   if (_suppressCount > 0) return;
   const persistedMessage = message.length > 500 ? message.slice(0, 500) + "…" : message;
-  const dedupKey = `${_basePath}:${severity}:${source}:${persistedMessage}`;
+  // Structured identity (kind + scope) keys dedup when present, so a rephrased
+  // message of the same event still dedups; otherwise fall back to the prose.
+  const identity = meta?.kind ? `${meta.kind}:${meta.scope ?? ""}` : persistedMessage;
+  const dedupKey = `${_basePath}:${severity}:${source}:${identity}`;
   const now = Date.now();
   const lastSeen = _recentMessageTimestamps.get(dedupKey);
   if (lastSeen !== undefined && now - lastSeen < DEDUP_WINDOW_MS) return;
@@ -82,6 +99,8 @@ export function appendNotification(
     message: persistedMessage,
     source,
     read: false,
+    ...(meta?.kind ? { kind: meta.kind } : {}),
+    ...(meta?.scope ? { scope: meta.scope } : {}),
   };
 
   try {
@@ -102,11 +121,15 @@ export function appendNotification(
 
 /**
  * Read all notification entries from disk. Returns newest-first.
+ * An optional filter narrows by structured identity (kind and/or scope).
  */
-export function readNotifications(basePath?: string): NotificationEntry[] {
+export function readNotifications(basePath?: string, filter?: NotificationMeta): NotificationEntry[] {
   const bp = basePath ?? _basePath;
   if (!bp) return [];
-  return _readEntriesFromDisk(bp).reverse();
+  const entries = _readEntriesFromDisk(bp).filter(
+    (e) => (!filter?.kind || e.kind === filter.kind) && (!filter?.scope || e.scope === filter.scope),
+  );
+  return entries.reverse();
 }
 
 /**

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/parallel-monitor-overlay.ts

@@ -128,8 +128,7 @@ function discoverWorkers(basePath: string): string[] {
   return [...mids].sort();
 }
 
-function querySliceProgress(basePath: string, mid: string): SliceProgress[] {
-  const workRoot = worktreePathFor(basePath, mid);
+function querySliceProgress(basePath: string, mid: string, workRoot: string = worktreePathFor(basePath, mid)): SliceProgress[] {
   const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
   if (!existsSync(dbPath)) return [];
 
@@ -193,9 +192,12 @@ function collectWorkerData(basePath: string): WorkerView[] {
   const workers: WorkerView[] = [];
 
   for (const mid of mids) {
+    // Resolve the worktree path once per worker per tick — this runs on a
+    // 5-second refresh interval and worktreePathFor probes the filesystem.
+    const workRoot = worktreePathFor(basePath, mid);
     const status = readJsonSafe<StatusJson>(join(parallelDir, `${mid}.status.json`));
-    const lock = readJsonSafe<AutoLock>(join(worktreePathFor(basePath, mid), ".gsd", "auto.lock"));
-    const slices = querySliceProgress(basePath, mid);
+    const lock = readJsonSafe<AutoLock>(join(workRoot, ".gsd", "auto.lock"));
+    const slices = querySliceProgress(basePath, mid, workRoot);
 
     const pid = lock?.pid || status?.pid || 0;
     const alive = pid ? isPidAlive(pid) : false;

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/paths.ts

@@ -148,6 +148,39 @@ export function clearPathCache(): void {
 
 // ─── Name Builders ─────────────────────────────────────────────────────────
 
+/** Directories owned by the GSD framework — metadata, never project source. */
+export const FRAMEWORK_METADATA_DIRS: readonly string[] = [".gsd", ".planning", ".audits"];
+
+/**
+ * Every artifact suffix used with the name builders below — the single source
+ * for the `<ID>-<SUFFIX>.md` naming vocabulary. Extend this list when a new
+ * artifact type is introduced; consumers (md-importer walking, pre-execution
+ * artifact detection) pick it up from here.
+ */
+export const PLANNING_ARTIFACT_SUFFIXES: readonly string[] = [
+  "CONTEXT",
+  "CONTEXT-DRAFT",
+  "ROADMAP",
+  "PLAN",
+  "REPLAN",
+  "SUMMARY",
+  "RESEARCH",
+  "VALIDATION",
+  "ASSESSMENT",
+  "UAT",
+  "DISCUSSION",
+  "EVAL-REVIEW",
+  "PARKED",
+  "VERIFICATION-FAILED",
+  "CONTINUE",
+];
+
+/** Matches a bare planning-artifact file name, e.g. "M001-CONTEXT.md", "S01-PLAN.md". */
+export const PLANNING_ARTIFACT_NAME_RE = new RegExp(
+  `^[MST]\\d+-(${PLANNING_ARTIFACT_SUFFIXES.join("|")})\\.md$`,
+  "i",
+);
+
 /**
  * Build a milestone-level file name.
  * ("M001", "CONTEXT") → "M001-CONTEXT.md"