@opengsd/gsd-pi 1.1.1-dev.a5a2de8 → 1.1.1-dev.b2556262

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

@@ -3,13 +3,13 @@
 import { ensureDbOpen } from "../bootstrap/dynamic-tools.js";
 import { sanitizeCompleteMilestoneParams } from "../bootstrap/sanitize-complete-milestone.js";
 import { loadWriteGateSnapshot, shouldBlockContextArtifactSaveInSnapshot, shouldBlockRootArtifactSaveInSnapshot } from "../bootstrap/write-gate.js";
-import { getActiveRequirements, insertMilestone, getMilestone, getSliceStatusSummary, getSliceTaskCounts, insertGateRun, readTransaction, saveGateResult, upsertQualityGate, } from "../gsd-db.js";
+import { getActiveRequirements, insertMilestone, getMilestone, getSliceStatusSummary, getSliceTaskCounts, insertAssessment, 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 { existsSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
-import { isAbsolute, join, resolve } from "node:path";
+import { unlinkSync } from "node:fs";
+import { join } from "node:path";
 import { handleCompleteMilestone } from "./complete-milestone.js";
 import { handleCompleteTask } from "./complete-task.js";
 import { handleCompleteSlice } from "./complete-slice.js";
@@ -26,7 +26,8 @@ import { invalidateStateCache } from "../state.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { parseProject } from "../schemas/parsers.js";
 import { getAutoRuntimeSnapshot } from "../auto-runtime-state.js";
-import { buildRunUatResultPresentation, canonicalWorkflowToolName, parseMcpToolName, RUN_UAT_FORBIDDEN_TOOL_NAMES, RUN_UAT_TOOL_PRESENTATION_PLAN_ID, RUN_UAT_WORKFLOW_TOOL_NAMES, } from "../tool-presentation-plan.js";
+import { renderPlanFromDb } from "../markdown-renderer.js";
+import { prepareUatRun, saveUatAttemptArtifact, } from "../uat-run.js";
 export const SUPPORTED_SUMMARY_ARTIFACT_TYPES = [
     "SUMMARY",
     "RESEARCH",
@@ -790,6 +791,7 @@ export async function executeSaveGateResult(params, basePath = process.cwd()) {
             rationale: params.rationale,
             findings: params.findings ?? "",
         });
+        await renderPlanFromDb(basePath, params.milestoneId, params.sliceId);
         invalidateStateCache();
         return {
             content: [{ type: "text", text: `Gate ${params.gateId} result saved: verdict=${params.verdict}` }],
@@ -813,436 +815,90 @@ function errorResult(operation, message, error) {
         isError: true,
     };
 }
-function isNonEmptyString(value) {
-    return typeof value === "string" && value.trim().length > 0;
-}
-function mergeBlockedTools(current, canonical) {
-    const merged = new Map();
-    for (const entry of [...(current ?? []), ...canonical]) {
-        merged.set(canonicalWorkflowToolName(parseMcpToolName(entry.name)?.tool ?? entry.name), entry);
-    }
-    return [...merged.values()];
-}
-function mergePresentedTools(current, canonical) {
-    return [...new Set([...(current ?? []), ...canonical])];
-}
-function normalizeUatVerdict(params) {
-    const raw = params;
-    if (typeof raw.verdict === "string") {
-        return { ...params, verdict: raw.verdict.toUpperCase() };
-    }
-    return params;
-}
-function supplyDefaultPresentation(params) {
-    const raw = params;
-    if (!raw.presentation) {
-        return { ...params, presentation: buildRunUatResultPresentation() };
-    }
-    return params;
-}
-function mergeCanonicalPresentation(params) {
-    const canonicalPresentation = buildRunUatResultPresentation();
-    const providedPresentation = params.presentation;
-    return {
-        ...params,
-        presentation: {
-            ...providedPresentation,
-            surface: providedPresentation.surface ?? canonicalPresentation.surface,
-            presentedTools: mergePresentedTools(providedPresentation.presentedTools, canonicalPresentation.presentedTools),
-            blockedTools: mergeBlockedTools(providedPresentation.blockedTools, canonicalPresentation.blockedTools),
-            toolPresentationPlanId: RUN_UAT_TOOL_PRESENTATION_PLAN_ID,
-        },
-    };
-}
-const VALID_UAT_TYPES = [
-    "artifact-driven",
-    "browser-executable",
-    "runtime-executable",
-    "live-runtime",
-    "mixed",
-    "human-experience",
-];
-function ensureUatRequiredFields(params) {
-    if (!isNonEmptyString(params.milestoneId))
-        return "milestoneId is required";
-    if (!isNonEmptyString(params.sliceId))
-        return "sliceId is required";
-    if (!isNonEmptyString(params.uatType))
-        return "uatType is required";
-    if (!VALID_UAT_TYPES.includes(params.uatType)) {
-        return `uatType must be one of: ${VALID_UAT_TYPES.join(", ")}`;
-    }
-    if (!["PASS", "FAIL", "PARTIAL"].includes(params.verdict))
-        return "verdict must be PASS, FAIL, or PARTIAL";
-    if (!Array.isArray(params.checks) || params.checks.length === 0)
-        return "checks must contain at least one UAT check";
-    if (!params.presentation || !Array.isArray(params.presentation.presentedTools))
-        return "presentation.presentedTools is required";
-    if (!Array.isArray(params.presentation.blockedTools))
-        return "presentation.blockedTools is required";
-    return null;
-}
-function approvedEvidenceRoots(basePath) {
-    const contract = resolveGsdPathContract(basePath);
-    return [contract.worktreeGsd, contract.projectGsd].filter((root) => typeof root === "string");
-}
-function approvedBrowserArtifactRoots(basePath) {
-    const contract = resolveGsdPathContract(basePath);
-    const roots = [contract.workRoot, contract.projectRoot].map((root) => join(root, ".artifacts", "browser"));
-    return [...new Set(roots)];
-}
-function pathStartsWithin(parent, target) {
-    const normalizedParent = parent.replace(/\\/g, "/").replace(/\/+$/, "");
-    const normalizedTarget = target.replace(/\\/g, "/").replace(/\/+$/, "");
-    return normalizedTarget === normalizedParent || normalizedTarget.startsWith(`${normalizedParent}/`);
-}
-function pushUnique(paths, candidate) {
-    if (!paths.includes(candidate))
-        paths.push(candidate);
-}
-function execMetaPathCandidates(basePath, ref) {
-    const trimmed = ref.trim();
-    const candidates = [];
-    const execDirs = approvedEvidenceRoots(basePath).map((root) => join(root, "exec"));
-    const normalizedRef = trimmed.replace(/\\/g, "/");
-    const pathLike = normalizedRef.endsWith(".meta.json") || normalizedRef.includes("/.gsd/exec/");
-    if (pathLike) {
-        const rawPath = isAbsolute(trimmed) ? resolve(trimmed) : resolve(basePath, trimmed);
-        pushUnique(candidates, rawPath);
-        const relativeExecMarker = ".gsd/exec/";
-        const markerIndex = normalizedRef.indexOf(relativeExecMarker);
-        if (markerIndex >= 0) {
-            const execRelative = normalizedRef.slice(markerIndex + relativeExecMarker.length);
-            for (const execDir of execDirs) {
-                pushUnique(candidates, join(execDir, execRelative));
-            }
-        }
-        return candidates.filter((candidate) => execDirs.some((execDir) => pathStartsWithin(execDir, candidate)));
-    }
-    for (const execDir of execDirs) {
-        pushUnique(candidates, join(execDir, `${trimmed}.meta.json`));
-    }
-    return candidates;
-}
-function resolveExecMetaPath(basePath, ref) {
-    for (const candidate of execMetaPathCandidates(basePath, ref)) {
-        if (existsSync(candidate))
-            return candidate;
-    }
-    return null;
-}
-function evidencePathIsApproved(basePath, ref) {
-    const normalizedRef = ref.replace(/\\/g, "/");
-    if (normalizedRef.startsWith(".gsd/exec/") || normalizedRef.startsWith(".gsd/uat/"))
-        return true;
-    if (normalizedRef.startsWith(".artifacts/browser/")) {
-        const resolvedRef = resolve(basePath, ref);
-        return approvedBrowserArtifactRoots(basePath).some((root) => pathStartsWithin(root, resolvedRef));
-    }
-    const gsdEvidenceApproved = approvedEvidenceRoots(basePath).some((root) => {
-        return pathStartsWithin(join(root, "exec"), ref) || pathStartsWithin(join(root, "uat"), ref);
-    });
-    if (gsdEvidenceApproved)
-        return true;
-    return approvedBrowserArtifactRoots(basePath).some((root) => pathStartsWithin(root, ref));
-}
-function validateEvidenceRef(basePath, evidence) {
-    if (!isNonEmptyString(evidence.ref))
-        return "evidence.ref is required";
-    if (evidence.kind === "gsd_uat_exec" || evidence.kind === "gsd_exec") {
-        const path = resolveExecMetaPath(basePath, evidence.ref.trim());
-        if (!path)
-            return `missing gsd_exec metadata for evidence id "${evidence.ref}"`;
-        if (evidence.kind === "gsd_uat_exec") {
-            try {
-                const meta = JSON.parse(readFileSync(path, "utf-8"));
-                if (meta.metadata?.kind !== "uat_exec")
-                    return `evidence id "${evidence.ref}" is not typed as uat_exec`;
-            }
-            catch {
-                return `invalid gsd_exec metadata JSON for evidence id "${evidence.ref}"`;
-            }
-        }
-        return null;
-    }
-    if (evidence.kind === "url") {
-        try {
-            const parsed = new URL(evidence.ref);
-            return parsed.protocol === "http:" || parsed.protocol === "https:"
-                ? null
-                : `invalid URL evidence ref "${evidence.ref}"`;
-        }
-        catch {
-            return `invalid URL evidence ref "${evidence.ref}"`;
-        }
-    }
-    return evidencePathIsApproved(basePath, evidence.ref)
-        ? null
-        : `evidence ref "${evidence.ref}" is outside approved evidence locations`;
-}
-function validateUatChecks(basePath, params) {
-    for (const check of params.checks) {
-        if (!isNonEmptyString(check.id))
-            return "every check must have a non-empty id";
-        if (!isNonEmptyString(check.description))
-            return `check ${check.id} must have a description`;
-        if (!["artifact", "runtime", "browser", "human-follow-up"].includes(check.mode)) {
-            return `check ${check.id} has invalid mode "${check.mode}"`;
-        }
-        if (!["PASS", "FAIL", "NEEDS-HUMAN"].includes(check.result)) {
-            return `check ${check.id} has invalid result "${check.result}"`;
-        }
-        if (check.result === "PASS" || check.result === "FAIL") {
-            if (!Array.isArray(check.evidence) || check.evidence.length === 0) {
-                return `check ${check.id} is ${check.result} but has no objective evidence`;
-            }
-            for (const evidence of check.evidence) {
-                const error = validateEvidenceRef(basePath, evidence);
-                if (error)
-                    return `check ${check.id}: ${error}`;
-            }
-        }
-        else if (!isNonEmptyString(check.notes)) {
-            return `check ${check.id} is NEEDS-HUMAN but has no manual instruction or reason`;
-        }
-    }
-    return null;
-}
-function validateFreshUatOwnedEvidence(params) {
-    const hasFreshUatEvidence = params.checks.some((check) => (check.evidence ?? []).some((evidence) => evidence.kind === "gsd_uat_exec"));
-    return hasFreshUatEvidence
-        ? null
-        : "UAT Assessment requires at least one fresh gsd_uat_exec evidence reference from run-uat";
-}
-function validateUatMode(params) {
-    const modes = new Set(params.checks.map((check) => check.mode));
-    const hasHuman = params.checks.some((check) => check.result === "NEEDS-HUMAN");
-    if (params.uatType === "artifact-driven" && hasHuman && params.verdict === "PASS") {
-        return "artifact-driven UAT cannot PASS with human-only checks";
-    }
-    if (hasHuman &&
-        params.verdict === "PASS" &&
-        !["human-experience", "mixed", "live-runtime"].includes(params.uatType) &&
-        !params.checks.every((check) => check.result !== "NEEDS-HUMAN" || check.nonAutomatable === true)) {
-        return "NEEDS-HUMAN checks can only coexist with PASS for human-experience, mixed, live-runtime, or explicitly non-automatable checks";
-    }
-    if (params.uatType === "runtime-executable" && !modes.has("runtime")) {
-        return "runtime-executable UAT requires at least one runtime check";
-    }
-    if (params.uatType === "browser-executable" && !modes.has("browser")) {
-        return "browser-executable UAT requires at least one browser check";
-    }
-    if (params.uatType === "live-runtime" && !modes.has("runtime") && !modes.has("browser")) {
-        return "live-runtime UAT requires runtime or browser evidence";
-    }
-    return null;
-}
-function quoteToolNames(toolNames) {
-    return toolNames.map((toolName) => `"${toolName}"`).join(", ");
-}
-function validateCanonicalPresentation(params) {
-    const aliasHints = {
-        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 = [];
-    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 presentedCanonical = new Set(params.presentation.presentedTools.map((toolName) => canonicalWorkflowToolName(parseMcpToolName(toolName)?.tool ?? toolName)));
-    const missingRequiredTools = RUN_UAT_WORKFLOW_TOOL_NAMES.filter((requiredTool) => !presentedCanonical.has(requiredTool));
-    if (missingRequiredTools.length === 1) {
-        errors.push(`presentation is missing required UAT tool "${missingRequiredTools[0]}"`);
-    }
-    else if (missingRequiredTools.length > 1) {
-        errors.push(`presentation is missing required UAT tools ${quoteToolNames(missingRequiredTools)}`);
-    }
-    const forbiddenCanonical = new Set(RUN_UAT_FORBIDDEN_TOOL_NAMES
-        .filter((toolName) => !toolName.includes("*"))
-        .map((toolName) => canonicalWorkflowToolName(parseMcpToolName(toolName)?.tool ?? toolName)));
-    const forbiddenPresentedTools = [];
-    for (const toolName of params.presentation.presentedTools) {
-        const canonical = canonicalWorkflowToolName(parseMcpToolName(toolName)?.tool ?? toolName);
-        if (toolName === "mcp__gsd-workflow__*" || forbiddenCanonical.has(canonical)) {
-            forbiddenPresentedTools.push(toolName);
-        }
-    }
-    if (forbiddenPresentedTools.length === 1) {
-        errors.push(`presentation includes forbidden run-uat tool "${forbiddenPresentedTools[0]}"`);
-    }
-    else if (forbiddenPresentedTools.length > 1) {
-        errors.push(`presentation includes forbidden run-uat tools ${quoteToolNames(forbiddenPresentedTools)}`);
-    }
-    const blockedCanonical = new Set(params.presentation.blockedTools.map((entry) => canonicalWorkflowToolName(parseMcpToolName(entry.name)?.tool ?? entry.name)));
-    const missingBlockedTools = ["gsd_exec", "gsd_summary_save", "gsd_save_gate_result"].filter((blockedTool) => !blockedCanonical.has(blockedTool));
-    if (missingBlockedTools.length === 1) {
-        errors.push(`presentation must record "${missingBlockedTools[0]}" as blocked during run-uat`);
-    }
-    else if (missingBlockedTools.length > 1) {
-        errors.push(`presentation must record ${quoteToolNames(missingBlockedTools)} as blocked during run-uat`);
-    }
-    return errors.length > 0 ? errors.join("; ") : null;
-}
-function nextUatAttempt(basePath, milestoneId, sliceId) {
-    const contract = resolveGsdPathContract(basePath);
-    const dir = join(contract.projectGsd, "uat", milestoneId, sliceId);
-    if (!existsSync(dir))
-        return 1;
-    let max = 0;
-    for (const entry of readdirSync(dir)) {
-        const match = /^attempt-(\d+)\.json$/.exec(entry);
-        if (match)
-            max = Math.max(max, Number(match[1]));
-    }
-    return max + 1;
-}
-function escapeMarkdownTableCell(value) {
-    return String(value ?? "")
-        .replace(/[\\|]/g, (char) => `\\${char}`)
-        .replace(/\r?\n/g, "<br>");
-}
-function renderUatAssessment(params, attempt, gateVerdict) {
-    const lines = [
-        "---",
-        `sliceId: ${params.sliceId}`,
-        `uatType: ${params.uatType}`,
-        `verdict: ${params.verdict}`,
-        `attempt: ${attempt}`,
-        `date: ${new Date().toISOString()}`,
-        "---",
-        "",
-        `# UAT Result - ${params.sliceId}`,
-        "",
-        "## Checks",
-        "",
-        "| Check | Mode | Result | Evidence | Notes |",
-        "|-------|------|--------|----------|-------|",
-        ...params.checks.map((check) => {
-            const evidence = (check.evidence ?? []).map((entry) => `${entry.kind}:${entry.ref}`).join("<br>") || "-";
-            return `| ${escapeMarkdownTableCell(check.description)} | ${escapeMarkdownTableCell(check.mode)} | ${escapeMarkdownTableCell(check.result)} | ${escapeMarkdownTableCell(evidence)} | ${escapeMarkdownTableCell(check.notes)} |`;
-        }),
-        "",
-        "## Overall Verdict",
-        "",
-        `${params.verdict} - ${params.notes ?? "UAT result saved."}`,
-        "",
-        "## Tool Presentation",
-        "",
-        "```json",
-        JSON.stringify(params.presentation, null, 2),
-        "```",
-        "",
-        "## Gate",
-        "",
-        `Aggregate UAT gate saved as ${gateVerdict}.`,
-    ];
-    return `${lines.join("\n")}\n`;
-}
-async function saveUatAttemptArtifact(basePath, params, attempt) {
-    const contract = resolveGsdPathContract(basePath);
-    const relativePath = `uat/${params.milestoneId}/${params.sliceId}/attempt-${attempt}.json`;
-    await saveFile(join(contract.projectGsd, relativePath), `${JSON.stringify({ ...params, attempt }, null, 2)}\n`);
-    return relativePath;
-}
 export async function executeUatResultSave(params, basePath = process.cwd()) {
     const unitGuard = blockIfWrongAutoUnit("run-uat", "save_uat_result");
     if (unitGuard)
         return unitGuard;
-    // Phase 1: normalize verdict and supply the canonical presentation when none was provided.
-    params = normalizeUatVerdict(params);
-    params = supplyDefaultPresentation(params);
     const dbAvailable = await ensureDbOpen(basePath);
     if (!dbAvailable)
         return errorResult("save_uat_result", "GSD database is not available.", "db_unavailable");
-    // Phase 2: validate the submitted presentation before the canonical merge so that
-    // presentations missing required workflow tools are rejected rather than silently patched.
-    const requiredError = ensureUatRequiredFields(params);
-    if (requiredError)
-        return errorResult("save_uat_result", requiredError, "invalid_params");
-    const presentationError = validateCanonicalPresentation(params);
-    if (presentationError)
-        return errorResult("save_uat_result", presentationError, "alias_tool_name");
-    // Phase 3: merge in the canonical plan ID and read-only audit tools so the persisted
-    // artifact always carries the full audit surface even when the provider omitted them.
-    params = mergeCanonicalPresentation(params);
-    const checkError = validateUatChecks(basePath, params);
-    if (checkError)
-        return errorResult("save_uat_result", checkError, "invalid_evidence");
-    const freshEvidenceError = validateFreshUatOwnedEvidence(params);
-    if (freshEvidenceError)
-        return errorResult("save_uat_result", freshEvidenceError, "missing_fresh_uat_evidence");
-    const modeError = validateUatMode(params);
-    if (modeError)
-        return errorResult("save_uat_result", modeError, "uat_mode_mismatch");
+    const prepared = prepareUatRun(basePath, params);
+    if (!prepared.ok) {
+        return errorResult("save_uat_result", prepared.error.message, prepared.error.code);
+    }
+    const { run } = prepared;
     try {
-        const attempt = params.attempt === "auto" || params.attempt === undefined
-            ? nextUatAttempt(basePath, params.milestoneId, params.sliceId)
-            : typeof params.attempt === "string"
-                ? Number.parseInt(params.attempt, 10)
-                : params.attempt;
-        if (!Number.isInteger(attempt) || attempt < 1) {
-            return errorResult("save_uat_result", "attempt must be a positive integer or auto", "invalid_attempt");
-        }
-        const gateVerdict = params.verdict === "PASS" ? "pass" : "flag";
-        const rationale = params.notes ?? `UAT ${params.verdict} for ${params.sliceId}.`;
-        const assessment = renderUatAssessment(params, attempt, gateVerdict);
         const summary = await executeSummarySave({
-            milestone_id: params.milestoneId,
-            slice_id: params.sliceId,
+            milestone_id: run.params.milestoneId,
+            slice_id: run.params.sliceId,
             artifact_type: "ASSESSMENT",
-            content: assessment,
+            content: run.assessment,
         }, basePath);
         if (summary.isError)
             return summary;
-        const attemptPath = await saveUatAttemptArtifact(basePath, params, attempt);
-        const evaluatedAt = new Date().toISOString();
+        const assessmentPath = relSliceFile(basePath, run.params.milestoneId, run.params.sliceId, "ASSESSMENT");
+        insertAssessment({
+            path: assessmentPath,
+            milestoneId: run.params.milestoneId,
+            sliceId: run.params.sliceId,
+            taskId: null,
+            status: run.params.verdict.toLowerCase(),
+            scope: "run-uat",
+            fullContent: run.assessment,
+        });
+        const attemptPath = await saveUatAttemptArtifact(basePath, run);
         upsertQualityGate({
-            milestoneId: params.milestoneId,
-            sliceId: params.sliceId,
+            milestoneId: run.params.milestoneId,
+            sliceId: run.params.sliceId,
             gateId: "UAT",
             scope: "slice",
             taskId: "",
             status: "complete",
-            verdict: gateVerdict,
-            rationale,
-            findings: assessment,
-            evaluatedAt,
+            verdict: run.gateVerdict,
+            rationale: run.rationale,
+            findings: run.assessment,
+            evaluatedAt: run.evaluatedAt,
         });
         insertGateRun({
-            traceId: `uat:${params.milestoneId}:${params.sliceId}`,
-            turnId: `uat:${params.sliceId}:attempt-${attempt}`,
+            traceId: `uat:${run.params.milestoneId}:${run.params.sliceId}`,
+            turnId: run.runId,
             gateId: "UAT",
             gateType: "uat",
             unitType: "run-uat",
-            unitId: `run-uat:${params.milestoneId}/${params.sliceId}`,
-            milestoneId: params.milestoneId,
-            sliceId: params.sliceId,
-            outcome: params.verdict === "PASS" ? "pass" : "fail",
-            failureClass: params.verdict === "PASS" ? "none" : "verification",
-            rationale,
-            findings: assessment,
-            attempt,
-            maxAttempts: attempt,
-            retryable: params.verdict !== "PASS",
-            evaluatedAt,
+            unitId: `run-uat:${run.params.milestoneId}/${run.params.sliceId}`,
+            milestoneId: run.params.milestoneId,
+            sliceId: run.params.sliceId,
+            outcome: run.gateOutcome,
+            failureClass: run.params.verdict === "PASS" ? "none" : "verification",
+            rationale: run.rationale,
+            findings: run.assessment,
+            attempt: run.attempt,
+            maxAttempts: run.attempt,
+            retryable: run.params.verdict !== "PASS",
+            evaluatedAt: run.evaluatedAt,
         });
         invalidateStateCache();
+        const savedText = `UAT result saved for ${run.params.milestoneId}/${run.params.sliceId}: ${run.params.verdict}`;
         return {
-            content: [{ type: "text", text: `UAT result saved for ${params.milestoneId}/${params.sliceId}: ${params.verdict}` }],
+            content: [{
+                    type: "text",
+                    text: run.manualGuidance ? `${savedText}\n\nManual validation needed:\n${run.manualGuidance}` : savedText,
+                }],
             details: {
                 operation: "save_uat_result",
-                milestoneId: params.milestoneId,
-                sliceId: params.sliceId,
-                verdict: params.verdict,
-                gateVerdict,
-                attempt,
+                milestoneId: run.params.milestoneId,
+                sliceId: run.params.sliceId,
+                verdict: run.params.verdict,
+                gateVerdict: run.gateVerdict,
+                attempt: run.attempt,
                 attemptPath,
-                recommendedNextUnit: params.verdict === "PASS" ? null : "reactive-execute",
+                runId: run.runId,
+                worktreeRoot: run.worktreeRoot,
+                browserToolsPresented: run.browserToolsPresented,
+                recommendedNextUnit: run.params.verdict === "PASS" ? null : "reactive-execute",
+                ...(run.hasHuman
+                    ? { manualValidationPath: run.worktreeRoot }
+                    : {}),
             },
         };
     }

package/dist/resources/extensions/gsd/uat-policy.js

@@ -0,0 +1,130 @@
+// Project/App: gsd-pi
+// File Purpose: Central UAT mode policy for dispatch, tool presentation, and result validation.
+import { extractUatType } from "./files.js";
+import { hasBrowserRequiredText } from "./browser-evidence.js";
+export const UAT_TYPES = [
+    "artifact-driven",
+    "browser-executable",
+    "runtime-executable",
+    "live-runtime",
+    "mixed",
+    "human-experience",
+];
+export const UAT_MODE_POLICIES = {
+    "artifact-driven": {
+        browserTools: false,
+        partialEligible: false,
+        passWithHumanFollowUp: false,
+        requiredAnyModes: [],
+    },
+    "browser-executable": {
+        browserTools: true,
+        partialEligible: false,
+        passWithHumanFollowUp: false,
+        requiredAnyModes: ["browser"],
+    },
+    "runtime-executable": {
+        browserTools: false,
+        partialEligible: false,
+        passWithHumanFollowUp: false,
+        requiredAnyModes: ["runtime"],
+    },
+    "live-runtime": {
+        browserTools: true,
+        partialEligible: true,
+        passWithHumanFollowUp: true,
+        requiredAnyModes: ["runtime", "browser"],
+    },
+    mixed: {
+        browserTools: true,
+        partialEligible: true,
+        passWithHumanFollowUp: true,
+        requiredAnyModes: [],
+    },
+    "human-experience": {
+        browserTools: true,
+        partialEligible: true,
+        passWithHumanFollowUp: true,
+        requiredAnyModes: [],
+    },
+};
+export function isUatType(value) {
+    return typeof value === "string" && UAT_TYPES.includes(value);
+}
+export function getDeclaredUatType(content) {
+    return extractUatType(content) ?? "artifact-driven";
+}
+export function classifyUatContent(content) {
+    const declaredType = getDeclaredUatType(content);
+    const browserRequired = hasBrowserRequiredText(content);
+    const effectiveType = declaredType === "artifact-driven" && browserRequired
+        ? "browser-executable"
+        : declaredType;
+    return {
+        declaredType,
+        effectiveType,
+        browserRequired,
+        shouldDispatchByDefault: effectiveType !== "artifact-driven" || browserRequired,
+    };
+}
+export function shouldEscalateArtifactUatToBrowser(content) {
+    const policy = classifyUatContent(content);
+    return policy.declaredType === "artifact-driven" && policy.browserRequired;
+}
+export function resolveEffectiveUatType(content) {
+    return classifyUatContent(content).effectiveType;
+}
+export function shouldDispatchUatForContent(content, prefs) {
+    return !!prefs?.uat_dispatch || classifyUatContent(content).shouldDispatchByDefault;
+}
+export function uatTypeIncludesBrowser(uatType) {
+    return isUatType(uatType) && UAT_MODE_POLICIES[uatType].browserTools;
+}
+function canonicalPresentedToolName(toolName) {
+    if (!toolName.startsWith("mcp__"))
+        return toolName;
+    const toolSeparator = toolName.indexOf("__", "mcp__".length);
+    return toolSeparator >= 0 ? toolName.slice(toolSeparator + 2) : toolName;
+}
+export function isUatBrowserToolName(toolName) {
+    return canonicalPresentedToolName(toolName).startsWith("browser_");
+}
+export function hasUatBrowserToolSurface(activeTools) {
+    return Array.isArray(activeTools) && activeTools.some(isUatBrowserToolName);
+}
+export function getUatBrowserToolSupportError(options) {
+    if (!uatTypeIncludesBrowser(options.uatType))
+        return null;
+    if (!Array.isArray(options.activeTools))
+        return null;
+    if (hasUatBrowserToolSurface(options.activeTools))
+        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.`;
+}
+export function isPartialEligibleUatType(uatType) {
+    return !!uatType && UAT_MODE_POLICIES[uatType].partialEligible;
+}
+function modeList(modes) {
+    if (modes.length === 1)
+        return modes[0];
+    return modes.slice(0, -1).join(", ") + " or " + modes[modes.length - 1];
+}
+export function validateUatModePolicy(params) {
+    const policy = UAT_MODE_POLICIES[params.uatType];
+    const modes = new Set(params.checks.map((check) => check.mode));
+    const hasHuman = params.checks.some((check) => check.result === "NEEDS-HUMAN");
+    if (params.uatType === "artifact-driven" && hasHuman && params.verdict === "PASS") {
+        return "artifact-driven UAT cannot PASS with human-only checks";
+    }
+    if (hasHuman &&
+        params.verdict === "PASS" &&
+        !policy.passWithHumanFollowUp &&
+        !params.checks.every((check) => check.result !== "NEEDS-HUMAN" || check.nonAutomatable === true)) {
+        return "NEEDS-HUMAN checks can only coexist with PASS for human-experience, mixed, live-runtime, or explicitly non-automatable checks";
+    }
+    if (policy.requiredAnyModes.length > 0 &&
+        !policy.requiredAnyModes.some((mode) => modes.has(mode))) {
+        return `${params.uatType} UAT requires ${modeList(policy.requiredAnyModes)} evidence`;
+    }
+    return null;
+}