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

package/dist/resources/extensions/gsd/context-masker.js

@@ -5,13 +5,36 @@
  * Reduces context bloat between compactions with zero LLM overhead.
  * Preserves message ordering, roles, and all assistant/user messages.
  *
- * Operates on the pi-ai Message[] format (post-convertToLlm, pre-provider):
+ * Operates on provider payloads after convertToLlm:
+ *
+ * pi-ai Message[] payloads:
  *   - toolResult messages: { role: "toolResult", content: TextContent[] }
  *   - bash results are already converted to: { role: "user", content: [{type:"text",text:"..."}] }
  *     and start with "Ran `" from bashExecutionToText.
+ *
+ * OpenAI/Codex Responses payloads:
+ *   - conversation items live in `input`, not `messages`
+ *   - tool results are { type: "function_call_output", output: string | content[] }
+ *   - bash results are user items with input_text content starting with "Ran `"
  */
 const MASK_PLACEHOLDER = "[result masked — within summarized history]";
 const MASK_CONTENT_BLOCK = [{ type: "text", text: MASK_PLACEHOLDER }];
+const RESPONSES_MASK_CONTENT_BLOCK = [{ type: "input_text", text: MASK_PLACEHOLDER }];
+const TRUNCATION_MARKER = "\n…[truncated]";
+function isTextLikeBlock(block) {
+    return Boolean(block && typeof block === "object" && "text" in block);
+}
+function firstTextFromContent(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return undefined;
+    const first = content.find(isTextLikeBlock);
+    return typeof first?.text === "string" ? first.text : undefined;
+}
+function isBashResultText(text) {
+    return typeof text === "string" && text.startsWith("Ran `");
+}
 function findTurnBoundary(messages, keepRecentTurns) {
     let turnsSeen = 0;
     for (let i = messages.length - 1; i >= 0; i--) {
@@ -35,11 +58,9 @@ function findTurnBoundary(messages, keepRecentTurns) {
  * The bashExecutionToText format always starts with "Ran `".
  */
 function isBashResultUserMessage(m) {
-    if (m.role !== "user" || !Array.isArray(m.content))
+    if (m.role !== "user")
         return false;
-    const first = m.content[0];
-    return first && typeof first === "object" && "text" in first &&
-        typeof first.text === "string" && first.text.startsWith("Ran `");
+    return isBashResultText(firstTextFromContent(m.content));
 }
 function isMaskableMessage(m) {
     // Tool result messages (role: "toolResult" in pi-ai format)
@@ -66,3 +87,106 @@ export function createObservationMask(keepRecentTurns = 8) {
         });
     };
 }
+function isResponsesBashResultUserItem(item) {
+    if (item.role !== "user")
+        return false;
+    return isBashResultText(firstTextFromContent(item.content));
+}
+function findResponsesTurnBoundary(items, keepRecentTurns) {
+    let turnsSeen = 0;
+    for (let i = items.length - 1; i >= 0; i--) {
+        const item = items[i];
+        if (item.role === "user" && !isResponsesBashResultUserItem(item)) {
+            turnsSeen++;
+            if (turnsSeen >= keepRecentTurns)
+                return i;
+        }
+    }
+    return 0;
+}
+/**
+ * Observation masking for OpenAI/Codex Responses API payloads.
+ *
+ * Responses payloads store the conversation under `input` instead of
+ * `messages`, with tool results as `function_call_output` items. Keep this
+ * separate from createObservationMask so each payload shape stays explicit.
+ */
+export function createResponsesInputObservationMask(keepRecentTurns = 8) {
+    return (items) => {
+        const boundary = findResponsesTurnBoundary(items, keepRecentTurns);
+        if (boundary === 0)
+            return items;
+        return items.map((item, i) => {
+            if (i >= boundary)
+                return item;
+            if (item.type === "function_call_output") {
+                return { ...item, output: MASK_PLACEHOLDER };
+            }
+            if (isResponsesBashResultUserItem(item)) {
+                return { ...item, content: RESPONSES_MASK_CONTENT_BLOCK };
+            }
+            return item;
+        });
+    };
+}
+function truncateText(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    return text.slice(0, maxChars) + TRUNCATION_MARKER;
+}
+function truncateTextBlocks(content, maxChars) {
+    if (typeof content === "string") {
+        return truncateText(content, maxChars);
+    }
+    if (!Array.isArray(content))
+        return content;
+    let remaining = maxChars;
+    let didTruncate = false;
+    const nextBlocks = [];
+    for (const block of content) {
+        if (!isTextLikeBlock(block) || typeof block.text !== "string") {
+            nextBlocks.push(block);
+            continue;
+        }
+        if (remaining <= 0) {
+            didTruncate = true;
+            continue;
+        }
+        const text = block.text;
+        if (text.length <= remaining) {
+            nextBlocks.push(block);
+            remaining -= text.length;
+            continue;
+        }
+        nextBlocks.push({ ...block, text: truncateText(text, remaining) });
+        remaining = 0;
+        didTruncate = true;
+    }
+    return didTruncate ? nextBlocks : content;
+}
+function normalizedMaxChars(maxChars) {
+    return Number.isFinite(maxChars) && maxChars > 0 ? Math.floor(maxChars) : 800;
+}
+export function truncateContextResultMessages(messages, maxChars = 800) {
+    const limit = normalizedMaxChars(maxChars);
+    return messages.map((message) => {
+        if (!isMaskableMessage(message))
+            return message;
+        const content = truncateTextBlocks(message.content, limit);
+        return content === message.content ? message : { ...message, content };
+    });
+}
+export function truncateResponsesInputResultItems(items, maxChars = 800) {
+    const limit = normalizedMaxChars(maxChars);
+    return items.map((item) => {
+        if (item.type === "function_call_output") {
+            const output = truncateTextBlocks(item.output, limit);
+            return output === item.output ? item : { ...item, output };
+        }
+        if (isResponsesBashResultUserItem(item)) {
+            const content = truncateTextBlocks(item.content, limit);
+            return content === item.content ? item : { ...item, content };
+        }
+        return item;
+    });
+}

package/dist/resources/extensions/gsd/guided-flow.js

@@ -865,7 +865,10 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType,
                     ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider)
                     : undefined,
             baseUrl: result.appliedModel?.baseUrl ?? ctx.model?.baseUrl,
-            activeTools: typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [],
+            // Guided flow starts the MCP workflow server as part of dispatch, so the
+            // parent session's activeTools doesn't include MCP tools yet. The MCP
+            // launch config check (detectWorkflowMcpLaunchConfig) is the right gate
+            // here — not whether MCP tools are pre-registered in the parent session.
         });
         if (compatibilityError) {
             ctx.ui.notify(compatibilityError, "error");

package/dist/resources/extensions/gsd/planner-handoff.js

@@ -0,0 +1,98 @@
+// Project/App: gsd-pi
+// File Purpose: Optional gsd-planner handoff after milestone planning.
+import { spawn as spawnChild } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { gsdRoot } from "./paths.js";
+export const PLANNER_HANDOFF_RULE_NAME = "planning review handoff -> gsd-planner";
+export const GSD_PLANNER_COMMAND = "gsd-planner";
+function handoffDir(basePath) {
+    return join(gsdRoot(basePath), "runtime", "planner-handoffs");
+}
+function safeMilestoneFileSegment(milestoneId) {
+    return milestoneId.replace(/[^A-Za-z0-9._-]/g, "_") || "unknown";
+}
+function handoffMarkerPath(basePath, milestoneId) {
+    return join(handoffDir(basePath), `${safeMilestoneFileSegment(milestoneId)}.json`);
+}
+export function hasPlannerHandoffBeenOffered(basePath, milestoneId) {
+    return existsSync(handoffMarkerPath(basePath, milestoneId));
+}
+export function markPlannerHandoffOffered(basePath, milestoneId, source = "auto") {
+    mkdirSync(handoffDir(basePath), { recursive: true });
+    writeFileSync(handoffMarkerPath(basePath, milestoneId), JSON.stringify({
+        milestoneId,
+        source,
+        offeredAt: new Date().toISOString(),
+    }, null, 2) + "\n", "utf-8");
+}
+export function buildGsdPlannerSpawnPlan(input) {
+    const args = ["--project", input.basePath];
+    const milestoneId = input.milestoneId?.trim();
+    if (milestoneId)
+        args.push("--milestone", milestoneId);
+    args.push(...(input.extraArgs ?? []));
+    return {
+        command: GSD_PLANNER_COMMAND,
+        args,
+        cwd: input.basePath,
+    };
+}
+function quoteArg(arg) {
+    return /^[A-Za-z0-9_./:=@+-]+$/.test(arg) ? arg : JSON.stringify(arg);
+}
+export function formatGsdPlannerCommand(plan) {
+    return [plan.command, ...plan.args].map(quoteArg).join(" ");
+}
+export async function launchGsdPlanner(input, deps = {}) {
+    const plan = buildGsdPlannerSpawnPlan(input);
+    const spawn = deps.spawn ?? spawnChild;
+    let child;
+    try {
+        child = spawn(plan.command, plan.args, {
+            cwd: plan.cwd,
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+        });
+    }
+    catch (err) {
+        return {
+            status: "failed",
+            plan,
+            error: err instanceof Error ? err : new Error(String(err)),
+        };
+    }
+    return new Promise((resolve) => {
+        let settled = false;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(result);
+        };
+        child.once("error", (err) => {
+            settle({
+                status: "failed",
+                plan,
+                error: err instanceof Error ? err : new Error(String(err)),
+            });
+        });
+        child.once("spawn", () => {
+            child.unref();
+            settle({ status: "launched", plan });
+        });
+    });
+}
+export function formatPlannerHandoffPauseReason(milestoneId) {
+    return [
+        `Milestone ${milestoneId} is planned. Review or customize the plan before implementation if needed.`,
+        `Run /gsd planner to launch ${GSD_PLANNER_COMMAND}, or run /gsd auto to continue without planner changes.`,
+    ].join(" ");
+}
+export function formatPlannerLaunchUnavailable(plan, error) {
+    return [
+        `Could not launch ${GSD_PLANNER_COMMAND}: ${error.message}`,
+        `Install ${GSD_PLANNER_COMMAND} or run it manually: ${formatGsdPlannerCommand(plan)}`,
+    ].join("\n");
+}

package/dist/resources/extensions/gsd/preferences-models.js

@@ -339,6 +339,7 @@ export function resolveAutoSupervisorConfig() {
         soft_timeout_minutes: configured.soft_timeout_minutes ?? 20,
         idle_timeout_minutes: configured.idle_timeout_minutes ?? 10,
         hard_timeout_minutes: configured.hard_timeout_minutes ?? 30,
+        stalled_tool_timeout_minutes: configured.stalled_tool_timeout_minutes ?? 5,
         ...(configured.model ? { model: configured.model } : {}),
     };
 }

package/dist/resources/extensions/gsd/prompts/plan-milestone.md

@@ -14,7 +14,7 @@ All relevant context is preloaded below. Start immediately without re-reading th
 
 ## Already Planned? Soft Brake
 
-If `{{outputPath}}` exists with at least one slice line (e.g. `- [ ] **S01:`) AND `gsd_query` reports slice rows for this milestone, a prior `gsd_plan_milestone` call already persisted the plan. Do **not** re-call it; its UPSERT could overwrite existing planning. Skip to the ready phrase.
+If `{{outputPath}}` exists with at least one slice line (e.g. `- [ ] **S01:`) AND `gsd_milestone_status` reports slice rows for this milestone, a prior `gsd_plan_milestone` call already persisted the plan. Do **not** re-call it; its UPSERT could overwrite existing planning. Skip to the ready phrase.
 
 If only the file or only DB rows exist, the prior write was incomplete; plan normally so the tool reconciles both.
 

package/dist/resources/extensions/gsd/prompts/run-uat.md

@@ -27,7 +27,7 @@ You are the UAT runner. Execute every check defined in `{{uatPath}}` as deeply a
 ### Automation rules by mode
 
 - `artifact-driven` — verify with shell commands, scripts, file reads, and artifact structure checks.
-- `browser-executable` — use gsd-browser tools to navigate to the target URL and verify expected behavior. Prefer `mcp__gsd-browser__browser_*` tools when namespaced, or direct `browser_*` tools when surfaced without a namespace. Capture screenshots as evidence. Record pass/fail with specific assertions.
+- `browser-executable` — use browser tools to navigate to the target URL and verify expected behavior. Prefer direct `browser_*` tools when available. Capture screenshots as evidence. Record pass/fail with specific assertions.
 - `runtime-executable` — execute the specified command or script. Capture stdout/stderr as evidence. Record pass/fail based on exit code and output.
 - `live-runtime` — exercise the real runtime path. Start or connect to the app/service if needed, use browser/runtime/network checks, and verify observable behavior.
 - `mixed` — run all automatable artifact-driven and live-runtime checks. Separate any remaining human-only checks explicitly.
@@ -48,7 +48,7 @@ Choose the lightest tool that proves the check honestly:
 - Run `node` / other script invocations
 - Read files and verify their contents
 - Check that expected artifacts exist and have correct structure
-- For live/runtime/UI checks, exercise the real flow with gsd-browser when applicable and inspect runtime/network/console state
+- For live/runtime/UI checks, exercise the real flow with browser tools when applicable and inspect runtime/network/console state
 - When a check cannot be honestly automated, gather the best objective evidence you can and mark it `NEEDS-HUMAN`
 
 For each check, record:

package/dist/resources/extensions/gsd/prompts/system.md

@@ -118,7 +118,7 @@ Templates are in `{{templatesDir}}`.
 
 **Secrets:** Use `secure_env_collect`. Never ask the user to edit `.env` files or paste secrets.
 
-**Browser verification:** Verify frontend work against a running app with gsd-browser by default. Use `browser_find`/`browser_snapshot_refs` for discovery, refs/selectors -> `browser_batch` for actions, `browser_assert` for verification, and `browser_diff` -> console/network logs -> full inspection as last resort. If tools are MCP-namespaced, prefer `mcp__gsd-browser__browser_*`. Retry only with a new hypothesis.
+**Browser verification:** Verify frontend work against a running app with browser tools by default. Use `browser_find`/`browser_snapshot_refs` for discovery, refs/selectors -> `browser_batch` for actions, `browser_assert` for verification, and `browser_diff` -> console/network logs -> full inspection as last resort. If browser tools are MCP-namespaced, use that host-provided browser surface. Retry only with a new hypothesis.
 
 **Database:** Never query `.gsd/gsd.db` directly via `sqlite3`, `better-sqlite3`, or `node -e require('better-sqlite3')`; the engine owns a single-writer WAL connection. Use `gsd_milestone_status`, `gsd_journal_query`, or other `gsd_*` tools.
 

package/dist/resources/extensions/gsd/skill-manifest.js

@@ -114,6 +114,18 @@ const UNIT_TYPE_SKILL_MANIFEST = {
         "review",
         "accessibility",
     ],
+    // Slice closeout — the "closer" role: verify assembled task work, write the
+    // downstream-ready summary + UAT, optionally drive reviewer/security/tester
+    // subagents. Predictable skill set, mirrors `complete-milestone`.
+    "complete-slice": [
+        "verify-before-complete",
+        "test",
+        "review",
+        "security-review",
+        "write-docs",
+        "observability",
+        "handoff",
+    ],
     // `execute-task` intentionally omitted — implementation hot path covers a
     // wide surface of technologies; wildcard fallback preserves today's
     // behavior until per-task skill hints can be derived from task-plan

package/dist/resources/extensions/gsd/tool-contract.js

@@ -16,7 +16,7 @@ export function compileUnitToolContract(unitType) {
     const requiredWorkflowTools = getRequiredWorkflowToolsForAutoUnit(unitType);
     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));
+    const closeoutTools = requiredWorkflowTools.filter((tool) => /^gsd_(?:task|slice|milestone|complete|validate|save|summary|uat)/.test(tool));
     if (requiresCloseoutTool(unitType) && closeoutTools.length === 0) {
         return {
             ok: false,

package/dist/resources/extensions/gsd/tool-presentation-plan.js

@@ -73,11 +73,28 @@ export function buildRunUatCanonicalToolNames(options = {}) {
         ...(options.includeBrowserTools ?? []),
     ]);
 }
+// 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 = [
+    "browser-executable",
+    "live-runtime",
+    "mixed",
+    "human-experience",
+];
+function uatTypeIncludesBrowser(uatType) {
+    return uatType !== undefined && BROWSER_INCLUSIVE_UAT_TYPES.includes(uatType);
+}
 export function runUatBrowserToolsForType(uatType) {
-    return uatType === "browser-executable" ? RUN_UAT_BROWSER_TOOL_NAMES : [];
+    return uatTypeIncludesBrowser(uatType) ? RUN_UAT_BROWSER_TOOL_NAMES : [];
 }
 export function runUatPresentationSurfaceForType(uatType) {
-    return uatType === "browser-executable" ? "hybrid" : "mcp";
+    return uatTypeIncludesBrowser(uatType) ? "hybrid" : "mcp";
 }
 export function buildRunUatPresentationForType(uatType, options = {}) {
     return buildRunUatResultPresentation({

package/dist/resources/extensions/gsd/tools/complete-slice.js

@@ -17,7 +17,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";
@@ -267,6 +268,32 @@ export async function handleCompleteSlice(params, basePath) {
     if (BLOCKED_SIGNALS.test(params.verification || "") || BLOCKED_SIGNALS.test(params.uatContent || "")) {
         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 = null;

package/dist/resources/extensions/gsd/tools/workflow-tool-executors.js

@@ -6,8 +6,9 @@ import { loadWriteGateSnapshot, shouldBlockContextArtifactSaveInSnapshot, should
 import { getActiveRequirements, insertMilestone, getMilestone, getSliceStatusSummary, getSliceTaskCounts, insertGateRun, readTransaction, saveGateResult, upsertQualityGate, } 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 { handleCompleteMilestone } from "./complete-milestone.js";
@@ -1106,7 +1107,7 @@ function escapeMarkdownTableCell(value) {
         .replace(/[\\|]/g, (char) => `\\${char}`)
         .replace(/\r?\n/g, "<br>");
 }
-function renderUatAssessment(params, attempt, gateVerdict) {
+function renderUatAssessment(params, attempt, gateVerdict, basePath) {
     const lines = [
         "---",
         `sliceId: ${params.sliceId}`,
@@ -1141,6 +1142,18 @@ function renderUatAssessment(params, attempt, gateVerdict) {
         "",
         `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`;
 }
 async function saveUatAttemptArtifact(basePath, params, attempt) {
@@ -1190,7 +1203,7 @@ export async function executeUatResultSave(params, basePath = process.cwd()) {
         }
         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,
             slice_id: params.sliceId,
@@ -1232,8 +1245,20 @@ export async function executeUatResultSave(params, basePath = process.cwd()) {
             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,
@@ -1243,6 +1268,9 @@ export async function executeUatResultSave(params, basePath = process.cwd()) {
                 attempt,
                 attemptPath,
                 recommendedNextUnit: params.verdict === "PASS" ? null : "reactive-execute",
+                ...(hasHuman
+                    ? { manualValidationPath: resolveCanonicalMilestoneRoot(basePath, params.milestoneId) }
+                    : {}),
             },
         };
     }

package/dist/resources/extensions/gsd/unit-tool-contracts.js

@@ -41,8 +41,14 @@ export const UNIT_TOOL_CONTRACTS = {
         requiredWorkflowTools: ["gsd_summary_save"],
     },
     "plan-milestone": {
-        allowedGsdTools: ["gsd_plan_milestone", "gsd_decision_save", "gsd_requirement_update"],
-        requiredWorkflowTools: ["gsd_plan_milestone"],
+        allowedGsdTools: [
+            "gsd_milestone_status",
+            "gsd_plan_milestone",
+            "gsd_plan_slice",
+            "gsd_decision_save",
+            "gsd_requirement_update",
+        ],
+        requiredWorkflowTools: ["gsd_milestone_status", "gsd_plan_milestone", "gsd_plan_slice"],
     },
     "discuss-milestone": {
         allowedGsdTools: [
@@ -66,27 +72,38 @@ export const UNIT_TOOL_CONTRACTS = {
         requiredWorkflowTools: ["gsd_summary_save"],
     },
     "validate-milestone": {
-        allowedGsdTools: ["gsd_validate_milestone", "gsd_reassess_roadmap", "subagent"],
+        allowedGsdTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap", "subagent"],
         requiredWorkflowTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap"],
     },
     "complete-milestone": {
-        allowedGsdTools: ["gsd_complete_milestone", "subagent"],
-        requiredWorkflowTools: ["gsd_milestone_status", "gsd_complete_milestone"],
+        allowedGsdTools: [
+            "gsd_milestone_status",
+            "gsd_requirement_update",
+            "gsd_summary_save",
+            "gsd_complete_milestone",
+            "subagent",
+        ],
+        requiredWorkflowTools: [
+            "gsd_milestone_status",
+            "gsd_requirement_update",
+            "gsd_summary_save",
+            "gsd_complete_milestone",
+        ],
     },
     "research-slice": {
         allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
         requiredWorkflowTools: ["gsd_summary_save"],
     },
     "plan-slice": {
-        allowedGsdTools: ["gsd_plan_slice", "gsd_plan_task", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_plan_slice"],
+        allowedGsdTools: ["gsd_plan_slice", "gsd_reassess_roadmap", "gsd_decision_save"],
+        requiredWorkflowTools: ["gsd_plan_slice", "gsd_reassess_roadmap"],
     },
     "refine-slice": {
-        allowedGsdTools: ["gsd_plan_slice", "gsd_plan_task", "gsd_decision_save"],
-        requiredWorkflowTools: [],
+        allowedGsdTools: ["gsd_plan_slice", "gsd_decision_save"],
+        requiredWorkflowTools: ["gsd_plan_slice"],
     },
     "replan-slice": {
-        allowedGsdTools: ["gsd_replan_slice", "gsd_plan_task", "gsd_decision_save"],
+        allowedGsdTools: ["gsd_replan_slice", "gsd_decision_save"],
         requiredWorkflowTools: ["gsd_replan_slice"],
     },
     "complete-slice": {
@@ -96,15 +113,22 @@ export const UNIT_TOOL_CONTRACTS = {
             "gsd_replan_slice",
             "gsd_decision_save",
             "gsd_requirement_update",
+            "gsd_summary_save",
             "subagent",
         ],
-        requiredWorkflowTools: ["gsd_slice_complete", "gsd_task_reopen", "gsd_replan_slice"],
+        requiredWorkflowTools: [
+            "gsd_slice_complete",
+            "gsd_task_reopen",
+            "gsd_replan_slice",
+            "gsd_requirement_update",
+            "gsd_summary_save",
+        ],
         forbiddenGsdTools: {
             gsd_uat_result_save: "Run UAT owns persisted UAT Assessment.",
         },
     },
     "reassess-roadmap": {
-        allowedGsdTools: ["gsd_reassess_roadmap"],
+        allowedGsdTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
         requiredWorkflowTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
     },
     "execute-task": {
@@ -116,8 +140,8 @@ export const UNIT_TOOL_CONTRACTS = {
         requiredWorkflowTools: ["gsd_task_complete"],
     },
     "reactive-execute": {
-        allowedGsdTools: ["gsd_task_complete", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_task_complete"],
+        allowedGsdTools: ["gsd_task_complete", "gsd_summary_save", "gsd_decision_save"],
+        requiredWorkflowTools: ["gsd_task_complete", "gsd_summary_save"],
     },
     "run-uat": {
         allowedGsdTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES, "subagent"],

package/dist/resources/extensions/gsd/workflow-mcp.js

@@ -409,10 +409,9 @@ export function getWorkflowTransportSupportError(provider, requiredTools, option
         return `Provider ${providerLabel} cannot run ${surface}${unitLabel}: the GSD workflow MCP server is not configured or discoverable. Detected Claude Code model but no workflow MCP. Please run /gsd mcp init . from your project root. You can also configure GSD_WORKFLOW_MCP_COMMAND, build packages/mcp-server/dist/cli.js, or install gsd-mcp-server on PATH.`;
     }
     const uniqueRequired = [...new Set(requiredTools)];
-    const piRuntimeRequired = uniqueRequired.filter((tool) => !MCP_WORKFLOW_TOOL_SURFACE.has(tool));
     const missing = (options.activeTools && options.activeTools.length > 0)
-        ? piRuntimeRequired.filter((tool) => !hasRequiredTool(tool, options.activeTools))
-        : piRuntimeRequired;
+        ? uniqueRequired.filter((tool) => !hasRequiredTool(tool, options.activeTools))
+        : uniqueRequired.filter((tool) => !MCP_WORKFLOW_TOOL_SURFACE.has(tool));
     if (missing.length === 0)
         return null;
     if (options.activeTools && options.activeTools.length > 0) {

package/dist/resources/extensions/gsd/worktree-manager.js

@@ -185,6 +185,32 @@ export function resolveCanonicalMilestoneRoot(basePath, milestoneId) {
     }
     return wtPath;
 }
+/**
+ * Build human-facing guidance for manually validating a milestone's work.
+ *
+ * When a milestone runs in a git worktree, its checkout lives under the hidden
+ * `.gsd/worktrees/<MID>/` path that a human can't easily discover. The UAT
+ * pause/handoff and the saved assessment use this to tell the human exactly
+ * where to `cd` to run or inspect the app before signing off on NEEDS-HUMAN
+ * checks, rather than leaving them to hunt for a buried path.
+ *
+ * Returns null when no milestone id is available.
+ */
+export function buildManualValidationGuidance(basePath, milestoneId, opts = {}) {
+    if (!milestoneId)
+        return null;
+    const validationRoot = resolveCanonicalMilestoneRoot(basePath, milestoneId);
+    const inWorktree = validationRoot.includes(`${sep}.gsd${sep}worktrees${sep}`);
+    const lines = [`Validate the work here: ${validationRoot}`];
+    if (inWorktree) {
+        lines.push("This milestone runs in a git worktree, so the code lives under the hidden " +
+            `\`.gsd/worktrees/\` path. Open it with: cd "${validationRoot}"`);
+    }
+    if (opts.uatPath) {
+        lines.push(`Follow the UAT checklist at: ${opts.uatPath}`);
+    }
+    return lines.join("\n");
+}
 // ─── Core Operations ───────────────────────────────────────────────────────
 /**
  * Create a new git worktree under .gsd/worktrees/<name>/ with branch worktree/<name>.