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

package/src/resources/extensions/gsd/guided-unit-completion.ts

@@ -0,0 +1,275 @@
+// Project/App: gsd-pi
+// File Purpose: Recover guided-unit completion signals that did not produce expected tool/file evidence.
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import {
+  clearPathCache,
+  relMilestoneFile,
+  resolveMilestoneFile,
+  resolveMilestonePath,
+} from "./paths.js";
+import {
+  _getPendingAutoStart,
+  deletePendingAutoStart,
+  hasPendingAutoStart,
+} from "./pending-auto-start.js";
+import { logWarning } from "./workflow-logger.js";
+
+// #4573: cap for how many times we nudge the LLM after a premature ready
+// phrase before giving up and asking the user to re-run /gsd.
+const MAX_READY_REJECTS = 2;
+
+// #4573: matches the canonical ready phrase the discuss prompt asks the LLM
+// to emit. Accepts any M-prefixed milestone ID (three digits + optional
+// suffix) with optional trailing punctuation.
+const READY_PHRASE_RE = /\bMilestone\s+M\d{3}[A-Z0-9-]*\s+ready\.?/i;
+
+const emptyTurnCounterByBase = new Map<string, number>();
+const MAX_EMPTY_TURN_RETRIES = 2;
+
+// Phrases that indicate the LLM is about to do something but has not yet.
+// Kept tight to avoid flagging legitimate narration like "I'll wait for your answer."
+//
+// "make" was previously in the verb list but matches conversational meta phrases
+// like "Let me make sure I understand…" which are NOT action announcements —
+// removed to prevent the empty-turn nudge from auto-replying to user questions
+// in discuss flows.
+const COMMIT_INTENT_RE =
+  /\b(?:I['’]ll|I will|Next,? I['’]ll|Now I['’]ll|Let me|I['’]m going to|I am going to)\s+(?:now\s+)?(?:write|create|call|invoke|update|add|run|execute|generate|produce|emit|compose|implement|save|apply|commit)\b/i;
+
+/**
+ * Extract the concatenated text content from an assistant message, whether it
+ * stores content as a string or as an array of text blocks.
+ */
+function extractAssistantText(msg: any): string {
+  if (!msg) return "";
+  const content = msg.content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const parts: string[] = [];
+  for (const block of content) {
+    if (!block || typeof block !== "object") continue;
+    if (block.type === "text" && typeof block.text === "string") parts.push(block.text);
+  }
+  return parts.join("\n");
+}
+
+/**
+ * Return true if the assistant message contains any tool-use block.
+ *
+ * The canonical pi-ai `AssistantMessage.content` (see packages/pi-ai/src/types.ts)
+ * uses `type: "toolCall"` and `type: "serverToolUse"` for tool invocations —
+ * every provider (anthropic-direct, claude-code-cli, openai, etc.) normalizes
+ * incoming tool blocks into these two shapes before they reach guided-flow.
+ *
+ * The Anthropic API wire shape `"tool_use"` / `"server_tool_use"` does NOT appear
+ * in the internal AssistantMessage — those literals are only used when sending
+ * messages back out to the Anthropic API. Matching them here was a latent bug:
+ * `hasToolUse` returned `false` for every real tool call, which let the
+ * empty-turn nudge fire and pre-empt MCP tools that block on the user
+ * (e.g. `ask_user_questions`). See investigation in PR for #4658.
+ */
+function hasToolUse(msg: any): boolean {
+  if (!msg) return false;
+  const content = msg.content;
+  if (!Array.isArray(content)) return false;
+  return content.some(
+    (b: any) =>
+      b &&
+      typeof b === "object" &&
+      (b.type === "toolCall" || b.type === "serverToolUse"),
+  );
+}
+
+/**
+ * #4573 — Detect and recover from the "ready phrase without files" failure mode.
+ *
+ * When the LLM emits "Milestone {{id}} ready." but has not written the
+ * milestone CONTEXT/ROADMAP artifacts, `checkAutoStartAfterDiscuss()` silently
+ * returns false and the next /gsd invocation loops into the "All milestones
+ * complete" warning.
+ *
+ * This function, called from `handleAgentEnd` after `checkAutoStartAfterDiscuss`
+ * returns false, pattern-matches the ready phrase on the last assistant message.
+ * If it fired AND neither the canonical M###-CONTEXT.md/M###-ROADMAP.md nor
+ * legacy CONTEXT.md/ROADMAP.md files exist, it:
+ *   1. Notifies the user that the signal was rejected.
+ *   2. Injects a system message via `pi.sendMessage(..., {triggerTurn:true})`
+ *      telling the LLM the signal was premature and to emit the writes now.
+ *   3. Caps at `MAX_READY_REJECTS` per-entry; beyond that, gives up and asks
+ *      the user to re-run /gsd.
+ *
+ * Returns true when a nudge (or give-up) was emitted, signaling the caller to
+ * skip `resolveAgentEnd`.
+ */
+export function maybeHandleReadyPhraseWithoutFiles(
+  event: { messages: any[] },
+  lookupBasePath?: string,
+): boolean {
+  const entry = _getPendingAutoStart(lookupBasePath);
+  if (!entry) return false;
+  const { ctx, pi, basePath, milestoneId } = entry;
+
+  // Gate: last assistant message must contain the ready phrase
+  const lastMsg = event.messages[event.messages.length - 1];
+  const text = extractAssistantText(lastMsg);
+  if (!READY_PHRASE_RE.test(text)) return false;
+
+  // Bust paths.ts cached dir listings before checking for fresh writes. The
+  // LLM's Write tool calls do not invalidate paths.ts caches, so a stale
+  // listing taken before the milestone dir or its CONTEXT/ROADMAP files
+  // existed would falsely report the artifacts as missing and trigger the
+  // 3-strike "ready without files" abort even though the writes succeeded.
+  clearPathCache();
+
+  // Gate: artifacts must still be missing — if they exist, the happy path
+  // already fired and we have nothing to do.
+  const contextFile = resolveMilestoneFile(basePath, milestoneId, "CONTEXT");
+  const roadmapFile = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+  if (contextFile || roadmapFile) return false;
+
+  // Diagnostic: when the cached resolver reports both files missing, also probe
+  // the canonical paths with uncached existsSync so we can tell whether the
+  // recovery is firing on real-missing files or a path-resolution miss
+  // (basePath/symlink mismatch, stale cache despite agent-end-recovery flush,
+  // legacy descriptor dir not matching, etc.).
+  try {
+    const mDir = resolveMilestonePath(basePath, milestoneId);
+    const canonicalCtx = mDir ? join(mDir, `${milestoneId}-CONTEXT.md`) : null;
+    const canonicalRoadmap = mDir ? join(mDir, `${milestoneId}-ROADMAP.md`) : null;
+    logWarning(
+      "guided",
+      `ready-phrase-reject diagnostic mid=${milestoneId} basePath=${basePath} ` +
+      `mDir=${mDir ?? "null"} ` +
+      `canonical-ctx=${canonicalCtx ?? "null"} ctx-exists=${canonicalCtx ? existsSync(canonicalCtx) : "n/a"} ` +
+      `canonical-roadmap=${canonicalRoadmap ?? "null"} roadmap-exists=${canonicalRoadmap ? existsSync(canonicalRoadmap) : "n/a"}`,
+    );
+  } catch (e) {
+    logWarning("guided", `ready-phrase-reject diagnostic failed: ${(e as Error).message}`);
+  }
+
+  entry.readyRejectCount = (entry.readyRejectCount ?? 0) + 1;
+
+  if (entry.readyRejectCount > MAX_READY_REJECTS) {
+    // Give up: clear state and tell the user to re-run /gsd. Avoids an
+    // infinite nudge loop when the LLM never produces the writes.
+    deletePendingAutoStart(basePath);
+    ctx.ui.notify(
+      `Milestone ${milestoneId}: LLM signaled "ready" ${entry.readyRejectCount} times without writing files. ` +
+      `Stopping auto-nudge. Run /gsd to try again.`,
+      "error",
+    );
+    return true;
+  }
+
+  const contextRel = relMilestoneFile(basePath, milestoneId, "CONTEXT");
+  const roadmapRel = relMilestoneFile(basePath, milestoneId, "ROADMAP");
+  ctx.ui.notify(
+    `Milestone ${milestoneId}: "ready" signal rejected — ${contextRel} and ${roadmapRel} are missing. Asking the LLM to complete the writes.`,
+    "warning",
+  );
+
+  const nudge =
+    `You emitted "Milestone ${milestoneId} ready." but neither ` +
+    `${contextRel} nor ${roadmapRel} exists on disk. ` +
+    `The ready phrase is a POST-WRITE signal and has been rejected. ` +
+    `In this turn: (1) write PROJECT.md, REQUIREMENTS.md, and the milestone ` +
+    `CONTEXT.md, (2) call gsd_plan_milestone, then (3) emit the ready phrase. ` +
+    `Do not describe these steps — execute them as tool calls. ` +
+    `This is retry ${entry.readyRejectCount}/${MAX_READY_REJECTS}; further ` +
+    `premature signals will clear the session.`;
+
+  try {
+    pi.sendMessage(
+      { customType: "gsd-ready-no-files", content: nudge, display: false },
+      { triggerTurn: true },
+    );
+  } catch (e) {
+    logWarning("guided", `ready-phrase nudge sendMessage failed: ${(e as Error).message}`);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Reset the empty-turn counter for a basePath after a successful tool-use turn.
+ * Called from handleAgentEnd when the last message contains tool_use blocks.
+ */
+export function resetEmptyTurnCounter(basePath?: string): void {
+  if (basePath) emptyTurnCounterByBase.delete(basePath);
+  else emptyTurnCounterByBase.clear();
+}
+
+export function maybeHandleEmptyIntentTurn(
+  event: { messages: any[] },
+  isAuto: boolean,
+  lookupBasePath?: string,
+): boolean {
+  // Gate: only fire when there is system-driven work in flight. Interactive
+  // /gsd discuss (user-driven) produces legitimate text-only turns.
+  if (!isAuto && !hasPendingAutoStart(lookupBasePath)) return false;
+
+  const lastMsg = event.messages[event.messages.length - 1];
+  if (!lastMsg) return false;
+  if (hasToolUse(lastMsg)) return false;
+
+  const text = extractAssistantText(lastMsg).trim();
+  if (!text) return false;
+
+  // Skip if the LLM is emitting the ready phrase — that is the ready-no-files
+  // path, handled by maybeHandleReadyPhraseWithoutFiles.
+  if (READY_PHRASE_RE.test(text)) return false;
+
+  // Skip if the LLM is clearly handing back to the user. Discuss flows
+  // often pose a question and follow it with a conditional intent on the
+  // same line ("Did I capture that correctly? If so, I'll write the
+  // requirements."). A line-trailing `?` check misses these because the
+  // line ends in `.`. Match any sentence-terminating `?` (followed by
+  // whitespace or end-of-text) — false negatives here auto-reply to the
+  // user, which is a much worse failure mode than a missed nudge.
+  if (/\?(?:\s|$)/.test(text)) return false;
+
+  // Must contain a commit-intent phrase — this is the stall we care about.
+  if (!COMMIT_INTENT_RE.test(text)) return false;
+
+  // Resolve the target basePath + pi for injection. Prefer the pending
+  // autostart entry (discuss flow); otherwise we cannot inject.
+  const entry = _getPendingAutoStart(lookupBasePath);
+  if (!entry) return false;
+  const { ctx, pi, basePath } = entry;
+
+  const count = (emptyTurnCounterByBase.get(basePath) ?? 0) + 1;
+  emptyTurnCounterByBase.set(basePath, count);
+
+  if (count > MAX_EMPTY_TURN_RETRIES) {
+    ctx.ui.notify(
+      `Empty-turn recovery: LLM announced intent ${count} times without calling any tool. ` +
+      `Stopping auto-nudge.`,
+      "error",
+    );
+    return false; // let the normal flow resolve/pause the unit
+  }
+
+  ctx.ui.notify(
+    `Empty-turn detected: LLM announced intent but called no tool. Prompting it to execute.`,
+    "info",
+  );
+
+  const nudge =
+    `Your last turn announced an action (e.g. "I'll write…" or "Let me call…") ` +
+    `but contained no tool call. The system records zero tool-use blocks for ` +
+    `that turn. Execute the announced action NOW as a tool call in this turn. ` +
+    `Do not describe it again. Retry ${count}/${MAX_EMPTY_TURN_RETRIES}.`;
+
+  try {
+    pi.sendMessage(
+      { customType: "gsd-empty-turn-recovery", content: nudge, display: false },
+      { triggerTurn: true },
+    );
+  } catch (e) {
+    logWarning("guided", `empty-turn nudge sendMessage failed: ${(e as Error).message}`);
+    return false;
+  }
+  return true;
+}

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

@@ -9,11 +9,10 @@
 // Critical invariant: rendered markdown must round-trip through
 // parseRoadmap(), parsePlan(), parseSummary() in files.ts.
 
-import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync, statSync } from "node:fs";
 import { logWarning } from "./workflow-logger.js";
 import { isClosedStatus } from "./status-guards.js";
 import { dirname, join, relative } from "node:path";
-import { createRequire } from "node:module";
 import {
   getAllMilestones,
   getMilestone,
@@ -38,7 +37,8 @@ import {
   buildTaskFileName,
   buildSliceFileName,
 } from "./paths.js";
-import { saveFile, clearParseCache } from "./files.js";
+import { saveFile, clearParseCache, registerCacheClearCallback } from "./files.js";
+import { parseRoadmap, parsePlan } from "./parsers-legacy.js";
 import { invalidateStateCache } from "./state.js";
 import { clearPathCache } from "./paths.js";
 import type { RiskLevel } from "./types.js";
@@ -171,7 +171,8 @@ function renderRoadmapMarkdown(milestone: MilestoneRow, slices: SliceRow[]): str
   lines.push("");
   for (const slice of slices) {
     const done = isClosedStatus(slice.status) ? "x" : " ";
-    const depends = `[${(slice.depends ?? []).join(",")}]`;
+    const cleanDepends = (slice.depends ?? []).map(d => d.replace(/^\[|\]$/g, '')).filter(d => /^[A-Za-z0-9][A-Za-z0-9-]*$/.test(d));
+    const depends = `[${cleanDepends.join(",")}]`;
     const safeTitle = sanitizeInlineRoadmapText(slice.title || slice.id) || slice.id;
     const safeRisk = normalizeRiskLevel(slice.risk);
     // ADR-011: sketch slices get a `[sketch]` badge so the roadmap shows at a
@@ -738,20 +739,41 @@ export interface StaleEntry {
  * Returns a list of stale entries with file path and reason.
  * Logs to stderr when stale files are detected.
  */
-export function detectStaleRenders(basePath: string): StaleEntry[] {
-  // Lazy-load parsers — intentional disk-vs-DB comparison requires parsers
-  const _require = createRequire(import.meta.url);
-  let parseRoadmap: Function, parsePlan: Function;
-  try {
-    // Prefer compiled JS for packaged/runtime installs; TS exists only in source/dev contexts.
-    const m = _require("./parsers-legacy.js");
-    parseRoadmap = m.parseRoadmap; parsePlan = m.parsePlan;
-  } catch (e) {
-    logWarning("renderer", `parsers-legacy.js require failed, falling back to .ts: ${(e as Error).message}`);
-    const m = _require("./parsers-legacy.ts");
-    parseRoadmap = m.parseRoadmap; parsePlan = m.parsePlan;
+// #442 Phase 1.5: cache parsed ROADMAP/PLAN projections by file identity
+// (path + mtimeMs + size) so an unchanged projection skips readFileSync AND
+// the parse entirely on repeated dispatches. The DB-vs-disk comparison below
+// still runs every call against fresh DB rows — only the disk-parse half is
+// memoized, and parsed output depends solely on file bytes, so this is
+// behavior-preserving. Invalidation rides the existing clearParseCache()
+// callback chain (fired by invalidateCaches() after every projection write and
+// by reconcileBeforeDispatch repairs), so a changed file always re-parses.
+interface CachedProjection { mtimeMs: number; size: number; parsed: unknown }
+const _projectionParseCache = new Map<string, CachedProjection>();
+registerCacheClearCallback(() => _projectionParseCache.clear());
+
+function parseProjectionByIdentity(path: string, parse: (content: string) => unknown): unknown {
+  let st: ReturnType<typeof statSync> | null = null;
+  try { st = statSync(path); } catch { st = null; }
+  if (st) {
+    const hit = _projectionParseCache.get(path);
+    if (hit && hit.mtimeMs === st.mtimeMs && hit.size === st.size) {
+      return hit.parsed;
+    }
+    const parsed = parse(readFileSync(path, "utf-8"));
+    _projectionParseCache.set(path, { mtimeMs: st.mtimeMs, size: st.size, parsed });
+    return parsed;
   }
+  // stat failed (e.g. file vanished between existsSync and here) — fall back to
+  // the original plain read+parse so error handling is unchanged.
+  return parse(readFileSync(path, "utf-8"));
+}
 
+export function detectStaleRenders(basePath: string): StaleEntry[] {
+  // parseRoadmap/parsePlan are statically imported (#442 Phase 1.4): the
+  // per-call createRequire("./parsers-legacy") that used to live here ran on
+  // every dispatch. The static `./parsers-legacy.js` specifier resolves in
+  // both packaged (.js) and source (.ts via the strip-types loader) contexts —
+  // the same form a dozen other modules already use.
   const stale: StaleEntry[] = [];
   const milestones = getAllMilestones();
 
@@ -762,8 +784,7 @@ export function detectStaleRenders(basePath: string): StaleEntry[] {
     const roadmapPath = resolveRoadmapProjectionPath(basePath, milestone.id);
     if (existsSync(roadmapPath)) {
       try {
-        const content = readFileSync(roadmapPath, "utf-8");
-        const parsed = parseRoadmap(content);
+        const parsed = parseProjectionByIdentity(roadmapPath, parseRoadmap) as ReturnType<typeof parseRoadmap>;
 
         for (const slice of slices) {
           const isCompleteInDb = isClosedStatus(slice.status);
@@ -795,8 +816,7 @@ export function detectStaleRenders(basePath: string): StaleEntry[] {
       const planPath = resolveSliceFile(basePath, milestone.id, slice.id, "PLAN");
       if (planPath && existsSync(planPath)) {
         try {
-          const content = readFileSync(planPath, "utf-8");
-          const parsed = parsePlan(content);
+          const parsed = parseProjectionByIdentity(planPath, parsePlan) as ReturnType<typeof parsePlan>;
 
           for (const task of tasks) {
             const isDoneInDb = isClosedStatus(task.status);
@@ -891,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-filter.ts

@@ -1,7 +1,10 @@
 import { existsSync, readFileSync } from "node:fs";
+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";
 
 interface McpJsonFile {
@@ -81,40 +84,24 @@ 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[] {
   return discoverMcpServers(projectDir).map((server) => server.name);
 }
 
+export function discoverUserMcpServerNames(): string[] {
+  const userSettingsPath = resolve(homedir(), ".claude", "settings.json");
+  const userSettings = readJsonFile(userSettingsPath, true) as ClaudeSettingsFile | undefined;
+  return collectServerEntries(userSettings?.mcpServers).map((s) => s.name);
+}
+
 export function computeMcpDisallowedTools(
   modelId: string,
   mcpConfig: ClaudeCodeMcpConfig | undefined,
@@ -152,5 +139,5 @@ export function computeMcpDisallowedTools(
     blocked.delete(workflowServerName);
   }
 
-  return [...blocked].map((name) => `mcp__${name}__*`);
+  return [...blocked].map(toMcpWildcardToolName);
 }

package/src/resources/extensions/gsd/mcp-tool-name.ts

@@ -0,0 +1,30 @@
+// Project/App: gsd-pi
+// 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__";
+
+export interface ParsedMcpToolName {
+  serverName: string;
+  toolName: string;
+}
+
+export function parseMcpToolName(toolName: string): ParsedMcpToolName | null {
+  const parsed = parsePiAiMcpToolName(toolName);
+  return parsed ? { serverName: parsed.server, toolName: parsed.tool } : null;
+}
+
+export { stripMcpToolPrefix };
+
+export function toMcpToolName(serverName: string, toolName: string): string {
+  return `${MCP_TOOL_PREFIX}${serverName}__${toolName}`;
+}
+
+export function toMcpWildcardToolName(serverName: string): string {
+  return toMcpToolName(serverName, "*");
+}
+
+export function mcpToolMatchesBaseName(toolName: string, baseName: string): boolean {
+  return parseMcpToolName(toolName)?.toolName === baseName;
+}

package/src/resources/extensions/gsd/md-importer.ts

@@ -14,12 +14,12 @@ import {
   insertMilestone,
   insertSlice,
   insertTask,
-  openDatabase,
   transaction,
   updateMilestoneStatus,
   updateSliceStatus,
   _getAdapter,
 } from './gsd-db.js';
+import { openWorkflowDatabasePath } from './db-workspace.js';
 import {
   resolveGsdRootFile,
   resolveMilestoneFile,
@@ -641,7 +641,7 @@ export function migrateHierarchyToDb(basePath: string): {
         title: sliceEntry.title,
         status: sliceStatus,
         risk: sliceEntry.risk,
-        depends: sliceEntry.depends,
+        depends: (sliceEntry.depends ?? []).map(d => d.replace(/^\[|\]$/g, '')).filter(d => /^[A-Za-z0-9][A-Za-z0-9-]*$/.test(d)),
         demo: sliceEntry.demo,
         sequence: si + 1, // Preserve roadmap parse order (#3356)
         isSketch: sliceEntry.isSketch ?? false, // ADR-011: preserve the `[sketch]` flag on re-import
@@ -753,7 +753,7 @@ export function migrateFromMarkdown(gsdDir: string): {
 
   // Open DB if not already open
   if (!_getAdapter()) {
-    openDatabase(dbPath);
+    openWorkflowDatabasePath(dbPath);
   }
 
   let decisions = 0;

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

@@ -7,9 +7,10 @@ import { homedir } from "node:os";
 
 import { ensureDbOpen } from "../bootstrap/dynamic-tools.js";
 import { readCrashLock, isLockProcessAlive } from "../crash-recovery.js";
-import { closeDatabase } from "../gsd-db.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,14 +107,24 @@ export function assertMigrationHasSlices(preview: MigrationPreview): void {
 }
 
 function hasWorktreeState(targetRoot: string): boolean {
-  const worktreesDir = join(gsdRoot(targetRoot), "worktrees");
-  if (!existsSync(worktreesDir)) return false;
-  try {
-    return readdirSync(worktreesDir, { withFileTypes: true })
-      .some((entry) => entry.isDirectory() || entry.isFile());
-  } catch {
-    return true;
+  // Legacy container is probed via gsdRoot() (symlink-resolved) on purpose —
+  // migration targets may have .gsd in the external-state layout.
+  const containers = [
+    canonicalWorktreesDir(targetRoot),
+    join(gsdRoot(targetRoot), "worktrees"),
+  ];
+  for (const worktreesDir of containers) {
+    if (!existsSync(worktreesDir)) continue;
+    try {
+      if (readdirSync(worktreesDir, { withFileTypes: true })
+        .some((entry) => entry.isDirectory() || entry.isFile())) {
+        return true;
+      }
+    } catch {
+      return true;
+    }
   }
+  return false;
 }
 
 export async function assertMigrationTargetAvailable(targetRoot: string): Promise<void> {
@@ -144,6 +155,6 @@ export async function assertMigrationTargetAvailable(targetRoot: string): Promis
       );
     }
   } finally {
-    closeDatabase();
+    closeWorkflowDatabase();
   }
 }

package/src/resources/extensions/gsd/migration-auto-check.ts

@@ -6,8 +6,8 @@ import {
   getMilestoneSlices,
   getSliceTasks,
   isDbAvailable,
-  refreshOpenDatabaseFromDisk,
 } from "./gsd-db.js";
+import { refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 import { parsePlan, parseRoadmap } from "./parsers-legacy.js";
 import {
   milestonesDir,
@@ -39,6 +39,9 @@ interface HierarchyScan {
   milestones: Set<string>;
   slices: Set<string>;
   tasks: Set<string>;
+  // Markdown milestones whose dir has no ROADMAP (CONTEXT/CONTEXT-DRAFT only
+  // or empty). Always empty for DB scans.
+  milestonesWithoutRoadmap: Set<string>;
 }
 
 function zeroCounts(): HierarchyCounts {
@@ -46,7 +49,13 @@ function zeroCounts(): HierarchyCounts {
 }
 
 function emptyScan(): HierarchyScan {
-  return { counts: zeroCounts(), milestones: new Set(), slices: new Set(), tasks: new Set() };
+  return {
+    counts: zeroCounts(),
+    milestones: new Set(),
+    slices: new Set(),
+    tasks: new Set(),
+    milestonesWithoutRoadmap: new Set(),
+  };
 }
 
 function sameCounts(a: HierarchyCounts, b: HierarchyCounts): boolean {
@@ -109,7 +118,10 @@ export function scanMarkdownHierarchy(basePath: string): HierarchyScan {
     scan.milestones.add(milestoneId);
 
     const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
-    if (!roadmapPath || !existsSync(roadmapPath)) continue;
+    if (!roadmapPath || !existsSync(roadmapPath)) {
+      scan.milestonesWithoutRoadmap.add(milestoneId);
+      continue;
+    }
 
     const roadmap = parseRoadmap(readFileSync(roadmapPath, "utf-8"));
     scan.counts.slices += roadmap.slices.length;
@@ -164,7 +176,6 @@ export async function checkMarkdownHierarchyAgainstDb(
   basePath: string,
 ): Promise<MigrationAutoCheckResult> {
   const markdownScan = scanMarkdownHierarchy(basePath);
-  const markdown = markdownScan.counts;
 
   // Always open the DB before deciding. An empty markdown tree does NOT imply
   // an empty project — the DB may hold authoritative rows whose markdown was
@@ -179,11 +190,25 @@ export async function checkMarkdownHierarchyAgainstDb(
   // The markdown projections may have just been written by a workflow/MCP
   // server in another process. Reopen before comparing so startup does not
   // warn from a stale long-lived SQLite handle.
-  refreshOpenDatabaseFromDisk();
+  refreshWorkflowDatabaseFromDisk();
 
   const dbScan = scanDbHierarchy();
   const beforeDb = dbScan.counts;
 
+  // Discussion-phase scratch: a milestone dir with no ROADMAP and no DB row is
+  // a pre-registration discussion artifact (CONTEXT/CONTEXT-DRAFT only — the
+  // queued DB row is inserted only at discussion handoff). Treating it as
+  // drift would warn on every live discussion and recommend
+  // `/gsd recover --confirm`, an import that materializes abandoned-discussion
+  // dirs as ghost active milestones. Exclude such dirs from this comparison
+  // only; recover preflights use the raw scans and still see them.
+  for (const id of markdownScan.milestonesWithoutRoadmap) {
+    if (dbScan.milestones.has(id)) continue;
+    markdownScan.milestones.delete(id);
+    markdownScan.counts.milestones--;
+  }
+  const markdown = markdownScan.counts;
+
   const markdownEmpty = sameCounts(markdown, zeroCounts());
   const dbEmpty = sameCounts(beforeDb, zeroCounts());