@opengsd/gsd-pi 1.1.1-dev.75048e7 → 1.1.1-dev.9f86580

package/src/resources/extensions/gsd/tests/workflow-mcp.test.ts

@@ -48,12 +48,52 @@ test("auto execute-task requires canonical task completion tool", () => {
   assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("execute-task"), ["gsd_task_complete"]);
 });
 
+test("plan-slice requires planning and roadmap reassessment tools", () => {
+  const expected = ["gsd_plan_slice", "gsd_reassess_roadmap"];
+  assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("plan-slice"), expected);
+  assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("plan-slice"), expected);
+});
+
+test("plan-milestone requires status, roadmap, and single-slice planning tools", () => {
+  const expected = ["gsd_milestone_status", "gsd_plan_milestone", "gsd_plan_slice"];
+  assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("plan-milestone"), expected);
+  assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("plan-milestone"), expected);
+});
+
+test("refine-slice requires canonical slice planning tool", () => {
+  assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("refine-slice"), ["gsd_plan_slice"]);
+  assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("refine-slice"), ["gsd_plan_slice"]);
+});
+
 test("complete-slice requires closeout and execution handoff tools", () => {
-  const expected = ["gsd_slice_complete", "gsd_task_reopen", "gsd_replan_slice"];
+  const expected = [
+    "gsd_slice_complete",
+    "gsd_task_reopen",
+    "gsd_replan_slice",
+    "gsd_requirement_update",
+    "gsd_summary_save",
+  ];
   assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("complete-slice"), expected);
   assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("complete-slice"), expected);
 });
 
+test("complete-milestone requires status, requirement, project refresh, and closeout tools", () => {
+  const expected = [
+    "gsd_milestone_status",
+    "gsd_requirement_update",
+    "gsd_summary_save",
+    "gsd_complete_milestone",
+  ];
+  assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("complete-milestone"), expected);
+  assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("complete-milestone"), expected);
+});
+
+test("reactive-execute requires task completion and failed-task summary tools", () => {
+  const expected = ["gsd_task_complete", "gsd_summary_save"];
+  assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("reactive-execute"), expected);
+  assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("reactive-execute"), expected);
+});
+
 test("workflow MCP capability surface includes native legacy gsd aliases", () => {
   const err = getWorkflowTransportSupportError(
     "claude-code",
@@ -679,7 +719,7 @@ test("transport compatibility ignores API-backed providers", () => {
 test("transport compatibility now allows plan-slice over workflow MCP surface", () => {
   const error = getWorkflowTransportSupportError(
     "claude-code",
-    ["gsd_plan_slice"],
+    getRequiredWorkflowToolsForAutoUnit("plan-slice"),
     {
       projectRoot: "/tmp/project",
       env: { GSD_WORKFLOW_MCP_COMMAND: "node" },
@@ -696,7 +736,7 @@ test("transport compatibility now allows plan-slice over workflow MCP surface",
 test("transport compatibility now allows complete-slice over workflow MCP surface", () => {
   const error = getWorkflowTransportSupportError(
     "claude-code",
-    ["gsd_complete_slice"],
+    getRequiredWorkflowToolsForAutoUnit("complete-slice"),
     {
       projectRoot: "/tmp/project",
       env: { GSD_WORKFLOW_MCP_COMMAND: "node" },
@@ -747,7 +787,7 @@ test("transport compatibility now allows gate-evaluate over workflow MCP surface
 test("transport compatibility now allows validate-milestone over workflow MCP surface", () => {
   const error = getWorkflowTransportSupportError(
     "claude-code",
-    ["gsd_milestone_status", "gsd_validate_milestone"],
+    getRequiredWorkflowToolsForAutoUnit("validate-milestone"),
     {
       projectRoot: "/tmp/project",
       env: { GSD_WORKFLOW_MCP_COMMAND: "node" },
@@ -764,7 +804,7 @@ test("transport compatibility now allows validate-milestone over workflow MCP su
 test("transport compatibility now allows complete-milestone over workflow MCP surface", () => {
   const error = getWorkflowTransportSupportError(
     "claude-code",
-    ["gsd_milestone_status", "gsd_complete_milestone"],
+    getRequiredWorkflowToolsForAutoUnit("complete-milestone"),
     {
       projectRoot: "/tmp/project",
       env: { GSD_WORKFLOW_MCP_COMMAND: "node" },
@@ -795,7 +835,7 @@ test("transport compatibility now allows replan-slice over workflow MCP surface"
   assert.equal(error, null);
 });
 
-test("transport compatibility accepts workflow MCP tools absent from parent active tool surface", () => {
+test("transport compatibility rejects MCP tools not connected in active tool surface", () => {
   const error = getWorkflowTransportSupportError(
     "claude-code",
     ["gsd_summary_save"],
@@ -810,10 +850,10 @@ test("transport compatibility accepts workflow MCP tools absent from parent acti
     },
   );
 
-  assert.equal(error, null);
+  assert.match(error ?? "", /requires gsd_summary_save/);
 });
 
-test("transport compatibility still checks non-MCP tools against parent active tool surface", () => {
+test("transport compatibility checks all required tools against active tool surface", () => {
   const error = getWorkflowTransportSupportError(
     "claude-code",
     ["gsd_summary_save", "secure_env_collect"],
@@ -828,8 +868,9 @@ test("transport compatibility still checks non-MCP tools against parent active t
     },
   );
 
-  assert.match(error ?? "", /requires secure_env_collect/);
-  assert.doesNotMatch(error ?? "", /gsd_summary_save/);
+  assert.match(error ?? "", /requires.*(?:gsd_summary_save|secure_env_collect)/);
+  assert.match(error ?? "", /gsd_summary_save/);
+  assert.match(error ?? "", /secure_env_collect/);
 });
 
 test("transport compatibility still blocks units whose MCP tools are not exposed", () => {
@@ -850,6 +891,32 @@ test("transport compatibility still blocks units whose MCP tools are not exposed
   assert.match(error ?? "", /currently exposes only/);
 });
 
+test("discuss-milestone guided flow does not abort when all required tools are on MCP surface (regression #469)", () => {
+  // Guided flow starts the workflow MCP server as part of dispatch, so the
+  // parent session active-tool list is not authoritative for MCP tools.
+  const discussMilestoneTools = [
+    "gsd_summary_save",
+    "gsd_requirement_save",
+    "gsd_requirement_update",
+    "gsd_plan_milestone",
+    "gsd_milestone_generate_id",
+  ];
+  const error = getWorkflowTransportSupportError(
+    "claude-code",
+    discussMilestoneTools,
+    {
+      projectRoot: "/tmp/project",
+      env: { GSD_WORKFLOW_MCP_COMMAND: "node" },
+      surface: "guided flow",
+      unitType: "discuss-milestone",
+      authMode: "externalCli",
+      baseUrl: "local://claude-code",
+    },
+  );
+
+  assert.equal(error, null);
+});
+
 test("transport compatibility accepts MCP-namespaced runtime tools", () => {
   const error = getWorkflowTransportSupportError(
     "claude-code",

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

@@ -737,13 +737,13 @@ test("executeUatResultSave supplies direct browser tools for browser-executable
       verdict: "PASS",
       checks: [{
         id: "UAT-01",
-        description: "Browser flow used managed gsd-browser tools",
+        description: "Browser flow used browser tools",
         mode: "browser",
         result: "PASS",
         evidence: [{ kind: "gsd_uat_exec", ref: evidenceId }],
         notes: "Browser check passed.",
       }],
-      notes: "UAT passed with managed browser evidence.",
+      notes: "UAT passed with browser evidence.",
     } as unknown as Parameters<typeof executeUatResultSave>[0], worktree));
 
     assert.equal(result.isError, undefined);
@@ -836,6 +836,135 @@ test("executeUatResultSave merges canonical plan ID and read-only tools when pre
   }
 });
 
+test("executeUatResultSave surfaces the worktree validation path for NEEDS-HUMAN checks", async () => {
+  const base = makeTmpBase();
+  const worktree = join(base, ".gsd", "worktrees", "M001");
+  const worktreeExecDir = join(worktree, ".gsd", "exec");
+  const evidenceId = "uat-human-validation-evidence";
+  try {
+    openTestDb(base);
+    seedMilestone("M001", "Milestone One");
+    seedSlice("M001", "S07", "complete");
+    mkdirSync(worktreeExecDir, { recursive: true });
+    writeFileSync(
+      join(worktreeExecDir, `${evidenceId}.meta.json`),
+      JSON.stringify({
+        id: evidenceId,
+        metadata: {
+          kind: "uat_exec",
+          milestoneId: "M001",
+          sliceId: "S07",
+          checkId: "UAT-01",
+          intent: "uat-runtime-check",
+        },
+      }),
+      "utf-8",
+    );
+
+    const result = await inProjectDir(worktree, () => executeUatResultSave({
+      milestoneId: "M001",
+      sliceId: "S07",
+      uatType: "human-experience",
+      verdict: "PASS",
+      checks: [
+        {
+          id: "UAT-01",
+          description: "Service boots and renders the dashboard",
+          mode: "runtime",
+          result: "PASS",
+          evidence: [{ kind: "gsd_uat_exec", ref: evidenceId }],
+          notes: "Boot check passed.",
+        },
+        {
+          id: "UAT-02",
+          description: "Dashboard layout feels balanced",
+          mode: "human-follow-up",
+          result: "NEEDS-HUMAN",
+          nonAutomatable: true,
+          notes: "Open the app and eyeball the spacing.",
+        },
+      ],
+      notes: "Automatable checks passed; layout taste needs a human.",
+    } as unknown as Parameters<typeof executeUatResultSave>[0], worktree));
+
+    assert.equal(result.isError, undefined);
+    assert.equal(result.details.verdict, "PASS");
+    // The reviewer needs the buried worktree checkout path, not just the file.
+    assert.equal(result.details.manualValidationPath, worktree);
+    const returnedText = (result.content[0] as { text: string }).text;
+    assert.match(returnedText, /Manual validation needed/);
+    assert.ok(returnedText.includes(worktree), "tool return should include the worktree path");
+
+    const assessment = readFileSync(
+      join(base, ".gsd", "milestones", "M001", "slices", "S07", "S07-ASSESSMENT.md"),
+      "utf-8",
+    );
+    assert.match(assessment, /## Manual Validation/);
+    assert.ok(assessment.includes(worktree), "assessment should include the worktree checkout path");
+    assert.match(assessment, /git worktree/);
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executeUatResultSave omits manual-validation guidance when no human checks remain", async () => {
+  const base = makeTmpBase();
+  const worktree = join(base, ".gsd", "worktrees", "M001");
+  const worktreeExecDir = join(worktree, ".gsd", "exec");
+  const evidenceId = "uat-no-human-evidence";
+  try {
+    openTestDb(base);
+    seedMilestone("M001", "Milestone One");
+    seedSlice("M001", "S08", "complete");
+    mkdirSync(worktreeExecDir, { recursive: true });
+    writeFileSync(
+      join(worktreeExecDir, `${evidenceId}.meta.json`),
+      JSON.stringify({
+        id: evidenceId,
+        metadata: {
+          kind: "uat_exec",
+          milestoneId: "M001",
+          sliceId: "S08",
+          checkId: "UAT-01",
+          intent: "uat-artifact-check",
+        },
+      }),
+      "utf-8",
+    );
+
+    const result = await inProjectDir(worktree, () => executeUatResultSave({
+      milestoneId: "M001",
+      sliceId: "S08",
+      uatType: "artifact-driven",
+      verdict: "PASS",
+      checks: [{
+        id: "UAT-01",
+        description: "Config file exists",
+        mode: "artifact",
+        result: "PASS",
+        evidence: [{ kind: "gsd_uat_exec", ref: evidenceId }],
+        notes: "Artifact present.",
+      }],
+      notes: "Fully automated pass.",
+    } as unknown as Parameters<typeof executeUatResultSave>[0], worktree));
+
+    assert.equal(result.isError, undefined);
+    assert.equal(result.details.manualValidationPath, undefined);
+    const returnedText = (result.content[0] as { text: string }).text;
+    assert.equal(returnedText.includes("Manual validation needed"), false);
+
+    const assessment = readFileSync(
+      join(base, ".gsd", "milestones", "M001", "slices", "S08", "S08-ASSESSMENT.md"),
+      "utf-8",
+    );
+    assert.equal(assessment.includes("## Manual Validation"), false);
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
 test("executeUatResultSave rejects saved UAT without fresh UAT-owned evidence", async () => {
   const base = makeTmpBase();
   const worktree = join(base, ".gsd", "worktrees", "M001");

package/src/resources/extensions/gsd/tests/worktree-reentry.test.ts

@@ -0,0 +1,102 @@
+/**
+ * worktree-reentry.test.ts — Unit tests for reenterActiveWorktreeIfNeeded.
+ *
+ * Covers the cold-start (/quit + relaunch) path where cwd lands at the project
+ * root instead of the active milestone's worktree. The helper should chdir back
+ * into the worktree deterministically, and no-op when it shouldn't act.
+ */
+
+import { describe, test, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execFileSync } from "node:child_process";
+
+import { createAutoWorktree, _resetAutoWorktreeOriginalBaseForTests } from "../auto-worktree.ts";
+import { reenterActiveWorktreeIfNeeded } from "../worktree-reentry.ts";
+
+// Safe: all inputs below are hardcoded test strings, not user input.
+function git(subArgs: string[], cwd: string): void {
+  execFileSync("git", subArgs, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+}
+
+function createTempRepo(
+  t: { after: (fn: () => void) => void },
+  opts: { isolation?: "worktree" | "none" } = {},
+): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "wt-reentry-")));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  git(["init"], dir);
+  git(["config", "user.email", "test@test.com"], dir);
+  git(["config", "user.name", "Test"], dir);
+  writeFileSync(join(dir, "README.md"), "# test\n");
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+  if (opts.isolation === "worktree") {
+    writeFileSync(join(dir, ".gsd", "PREFERENCES.md"), "---\ngit:\n  isolation: worktree\n---\n", "utf-8");
+  }
+  const msDir = join(dir, ".gsd", "milestones", "M001");
+  mkdirSync(msDir, { recursive: true });
+  writeFileSync(join(msDir, "CONTEXT.md"), "# M001 Context\n");
+  git(["add", "."], dir);
+  git(["commit", "-m", "init"], dir);
+  git(["branch", "-M", "main"], dir);
+  return dir;
+}
+
+describe("reenterActiveWorktreeIfNeeded", () => {
+  const savedCwd = process.cwd();
+
+  beforeEach(() => {
+    _resetAutoWorktreeOriginalBaseForTests();
+    process.chdir(savedCwd);
+  });
+
+  test("re-enters the sole live worktree when sitting at the project root", async (t) => {
+    const dir = createTempRepo(t, { isolation: "worktree" });
+    t.after(() => process.chdir(savedCwd));
+
+    // createAutoWorktree chdir's INTO the worktree; simulate a cold start by
+    // returning to the project root with a clean workspace registry.
+    createAutoWorktree(dir, "M001");
+    process.chdir(dir);
+    _resetAutoWorktreeOriginalBaseForTests();
+
+    const entered = await reenterActiveWorktreeIfNeeded(dir);
+    assert.ok(entered, "re-entry returned a worktree path");
+    assert.strictEqual(realpathSync(process.cwd()), realpathSync(entered!), "cwd moved into the worktree");
+    assert.strictEqual(entered, join(dir, ".gsd", "worktrees", "M001"));
+  });
+
+  test("no-op when already inside a worktree", async (t) => {
+    const dir = createTempRepo(t, { isolation: "worktree" });
+    t.after(() => process.chdir(savedCwd));
+
+    createAutoWorktree(dir, "M001"); // leaves cwd inside the worktree
+    const cwdBefore = process.cwd();
+
+    const entered = await reenterActiveWorktreeIfNeeded(dir);
+    assert.strictEqual(entered, null, "no re-entry when already in a worktree");
+    assert.strictEqual(process.cwd(), cwdBefore, "cwd unchanged");
+  });
+
+  test("no-op when isolation is not worktree", async (t) => {
+    const dir = createTempRepo(t, { isolation: "none" });
+    t.after(() => process.chdir(savedCwd));
+    process.chdir(dir);
+
+    const entered = await reenterActiveWorktreeIfNeeded(dir);
+    assert.strictEqual(entered, null, "isolation=none never re-enters");
+    assert.strictEqual(realpathSync(process.cwd()), realpathSync(dir), "cwd stays at project root");
+  });
+
+  test("no-op when there are no worktrees", async (t) => {
+    const dir = createTempRepo(t, { isolation: "worktree" });
+    t.after(() => process.chdir(savedCwd));
+    process.chdir(dir);
+
+    const entered = await reenterActiveWorktreeIfNeeded(dir);
+    assert.strictEqual(entered, null, "nothing to re-enter");
+    assert.strictEqual(realpathSync(process.cwd()), realpathSync(dir), "cwd stays at project root");
+  });
+});

package/src/resources/extensions/gsd/tool-contract.ts

@@ -45,7 +45,7 @@ export function compileUnitToolContract(unitType: string): ToolContractResult {
   const forbiddenWorkflowTools = Object.entries(surfaceContract?.forbiddenGsdTools ?? {})
     .map(([name, reason]) => ({ name, reason }));
   const closeoutTools = requiredWorkflowTools.filter((tool) =>
-    /^gsd_(?:task|slice|milestone|complete|validate|save|summary)/.test(tool),
+    /^gsd_(?:task|slice|milestone|complete|validate|save|summary|uat)/.test(tool),
   );
 
   if (requiresCloseoutTool(unitType) && closeoutTools.length === 0) {

package/src/resources/extensions/gsd/tool-presentation-plan.ts

@@ -123,12 +123,31 @@ export function buildRunUatCanonicalToolNames(options: { includeBrowserTools?: r
   ]);
 }
 
+// UAT modes whose run-uat instructions direct the runner to exercise the live
+// app in a browser. These modes receive the browser tool surface so the runner
+// can actually drive the page instead of silently deferring browser checks to a
+// human. See run-uat.md automation rules: `browser-executable`, `live-runtime`,
+// and `mixed` are all told to drive a browser/runtime path, and
+// `human-experience` is told to capture screenshots. Without this, a webpage
+// UAT classified as anything but `browser-executable` had no browser tools and
+// downgraded its live checks to NEEDS-HUMAN (M001/S03 regression).
+export const BROWSER_INCLUSIVE_UAT_TYPES: readonly string[] = [
+  "browser-executable",
+  "live-runtime",
+  "mixed",
+  "human-experience",
+];
+
+function uatTypeIncludesBrowser(uatType: string | undefined): boolean {
+  return uatType !== undefined && BROWSER_INCLUSIVE_UAT_TYPES.includes(uatType);
+}
+
 export function runUatBrowserToolsForType(uatType: string | undefined): readonly string[] {
-  return uatType === "browser-executable" ? RUN_UAT_BROWSER_TOOL_NAMES : [];
+  return uatTypeIncludesBrowser(uatType) ? RUN_UAT_BROWSER_TOOL_NAMES : [];
 }
 
 export function runUatPresentationSurfaceForType(uatType: string | undefined): ToolPresentationSurface {
-  return uatType === "browser-executable" ? "hybrid" : "mcp";
+  return uatTypeIncludesBrowser(uatType) ? "hybrid" : "mcp";
 }
 
 export function buildRunUatPresentationForType(

package/src/resources/extensions/gsd/tools/complete-slice.ts

@@ -34,7 +34,8 @@ import { getGatesForTurn } from "../gate-registry.js";
 import { gsdProjectionRoot, clearPathCache, resolveMilestoneFile } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { checkOwnership, sliceUnitKey } from "../unit-ownership.js";
-import { saveFile, clearParseCache } from "../files.js";
+import { saveFile, clearParseCache, extractUatType } from "../files.js";
+import { hasBrowserRequiredText } from "../browser-evidence.js";
 import { invalidateStateCache } from "../state.js";
 import { renderRoadmapFromDb } from "../markdown-renderer.js";
 import { parseRoadmap } from "../parsers-legacy.js";
@@ -342,6 +343,33 @@ export async function handleCompleteSlice(
     return { error: `slice verification indicates blocked/failed state — do not complete a slice that has not passed verification. Address the blockers and re-verify first.` };
   }
 
+  // ── Browser/web UAT classification gate ────────────────────────────────
+  // A UAT that drives a running web UI (opening a page in a browser,
+  // navigating to a page/localhost) must declare a browser-capable mode so the
+  // run-uat runner surfaces browser tools and actually launches a browser.
+  // Otherwise the browser checks get silently deferred to a human and the slice
+  // passes on static checks alone (M001/S03 regression). `browser-executable`,
+  // `live-runtime`, and `mixed` all receive browser tools (see
+  // BROWSER_INCLUSIVE_UAT_TYPES); only the non-browser modes are rejected here.
+  //
+  // Reuse the canonical hasBrowserRequiredText detector (also used by dispatch
+  // and milestone validation): it skips Not-Proven/Out-of-Scope disclaimer
+  // sections and only treats verbs like navigate/open as web when they sit next
+  // to browser/page/localhost — avoiding false positives on CLI/file/API steps.
+  //
+  // Only `artifact-driven` is gated. It is the one mode that performs no
+  // execution at all (static/file checks), so a browser-requiring UAT under it
+  // genuinely defers verification to a human. Every other mode has a real
+  // verification path: `runtime-executable` runs browser test commands like
+  // `npx playwright test` via gsd_uat_exec, and live-runtime/mixed/
+  // browser-executable receive browser tools (BROWSER_INCLUSIVE_UAT_TYPES).
+  const declaredUatMode = extractUatType(params.uatContent || "") ?? "artifact-driven";
+  if (declaredUatMode === "artifact-driven" && hasBrowserRequiredText(params.uatContent || "")) {
+    return {
+      error: `UAT requires browser verification (opening a page in a browser, navigating to a page or localhost, screenshots) but declares "UAT mode: artifact-driven", which only runs static/file checks and would defer the browser work to a human. Use a mode that actually verifies the UI: "browser-executable" (interactive browser tools), "runtime-executable" (a browser test command such as playwright), or a browser-inclusive "mixed"/"live-runtime". Re-author the UAT Type section and complete the slice again.`,
+    };
+  }
+
   // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
   const completedAt = new Date().toISOString();
   let guardError: string | null = null;

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

@@ -17,8 +17,9 @@ import {
 } from "../gsd-db.js";
 import { GATE_REGISTRY } from "../gate-registry.js";
 import { generateRequirementsMd, saveArtifactToDb } from "../db-writer.js";
-import { clearPathCache, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
+import { clearPathCache, relSliceFile, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
 import { saveFile, clearParseCache } from "../files.js";
+import { buildManualValidationGuidance, resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { existsSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
 import { isAbsolute, join, resolve } from "node:path";
 import type { CompleteMilestoneParams } from "./complete-milestone.js";
@@ -1337,7 +1338,12 @@ function escapeMarkdownTableCell(value: unknown): string {
     .replace(/\r?\n/g, "<br>");
 }
 
-function renderUatAssessment(params: UatResultSaveParams, attempt: number, gateVerdict: "pass" | "flag"): string {
+function renderUatAssessment(
+  params: UatResultSaveParams,
+  attempt: number,
+  gateVerdict: "pass" | "flag",
+  basePath: string,
+): string {
   const lines = [
     "---",
     `sliceId: ${params.sliceId}`,
@@ -1372,6 +1378,27 @@ function renderUatAssessment(params: UatResultSaveParams, attempt: number, gateV
     "",
     `Aggregate UAT gate saved as ${gateVerdict}.`,
   ];
+
+  // When any check still needs a human, point them at the exact checkout to
+  // validate — critical for worktree milestones whose code sits under a hidden
+  // `.gsd/worktrees/` path the reviewer would otherwise have to hunt for.
+  const hasHuman = params.checks.some((check) => check.result === "NEEDS-HUMAN");
+  if (hasHuman) {
+    const guidance = buildManualValidationGuidance(basePath, params.milestoneId, {
+      uatPath: relSliceFile(basePath, params.milestoneId, params.sliceId, "UAT"),
+    });
+    if (guidance) {
+      lines.push(
+        "",
+        "## Manual Validation",
+        "",
+        "One or more checks are marked `NEEDS-HUMAN` and require a person to validate:",
+        "",
+        ...guidance.split("\n").map((line) => `- ${line}`),
+      );
+    }
+  }
+
   return `${lines.join("\n")}\n`;
 }
 
@@ -1424,7 +1451,7 @@ export async function executeUatResultSave(
     }
     const gateVerdict = params.verdict === "PASS" ? "pass" : "flag";
     const rationale = params.notes ?? `UAT ${params.verdict} for ${params.sliceId}.`;
-    const assessment = renderUatAssessment(params, attempt, gateVerdict);
+    const assessment = renderUatAssessment(params, attempt, gateVerdict, basePath);
     const summary = await executeSummarySave(
       {
         milestone_id: params.milestoneId,
@@ -1468,8 +1495,20 @@ export async function executeUatResultSave(
       evaluatedAt,
     });
     invalidateStateCache();
+    // Surface where to validate when checks are left for a human, so the path
+    // (often a buried worktree checkout) reaches the reviewer, not just the file.
+    const hasHuman = params.checks.some((check) => check.result === "NEEDS-HUMAN");
+    const manualGuidance = hasHuman
+      ? buildManualValidationGuidance(basePath, params.milestoneId, {
+          uatPath: relSliceFile(basePath, params.milestoneId, params.sliceId, "UAT"),
+        })
+      : null;
+    const savedText = `UAT result saved for ${params.milestoneId}/${params.sliceId}: ${params.verdict}`;
     return {
-      content: [{ type: "text", text: `UAT result saved for ${params.milestoneId}/${params.sliceId}: ${params.verdict}` }],
+      content: [{
+        type: "text",
+        text: manualGuidance ? `${savedText}\n\nManual validation needed:\n${manualGuidance}` : savedText,
+      }],
       details: {
         operation: "save_uat_result",
         milestoneId: params.milestoneId,
@@ -1479,6 +1518,9 @@ export async function executeUatResultSave(
         attempt,
         attemptPath,
         recommendedNextUnit: params.verdict === "PASS" ? null : "reactive-execute",
+        ...(hasHuman
+          ? { manualValidationPath: resolveCanonicalMilestoneRoot(basePath, params.milestoneId) }
+          : {}),
       },
     };
   } catch (err) {