@opengsd/gsd-pi 1.1.1-dev.616a1a1 → 1.1.1-dev.74e8dd1

package/dist/resources/extensions/gsd/tools/exec-tool.js

@@ -5,6 +5,27 @@ import { realpathSync } from "node:fs";
 import path from "node:path";
 import { isContextModeEnabled } from "../preferences-types.js";
 import { contextModeDisabledResult } from "./context-mode-tool-result.js";
+const UAT_EXEC_INTENTS = [
+    "uat-artifact-check",
+    "uat-runtime-check",
+    "uat-browser-check",
+    "uat-service-start",
+    "uat-log-inspection",
+];
+const UAT_EXEC_INTENT_ALIASES = {
+    artifact: "uat-artifact-check",
+    "artifact-driven": "uat-artifact-check",
+    runtime: "uat-runtime-check",
+    "runtime-executable": "uat-runtime-check",
+    "live-runtime": "uat-runtime-check",
+    browser: "uat-browser-check",
+    "browser-executable": "uat-browser-check",
+    service: "uat-service-start",
+    "service-start": "uat-service-start",
+    log: "uat-log-inspection",
+    logs: "uat-log-inspection",
+    "log-inspection": "uat-log-inspection",
+};
 export function buildExecOptions(baseDir, cfg, extras) {
     const allowlist = Array.isArray(cfg?.exec_env_allowlist) ? cfg.exec_env_allowlist : EXEC_DEFAULTS.envAllowlist;
     const stdoutCap = clampNumber(cfg?.exec_stdout_cap_bytes, EXEC_DEFAULTS.stdoutCapBytes, 4_096, 16_777_216);
@@ -73,6 +94,39 @@ function normalizeScript(params) {
     }
     return paramError("script is required and must be a non-empty string");
 }
+function normalizeRequiredString(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        return paramError(`${field} is required and must be a non-empty string`);
+    }
+    return value.trim();
+}
+function normalizeUatIntent(value) {
+    if (typeof value !== "string") {
+        return paramError(`intent is required and must be one of: ${UAT_EXEC_INTENTS.join(", ")}`);
+    }
+    const normalized = value.trim().toLowerCase();
+    if (UAT_EXEC_INTENTS.includes(normalized))
+        return normalized;
+    const alias = UAT_EXEC_INTENT_ALIASES[normalized];
+    if (alias)
+        return alias;
+    return paramError(`invalid intent "${value}" — must be one of: ${UAT_EXEC_INTENTS.join(", ")}`);
+}
+function rejectUatScript(script) {
+    const patterns = [
+        { re: /\b(?:npm|pnpm|yarn|bun)\s+(?:i|install|add|remove|update|upgrade)\b/i, reason: "package dependency mutation is not allowed during UAT" },
+        { re: /\b(?:pip|pip3|python\s+-m\s+pip)\s+install\b/i, reason: "package dependency mutation is not allowed during UAT" },
+        { re: /\bgit\s+(?:add|commit|push|reset|checkout|switch|merge|rebase|clean|rm|mv|tag|branch)\b/i, reason: "git mutations are not allowed during UAT" },
+        { re: /\brm\s+-[^\n\r;|&]*r[^\n\r;|&]*f\b/i, reason: "destructive filesystem cleanup is not allowed during UAT" },
+        { re: /\b(?:env|printenv)\b(?:\s|$)/i, reason: "dumping environment variables is not allowed during UAT" },
+        { re: /\bcat\s+\.env(?:\b|\.|$)/i, reason: "reading credential files is not allowed during UAT" },
+    ];
+    for (const pattern of patterns) {
+        if (pattern.re.test(script))
+            return pattern.reason;
+    }
+    return null;
+}
 function isToolExecutionResult(value) {
     return typeof value === "object" && value !== null && Array.isArray(value.content);
 }
@@ -207,6 +261,7 @@ export async function executeGsdExec(params, deps) {
             runtime,
             script,
             ...(typeof params.purpose === "string" ? { purpose: params.purpose } : {}),
+            ...(params.metadata && typeof params.metadata === "object" ? { metadata: params.metadata } : {}),
             ...(typeof params.timeout_ms === "number" ? { timeout_ms: params.timeout_ms } : {}),
         }, opts);
         return formatResult(result);
@@ -220,6 +275,60 @@ export async function executeGsdExec(params, deps) {
         };
     }
 }
+export async function executeUatExec(params, deps) {
+    const milestoneId = normalizeRequiredString(params.milestoneId, "milestoneId");
+    if (isToolExecutionResult(milestoneId))
+        return milestoneId;
+    const sliceId = normalizeRequiredString(params.sliceId, "sliceId");
+    if (isToolExecutionResult(sliceId))
+        return sliceId;
+    const checkId = normalizeRequiredString(params.checkId, "checkId");
+    if (isToolExecutionResult(checkId))
+        return checkId;
+    const intent = normalizeUatIntent(params.intent);
+    if (isToolExecutionResult(intent))
+        return intent;
+    const script = normalizeScript(params);
+    if (isToolExecutionResult(script))
+        return script;
+    const rejected = rejectUatScript(script);
+    if (rejected) {
+        return {
+            content: [{ type: "text", text: `Error: gsd_uat_exec blocked command — ${rejected}` }],
+            details: { operation: "gsd_uat_exec", error: "uat_exec_policy_block", reason: rejected },
+            isError: true,
+        };
+    }
+    const result = await executeGsdExec({
+        ...params,
+        script,
+        purpose: typeof params.purpose === "string" && params.purpose.trim().length > 0
+            ? params.purpose
+            : `UAT ${milestoneId}/${sliceId}/${checkId} (${intent})`,
+        metadata: {
+            kind: "uat_exec",
+            milestoneId,
+            sliceId,
+            checkId,
+            intent,
+            ...(typeof params.expected === "string" && params.expected.trim().length > 0
+                ? { expected: params.expected.trim() }
+                : {}),
+        },
+    }, deps);
+    const details = result.details ?? {};
+    return {
+        ...result,
+        details: {
+            ...details,
+            operation: "gsd_uat_exec",
+            milestoneId,
+            sliceId,
+            checkId,
+            intent,
+        },
+    };
+}
 function formatResult(result) {
     const headerLines = [
         `gsd_exec[${result.id}] runtime=${result.runtime} exit=${formatExit(result)} duration=${result.duration_ms}ms`,

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

@@ -268,15 +268,9 @@ export async function handlePlanSlice(rawParams, basePath) {
             for (const taskId of omittedTaskIds) {
                 deleteTask(params.milestoneId, params.sliceId, taskId);
             }
+            const existingTaskById = new Map(existingTasks.map((task) => [task.id, task]));
             for (const task of params.tasks) {
-                insertTask({
-                    id: task.taskId,
-                    sliceId: params.sliceId,
-                    milestoneId: params.milestoneId,
-                    title: task.title,
-                    status: "pending",
-                });
-                upsertTaskPlanning(params.milestoneId, params.sliceId, task.taskId, {
+                const planning = {
                     title: task.title,
                     description: task.description,
                     estimate: task.estimate,
@@ -287,7 +281,18 @@ export async function handlePlanSlice(rawParams, basePath) {
                     observabilityImpact: task.observabilityImpact ?? "",
                     fullPlanMd: task.fullPlanMd,
                     targetRepositories: task.targetRepositories ?? params.targetRepositories ?? defaultTargets,
-                });
+                };
+                const existingTask = existingTaskById.get(task.taskId);
+                if (!existingTask || !isClosedStatus(existingTask.status)) {
+                    insertTask({
+                        id: task.taskId,
+                        sliceId: params.sliceId,
+                        milestoneId: params.milestoneId,
+                        title: task.title,
+                        status: "pending",
+                    });
+                }
+                upsertTaskPlanning(params.milestoneId, params.sliceId, task.taskId, planning);
             }
             // Seed quality gate rows inside the transaction — all-or-nothing with
             // the plan data so a crash can't leave orphaned gates without tasks.

package/dist/resources/extensions/gsd/tools/reopen-milestone.js

@@ -7,7 +7,7 @@
  * artifacts so the DB-filesystem reconciler does not auto-correct
  * entities back to "complete".
  */
-import { getMilestone, getMilestoneSlices, getSliceTasks, updateMilestoneStatus, updateSliceStatus, updateTaskStatus, transaction, } from "../gsd-db.js";
+import { getMilestone, getMilestoneSlices, getSliceTasks, reopenMilestoneStatus, updateSliceStatus, updateTaskStatus, transaction, } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { isClosedStatus } from "../status-guards.js";
 import { renderAllProjections } from "../workflow-projections.js";
@@ -37,7 +37,7 @@ export async function handleReopenMilestone(params, basePath) {
             guardError = `milestone ${params.milestoneId} is not closed (status: ${milestone.status}) — nothing to reopen`;
             return;
         }
-        updateMilestoneStatus(params.milestoneId, "active", null);
+        reopenMilestoneStatus(params.milestoneId);
         const slices = getMilestoneSlices(params.milestoneId);
         slicesResetCount = slices.length;
         for (const slice of slices) {

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, readTransaction, saveGateResult, } from "../gsd-db.js";
+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 { saveFile, clearParseCache } from "../files.js";
-import { unlinkSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
 import { handleCompleteMilestone } from "./complete-milestone.js";
 import { handleCompleteTask } from "./complete-task.js";
 import { handleCompleteSlice } from "./complete-slice.js";
@@ -26,6 +26,7 @@ import { invalidateStateCache } from "../state.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { parseProject } from "../schemas/parsers.js";
 import { getAutoRuntimeSnapshot } from "../auto-runtime-state.js";
+import { canonicalWorkflowToolName, parseMcpToolName, RUN_UAT_FORBIDDEN_TOOL_NAMES, RUN_UAT_WORKFLOW_TOOL_NAMES, } from "../tool-presentation-plan.js";
 export const SUPPORTED_SUMMARY_ARTIFACT_TYPES = [
     "SUMMARY",
     "RESEARCH",
@@ -775,6 +776,368 @@ export async function executeSaveGateResult(params, basePath = process.cwd()) {
         };
     }
 }
+function errorResult(operation, message, error) {
+    return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        details: { operation, error },
+        isError: true,
+    };
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+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 (!["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 validateUatMode(params) {
+    const modes = new Set(params.checks.map((check) => check.mode));
+    const hasHuman = params.checks.some((check) => check.result === "NEEDS-HUMAN");
+    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";
+    }
+    if (params.uatType === "artifact-driven" && hasHuman && params.verdict === "PASS") {
+        return "artifact-driven UAT cannot PASS with human-only checks";
+    }
+    return null;
+}
+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",
+    };
+    for (const toolName of params.presentation.presentedTools) {
+        const baseName = parseMcpToolName(toolName)?.tool ?? toolName;
+        const canonical = aliasHints[baseName];
+        if (canonical)
+            return `presentation tool "${toolName}" uses an alias; use canonical "${canonical}"`;
+    }
+    const presentedCanonical = new Set(params.presentation.presentedTools.map((toolName) => canonicalWorkflowToolName(parseMcpToolName(toolName)?.tool ?? toolName)));
+    for (const requiredTool of RUN_UAT_WORKFLOW_TOOL_NAMES) {
+        if (!presentedCanonical.has(requiredTool)) {
+            return `presentation is missing required UAT tool "${requiredTool}"`;
+        }
+    }
+    const forbiddenCanonical = new Set(RUN_UAT_FORBIDDEN_TOOL_NAMES
+        .filter((toolName) => !toolName.includes("*"))
+        .map((toolName) => canonicalWorkflowToolName(parseMcpToolName(toolName)?.tool ?? toolName)));
+    for (const toolName of params.presentation.presentedTools) {
+        const canonical = canonicalWorkflowToolName(parseMcpToolName(toolName)?.tool ?? toolName);
+        if (toolName === "mcp__gsd-workflow__*" || forbiddenCanonical.has(canonical)) {
+            return `presentation includes forbidden run-uat tool "${toolName}"`;
+        }
+    }
+    const blockedCanonical = new Set(params.presentation.blockedTools.map((entry) => canonicalWorkflowToolName(parseMcpToolName(entry.name)?.tool ?? entry.name)));
+    for (const blockedTool of ["gsd_exec", "gsd_summary_save", "gsd_save_gate_result"]) {
+        if (!blockedCanonical.has(blockedTool)) {
+            return `presentation must record "${blockedTool}" as blocked during run-uat`;
+        }
+    }
+    return 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 dbAvailable = await ensureDbOpen(basePath);
+    if (!dbAvailable)
+        return errorResult("save_uat_result", "GSD database is not available.", "db_unavailable");
+    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");
+    const checkError = validateUatChecks(basePath, params);
+    if (checkError)
+        return errorResult("save_uat_result", checkError, "invalid_evidence");
+    const modeError = validateUatMode(params);
+    if (modeError)
+        return errorResult("save_uat_result", modeError, "uat_mode_mismatch");
+    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,
+            artifact_type: "ASSESSMENT",
+            content: assessment,
+        }, basePath);
+        if (summary.isError)
+            return summary;
+        const attemptPath = await saveUatAttemptArtifact(basePath, params, attempt);
+        const evaluatedAt = new Date().toISOString();
+        upsertQualityGate({
+            milestoneId: params.milestoneId,
+            sliceId: params.sliceId,
+            gateId: "UAT",
+            scope: "slice",
+            taskId: "",
+            status: "complete",
+            verdict: gateVerdict,
+            rationale,
+            findings: assessment,
+            evaluatedAt,
+        });
+        insertGateRun({
+            traceId: `uat:${params.milestoneId}:${params.sliceId}`,
+            turnId: `uat:${params.sliceId}:attempt-${attempt}`,
+            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,
+        });
+        invalidateStateCache();
+        return {
+            content: [{ type: "text", text: `UAT result saved for ${params.milestoneId}/${params.sliceId}: ${params.verdict}` }],
+            details: {
+                operation: "save_uat_result",
+                milestoneId: params.milestoneId,
+                sliceId: params.sliceId,
+                verdict: params.verdict,
+                gateVerdict,
+                attempt,
+                attemptPath,
+                recommendedNextUnit: params.verdict === "PASS" ? null : "reactive-execute",
+            },
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logError("tool", `gsd_uat_result_save failed: ${msg}`, { tool: "gsd_uat_result_save", error: String(err) });
+        return errorResult("save_uat_result", `saving UAT result failed: ${msg}`, msg);
+    }
+}
 export async function executePlanMilestone(params, basePath = process.cwd()) {
     const dbAvailable = await ensureDbOpen(basePath);
     if (!dbAvailable) {

package/dist/resources/extensions/gsd/unit-context-manifest.js

@@ -83,6 +83,10 @@ const COMMON_BUDGET_SMALL = 250_000; // ~65K tokens
 const TOOLS_ALL = { mode: "all" };
 const TOOLS_PLANNING = { mode: "planning" };
 const TOOLS_VERIFICATION = { mode: "verification" };
+const TOOLS_VERIFICATION_DISPATCH_UAT = {
+    mode: "verification",
+    allowedSubagents: ["mnemo", "scout", "reviewer", "tester"],
+};
 // Like TOOLS_PLANNING but permits dispatch to read-only recon/planning
 // specialists. Runtime-enforced by write-gate.ts before the subagent tool runs.
 const TOOLS_PLANNING_DISPATCH_RECON = {
@@ -372,7 +376,7 @@ export const UNIT_MANIFESTS = {
         codebaseMap: false,
         preferences: "active-only",
         contextMode: "verification",
-        tools: TOOLS_VERIFICATION,
+        tools: TOOLS_VERIFICATION_DISPATCH_UAT,
         artifacts: {
             inline: ["slice-uat"],
             excerpt: ["slice-summary"],
@@ -551,9 +555,10 @@ export function compileSubagentPermissionContract(policy) {
     if (policy.mode === "all") {
         return { allowed: true, allowedSubagents: ["*"], toolsMode: policy.mode };
     }
-    if (policy.mode === "planning-dispatch") {
+    if ((policy.mode === "planning-dispatch" || policy.mode === "verification") &&
+        Array.isArray(policy.allowedSubagents)) {
         return {
-            allowed: true,
+            allowed: policy.allowedSubagents.length > 0,
             allowedSubagents: [...policy.allowedSubagents],
             toolsMode: policy.mode,
         };

package/dist/resources/extensions/gsd/validation-block-guard.js

@@ -8,6 +8,8 @@ import { deriveState } from "./state.js";
 import { detectWorktreeName } from "./worktree.js";
 const VALIDATION_BLOCK_RE = /milestone validation returned needs-(?:attention|remediation)|validation verdict is needs-(?:attention|remediation)/i;
 const VALIDATION_SAFE_DISPATCH_COMMANDS = new Set([
+    "reassess",
+    "reassess-roadmap",
     "validate",
     "validate-milestone",
 ]);

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

@@ -33,6 +33,8 @@ export function shouldAutoPrepareWorkflowMcp(ctx) {
     const authMode = getAuthModeSafe(ctx, provider);
     if (provider !== "claude-code")
         return false;
+    if (authMode === undefined)
+        return true;
     return usesWorkflowMcpTransport(authMode, baseUrl) || authMode === "externalCli";
 }
 export function prepareWorkflowMcpForProject(ctx, projectRoot, modelOverride) {
@@ -42,7 +44,7 @@ export function prepareWorkflowMcpForProject(ctx, projectRoot, modelOverride) {
     try {
         const result = ensureProjectWorkflowMcpConfig(projectRoot);
         if (result.status !== "unchanged") {
-            prepCtx.ui?.notify?.(`Claude Code MCP prepared at ${result.configPath}`, "info");
+            prepCtx.ui?.notify?.(`GSD MCP Server Prepared at ${result.configPath}`, "info");
         }
         return result;
     }

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

@@ -2,6 +2,7 @@ import { execSync } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
 import { dirname, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { RUN_UAT_WORKFLOW_TOOL_NAMES } from "./tool-presentation-plan.js";
 /** Session cwd may be a milestone worktree; MCP config and server discovery use the project root. */
 export function resolveWorkflowMcpProjectRoot(sessionCwd) {
     let resolved;
@@ -77,6 +78,8 @@ const MCP_WORKFLOW_TOOL_SURFACE = new Set([
     "gsd_task_complete",
     "gsd_task_reopen",
     "gsd_update_requirement",
+    "gsd_uat_exec",
+    "gsd_uat_result_save",
     "gsd_validate_milestone",
 ]);
 /** Workflow MCP tools are validated by transport compatibility, not pi tool-compat profiles. */
@@ -397,8 +400,9 @@ export function getRequiredWorkflowToolsForAutoUnit(unitType) {
             ];
         case "research-milestone":
         case "research-slice":
-        case "run-uat":
             return ["gsd_summary_save"];
+        case "run-uat":
+            return [...RUN_UAT_WORKFLOW_TOOL_NAMES];
         case "plan-milestone":
             return ["gsd_plan_milestone"];
         case "plan-slice":