@opengsd/gsd-pi 1.1.1-dev.74e8dd1 → 1.1.1-dev.75048e7

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

@@ -1,12 +1,7 @@
 // Project/App: gsd-pi
 // File Purpose: Resolve phase-aware tool surfaces for GSD model presentations.
-export const RUN_UAT_WORKFLOW_TOOL_NAMES = [
-    "gsd_uat_exec",
-    "gsd_uat_result_save",
-    "gsd_resume",
-    "gsd_milestone_status",
-    "gsd_journal_query",
-];
+import { RUN_UAT_BROWSER_TOOL_NAMES, RUN_UAT_READ_ONLY_TOOL_NAMES, RUN_UAT_TOOL_PRESENTATION_PLAN_ID, RUN_UAT_WORKFLOW_TOOL_NAMES, } from "./unit-tool-contracts.js";
+export { RUN_UAT_BROWSER_TOOL_NAMES, RUN_UAT_READ_ONLY_TOOL_NAMES, RUN_UAT_TOOL_PRESENTATION_PLAN_ID, RUN_UAT_WORKFLOW_TOOL_NAMES, } from "./unit-tool-contracts.js";
 export const RUN_UAT_FORBIDDEN_TOOL_NAMES = [
     "edit",
     "write",
@@ -74,9 +69,37 @@ function addBlockedTool(blocked, name, reason) {
 export function buildRunUatCanonicalToolNames(options = {}) {
     return dedupe([
         ...RUN_UAT_WORKFLOW_TOOL_NAMES,
+        ...RUN_UAT_READ_ONLY_TOOL_NAMES,
         ...(options.includeBrowserTools ?? []),
     ]);
 }
+export function runUatBrowserToolsForType(uatType) {
+    return uatType === "browser-executable" ? RUN_UAT_BROWSER_TOOL_NAMES : [];
+}
+export function runUatPresentationSurfaceForType(uatType) {
+    return uatType === "browser-executable" ? "hybrid" : "mcp";
+}
+export function buildRunUatPresentationForType(uatType, options = {}) {
+    return buildRunUatResultPresentation({
+        ...options,
+        surface: options.surface ?? runUatPresentationSurfaceForType(uatType),
+        includeBrowserTools: runUatBrowserToolsForType(uatType),
+    });
+}
+export function buildRunUatResultPresentation(options = {}) {
+    const presentedTools = options.presentedTools
+        ? dedupe(options.presentedTools)
+        : buildRunUatCanonicalToolNames({ includeBrowserTools: options.includeBrowserTools });
+    const blockedTools = RUN_UAT_FORBIDDEN_TOOL_NAMES
+        .filter((toolName) => !toolName.includes("*"))
+        .map((name) => ({ name, reason: "forbidden during run-uat" }));
+    return {
+        surface: options.surface ?? "mcp",
+        presentedTools,
+        blockedTools,
+        toolPresentationPlanId: RUN_UAT_TOOL_PRESENTATION_PLAN_ID,
+    };
+}
 export function resolveToolPresentationPlan(options) {
     const requested = options.requestedToolNames ?? (options.phase === "run-uat"
         ? buildRunUatCanonicalToolNames({ includeBrowserTools: options.includeBrowserTools })

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

@@ -158,7 +158,7 @@ ${params.narrative}
 
 ## Verification
 
-${params.verification}
+${params.verification ?? ""}
 
 ## Requirements Advanced
 
@@ -351,6 +351,20 @@ export async function handleCompleteSlice(params, basePath) {
             if (parsed.length > 0)
                 effectiveParams.requirementsInvalidated = parsed;
         }
+        if (effectiveParams.verification === undefined) {
+            const headingLine = "## Verification\n\n";
+            const start = existingSummaryMd.indexOf(headingLine);
+            if (start !== -1) {
+                const contentStart = start + headingLine.length;
+                const nextHeading = existingSummaryMd.indexOf("\n\n## ", contentStart);
+                const prior = nextHeading === -1
+                    ? existingSummaryMd.slice(contentStart)
+                    : existingSummaryMd.slice(contentStart, nextHeading);
+                const trimmed = prior.trim();
+                if (trimmed)
+                    effectiveParams.verification = trimmed;
+            }
+        }
     }
     // Render summary markdown
     const summaryMd = renderSliceSummaryMarkdown(effectiveParams);

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

@@ -314,9 +314,18 @@ export async function handleCompleteTask(params, basePath) {
     // overwrite it; gate rows are UPSERT-keyed per task and will also be
     // overwritten. This restores the invariant that deriveState() sees a
     // consistent "task not done" view so the loop re-dispatches the task.
+    let escalationMetadata;
     if (validatedEscalationArtifact) {
         try {
-            writeEscalationArtifact(artifactBasePath, validatedEscalationArtifact);
+            const escalationPath = writeEscalationArtifact(artifactBasePath, validatedEscalationArtifact);
+            escalationMetadata = {
+                artifactPath: escalationPath,
+                question: validatedEscalationArtifact.question,
+                options: validatedEscalationArtifact.options,
+                recommendation: validatedEscalationArtifact.recommendation,
+                recommendationRationale: validatedEscalationArtifact.recommendationRationale,
+                continueWithDefault: validatedEscalationArtifact.continueWithDefault,
+            };
         }
         catch (escalationErr) {
             const msg = `complete-task escalation write failed for ${params.milestoneId}/${params.sliceId}/${params.taskId}: ${escalationErr.message}`;
@@ -378,6 +387,7 @@ export async function handleCompleteTask(params, basePath) {
         sliceId: params.sliceId,
         milestoneId: params.milestoneId,
         summaryPath,
+        ...(escalationMetadata ? { escalation: escalationMetadata } : {}),
         ...(projectionStale ? { stale: true } : {}),
     };
 }

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

@@ -44,19 +44,12 @@ function getRequiredVerificationClasses(milestoneId) {
         required.push("UAT");
     return required;
 }
-async function collectPersistedBrowserEvidence(basePath, milestoneId) {
-    const chunks = [];
-    for (const slice of getMilestoneSlices(milestoneId)) {
-        const artifactPath = `milestones/${milestoneId}/slices/${slice.id}/${slice.id}-ASSESSMENT.md`;
-        const artifact = getArtifact(artifactPath);
-        if (artifact?.full_content)
-            chunks.push(artifact.full_content);
-        const assessmentPath = resolveSliceFile(basePath, milestoneId, slice.id, "ASSESSMENT");
-        const assessmentContent = assessmentPath ? await loadFile(assessmentPath) : null;
-        if (assessmentContent)
-            chunks.push(assessmentContent);
-    }
-    return chunks.join("\n\n");
+function hasRuntimeExecutableUatEvidenceText(text) {
+    if (!/\buatType:\s*runtime-executable\b/i.test(text))
+        return false;
+    if (!/\bverdict:\s*PASS\b/i.test(text))
+        return false;
+    return /^\|\s*[^|\n]+\s*\|\s*runtime\s*\|\s*PASS\s*\|[^|\n]*\bgsd_uat_exec\b/mi.test(text);
 }
 async function browserEvidenceGateRequiresAttention(params, basePath) {
     if (params.verdict !== "pass")
@@ -77,7 +70,36 @@ async function browserEvidenceGateRequiresAttention(params, basePath) {
     ]);
     if (!hasBrowserRequiredText(requirementText))
         return false;
-    const persistedEvidence = await collectPersistedBrowserEvidence(basePath, params.milestoneId);
+    // Collect per-slice evidence so the runtime bypass is checked independently
+    // for each slice. Concatenating all slices before checking would allow runtime
+    // evidence from one slice to cover another slice's browser requirements.
+    const sliceEvidencePairs = [];
+    for (const slice of slices) {
+        const chunks = [];
+        const artifactPath = `milestones/${params.milestoneId}/slices/${slice.id}/${slice.id}-ASSESSMENT.md`;
+        const artifact = getArtifact(artifactPath);
+        if (artifact?.full_content)
+            chunks.push(artifact.full_content);
+        const assessmentPath = resolveSliceFile(basePath, params.milestoneId, slice.id, "ASSESSMENT");
+        const assessmentContent = assessmentPath ? await loadFile(assessmentPath) : null;
+        if (assessmentContent)
+            chunks.push(assessmentContent);
+        sliceEvidencePairs.push({
+            sliceRequirementText: compactTextParts([slice.demo, slice.goal, slice.success_criteria]),
+            evidenceText: chunks.join("\n\n"),
+        });
+    }
+    const persistedEvidence = sliceEvidencePairs.map((s) => s.evidenceText).join("\n\n");
+    // Runtime bypass: each slice whose own requirement text has browser-observable
+    // criteria must have its own runtime-executable UAT evidence. When no individual
+    // slice has slice-level browser requirements (e.g., they come from milestone-level
+    // fields only), fall back to checking whether any slice has runtime evidence.
+    const browserRequiringSlices = sliceEvidencePairs.filter((s) => hasBrowserRequiredText(s.sliceRequirementText));
+    const runtimeBypasses = browserRequiringSlices.length > 0
+        ? browserRequiringSlices.every((s) => hasRuntimeExecutableUatEvidenceText(s.evidenceText))
+        : sliceEvidencePairs.some((s) => hasRuntimeExecutableUatEvidenceText(s.evidenceText));
+    if (runtimeBypasses)
+        return false;
     const validationEvidence = compactTextParts([
         params.successCriteriaChecklist,
         params.verificationClasses,
@@ -138,12 +160,20 @@ export async function handleValidateMilestone(params, basePath, opts) {
     const requiredClasses = getRequiredVerificationClasses(params.milestoneId);
     if (requiredClasses.length > 0) {
         const verificationClasses = params.verificationClasses ?? "";
-        const missingClass = requiredClasses.find((className) => !new RegExp(`\\b${className}\\b`, "i").test(verificationClasses));
-        if (missingClass) {
+        const missingClasses = requiredClasses.filter((className) => !new RegExp(`\\b${className}\\b`, "i").test(verificationClasses));
+        if (missingClasses.length === 1) {
+            const missingClass = missingClasses[0];
             return {
                 error: `verificationClasses must include canonical row "${missingClass}" because this milestone planned ${missingClass.toLowerCase()} verification`,
             };
         }
+        if (missingClasses.length > 1) {
+            const quotedClasses = missingClasses.map((className) => `"${className}"`).join(", ");
+            const plannedClasses = missingClasses.map((className) => className.toLowerCase()).join(", ");
+            return {
+                error: `verificationClasses must include canonical rows ${quotedClasses} because this milestone planned ${plannedClasses} verification`,
+            };
+        }
     }
     const artifactBasePath = resolveCanonicalMilestoneRoot(basePath, params.milestoneId);
     const shouldApplyBrowserEvidenceGate = !opts?.skipBrowserEvidenceGate &&

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

@@ -26,7 +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";
+import { buildRunUatPresentationForType, canonicalWorkflowToolName, parseMcpToolName, RUN_UAT_FORBIDDEN_TOOL_NAMES, RUN_UAT_TOOL_PRESENTATION_PLAN_ID, RUN_UAT_WORKFLOW_TOOL_NAMES, } from "../tool-presentation-plan.js";
 export const SUPPORTED_SUMMARY_ARTIFACT_TYPES = [
     "SUMMARY",
     "RESEARCH",
@@ -53,7 +53,7 @@ function blockIfWrongAutoUnit(requiredUnitType, operation) {
         return null;
     if (snapshot.currentUnit.type === requiredUnitType)
         return null;
-    const error = `HARD BLOCK: ${operation} may only run from ${requiredUnitType}; active unit is ${snapshot.currentUnit.type}. The orchestrator owns phase transitions.`;
+    const error = `HARD BLOCK: Tool Contract failure: ${operation} may only run from ${requiredUnitType}; active unit is ${snapshot.currentUnit.type}. Fix unit-tool-contracts.ts or the active Unit prompt. The orchestrator owns phase transitions.`;
     return {
         content: [{ type: "text", text: error }],
         details: { operation, error },
@@ -121,7 +121,11 @@ export async function executeSummarySave(params, basePath = process.cwd()) {
     if (rootArtifactGuard.block) {
         return {
             content: [{ type: "text", text: `Error saving artifact: ${rootArtifactGuard.reason ?? "root artifact write blocked"}` }],
-            details: { operation: "save_summary", error: "root_artifact_write_blocked" },
+            details: {
+                operation: "save_summary",
+                error: "root_artifact_write_blocked",
+                displayReason: "Approval confirmation required before saving final project setup artifacts.",
+            },
             isError: true,
         };
     }
@@ -129,7 +133,11 @@ export async function executeSummarySave(params, basePath = process.cwd()) {
     if (contextGuard.block) {
         return {
             content: [{ type: "text", text: `Error saving artifact: ${contextGuard.reason ?? "context write blocked"}` }],
-            details: { operation: "save_summary", error: "context_write_blocked" },
+            details: {
+                operation: "save_summary",
+                error: "context_write_blocked",
+                displayReason: "Depth check required before writing milestone context.",
+            },
             isError: true,
         };
     }
@@ -334,6 +342,28 @@ export async function executeTaskComplete(params, basePath = process.cwd()) {
                 isError: true,
             };
         }
+        if (result.escalation) {
+            const recommended = result.escalation.options.find((option) => option.id === result.escalation?.recommendation);
+            const optionIds = result.escalation.options.map((option) => option.id).join("|");
+            return {
+                content: [{
+                        type: "text",
+                        text: [
+                            `Task completed with escalation decision required: ${result.escalation.question}`,
+                            `Recommendation: ${result.escalation.recommendation}${recommended ? ` (${recommended.label})` : ""} — ${result.escalation.recommendationRationale}`,
+                            `Resolve with: /gsd escalate resolve ${result.taskId} <${optionIds}|accept|reject-blocker> [rationale...]`,
+                        ].join("\n"),
+                    }],
+                details: {
+                    operation: "complete_task",
+                    taskId: result.taskId,
+                    sliceId: result.sliceId,
+                    milestoneId: result.milestoneId,
+                    summaryPath: result.summaryPath,
+                    escalation: result.escalation,
+                },
+            };
+        }
         return {
             content: [{ type: "text", text: `Completed task ${result.taskId} (${result.sliceId}/${result.milestoneId})` }],
             details: {
@@ -786,6 +816,52 @@ function errorResult(operation, message, error) {
 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: buildRunUatPresentationForType(params.uatType) };
+    }
+    return params;
+}
+function mergeCanonicalPresentation(params) {
+    const canonicalPresentation = buildRunUatPresentationForType(params.uatType);
+    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";
@@ -793,6 +869,9 @@ function ensureUatRequiredFields(params) {
         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)
@@ -929,9 +1008,18 @@ function validateUatChecks(basePath, params) {
     }
     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) &&
@@ -947,11 +1035,11 @@ function validateUatMode(params) {
     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 quoteToolNames(toolNames) {
+    return toolNames.map((toolName) => `"${toolName}"`).join(", ");
+}
 function validateCanonicalPresentation(params) {
     const aliasHints = {
         gsd_save_summary: "gsd_summary_save",
@@ -959,34 +1047,46 @@ function validateCanonicalPresentation(params) {
         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)
-            return `presentation tool "${toolName}" uses an alias; use canonical "${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)));
-    for (const requiredTool of RUN_UAT_WORKFLOW_TOOL_NAMES) {
-        if (!presentedCanonical.has(requiredTool)) {
-            return `presentation is missing required UAT tool "${requiredTool}"`;
-        }
+    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)) {
-            return `presentation includes forbidden run-uat tool "${toolName}"`;
+            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)));
-    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`;
-        }
+    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`);
     }
-    return null;
+    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);
@@ -1050,18 +1150,32 @@ async function saveUatAttemptArtifact(basePath, params, attempt) {
     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");

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

@@ -0,0 +1,169 @@
+// Project/App: gsd-pi
+// File Purpose: Central Unit-to-tool contracts for phase-aware GSD tool surfaces.
+export const RUN_UAT_WORKFLOW_TOOL_NAMES = [
+    "gsd_uat_exec",
+    "gsd_uat_result_save",
+    "gsd_resume",
+    "gsd_milestone_status",
+    "gsd_journal_query",
+];
+export const RUN_UAT_READ_ONLY_TOOL_NAMES = [
+    "find",
+    "glob",
+    "grep",
+    "ls",
+    "read",
+];
+export const RUN_UAT_BROWSER_TOOL_NAMES = [
+    "browser_navigate",
+    "browser_click",
+    "browser_type",
+    "browser_fill_form",
+    "browser_click_ref",
+    "browser_fill_ref",
+    "browser_wait_for",
+    "browser_assert",
+    "browser_verify",
+    "browser_screenshot",
+    "browser_snapshot_refs",
+    "browser_find",
+    "browser_get_console_logs",
+    "browser_get_network_logs",
+    "browser_evaluate",
+    "browser_reload",
+    "browser_batch",
+    "browser_act",
+];
+export const RUN_UAT_TOOL_PRESENTATION_PLAN_ID = "run-uat/default-v1";
+export const UNIT_TOOL_CONTRACTS = {
+    "research-milestone": {
+        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+        requiredWorkflowTools: ["gsd_summary_save"],
+    },
+    "plan-milestone": {
+        allowedGsdTools: ["gsd_plan_milestone", "gsd_decision_save", "gsd_requirement_update"],
+        requiredWorkflowTools: ["gsd_plan_milestone"],
+    },
+    "discuss-milestone": {
+        allowedGsdTools: [
+            "gsd_summary_save",
+            "gsd_decision_save",
+            "gsd_requirement_save",
+            "gsd_requirement_update",
+            "gsd_plan_milestone",
+            "gsd_milestone_generate_id",
+        ],
+        requiredWorkflowTools: [
+            "gsd_summary_save",
+            "gsd_requirement_save",
+            "gsd_requirement_update",
+            "gsd_plan_milestone",
+            "gsd_milestone_generate_id",
+        ],
+    },
+    "discuss-slice": {
+        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+        requiredWorkflowTools: ["gsd_summary_save"],
+    },
+    "validate-milestone": {
+        allowedGsdTools: ["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"],
+    },
+    "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"],
+    },
+    "refine-slice": {
+        allowedGsdTools: ["gsd_plan_slice", "gsd_plan_task", "gsd_decision_save"],
+        requiredWorkflowTools: [],
+    },
+    "replan-slice": {
+        allowedGsdTools: ["gsd_replan_slice", "gsd_plan_task", "gsd_decision_save"],
+        requiredWorkflowTools: ["gsd_replan_slice"],
+    },
+    "complete-slice": {
+        allowedGsdTools: [
+            "gsd_slice_complete",
+            "gsd_task_reopen",
+            "gsd_replan_slice",
+            "gsd_decision_save",
+            "gsd_requirement_update",
+            "subagent",
+        ],
+        requiredWorkflowTools: ["gsd_slice_complete", "gsd_task_reopen", "gsd_replan_slice"],
+        forbiddenGsdTools: {
+            gsd_uat_result_save: "Run UAT owns persisted UAT Assessment.",
+        },
+    },
+    "reassess-roadmap": {
+        allowedGsdTools: ["gsd_reassess_roadmap"],
+        requiredWorkflowTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
+    },
+    "execute-task": {
+        allowedGsdTools: ["gsd_task_complete", "gsd_decision_save"],
+        requiredWorkflowTools: ["gsd_task_complete"],
+    },
+    "execute-task-simple": {
+        allowedGsdTools: ["gsd_task_complete", "gsd_decision_save"],
+        requiredWorkflowTools: ["gsd_task_complete"],
+    },
+    "reactive-execute": {
+        allowedGsdTools: ["gsd_task_complete", "gsd_decision_save"],
+        requiredWorkflowTools: ["gsd_task_complete"],
+    },
+    "run-uat": {
+        allowedGsdTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES, "subagent"],
+        requiredWorkflowTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES],
+        forbiddenGsdTools: {
+            gsd_exec: "Use gsd_uat_exec so acceptance evidence is typed as UAT-owned.",
+            gsd_save_gate_result: "gsd_uat_result_save owns the aggregate UAT gate.",
+            gsd_summary_save: "gsd_uat_result_save owns persisted UAT Assessment writes.",
+        },
+    },
+    "gate-evaluate": {
+        allowedGsdTools: ["gsd_save_gate_result"],
+        requiredWorkflowTools: ["gsd_save_gate_result"],
+    },
+    "rewrite-docs": {
+        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+        requiredWorkflowTools: [],
+    },
+    "workflow-preferences": {
+        allowedGsdTools: ["gsd_summary_save"],
+        requiredWorkflowTools: [],
+    },
+    "discuss-project": {
+        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save", "gsd_requirement_save"],
+        requiredWorkflowTools: ["ask_user_questions", "gsd_summary_save"],
+    },
+    "discuss-requirements": {
+        allowedGsdTools: ["gsd_requirement_save", "gsd_summary_save"],
+        requiredWorkflowTools: ["ask_user_questions", "gsd_requirement_save", "gsd_summary_save"],
+    },
+    "research-decision": {
+        allowedGsdTools: ["gsd_summary_save"],
+        requiredWorkflowTools: ["ask_user_questions"],
+    },
+    "research-project": {
+        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+        requiredWorkflowTools: [],
+    },
+};
+export const AUTO_UNIT_SCOPED_TOOLS = Object.fromEntries(Object.entries(UNIT_TOOL_CONTRACTS).map(([unitType, contract]) => [unitType, contract.allowedGsdTools]));
+export function getUnitToolSurfaceContract(unitType) {
+    return UNIT_TOOL_CONTRACTS[unitType];
+}
+export function getRequiredWorkflowToolsForUnit(unitType) {
+    return [...(UNIT_TOOL_CONTRACTS[unitType]?.requiredWorkflowTools ?? [])];
+}
+export function getForbiddenGsdToolReason(unitType, toolName) {
+    return UNIT_TOOL_CONTRACTS[unitType]?.forbiddenGsdTools?.[toolName];
+}