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

package/src/resources/extensions/gsd/tests/single-writer-invariant.test.ts

@@ -74,6 +74,29 @@ const PREPARE_WRITE_RE = /\.prepare\s*\(\s*[`'"][^`'"]*\b(INSERT|UPDATE|DELETE|R
 
 // Match .exec("... INSERT|UPDATE|DELETE|REPLACE ...") or raw BEGIN/COMMIT/ROLLBACK.
 const EXEC_WRITE_RE = /\.exec\s*\(\s*[`'"][^`'"]*\b(INSERT|UPDATE|DELETE|REPLACE|BEGIN|COMMIT|ROLLBACK)\b/i;
+const DB_WORKSPACE_MECHANICS = new Set([
+  "backupDatabaseSnapshot",
+  "checkpointDatabase",
+  "closeAllDatabases",
+  "closeDatabase",
+  "closeDatabaseByWorkspace",
+  "getDbPath",
+  "getDbProvider",
+  "getDbStatus",
+  "openDatabase",
+  "openDatabaseByScope",
+  "openDatabaseByWorkspace",
+  "refreshOpenDatabaseFromDisk",
+  "vacuumDatabase",
+  "wasDbOpenAttempted",
+]);
+
+function importNames(specifierBlock: string): string[] {
+  return specifierBlock
+    .split(",")
+    .map((name) => name.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0]?.trim() ?? "")
+    .filter(Boolean);
+}
 
 test("no module outside gsd-db.ts issues raw write SQL against the engine DB", () => {
   const files = walkTsFiles(gsdDir);
@@ -166,6 +189,84 @@ test("gsd-db.ts exports the expected single-writer wrappers", async () => {
   }
 });
 
+test("DB Workspace Interface owns database open-state and maintenance calls", async () => {
+  const workspaceDb = await import("../db-workspace.js");
+
+  const expected = [
+    "backupWorkflowDatabaseSnapshot",
+    "checkpointWorkflowDatabase",
+    "closeAllWorkflowDatabases",
+    "closeWorkflowDatabase",
+    "closeWorkflowDatabaseByWorkspace",
+    "getWorkflowDatabasePath",
+    "getWorkflowDatabaseProvider",
+    "getWorkflowDatabaseStatus",
+    "isWorkflowDatabaseOpen",
+    "openExistingWorkflowDatabase",
+    "openWorkflowDatabase",
+    "openWorkflowDatabaseByScope",
+    "openWorkflowDatabaseByWorkspace",
+    "openWorkflowDatabasePath",
+    "refreshWorkflowDatabaseFromDisk",
+    "resolveProjectRootDbPath",
+    "resolveWorkflowDatabaseLocation",
+    "vacuumWorkflowDatabase",
+    "wasWorkflowDatabaseOpenAttempted",
+  ];
+
+  for (const name of expected) {
+    assert.ok(
+      typeof (workspaceDb as Record<string, unknown>)[name] === "function",
+      `db-workspace.ts must export ${name} as a function`,
+    );
+  }
+});
+
+test("production modules do not import DB open-state mechanics from gsd-db.ts", () => {
+  const files = walkTsFiles(gsdDir);
+  const violations: Violation[] = [];
+  const staticImportRe = /import\s*\{([\s\S]*?)\}\s*from\s*["'][^"']*gsd-db\.(?:js|ts)["']/g;
+  const dynamicImportRe = /(?:const|let)\s*\{([\s\S]*?)\}\s*=\s*await\s+import\(["'][^"']*gsd-db\.(?:js|ts)["']\)/g;
+
+  for (const abs of files) {
+    const rel = relative(gsdDir, abs);
+    if (rel === "gsd-db.ts" || rel === "db-workspace.ts") continue;
+
+    let content: string;
+    try {
+      content = readFileSync(abs, "utf-8");
+    } catch {
+      continue;
+    }
+
+    for (const re of [staticImportRe, dynamicImportRe]) {
+      re.lastIndex = 0;
+      let match: RegExpExecArray | null;
+      while ((match = re.exec(content)) !== null) {
+        const leaked = importNames(match[1] ?? "").filter((name) => DB_WORKSPACE_MECHANICS.has(name));
+        if (leaked.length === 0) continue;
+        violations.push({
+          file: rel,
+          line: content.slice(0, match.index).split("\n").length,
+          snippet: leaked.join(", "),
+          kind: "db-workspace-leak",
+        });
+      }
+    }
+  }
+
+  if (violations.length > 0) {
+    const lines = violations.map(
+      (v) => `  ${v.file}:${v.line} [${v.kind}] — ${v.snippet}`,
+    );
+    assert.fail(
+      `Found ${violations.length} DB open-state import(s) from gsd-db.ts:\n` +
+        lines.join("\n") +
+        "\n\nImport these through db-workspace.ts so gsd-db.ts stays the single-writer implementation, not the caller-facing DB Workspace Interface.",
+    );
+  }
+});
+
 test("the invariant test touches every .ts module under gsd/ (sanity check)", () => {
   const files = walkTsFiles(gsdDir);
   // Rough sanity: ensure we're not accidentally walking an empty tree
@@ -177,4 +278,3 @@ test("the invariant test touches every .ts module under gsd/ (sanity check)", ()
   assert.ok(rels.includes("memory-store.ts"), "walker must include memory-store.ts");
   assert.ok(rels.includes("workflow-manifest.ts"), "walker must include workflow-manifest.ts");
 });
-

package/src/resources/extensions/gsd/tests/stale-queued-milestone.test.ts

@@ -74,6 +74,33 @@ describe("stale queued milestone selection (#3470)", () => {
     assert.equal(m070Entry!.status, "active", "M070 should be active in registry");
   });
 
+  test("queued milestone with roadmap projection but no DB slices stays deferred", async () => {
+    base = createFixtureBase();
+    openDatabase(":memory:");
+
+    // M068: queued shell with a stale ROADMAP projection, but no CONTEXT and no DB slices.
+    insertMilestone({ id: "M068", title: "Queued Roadmap Projection", status: "queued" });
+    writeFile(base, "milestones/M068/M068-ROADMAP.md", "# M068\n\n## Slices\n\n- [ ] **S99: Stale Slice**");
+
+    // M070: real active milestone — context, roadmap, slices, tasks
+    insertMilestone({ id: "M070", title: "Real Active", status: "active" });
+    insertSlice({ id: "S01", milestoneId: "M070", title: "Slice One", status: "active", risk: "low", depends: [] });
+    insertTask({ id: "T01", sliceId: "S01", milestoneId: "M070", title: "Task One", status: "pending" });
+
+    writeFile(base, "milestones/M070/M070-CONTEXT.md", "# M070: Real Active\n\nThis is the real milestone.");
+    writeFile(base, "milestones/M070/M070-ROADMAP.md", "# M070: Real Active\n\n## Slices\n\n- [ ] **S01: Slice One**");
+    writeFile(base, "milestones/M070/slices/S01/S01-PLAN.md", "# S01: Slice One\n\n## Tasks\n\n- [ ] **T01: Task One**");
+
+    invalidateStateCache();
+    const state = await deriveStateFromDb(base);
+
+    assert.equal(state.activeMilestone?.id, "M070", "ROADMAP-only queued milestone must not block active M070");
+
+    const m068Entry = state.registry.find((e: any) => e.id === "M068");
+    assert.ok(m068Entry, "M068 should still appear in registry");
+    assert.equal(m068Entry!.status, "pending", "M068 should stay pending without CONTEXT or DB slices");
+  });
+
   test("queued milestone WITH context file can still be selected as active", async () => {
     base = createFixtureBase();
     openDatabase(":memory:");

package/src/resources/extensions/gsd/tests/start-auto-detached.test.ts

@@ -364,6 +364,7 @@ test("effective unit isolation follows degraded branch fallback", () => {
 
 test("discuss-to-auto handoff defaults to step mode unless explicitly disabled", () => {
   const guidedFlowSrc = readGsdFile("guided-flow.ts");
+  const discussionHandoffSrc = readGsdFile("discussion-handoff.ts");
   const workflowSrc = readGsdFile("commands/handlers/workflow.ts");
 
   assert.ok(
@@ -371,7 +372,7 @@ test("discuss-to-auto handoff defaults to step mode unless explicitly disabled",
     "guided-flow must not hardcode step: false on pending auto-start entries",
   );
   assert.match(
-    guidedFlowSrc,
+    discussionHandoffSrc,
     /scheduleAutoStartAfterIdle\(ctx, pi, basePath, false, \{ step: step \?\? true \}\)/,
     "checkAutoStartAfterDiscuss should default missing step flags to step mode",
   );

package/src/resources/extensions/gsd/tests/tool-availability-audit.test.ts

@@ -141,6 +141,41 @@ for (const customType of ["gsd-discuss", "gsd-run"] as const) {
   });
 }
 
+for (const unitType of ["execute-task", "execute-task-simple", "reactive-execute"] as const) {
+  test(`${unitType}: resolves gsd_task_complete via alias gsd_complete_task when only alias is registered`, () => {
+    // Simulates the MCP transport registering gsd_complete_task (alias) instead of gsd_task_complete.
+    // adjust_tool_set strips aliases from providerCompatible, so gsd_complete_task is only present
+    // in registeredToolNames. resolveScopedToolNames must still surface it so the agent can complete tasks.
+    const base: string[] = [...FULL_REGISTERED_TOOLS];
+    const aliasOnlyRegistered = base
+      .filter((name) => name !== "gsd_task_complete")
+      .concat("gsd_complete_task");
+    const aliasStrippedActive = aliasOnlyRegistered.filter((name) => name !== "gsd_complete_task");
+
+    const result = buildMinimalAutoGsdToolSet(aliasStrippedActive, unitType, aliasOnlyRegistered);
+
+    assert.ok(
+      result.includes("gsd_task_complete") || result.includes("gsd_complete_task"),
+      `${unitType} missing gsd_task_complete / gsd_complete_task — agent cannot complete tasks`,
+    );
+  });
+
+  test(`${unitType}: alias does not duplicate canonical when both are in the active set`, () => {
+    // When both canonical and alias are registered/active, only the canonical should be surfaced.
+    const bothPresent: string[] = [...FULL_REGISTERED_TOOLS, "gsd_complete_task"];
+
+    const result = buildMinimalAutoGsdToolSet(bothPresent, unitType, bothPresent);
+
+    const hasCanonical = result.includes("gsd_task_complete");
+    const hasAlias = result.includes("gsd_complete_task");
+    assert.ok(hasCanonical || hasAlias, `${unitType} missing completion tool`);
+    assert.ok(
+      !(hasCanonical && hasAlias),
+      `${unitType} surfaces both gsd_task_complete and gsd_complete_task — alias should not duplicate canonical`,
+    );
+  });
+}
+
 test("discuss-milestone two-stage scoping matches adjust_tool_set request scope", () => {
   const activeTools = simulateDiscussAllowlistFilter(FULL_REGISTERED_TOOLS);
   const dispatchScoped = buildMinimalAutoGsdToolSet(

package/src/resources/extensions/gsd/tests/tool-naming.test.ts

@@ -5,6 +5,10 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { registerDbTools } from '../bootstrap/db-tools.ts';
 import { getLegacyTelemetry, resetLegacyTelemetry } from '../legacy-telemetry.ts';
+import {
+  WORKFLOW_TOOL_ALIAS_PAIRS,
+  WORKFLOW_TOOL_CONTRACTS,
+} from '../workflow-tool-surface.ts';
 
 
 // ─── Mock PI ──────────────────────────────────────────────────────────────────
@@ -17,49 +21,38 @@ function makeMockPi() {
   } as any;
 }
 
-// ─── Rename map ───────────────────────────────────────────────────────────────
-
-const RENAME_MAP: Array<{ canonical: string; alias: string }> = [
-  { canonical: "gsd_decision_save", alias: "gsd_save_decision" },
-  { canonical: "gsd_requirement_update", alias: "gsd_update_requirement" },
-  { canonical: "gsd_requirement_save", alias: "gsd_save_requirement" },
-  { canonical: "gsd_summary_save", alias: "gsd_save_summary" },
-  { canonical: "gsd_milestone_generate_id", alias: "gsd_generate_milestone_id" },
-  { canonical: "gsd_task_complete", alias: "gsd_complete_task" },
-  { canonical: "gsd_slice_complete", alias: "gsd_complete_slice" },
-  { canonical: "gsd_plan_milestone", alias: "gsd_milestone_plan" },
-  { canonical: "gsd_plan_slice", alias: "gsd_slice_plan" },
-  { canonical: "gsd_plan_task", alias: "gsd_task_plan" },
-  { canonical: "gsd_replan_slice", alias: "gsd_slice_replan" },
-  { canonical: "gsd_reassess_roadmap", alias: "gsd_roadmap_reassess" },
-  { canonical: "gsd_complete_milestone", alias: "gsd_milestone_complete" },
-  { canonical: "gsd_validate_milestone", alias: "gsd_milestone_validate" },
-  { canonical: "gsd_task_reopen", alias: "gsd_reopen_task" },
-  { canonical: "gsd_slice_reopen", alias: "gsd_reopen_slice" },
-  { canonical: "gsd_milestone_reopen", alias: "gsd_reopen_milestone" },
-];
-
-const STANDALONE_TOOLS = [
-  "gsd_save_gate_result",
-  "gsd_skip_slice",
-  "gsd_uat_result_save",
-];
-
 // ─── Registration count ──────────────────────────────────────────────────────
 
 console.log('\n── Tool naming: registration count ──');
 
 const pi = makeMockPi();
 registerDbTools(pi);
-
+const toolByName = new Map<string, any>(pi.tools.map((tool: any) => [tool.name, tool]));
+const registeredCanonicalNames = new Set<string>(
+  WORKFLOW_TOOL_CONTRACTS
+    .map((tool) => tool.canonicalName)
+    .filter((name) => toolByName.has(name)),
+);
+const RENAME_MAP = WORKFLOW_TOOL_ALIAS_PAIRS.filter(({ canonical }) =>
+  registeredCanonicalNames.has(canonical),
+);
+const STANDALONE_TOOLS = WORKFLOW_TOOL_CONTRACTS
+  .filter((tool) => registeredCanonicalNames.has(tool.canonicalName) && tool.aliases.length === 0)
+  .map((tool) => tool.canonicalName);
+const expectedRegisteredNames = [
+  ...STANDALONE_TOOLS,
+  ...RENAME_MAP.flatMap(({ canonical, alias }) => [canonical, alias]),
+].sort();
+
+assert.equal(pi.tools.length, toolByName.size, 'Tool registration should not produce duplicate names');
 assert.deepStrictEqual(
-  pi.tools.length,
-  RENAME_MAP.length * 2 + STANDALONE_TOOLS.length,
-  'Should register canonical/alias tool pairs plus standalone DB tools',
+  [...toolByName.keys()].sort(),
+  expectedRegisteredNames,
+  'Should register only workflow surface tools and their declared aliases',
 );
 
 for (const name of STANDALONE_TOOLS) {
-  assert.ok(pi.tools.some((t: any) => t.name === name), `Standalone tool "${name}" should be registered`);
+  assert.ok(toolByName.has(name), `Standalone tool "${name}" should be registered`);
 }
 
 // ─── Both names exist for each pair ──────────────────────────────────────────
@@ -67,8 +60,8 @@ for (const name of STANDALONE_TOOLS) {
 console.log('\n── Tool naming: canonical and alias names exist ──');
 
 for (const { canonical, alias } of RENAME_MAP) {
-  const canonicalTool = pi.tools.find((t: any) => t.name === canonical);
-  const aliasTool = pi.tools.find((t: any) => t.name === alias);
+  const canonicalTool = toolByName.get(canonical);
+  const aliasTool = toolByName.get(alias);
 
   assert.ok(canonicalTool !== undefined, `Canonical tool "${canonical}" should be registered`);
   assert.ok(aliasTool !== undefined, `Alias tool "${alias}" should be registered`);
@@ -79,8 +72,8 @@ for (const { canonical, alias } of RENAME_MAP) {
 console.log('\n── Tool naming: alias execute wrapper ──');
 
 for (const { canonical, alias } of RENAME_MAP) {
-  const canonicalTool = pi.tools.find((t: any) => t.name === canonical);
-  const aliasTool = pi.tools.find((t: any) => t.name === alias);
+  const canonicalTool = toolByName.get(canonical);
+  const aliasTool = toolByName.get(alias);
 
   if (canonicalTool && aliasTool) {
     assert.ok(
@@ -91,8 +84,8 @@ for (const { canonical, alias } of RENAME_MAP) {
 }
 
 test("alias execute increments legacy MCP alias telemetry before delegating", async () => {
-  const canonicalTool = pi.tools.find((t: any) => t.name === "gsd_decision_save");
-  const aliasTool = pi.tools.find((t: any) => t.name === "gsd_save_decision");
+  const canonicalTool = toolByName.get("gsd_decision_save");
+  const aliasTool = toolByName.get("gsd_save_decision");
   assert.ok(canonicalTool);
   assert.ok(aliasTool);
 
@@ -120,7 +113,7 @@ test("alias execute increments legacy MCP alias telemetry before delegating", as
 console.log('\n── Tool naming: alias descriptions ──');
 
 for (const { canonical, alias } of RENAME_MAP) {
-  const aliasTool = pi.tools.find((t: any) => t.name === alias);
+  const aliasTool = toolByName.get(alias);
 
   if (aliasTool) {
     assert.ok(
@@ -135,7 +128,7 @@ for (const { canonical, alias } of RENAME_MAP) {
 console.log('\n── Tool naming: canonical promptGuidelines use canonical name ──');
 
 for (const { canonical } of RENAME_MAP) {
-  const canonicalTool = pi.tools.find((t: any) => t.name === canonical);
+  const canonicalTool = toolByName.get(canonical);
 
   if (canonicalTool) {
     const guidelinesText = canonicalTool.promptGuidelines.join(' ');
@@ -151,7 +144,7 @@ for (const { canonical } of RENAME_MAP) {
 console.log('\n── Tool naming: alias promptGuidelines redirect to canonical ──');
 
 for (const { canonical, alias } of RENAME_MAP) {
-  const aliasTool = pi.tools.find((t: any) => t.name === alias);
+  const aliasTool = toolByName.get(alias);
 
   if (aliasTool) {
     const guidelinesText = aliasTool.promptGuidelines.join(' ');

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

@@ -66,6 +66,9 @@ describe("uat-policy", () => {
   it("detects direct and MCP-shaped browser tool surfaces", () => {
     assert.equal(hasUatBrowserToolSurface(["read", "browser_navigate"]), true);
     assert.equal(hasUatBrowserToolSurface(["read", "mcp__gsd-browser__browser_navigate"]), true);
+    assert.equal(hasUatBrowserToolSurface(["read", "mcp__gsd-browser__*"]), true);
+    assert.equal(hasUatBrowserToolSurface(["read", "mcp__browser-uat__*"]), true);
+    assert.equal(hasUatBrowserToolSurface(["read", "mcp__gsd-workflow__*"]), false);
     assert.equal(hasUatBrowserToolSurface(["read", "gsd_uat_exec"]), false);
     assert.equal(hasUatBrowserToolSurface(undefined), false);
   });
@@ -89,6 +92,26 @@ describe("uat-policy", () => {
       }),
       null,
     );
+    assert.equal(
+      getUatBrowserToolSupportError({
+        uatType: "human-experience",
+        activeTools: ["read", "gsd_uat_exec"],
+        registeredTools: ["browser_navigate"],
+        milestoneId: "M001",
+        sliceId: "S01",
+      }),
+      null,
+    );
+    assert.equal(
+      getUatBrowserToolSupportError({
+        uatType: "human-experience",
+        activeTools: ["read", "gsd_uat_exec"],
+        registeredTools: ["mcp__gsd-browser__*"],
+        milestoneId: "M001",
+        sliceId: "S01",
+      }),
+      null,
+    );
 
     const error = getUatBrowserToolSupportError({
       uatType: "browser-executable",

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

@@ -8,6 +8,7 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 
 import {
+  composeContractedUnitContext,
   composeContextModeInstructions,
   composeInlinedContext,
   composeUnitContext,
@@ -15,6 +16,7 @@ import {
   type ArtifactResolver,
   type ExcerptResolver,
 } from "../unit-context-composer.ts";
+import { compileUnitContextContract } from "../tool-contract.ts";
 import type {
   ArtifactKey,
   BaseResolverContext,
@@ -268,6 +270,21 @@ test("#4782 phase 2: buildReassessRoadmapPrompt emits composer-shaped context wi
   assert.ok(!prompt.includes("Slice Context (from discussion)"));
 });
 
+test("execute-task prompt surfaces contract-declared on-demand slice research", async (t) => {
+  const base = makeFixtureBase();
+  t.after(() => cleanup(base));
+  invalidateAllCaches();
+
+  seed(base, "M001");
+  writeArtifacts(base);
+
+  const prompt = await buildExecuteTaskPrompt("M001", "S01", "First", "T01", "Task", base);
+
+  assert.match(prompt, /## On-demand Context/);
+  assert.match(prompt, /\.gsd\/milestones\/M001\/slices\/S01\/S01-RESEARCH\.md/);
+  assert.match(prompt, /Read it only if the inlined task plan, slice plan excerpt, and carry-forward context do not explain/);
+});
+
 test("Context Mode resume injection: eligible prompts include one bounded snapshot block above inlined context", async (t) => {
   const base = makeFixtureBase();
   t.after(() => cleanup(base));
@@ -370,6 +387,36 @@ test("#4924 v2 composer: returns empty sections for unknown unit type", async ()
   assert.deepEqual(out, { prepend: "", inline: "" });
 });
 
+test("Unit Context Contract composer exposes keyed blocks and on-demand artifacts", async () => {
+  const result = compileUnitContextContract("execute-task");
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+
+  const calls: ArtifactKey[] = [];
+  const out = await composeContractedUnitContext(result.contract, {
+    base: { ...fakeBase, unitType: "stale-unit", taskId: "T01" },
+    resolveArtifact: async (key) => {
+      calls.push(key);
+      return `BODY:${key}`;
+    },
+  });
+
+  assert.deepEqual(calls, [
+    "task-plan",
+    "slice-plan",
+    "prior-task-summaries",
+    "templates",
+  ]);
+  assert.deepEqual(out.blocks.map((block) => [block.key, block.mode]), [
+    ["task-plan", "inline"],
+    ["slice-plan", "inline"],
+    ["prior-task-summaries", "inline"],
+    ["templates", "inline"],
+  ]);
+  assert.deepEqual(out.onDemand, ["slice-research"]);
+  assert.match(out.inline, /BODY:task-plan\n\n---\n\nBODY:slice-plan/);
+});
+
 test("#4924 v2 composer: omitting resolveArtifact skips inline keys without erroring", async () => {
   const out = await composeUnitContext("reassess-roadmap", { base: fakeBase });
   assert.strictEqual(out.inline, "");

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

@@ -2,7 +2,11 @@ import test from "node:test";
 import assert from "node:assert/strict";
 
 import * as userInputBoundary from "../user-input-boundary.ts";
-import { isAwaitingUserInput, shouldPauseForUserApprovalQuestion } from "../user-input-boundary.ts";
+import {
+  isAwaitingUserInput,
+  messageHasPendingAskUserQuestionsTool,
+  shouldPauseForUserApprovalQuestion,
+} from "../user-input-boundary.ts";
 
 test("lastAssistantText extracts the latest assistant text block content", () => {
   const lastAssistantText = (userInputBoundary as {
@@ -73,6 +77,87 @@ test("isAwaitingUserInput does not trigger on thinking-block approval phrases",
   assert.equal(shouldPauseForUserApprovalQuestion("discuss-requirements", messages), false);
 });
 
+test("messageHasPendingAskUserQuestionsTool detects in-flight structured question tools", () => {
+  // state: "running" with no externalResult → still in-flight
+  assert.equal(
+    messageHasPendingAskUserQuestionsTool({
+      role: "assistant",
+      content: [
+        { type: "text", text: "Which direction?" },
+        { type: "toolCall", name: "mcp__gsd-workflow__ask_user_questions", state: "running" },
+      ],
+    }),
+    true,
+  );
+
+  // no state, no externalResult — streaming block that hasn't completed yet
+  assert.equal(
+    messageHasPendingAskUserQuestionsTool({
+      role: "assistant",
+      content: [
+        { type: "toolCall", name: "ask_user_questions" },
+      ],
+    }),
+    true,
+  );
+
+  // state: "completed" — legacy state-based completion
+  assert.equal(
+    messageHasPendingAskUserQuestionsTool({
+      role: "assistant",
+      content: [
+        { type: "toolCall", name: "ask_user_questions", state: "completed" },
+      ],
+    }),
+    false,
+  );
+
+  // externalResult present — Claude Code signals completion via externalResult, not state
+  assert.equal(
+    messageHasPendingAskUserQuestionsTool({
+      role: "assistant",
+      content: [
+        { type: "toolCall", name: "ask_user_questions", externalResult: { content: [], isError: false } },
+      ],
+    }),
+    false,
+  );
+  assert.equal(
+    messageHasPendingAskUserQuestionsTool({
+      role: "assistant",
+      content: [
+        {
+          type: "toolCall",
+          name: "ask_user_questions",
+          externalResult: { content: [{ type: "text", text: "answer" }], isError: false },
+        },
+      ],
+    }),
+    false,
+  );
+
+  // serverToolUse shape (claude-code-cli MCP path) — no externalResult → in-flight
+  assert.equal(
+    messageHasPendingAskUserQuestionsTool({
+      role: "assistant",
+      content: [
+        { type: "serverToolUse", name: "mcp__gsd-workflow__ask_user_questions" },
+      ],
+    }),
+    true,
+  );
+  // serverToolUse shape — externalResult present → completed
+  assert.equal(
+    messageHasPendingAskUserQuestionsTool({
+      role: "assistant",
+      content: [
+        { type: "serverToolUse", name: "ask_user_questions", externalResult: { content: [], isError: false } },
+      ],
+    }),
+    false,
+  );
+});
+
 test("isAwaitingUserInput still triggers on text-block question marks when thinking is also present", () => {
   // When thinking + text are both present and the text asks a question, it should still pause.
   const messages = [

package/src/resources/extensions/gsd/tests/validate-milestone-stuck-guard.test.ts

@@ -12,6 +12,7 @@ import { clearPathCache } from "../paths.ts";
 import {
   openDatabase,
   closeDatabase,
+  insertAssessment,
   insertMilestone,
   insertSlice,
 } from "../gsd-db.ts";
@@ -222,6 +223,44 @@ describe("validate-milestone stuck-loop guard (#4094)", () => {
     assert.equal(s.pendingVerificationRetry, null);
   });
 
+  test("continues when DB pass overrides stale worktree needs-attention after /gsd verdict", async () => {
+    insertMilestone({ id: "M001" });
+    insertSlice({ id: "S01", milestoneId: "M001", title: "Slice 1", status: "complete" });
+    writeWorktreeValidationFile("needs-attention");
+
+    const worktreeValidationPath = join(
+      tempDir,
+      ".gsd",
+      "worktrees",
+      "M001",
+      ".gsd",
+      "milestones",
+      "M001",
+      "M001-VALIDATION.md",
+    );
+    insertAssessment({
+      path: worktreeValidationPath,
+      milestoneId: "M001",
+      sliceId: null,
+      taskId: null,
+      status: "pass",
+      scope: "milestone-validation",
+      fullContent: "---\nverdict: pass\n---\n\n# Validation\nManually overridden via /gsd verdict\n",
+    });
+    invalidateAllCaches();
+
+    const ctx = makeMockCtx();
+    const pi = makeMockPi();
+    const pauseAutoMock = mock.fn(async () => {});
+    const s = makeMockSession(tempDir, "validate-milestone", "M001");
+
+    const result = await runPostUnitVerification({ s, ctx, pi } as VerificationContext, pauseAutoMock);
+
+    assert.equal(result, "continue");
+    assert.equal(pauseAutoMock.mock.callCount(), 0);
+    assert.equal(ctx.ui.notify.mock.callCount(), 0);
+  });
+
   test("retries when no VALIDATION file exists yet", async () => {
     insertMilestone({ id: "M001" });
     insertSlice({ id: "S01", milestoneId: "M001", title: "Slice 1", status: "complete" });