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

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

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

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

@@ -2,8 +2,10 @@
 // File Purpose: ADR-015 Tool Contract module for Unit prompt, policy, and tool parity.
 import { resolveManifest, } from "./unit-context-manifest.js";
 import { getRequiredWorkflowToolsForAutoUnit } from "./workflow-mcp.js";
+import { getUnitToolSurfaceContract } from "./unit-tool-contracts.js";
 export function compileUnitToolContract(unitType) {
     const manifest = resolveManifest(unitType);
+    const surfaceContract = getUnitToolSurfaceContract(unitType);
     if (!manifest) {
         return {
             ok: false,
@@ -12,7 +14,9 @@ export function compileUnitToolContract(unitType) {
         };
     }
     const requiredWorkflowTools = getRequiredWorkflowToolsForAutoUnit(unitType);
-    const closeoutTools = requiredWorkflowTools.filter((tool) => /^gsd_(?:task|slice|milestone|complete|validate|save|summary)/.test(tool));
+    const forbiddenWorkflowTools = Object.entries(surfaceContract?.forbiddenGsdTools ?? {})
+        .map(([name, reason]) => ({ name, reason }));
+    const closeoutTools = requiredWorkflowTools.filter((tool) => /^gsd_(?:task|slice|milestone|complete|validate|save|summary|uat)/.test(tool));
     if (requiresCloseoutTool(unitType) && closeoutTools.length === 0) {
         return {
             ok: false,
@@ -27,6 +31,7 @@ export function compileUnitToolContract(unitType) {
             contextMode: manifest.contextMode,
             toolsPolicy: manifest.tools,
             requiredWorkflowTools,
+            forbiddenWorkflowTools,
             promptObligations: [
                 `context-mode:${manifest.contextMode}`,
                 `tools-policy:${manifest.tools.mode}`,

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

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

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

@@ -6,8 +6,9 @@ import { loadWriteGateSnapshot, shouldBlockContextArtifactSaveInSnapshot, should
 import { getActiveRequirements, insertMilestone, getMilestone, getSliceStatusSummary, getSliceTaskCounts, insertGateRun, readTransaction, saveGateResult, upsertQualityGate, } from "../gsd-db.js";
 import { GATE_REGISTRY } from "../gate-registry.js";
 import { generateRequirementsMd, saveArtifactToDb } from "../db-writer.js";
-import { clearPathCache, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
+import { clearPathCache, relSliceFile, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
 import { saveFile, clearParseCache } from "../files.js";
+import { buildManualValidationGuidance, resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { existsSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
 import { isAbsolute, join, resolve } from "node:path";
 import { handleCompleteMilestone } from "./complete-milestone.js";
@@ -26,7 +27,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 +54,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 +122,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 +134,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,
         };
     }
@@ -808,6 +817,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";
@@ -815,6 +870,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)
@@ -951,6 +1009,12 @@ 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");
@@ -1043,7 +1107,7 @@ function escapeMarkdownTableCell(value) {
         .replace(/[\\|]/g, (char) => `\\${char}`)
         .replace(/\r?\n/g, "<br>");
 }
-function renderUatAssessment(params, attempt, gateVerdict) {
+function renderUatAssessment(params, attempt, gateVerdict, basePath) {
     const lines = [
         "---",
         `sliceId: ${params.sliceId}`,
@@ -1078,6 +1142,18 @@ function renderUatAssessment(params, attempt, gateVerdict) {
         "",
         `Aggregate UAT gate saved as ${gateVerdict}.`,
     ];
+    // When any check still needs a human, point them at the exact checkout to
+    // validate — critical for worktree milestones whose code sits under a hidden
+    // `.gsd/worktrees/` path the reviewer would otherwise have to hunt for.
+    const hasHuman = params.checks.some((check) => check.result === "NEEDS-HUMAN");
+    if (hasHuman) {
+        const guidance = buildManualValidationGuidance(basePath, params.milestoneId, {
+            uatPath: relSliceFile(basePath, params.milestoneId, params.sliceId, "UAT"),
+        });
+        if (guidance) {
+            lines.push("", "## Manual Validation", "", "One or more checks are marked `NEEDS-HUMAN` and require a person to validate:", "", ...guidance.split("\n").map((line) => `- ${line}`));
+        }
+    }
     return `${lines.join("\n")}\n`;
 }
 async function saveUatAttemptArtifact(basePath, params, attempt) {
@@ -1087,18 +1163,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");
@@ -1113,7 +1203,7 @@ export async function executeUatResultSave(params, basePath = process.cwd()) {
         }
         const gateVerdict = params.verdict === "PASS" ? "pass" : "flag";
         const rationale = params.notes ?? `UAT ${params.verdict} for ${params.sliceId}.`;
-        const assessment = renderUatAssessment(params, attempt, gateVerdict);
+        const assessment = renderUatAssessment(params, attempt, gateVerdict, basePath);
         const summary = await executeSummarySave({
             milestone_id: params.milestoneId,
             slice_id: params.sliceId,
@@ -1155,8 +1245,20 @@ export async function executeUatResultSave(params, basePath = process.cwd()) {
             evaluatedAt,
         });
         invalidateStateCache();
+        // Surface where to validate when checks are left for a human, so the path
+        // (often a buried worktree checkout) reaches the reviewer, not just the file.
+        const hasHuman = params.checks.some((check) => check.result === "NEEDS-HUMAN");
+        const manualGuidance = hasHuman
+            ? buildManualValidationGuidance(basePath, params.milestoneId, {
+                uatPath: relSliceFile(basePath, params.milestoneId, params.sliceId, "UAT"),
+            })
+            : null;
+        const savedText = `UAT result saved for ${params.milestoneId}/${params.sliceId}: ${params.verdict}`;
         return {
-            content: [{ type: "text", text: `UAT result saved for ${params.milestoneId}/${params.sliceId}: ${params.verdict}` }],
+            content: [{
+                    type: "text",
+                    text: manualGuidance ? `${savedText}\n\nManual validation needed:\n${manualGuidance}` : savedText,
+                }],
             details: {
                 operation: "save_uat_result",
                 milestoneId: params.milestoneId,
@@ -1166,6 +1268,9 @@ export async function executeUatResultSave(params, basePath = process.cwd()) {
                 attempt,
                 attemptPath,
                 recommendedNextUnit: params.verdict === "PASS" ? null : "reactive-execute",
+                ...(hasHuman
+                    ? { manualValidationPath: resolveCanonicalMilestoneRoot(basePath, params.milestoneId) }
+                    : {}),
             },
         };
     }

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

@@ -0,0 +1,193 @@
+// 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_milestone_status",
+            "gsd_plan_milestone",
+            "gsd_plan_slice",
+            "gsd_decision_save",
+            "gsd_requirement_update",
+        ],
+        requiredWorkflowTools: ["gsd_milestone_status", "gsd_plan_milestone", "gsd_plan_slice"],
+    },
+    "discuss-milestone": {
+        allowedGsdTools: [
+            "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_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap", "subagent"],
+        requiredWorkflowTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap"],
+    },
+    "complete-milestone": {
+        allowedGsdTools: [
+            "gsd_milestone_status",
+            "gsd_requirement_update",
+            "gsd_summary_save",
+            "gsd_complete_milestone",
+            "subagent",
+        ],
+        requiredWorkflowTools: [
+            "gsd_milestone_status",
+            "gsd_requirement_update",
+            "gsd_summary_save",
+            "gsd_complete_milestone",
+        ],
+    },
+    "research-slice": {
+        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+        requiredWorkflowTools: ["gsd_summary_save"],
+    },
+    "plan-slice": {
+        allowedGsdTools: ["gsd_plan_slice", "gsd_reassess_roadmap", "gsd_decision_save"],
+        requiredWorkflowTools: ["gsd_plan_slice", "gsd_reassess_roadmap"],
+    },
+    "refine-slice": {
+        allowedGsdTools: ["gsd_plan_slice", "gsd_decision_save"],
+        requiredWorkflowTools: ["gsd_plan_slice"],
+    },
+    "replan-slice": {
+        allowedGsdTools: ["gsd_replan_slice", "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",
+            "gsd_summary_save",
+            "subagent",
+        ],
+        requiredWorkflowTools: [
+            "gsd_slice_complete",
+            "gsd_task_reopen",
+            "gsd_replan_slice",
+            "gsd_requirement_update",
+            "gsd_summary_save",
+        ],
+        forbiddenGsdTools: {
+            gsd_uat_result_save: "Run UAT owns persisted UAT Assessment.",
+        },
+    },
+    "reassess-roadmap": {
+        allowedGsdTools: ["gsd_milestone_status", "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_summary_save", "gsd_decision_save"],
+        requiredWorkflowTools: ["gsd_task_complete", "gsd_summary_save"],
+    },
+    "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];
+}