@opengsd/gsd-pi 1.1.1-dev.b2556262 → 1.2.0-dev.4813ead6

package/src/resources/extensions/gsd/tools/workflow-tool-executors.ts

@@ -6,10 +6,11 @@ import { sanitizeCompleteMilestoneParams } from "../bootstrap/sanitize-complete-
 import { loadWriteGateSnapshot, shouldBlockContextArtifactSaveInSnapshot, shouldBlockRootArtifactSaveInSnapshot } from "../bootstrap/write-gate.js";
 import {
   getActiveRequirements,
-  insertMilestone,
+  getAllMilestones,
   getMilestone,
   getSliceStatusSummary,
   getSliceTaskCounts,
+  insertMilestone,
   insertAssessment,
   insertGateRun,
   readTransaction,
@@ -126,6 +127,111 @@ function registerProjectMilestoneSequence(content: string): string[] {
   return registered;
 }
 
+/** Minimal shape of a DB milestone row needed to re-render the sequence section. */
+interface MilestoneSeqRow {
+  id: string;
+  title: string;
+  status: string;
+  vision: string;
+}
+
+/**
+ * Best-effort recovery of the human one-liner for each milestone id from a
+ * (possibly malformed) Milestone Sequence body. Deliberately lenient: tolerates
+ * any separator the canonical MILESTONE_LINE_RE rejects (en-dash, " : ", a
+ * missing checkbox, etc.) so a model formatting slip does not discard the prose.
+ */
+function recoverMilestoneTails(sequenceBody: string): Map<string, string> {
+  const out = new Map<string, string>();
+  const lenient = /^\s*(?:-\s*)?(?:\[[ xX]\]\s*)?(M\d{3})\b\s*[:.\-–—]*\s*(.*)$/;
+  for (const rawLine of sequenceBody.split("\n")) {
+    const m = rawLine.match(lenient);
+    if (m) out.set(m[1], m[2].trim());
+  }
+  return out;
+}
+
+function firstSentence(text: string): string {
+  const trimmed = text.trim();
+  if (!trimmed) return "";
+  const idx = trimmed.search(/[.!?](\s|$)/);
+  return (idx >= 0 ? trimmed.slice(0, idx + 1) : trimmed).trim();
+}
+
+/** Render one canonical, parseable milestone line for the given DB row. */
+function renderMilestoneLine(m: MilestoneSeqRow, recoveredTail: string): string {
+  const done = m.status === "complete";
+  let oneLiner = recoveredTail;
+  // The recovered tail often still carries the title (e.g. "Foo — bar" or
+  // "Foo : bar"). Strip a leading repetition of the title, then any separator.
+  if (oneLiner.toLowerCase().startsWith(m.title.toLowerCase())) {
+    oneLiner = oneLiner.slice(m.title.length).replace(/^\s*[:.\-–—]+\s*/, "").trim();
+  } else {
+    const sep = oneLiner.match(/\s+(?:—|–|--|-|:)\s+/);
+    if (sep && sep.index !== undefined) oneLiner = oneLiner.slice(sep.index + sep[0].length).trim();
+  }
+  // MILESTONE_LINE_RE requires non-empty prose after the separator.
+  if (!oneLiner) oneLiner = firstSentence(m.vision) || (done ? "Completed." : "Planned.");
+  return `- [${done ? "x" : " "}] ${m.id}: ${m.title} — ${oneLiner}`;
+}
+
+/**
+ * Rebuild the "## Milestone Sequence" section from authoritative DB rows when a
+ * model-authored PROJECT.md projection parsed to zero milestone lines but the DB
+ * already holds milestones. The DB is the source of truth (markdown is a
+ * projection), so this repairs the projection rather than failing the save.
+ * Preserves a leading HTML comment in the section and recovers one-liners
+ * best-effort. The returned content parses cleanly under MILESTONE_LINE_RE.
+ */
+function rebuildMilestoneSequenceSection(content: string, milestones: MilestoneSeqRow[]): string {
+  const lines = content.split("\n");
+  const headerIdx = lines.findIndex(l => /^##\s+Milestone Sequence\s*$/.test(l));
+
+  const canonicalLines = (() => {
+    // Recover tails from the existing (malformed) body when the section exists.
+    let body = "";
+    if (headerIdx !== -1) {
+      let end = headerIdx + 1;
+      while (end < lines.length && !/^##\s+/.test(lines[end])) end++;
+      body = lines.slice(headerIdx + 1, end).join("\n");
+    }
+    const tails = recoverMilestoneTails(body);
+    return milestones.map(m => renderMilestoneLine(m, tails.get(m.id) ?? ""));
+  })();
+
+  if (headerIdx === -1) {
+    // No section at all — append a fresh, canonical one.
+    const sep = content.endsWith("\n") ? "" : "\n";
+    return `${content}${sep}\n## Milestone Sequence\n\n${canonicalLines.join("\n")}\n`;
+  }
+
+  let bodyEnd = headerIdx + 1;
+  while (bodyEnd < lines.length && !/^##\s+/.test(lines[bodyEnd])) bodyEnd++;
+  const existingBody = lines.slice(headerIdx + 1, bodyEnd);
+
+  // Preserve a contiguous leading HTML comment block (the "Check off…" hint).
+  let i = 0;
+  while (i < existingBody.length && existingBody[i].trim() === "") i++;
+  const preserved: string[] = [];
+  if (i < existingBody.length && existingBody[i].trim().startsWith("<!--")) {
+    while (i < existingBody.length) {
+      preserved.push(existingBody[i]);
+      const closed = existingBody[i].includes("-->");
+      i++;
+      if (closed) break;
+    }
+  }
+
+  return [
+    ...lines.slice(0, headerIdx + 1),
+    "",
+    ...(preserved.length ? [...preserved, ""] : []),
+    ...canonicalLines,
+    "",
+    ...lines.slice(bodyEnd),
+  ].join("\n");
+}
+
 async function mirrorArtifactToActiveWorktreeProjection(
   basePath: string,
   relativePath: string,
@@ -260,6 +366,7 @@ export async function executeSummarySave(
     await mirrorArtifactToActiveWorktreeProjection(basePath, relativePath, contentToSave);
 
     let registeredMilestones: string[] = [];
+    let milestoneSequenceSelfHealed = false;
     if (params.artifact_type === "PROJECT") {
       try {
         registeredMilestones = registerProjectMilestoneSequence(contentToSave);
@@ -294,29 +401,83 @@ export async function executeSummarySave(
         };
       }
       if (registeredMilestones.length === 0) {
-        logError("tool", `gsd_summary_save: PROJECT.md saved to ${relativePath} but parsed zero milestones — registration produced no DB rows`, {
+        const existingMilestones = getAllMilestones();
+        if (existingMilestones.length === 0) {
+          // Genuine first-save failure: no milestones parsed AND none in the DB.
+          // /gsd really would report "No Active Milestone" — hard-fail so the
+          // caller rewrites the sequence before proceeding.
+          logError("tool", `gsd_summary_save: PROJECT.md saved to ${relativePath} but parsed zero milestones — registration produced no DB rows`, {
+            tool: "gsd_summary_save",
+          });
+          // PROJECT.md was persisted; invalidate so subsequent reads see the new
+          // artifacts row even though no milestones registered.
+          invalidateStateCache();
+          return {
+            content: [{
+              type: "text",
+              text:
+                `Error: PROJECT.md was saved to ${relativePath} but contains zero parseable milestone lines, ` +
+                `so no milestones were registered in the DB. /gsd will report "No Active Milestone". ` +
+                `Rewrite PROJECT.md so the "Milestone Sequence" section uses canonical lines: ` +
+                `\`- [ ] M001: <Title> — <One-liner>\` (em-dash, double-dash \`--\`, or single-dash \`-\` separator), then re-call gsd_summary_save(PROJECT).`,
+            }],
+            details: {
+              operation: "save_summary",
+              path: relativePath,
+              artifact_type: params.artifact_type,
+              error: "milestone_registration_empty_parse",
+            },
+            isError: true,
+          };
+        }
+
+        // Existing DB rows mean this is projection drift, not data loss. Rebuild
+        // the section from DB state and re-persist a parseable projection.
+        logWarning("tool", `gsd_summary_save: PROJECT.md parsed zero milestone lines but DB has ${existingMilestones.length} — rebuilding Milestone Sequence from DB (projection self-heal)`, {
           tool: "gsd_summary_save",
+          path: relativePath,
         });
-        // PROJECT.md was persisted; invalidate so subsequent reads see the new
-        // artifacts row even though no milestones registered.
-        invalidateStateCache();
-        return {
-          content: [{
-            type: "text",
-            text:
-              `Error: PROJECT.md was saved to ${relativePath} but contains zero parseable milestone lines, ` +
-              `so no milestones were registered in the DB. /gsd will report "No Active Milestone". ` +
-              `Rewrite PROJECT.md so the "Milestone Sequence" section uses canonical lines: ` +
-              `\`- [ ] M001: <Title> — <One-liner>\` (em-dash, double-dash \`--\`, or single-dash \`-\` separator), then re-call gsd_summary_save(PROJECT).`,
-          }],
-          details: {
-            operation: "save_summary",
+        try {
+          const healed = rebuildMilestoneSequenceSection(contentToSave, existingMilestones);
+          await saveArtifactToDb(
+            { path: relativePath, artifact_type: params.artifact_type, content: healed },
+            basePath,
+          );
+          await mirrorArtifactToActiveWorktreeProjection(basePath, relativePath, healed);
+          const healedRegisteredMilestones = registerProjectMilestoneSequence(healed);
+          if (healedRegisteredMilestones.length === 0) {
+            throw new Error("self-healed PROJECT.md still parsed zero milestone lines");
+          }
+          registeredMilestones = healedRegisteredMilestones;
+          milestoneSequenceSelfHealed = true;
+        } catch (healErr) {
+          const msg = healErr instanceof Error ? healErr.message : String(healErr);
+          logError("tool", `gsd_summary_save: Milestone Sequence self-heal failed: ${msg}`, {
+            tool: "gsd_summary_save",
             path: relativePath,
-            artifact_type: params.artifact_type,
-            error: "milestone_registration_empty_parse",
-          },
-          isError: true,
-        };
+            error: msg,
+          });
+          invalidateStateCache();
+          return {
+            content: [{
+              type: "text",
+              text:
+                `Error: PROJECT.md was saved to ${relativePath} but contains zero parseable milestone lines, ` +
+                `and automatic DB-backed Milestone Sequence repair failed: ${msg}. ` +
+                `Rewrite PROJECT.md so the "Milestone Sequence" section uses canonical lines: ` +
+                `\`- [ ] M001: <Title> — <One-liner>\`, then re-call gsd_summary_save(PROJECT).`,
+            }],
+            details: {
+              operation: "save_summary",
+              path: relativePath,
+              artifact_type: params.artifact_type,
+              error: "milestone_sequence_self_heal_failed",
+              self_heal_error: msg,
+            },
+            isError: true,
+          };
+        }
+        invalidateStateCache();
       }
     }
 
@@ -339,6 +500,7 @@ export async function executeSummarySave(
         artifact_type: params.artifact_type,
         content_source: contentSource,
         ...(registeredMilestones.length > 0 ? { registeredMilestones } : {}),
+        ...(milestoneSequenceSelfHealed ? { milestoneSequenceSelfHealed: true } : {}),
       },
     };
   } catch (err) {

package/src/resources/extensions/gsd/uat-policy.ts

@@ -4,6 +4,7 @@
 import { extractUatType } from "./files.js";
 import type { UatType } from "./files.js";
 import { hasBrowserRequiredText } from "./browser-evidence.js";
+import { parseMcpToolName } from "./mcp-tool-name.js";
 
 export type { UatType } from "./files.js";
 
@@ -122,31 +123,39 @@ export function uatTypeIncludesBrowser(uatType: string | undefined): boolean {
   return isUatType(uatType) && UAT_MODE_POLICIES[uatType].browserTools;
 }
 
-function canonicalPresentedToolName(toolName: string): string {
-  if (!toolName.startsWith("mcp__")) return toolName;
-  const toolSeparator = toolName.indexOf("__", "mcp__".length);
-  return toolSeparator >= 0 ? toolName.slice(toolSeparator + 2) : toolName;
-}
-
 export function isUatBrowserToolName(toolName: string): boolean {
-  return canonicalPresentedToolName(toolName).startsWith("browser_");
+  const parsed = parseMcpToolName(toolName);
+  const canonicalName = parsed?.toolName ?? toolName;
+  if (canonicalName.startsWith("browser_")) return true;
+  return parsed?.toolName === "*" && parsed.serverName.toLowerCase().includes("browser");
 }
 
 export function hasUatBrowserToolSurface(activeTools: readonly string[] | undefined): boolean {
   return Array.isArray(activeTools) && activeTools.some(isUatBrowserToolName);
 }
 
+export function resolveUatBrowserToolSurface(options: {
+  activeTools: readonly string[] | undefined;
+  registeredTools?: readonly string[] | undefined;
+}): readonly string[] | undefined {
+  const surfaces = [options.activeTools, options.registeredTools].filter(Array.isArray);
+  if (surfaces.length === 0) return undefined;
+  return [...new Set(surfaces.flat())];
+}
+
 export function getUatBrowserToolSupportError(options: {
   uatType: UatType;
   activeTools: readonly string[] | undefined;
+  registeredTools?: readonly string[] | undefined;
   milestoneId: string;
   sliceId: string;
 }): string | null {
   if (!uatTypeIncludesBrowser(options.uatType)) return null;
-  if (!Array.isArray(options.activeTools)) return null;
-  if (hasUatBrowserToolSurface(options.activeTools)) return null;
+  const toolSurface = resolveUatBrowserToolSurface(options);
+  if (!toolSurface) return null;
+  if (hasUatBrowserToolSurface(toolSurface)) return null;
 
-  return `Cannot dispatch browser-backed run-uat for ${options.milestoneId}/${options.sliceId}: UAT mode "${options.uatType}" requires browser tools, but the active tool surface has none. Enable browser tools or change the UAT to a runtime-executable Playwright command, then rerun /gsd auto.`;
+  return `Cannot dispatch browser-backed run-uat for ${options.milestoneId}/${options.sliceId}: UAT mode "${options.uatType}" requires browser tools, but the run-uat tool surface has none. Enable browser tools or change the UAT to a runtime-executable Playwright command, then rerun /gsd auto.`;
 }
 
 export function isPartialEligibleUatType(uatType: UatType | undefined): boolean {

package/src/resources/extensions/gsd/uat-run.ts

@@ -103,7 +103,7 @@ function mergeBlockedTools(
 ): UatPresentationInput["blockedTools"] {
   const merged = new Map<string, { name: string; reason: string }>();
   for (const entry of [...(current ?? []), ...canonical]) {
-    merged.set(canonicalWorkflowToolName(parseMcpToolName(entry.name)?.tool ?? entry.name), entry);
+    merged.set(canonicalWorkflowToolName(parseMcpToolName(entry.name)?.toolName ?? entry.name), entry);
   }
   return [...merged.values()];
 }
@@ -299,22 +299,18 @@ function quoteToolNames(toolNames: readonly string[]): string {
 }
 
 function validateCanonicalPresentation(params: UatResultSaveParams): string | null {
-  const aliasHints: Record<string, string> = {
-    gsd_save_summary: "gsd_summary_save",
-    gsd_complete_task: "gsd_task_complete",
-    gsd_complete_slice: "gsd_slice_complete",
-    gsd_milestone_complete: "gsd_complete_milestone",
-  };
   const errors: string[] = [];
   for (const toolName of params.presentation.presentedTools) {
-    const baseName = parseMcpToolName(toolName)?.tool ?? toolName;
-    const canonical = aliasHints[baseName];
-    if (canonical) errors.push(`presentation tool "${toolName}" uses an alias; use canonical "${canonical}"`);
+    const baseName = parseMcpToolName(toolName)?.toolName ?? toolName;
+    const canonical = canonicalWorkflowToolName(baseName);
+    if (canonical !== baseName) {
+      errors.push(`presentation tool "${toolName}" uses an alias; use canonical "${canonical}"`);
+    }
   }
 
   const presentedCanonical = new Set(
     params.presentation.presentedTools.map((toolName) =>
-      canonicalWorkflowToolName(parseMcpToolName(toolName)?.tool ?? toolName)
+      canonicalWorkflowToolName(parseMcpToolName(toolName)?.toolName ?? toolName)
     ),
   );
   const missingRequiredTools = RUN_UAT_WORKFLOW_TOOL_NAMES.filter(
@@ -329,11 +325,11 @@ function validateCanonicalPresentation(params: UatResultSaveParams): string | nu
   const forbiddenCanonical = new Set(
     RUN_UAT_FORBIDDEN_TOOL_NAMES
       .filter((toolName) => !toolName.includes("*"))
-      .map((toolName) => canonicalWorkflowToolName(parseMcpToolName(toolName)?.tool ?? toolName)),
+      .map((toolName) => canonicalWorkflowToolName(parseMcpToolName(toolName)?.toolName ?? toolName)),
   );
   const forbiddenPresentedTools: string[] = [];
   for (const toolName of params.presentation.presentedTools) {
-    const canonical = canonicalWorkflowToolName(parseMcpToolName(toolName)?.tool ?? toolName);
+    const canonical = canonicalWorkflowToolName(parseMcpToolName(toolName)?.toolName ?? toolName);
     if (toolName === "mcp__gsd-workflow__*" || forbiddenCanonical.has(canonical)) {
       forbiddenPresentedTools.push(toolName);
     }
@@ -346,7 +342,7 @@ function validateCanonicalPresentation(params: UatResultSaveParams): string | nu
 
   const blockedCanonical = new Set(
     params.presentation.blockedTools.map((entry) =>
-      canonicalWorkflowToolName(parseMcpToolName(entry.name)?.tool ?? entry.name)
+      canonicalWorkflowToolName(parseMcpToolName(entry.name)?.toolName ?? entry.name)
     ),
   );
   const missingBlockedTools = ["gsd_exec", "gsd_summary_save", "gsd_save_gate_result"].filter(

package/src/resources/extensions/gsd/unit-context-composer.ts

@@ -45,6 +45,7 @@ import {
   type ContextModePolicy,
   type UnitContextManifest,
 } from "./unit-context-manifest.js";
+import type { UnitPromptContextContract } from "./tool-contract.js";
 
 /**
  * Async function mapping an artifact key to its inlined-content string,
@@ -195,8 +196,32 @@ export interface ComposedUnitContext {
   readonly inline: string;
 }
 
+export type UnitContextBlockMode = "prepend" | "inline" | "excerpt" | "computed";
+
+export interface ComposedUnitContextBlock {
+  readonly key: string;
+  readonly mode: UnitContextBlockMode;
+  readonly body: string;
+}
+
+export interface ComposedContractedUnitContext extends ComposedUnitContext {
+  readonly blocks: readonly ComposedUnitContextBlock[];
+  readonly onDemand: readonly ArtifactKey[];
+}
+
 const SECTION_SEPARATOR = "\n\n---\n\n";
 
+interface UnitContextCompositionContract {
+  readonly unitType: string;
+  readonly artifacts: {
+    readonly inline: readonly ArtifactKey[];
+    readonly excerpt: readonly ArtifactKey[];
+    readonly onDemand: readonly ArtifactKey[];
+    readonly computed: readonly ComputedArtifactId[];
+    readonly prepend: readonly ComputedArtifactId[];
+  };
+}
+
 /**
  * Compose all manifest-declared context for a unit type using the v2
  * surface. Walks `prepend` first (computed-only), then the `inline` list
@@ -220,36 +245,73 @@ export async function composeUnitContext(
   const manifest: UnitContextManifest | null = resolveManifest(unitType);
   if (!manifest) return { prepend: "", inline: "" };
 
-  // Single-source `unitType`: the manifest is resolved against the
+  const composed = await composeDeclaredUnitContext({
+    unitType,
+    artifacts: {
+      inline: manifest.artifacts.inline,
+      excerpt: manifest.artifacts.excerpt,
+      onDemand: manifest.artifacts.onDemand,
+      computed: manifest.artifacts.computed ?? [],
+      prepend: manifest.prepend ?? [],
+    },
+  }, opts);
+  return {
+    prepend: composed.prepend,
+    inline: composed.inline,
+  };
+}
+
+export async function composeContractedUnitContext(
+  contract: UnitPromptContextContract,
+  opts: ComposeUnitContextOptions,
+): Promise<ComposedContractedUnitContext> {
+  return composeDeclaredUnitContext(contract, opts);
+}
+
+async function composeDeclaredUnitContext(
+  contract: UnitContextCompositionContract,
+  opts: ComposeUnitContextOptions,
+): Promise<ComposedContractedUnitContext> {
+  // Single-source `unitType`: contract/manifest selection comes from the
   // function arg, but computed builders read it from `base.unitType`.
-  // If those ever diverge (caller passes one type to composeUnitContext
-  // but a different one in opts.base), the composer would silently
-  // mix one unit's manifest with another unit's computed context.
-  // Normalize here so the composer dispatches a consistent identity
-  // through to every builder.
+  // Normalize here so every builder sees the same Unit identity.
   const normalizedOpts: ComposeUnitContextOptions = {
     ...opts,
-    base: { ...opts.base, unitType },
+    base: { ...opts.base, unitType: contract.unitType },
   };
 
-  const prependBlocks = await runComputed(manifest.prepend ?? [], normalizedOpts);
-  const inlineBlocks: string[] = [];
+  const prependBlocks = await runComputedBlocks(
+    contract.artifacts.prepend,
+    normalizedOpts,
+    "prepend",
+  );
+  const inlineBlocks: ComposedUnitContextBlock[] = [];
 
-  for (const key of manifest.artifacts.inline) {
+  for (const key of contract.artifacts.inline) {
     if (!normalizedOpts.resolveArtifact) break;
     const body = await normalizedOpts.resolveArtifact(key);
-    if (body && body.length > 0) inlineBlocks.push(body);
+    if (body && body.length > 0) {
+      inlineBlocks.push({ key, mode: "inline", body });
+    }
   }
-  for (const key of manifest.artifacts.excerpt) {
+  for (const key of contract.artifacts.excerpt) {
     if (!normalizedOpts.resolveExcerpt) break;
     const body = await normalizedOpts.resolveExcerpt(key);
-    if (body && body.length > 0) inlineBlocks.push(body);
+    if (body && body.length > 0) {
+      inlineBlocks.push({ key, mode: "excerpt", body });
+    }
   }
-  inlineBlocks.push(...await runComputed(manifest.artifacts.computed ?? [], normalizedOpts));
+  inlineBlocks.push(...await runComputedBlocks(
+    contract.artifacts.computed,
+    normalizedOpts,
+    "computed",
+  ));
 
   return {
-    prepend: prependBlocks.join(SECTION_SEPARATOR),
-    inline: inlineBlocks.join(SECTION_SEPARATOR),
+    prepend: prependBlocks.map((block) => block.body).join(SECTION_SEPARATOR),
+    inline: inlineBlocks.map((block) => block.body).join(SECTION_SEPARATOR),
+    blocks: [...prependBlocks, ...inlineBlocks],
+    onDemand: contract.artifacts.onDemand,
   };
 }
 
@@ -258,10 +320,11 @@ export async function composeUnitContext(
  * Missing registry entries (manifest declares the id but caller didn't
  * register it) are skipped silently — see composeUnitContext rationale.
  */
-async function runComputed(
+async function runComputedBlocks(
   ids: readonly ComputedArtifactId[],
   opts: ComposeUnitContextOptions,
-): Promise<string[]> {
+  mode: Extract<UnitContextBlockMode, "prepend" | "computed">,
+): Promise<ComposedUnitContextBlock[]> {
   if (ids.length === 0 || !opts.computed) return [];
   // Type safety lives at the registration boundary (caller-supplied
   // `computed` is typed against ComputedArtifactInputs[K] per id). Inside
@@ -274,12 +337,14 @@ async function runComputed(
     inputs: unknown;
   };
   const registry = opts.computed as Record<string, AnyEntry | undefined>;
-  const out: string[] = [];
+  const out: ComposedUnitContextBlock[] = [];
   for (const id of ids) {
     const entry = registry[id];
     if (!entry) continue;
     const body = await entry.build(entry.inputs, opts.base);
-    if (body && body.length > 0) out.push(body);
+    if (body && body.length > 0) {
+      out.push({ key: id, mode, body });
+    }
   }
   return out;
 }

package/src/resources/extensions/gsd/unit-runtime.ts

@@ -10,7 +10,8 @@ import {
 } from "./paths.js";
 import { loadFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.js";
 import { parseUnitId } from "./unit-id.js";
-import { getTask, isDbAvailable, refreshOpenDatabaseFromDisk } from "./gsd-db.js";
+import { getTask, isDbAvailable } from "./gsd-db.js";
+import { refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 import { isClosedStatus } from "./status-guards.js";
 
 // Per-record advisory lock — prevents read-modify-write races between
@@ -218,7 +219,7 @@ export async function inspectExecuteTaskDurability(
   const nextActionAdvanced = !new RegExp(`Execute ${tid}\\b`).test(stateContent);
   let dbComplete = false;
   if (isDbAvailable()) {
-    refreshOpenDatabaseFromDisk();
+    refreshWorkflowDatabaseFromDisk();
     const task = getTask(mid, sid, tid);
     dbComplete = !!task && isClosedStatus(task.status);
   }

package/src/resources/extensions/gsd/unit-tool-contracts.ts

@@ -71,6 +71,7 @@ export const UNIT_TOOL_CONTRACTS: Record<string, UnitToolSurfaceContract> = {
       "gsd_milestone_generate_id",
     ],
     requiredWorkflowTools: [
+      "ask_user_questions",
       "gsd_summary_save",
       "gsd_requirement_save",
       "gsd_requirement_update",
@@ -80,7 +81,7 @@ export const UNIT_TOOL_CONTRACTS: Record<string, UnitToolSurfaceContract> = {
   },
   "discuss-slice": {
     allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
-    requiredWorkflowTools: ["gsd_summary_save"],
+    requiredWorkflowTools: ["ask_user_questions", "gsd_summary_save"],
   },
   "validate-milestone": {
     allowedGsdTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap", "subagent"],

package/src/resources/extensions/gsd/user-input-boundary.ts

@@ -23,7 +23,7 @@ const APPROVAL_CHANGE_QUESTION_RE =
 const RESEARCH_DECISION_QUESTION_RE =
   /\b(?:research|skip)\b/i;
 
-function extractTextFromMessage(msg: unknown): string {
+function extractVisibleTextFromMessage(msg: unknown): string {
   if (!msg || typeof msg !== "object") return "";
   const content = (msg as { content?: unknown }).content;
   if (typeof content === "string") return content;
@@ -35,6 +35,26 @@ function extractTextFromMessage(msg: unknown): string {
     if (typed.type === "text" && typeof typed.text === "string") {
       parts.push(typed.text);
     }
+    // thinking blocks intentionally excluded — they are internal reasoning, not user-visible
+  }
+  return parts.join("\n");
+}
+
+function extractTextFromMessage(msg: unknown): string {
+  if (!msg || typeof msg !== "object") return "";
+  const content = (msg as { content?: unknown }).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;
+    const typed = block as { type?: unknown; text?: unknown; thinking?: unknown };
+    if (typed.type === "text" && typeof typed.text === "string") {
+      parts.push(typed.text);
+    }
+    if (typed.type === "thinking" && typeof typed.thinking === "string") {
+      parts.push(typed.thinking);
+    }
   }
   return parts.join("\n");
 }
@@ -51,12 +71,24 @@ export function lastAssistantText(messages: unknown[] | null | undefined): strin
   return "";
 }
 
+function lastAssistantVisibleText(messages: unknown[] | null | undefined): string {
+  if (!Array.isArray(messages)) return "";
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (!msg || typeof msg !== "object") continue;
+    if ((msg as { role?: unknown }).role !== "assistant") continue;
+    const text = extractVisibleTextFromMessage(msg).trim();
+    if (text) return text;
+  }
+  return "";
+}
+
 function anyMessageMatches(messages: unknown[] | undefined, pattern: RegExp): boolean {
   if (!Array.isArray(messages)) return false;
   return messages.some((msg) => {
     if (!msg || typeof msg !== "object") return false;
     if ((msg as { role?: unknown }).role === "user") return false;
-    return pattern.test(extractTextFromMessage(msg));
+    return pattern.test(extractVisibleTextFromMessage(msg));
   });
 }
 
@@ -134,7 +166,7 @@ export function isExplicitApprovalResponse(
 export function isAwaitingUserInput(messages: unknown[] | undefined): boolean {
   if (anyMessageMatches(messages, /ask_user_questions was cancelled before receiving a response/i)) return true;
   if (anyMessageMatches(messages, REMOTE_QUESTION_FAILURE_RE)) return true;
-  const text = lastAssistantText(messages);
+  const text = lastAssistantVisibleText(messages);
   if (!text) return false;
   if (APPROVAL_WAIT_RE.test(text)) return true;
   const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
@@ -145,12 +177,30 @@ export function isAwaitingUserInput(messages: unknown[] | undefined): boolean {
 export function isAwaitingApprovalBoundary(messages: unknown[] | undefined): boolean {
   if (anyMessageMatches(messages, /ask_user_questions was cancelled before receiving a response/i)) return true;
   if (anyMessageMatches(messages, REMOTE_QUESTION_FAILURE_RE)) return true;
-  const text = lastAssistantText(messages);
+  const text = lastAssistantVisibleText(messages);
   if (!text) return false;
   if (APPROVAL_WAIT_RE.test(text)) return true;
   return hasApprovalQuestion(text);
 }
 
+/** True when an assistant message already has an in-flight ask_user_questions tool call. */
+export function messageHasPendingAskUserQuestionsTool(message: unknown): boolean {
+  if (!message || typeof message !== "object") return false;
+  const content = (message as { content?: unknown }).content;
+  if (!Array.isArray(content)) return false;
+  return content.some((block) => {
+    if (!block || typeof block !== "object") return false;
+    // Claude Code marks completion by attaching externalResult, not by setting state.
+    // Streaming blocks often carry no state; serverToolUse is the claude-code-cli MCP path.
+    const tool = block as { type?: string; name?: string; state?: string; externalResult?: unknown };
+    if (tool.type !== "toolCall" && tool.type !== "serverToolUse") return false;
+    const name = String(tool.name ?? "").toLowerCase();
+    if (!name.includes("ask_user_questions")) return false;
+    if (tool.externalResult !== undefined) return false;
+    return tool.state !== "completed" && tool.state !== "done";
+  });
+}
+
 export function shouldPauseForUserApprovalQuestion(
   unitType: string | undefined,
   messages: unknown[] | undefined,
@@ -158,7 +208,7 @@ export function shouldPauseForUserApprovalQuestion(
   if (!unitType || !USER_APPROVAL_UNIT_TYPES.has(unitType)) return false;
   if (anyMessageMatches(messages, /ask_user_questions was cancelled before receiving a response/i)) return true;
   if (anyMessageMatches(messages, REMOTE_QUESTION_FAILURE_RE)) return true;
-  const text = lastAssistantText(messages);
+  const text = lastAssistantVisibleText(messages);
   if (!text) return false;
   if (APPROVAL_WAIT_RE.test(text)) return true;
   if (unitType === "research-decision") return hasResearchDecisionQuestion(text);