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

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

@@ -178,6 +178,84 @@ export function _roadmapHasParseableSlicesForTest(roadmapContent) {
         return false;
     return parseRoadmapSlices(roadmapContent).length > 0;
 }
+function hasExecutablePlanForHandoff(milestoneId, roadmapFile) {
+    if (isDbAvailable()) {
+        return getMilestoneSlices(milestoneId).length > 0;
+    }
+    if (!roadmapFile)
+        return false;
+    try {
+        return parseRoadmapSlices(readFileSync(roadmapFile, "utf-8")).length > 0;
+    }
+    catch (e) {
+        logWarning("guided", `failed to parse roadmap slices for ${milestoneId}: ${e.message}`);
+        return false;
+    }
+}
+function formatAcceptedDiscussHandoffMessage(milestoneId, contextFile, hasExecutablePlan) {
+    if (hasExecutablePlan)
+        return `Milestone ${milestoneId} ready.`;
+    if (contextFile)
+        return `Milestone ${milestoneId} context captured. Continuing the planning pipeline.`;
+    return `Milestone ${milestoneId} planning artifacts captured. Continuing the planning pipeline.`;
+}
+function manifestContainsMilestone(basePath, milestoneId) {
+    try {
+        const manifest = readManifest(basePath);
+        return (Array.isArray(manifest?.milestones) &&
+            manifest.milestones.some(m => m.id === milestoneId));
+    }
+    catch (e) {
+        logWarning("guided", `R3b: failed to read state manifest: ${e.message}`);
+        return false;
+    }
+}
+function notifyDbRowRecoveryFailed(entry) {
+    entry.ctx.ui.notify(`Milestone ${entry.milestoneId}: DB row recovery failed ${entry.r3bRecoveryCount} times. ` +
+        `Re-run /gsd to reset the recovery counter, or run /gsd-debug to diagnose without resetting.`, "error");
+}
+function noteDbRowRecoveryMiss(entry) {
+    entry.r3bRecoveryCount += 1;
+    if (entry.r3bRecoveryCount >= MAX_DB_ROW_RECOVERIES) {
+        notifyDbRowRecoveryFailed(entry);
+    }
+}
+function ensureMilestoneRowForAcceptedHandoff(entry, contextFile) {
+    if (!isDbAvailable())
+        return true;
+    const { basePath, milestoneId } = entry;
+    const milestoneRow = getMilestone(milestoneId);
+    if (milestoneRow)
+        return true;
+    if (manifestContainsMilestone(basePath, milestoneId)) {
+        logWarning("guided", `R3b: getMilestone(${milestoneId}) returned null but manifest has the row — treating as stale read`);
+        return true;
+    }
+    if (!contextFile) {
+        entry.ctx.ui.notify(`Milestone ${milestoneId}: discuss artifacts on disk but no DB row exists. ` +
+            `PROJECT.md may have failed to register milestones. ` +
+            `Re-save PROJECT.md with canonical "- [ ] M001: Title — One-liner" lines, ` +
+            `then re-run /gsd to recover.`, "error");
+        return false;
+    }
+    if (entry.r3bRecoveryCount >= MAX_DB_ROW_RECOVERIES) {
+        logWarning("guided", `R3b: milestone ${milestoneId} DB-row recovery limit reached ` +
+            `(${entry.r3bRecoveryCount}/${MAX_DB_ROW_RECOVERIES}); user already notified`);
+        return false;
+    }
+    logWarning("guided", `R3b: ${milestoneId} has CONTEXT.md but no DB row — inserting placeholder "queued" row ` +
+        `(attempt ${entry.r3bRecoveryCount + 1}/${MAX_DB_ROW_RECOVERIES})`);
+    try {
+        insertMilestone({ id: milestoneId, title: milestoneId, status: "queued" });
+    }
+    catch (e) {
+        logWarning("guided", `R3b: insertMilestone failed: ${e.message}`);
+    }
+    if (getMilestone(milestoneId))
+        return true;
+    noteDbRowRecoveryMiss(entry);
+    return false;
+}
 // ─── Commit Instruction Helpers ──────────────────────────────────────────────
 /** Build commit instruction for planning prompts. .gsd/ is managed externally and always gitignored. */
 function buildDocsCommitInstruction(_message) {
@@ -186,10 +264,8 @@ function buildDocsCommitInstruction(_message) {
 // #4573: cap for how many times we nudge the LLM after a premature ready
 // phrase before giving up and asking the user to re-run /gsd.
 const MAX_READY_REJECTS = 2;
-// H1 (#5012): cap for Gate 1b plan-blocked recovery hints. After this many
-// consecutive recovery attempts the loop is stopped and the user is directed
-// to investigate manually.
-const MAX_PLAN_BLOCKED_RECOVERIES = 3;
+// Cap failed in-flight DB row repair attempts before escalating to the user.
+const MAX_DB_ROW_RECOVERIES = 3;
 // #4573: matches the canonical ready phrase the discuss prompt asks the LLM
 // to emit. Accepts any M-prefixed milestone ID (three digits + optional
 // suffix) with optional trailing punctuation.
@@ -420,56 +496,12 @@ export function checkAutoStartAfterDiscuss(lookupBasePath) {
             return false;
         }
     }
-    // Gate 1b: Discriminate plan-blocked from discuss-incomplete when the DB row is queued.
-    // If the DB is available and the row is still "queued" but CONTEXT.md already exists on
-    // disk, the discuss phase completed but gsd_plan_milestone was hard-blocked by the
-    // depth-verification gate.  Emit a recovery hint so the next agent turn can retry
-    // gsd_plan_milestone, then return false (keep blocking auto-start).
-    // If CONTEXT.md does not exist (discuss-incomplete), Gate 1 already blocked above.
-    if (isDbAvailable()) {
-        const dbRow = getMilestone(milestoneId);
-        if (dbRow?.status === "queued" && contextFile) {
-            if (entry.planBlockedRecoveryCount >= MAX_PLAN_BLOCKED_RECOVERIES) {
-                // H1: recovery loop cap reached — stop triggering new turns, escalate to user.
-                logWarning("guided", `Gate 1b: milestone ${milestoneId} plan-blocked recovery limit reached ` +
-                    `(${entry.planBlockedRecoveryCount}/${MAX_PLAN_BLOCKED_RECOVERIES}); escalating to user`);
-                ctx.ui.notify(`Milestone ${milestoneId} plan_milestone has been blocked ${entry.planBlockedRecoveryCount} times. ` +
-                    `Re-run /gsd to reset the recovery counter, or run /gsd-debug to diagnose without resetting.`, "error");
-                return false;
-            }
-            logWarning("guided", `Gate 1b: milestone ${milestoneId} queued with CONTEXT.md present — ` +
-                `plan_milestone was blocked; emitting recovery hint ` +
-                `(attempt ${entry.planBlockedRecoveryCount + 1}/${MAX_PLAN_BLOCKED_RECOVERIES})`);
-            ctx.ui.notify(`Milestone ${milestoneId}: context file exists but milestone is still queued. ` +
-                `Retrying gsd_plan_milestone to complete the blocked planning step.`, "warning");
-            try {
-                pi.sendMessage({
-                    customType: "gsd-plan-milestone-blocked-recovery",
-                    content: `Milestone ${milestoneId} has ${contextFile} on disk but its DB row is still ` +
-                        `"queued". The gsd_plan_milestone tool was previously blocked by the ` +
-                        `depth-verification gate. Call gsd_plan_milestone now to complete the ` +
-                        `planning phase.`,
-                    display: false,
-                }, { triggerTurn: true });
-                // Increment only after a successful dispatch so transient sendMessage
-                // failures do not consume recovery budget.
-                entry.planBlockedRecoveryCount += 1;
-            }
-            catch (e) {
-                logWarning("guided", `Gate 1b recovery sendMessage failed: ${e.message}`);
-            }
-            return false;
-        }
-    }
-    // Gate 2: STATE.md must exist — written as the last step in the discuss
-    // output phase. This prevents auto-start from firing during Phase 3
-    // (sequential readiness gates for remaining milestones) in multi-milestone
-    // discussions, where M001-CONTEXT.md exists but M002/M003 haven't been
-    // processed yet.
-    const stateFilePath = entry.scope.stateFile();
-    if (!existsSync(stateFilePath))
-        return false; // discussion not finalized yet
-    // Gate 3: Multi-milestone completeness warning
+    // Gate 1b: accept the in-flight discuss handoff. A queued DB row with pinned
+    // CONTEXT.md is Discussion Complete, Planning Pending, not a plan-blocked
+    // failure. If the row is missing, only this pending handoff may repair it.
+    if (!ensureMilestoneRowForAcceptedHandoff(entry, contextFile))
+        return false;
+    // Gate 2: Multi-milestone completeness warning
     // Parse PROJECT.md for milestone sequence, warn if any are missing context.
     // Don't block — milestones can be intentionally queued without context.
     const projectFile = resolveGsdRootFile(basePath, "PROJECT");
@@ -495,7 +527,7 @@ export function checkAutoStartAfterDiscuss(lookupBasePath) {
             logWarning("guided", `PROJECT.md parsing failed: ${e.message}`);
         }
     }
-    // Gate 4: Discussion manifest process verification (multi-milestone only)
+    // Gate 3: Discussion manifest process verification (multi-milestone only)
     // The LLM writes DISCUSSION-MANIFEST.json after each Phase 3 gate decision.
     // When it exists, validate it before auto-starting. Project history alone is
     // not a reliable signal for the current discussion mode.
@@ -541,59 +573,9 @@ export function checkAutoStartAfterDiscuss(lookupBasePath) {
             logWarning("guided", `manifest unlink failed: ${e.message}`);
         }
     }
-    // R3b: belt-and-suspenders for silent registration failure. The discuss flow
-    // finished and STATE.md exists, but the milestone may never have landed in
-    // the DB. Without this guard, the user sees "Milestone M001 ready." and then
-    // /gsd reports "No Active Milestone".
-    if (isDbAvailable()) {
-        const milestoneRow = getMilestone(milestoneId);
-        if (!milestoneRow) {
-            let manifestHasMilestone = false;
-            try {
-                const manifest = readManifest(basePath);
-                manifestHasMilestone = Array.isArray(manifest?.milestones) && manifest.milestones.some(m => m.id === milestoneId);
-            }
-            catch (e) {
-                logWarning("guided", `R3b: failed to read state manifest: ${e.message}`);
-            }
-            if (manifestHasMilestone) {
-                logWarning("guided", `R3b: getMilestone(${milestoneId}) returned null but manifest has the row — treating as stale read`);
-            }
-            else if (contextFile) {
-                // R3b-recovery: CONTEXT.md is on disk but gsd_plan_milestone was never called
-                // (likely blocked by the depth-verification gate re-firing on post-verification
-                // text). Auto-register as "queued" so Gate 1b can pick it up and retry
-                // gsd_plan_milestone on the next checkAutoStartAfterDiscuss call.
-                if (entry.r3bRecoveryCount >= MAX_PLAN_BLOCKED_RECOVERIES) {
-                    logWarning("guided", `R3b: milestone ${milestoneId} DB-row recovery limit reached ` +
-                        `(${entry.r3bRecoveryCount}/${MAX_PLAN_BLOCKED_RECOVERIES}); escalating to user`);
-                    ctx.ui.notify(`Milestone ${milestoneId}: DB row recovery failed ${entry.r3bRecoveryCount} times. ` +
-                        `Re-run /gsd to reset the recovery counter, or run /gsd-debug to diagnose without resetting.`, "error");
-                    return false;
-                }
-                logWarning("guided", `R3b: ${milestoneId} has CONTEXT.md but no DB row — inserting placeholder "queued" row ` +
-                    `for Gate 1b recovery (attempt ${entry.r3bRecoveryCount + 1}/${MAX_PLAN_BLOCKED_RECOVERIES})`);
-                try {
-                    insertMilestone({ id: milestoneId, title: milestoneId, status: "queued" });
-                }
-                catch (e) {
-                    logWarning("guided", `R3b: insertMilestone failed: ${e.message}`);
-                }
-                entry.r3bRecoveryCount += 1;
-                ctx.ui.notify(`Milestone ${milestoneId}: context file exists but DB row was missing — recovering. Retrying gsd_plan_milestone.`, "warning");
-                return false;
-            }
-            else {
-                ctx.ui.notify(`Milestone ${milestoneId}: discuss artifacts on disk but no DB row exists. ` +
-                    `PROJECT.md may have failed to register milestones. ` +
-                    `Re-save PROJECT.md with canonical "- [ ] M001: Title — One-liner" lines, ` +
-                    `then re-run /gsd to recover.`, "error");
-                return false;
-            }
-        }
-    }
     deletePendingAutoStart(basePath);
-    ctx.ui.notify(`Milestone ${milestoneId} ready.`, "success");
+    const hasExecutablePlan = hasExecutablePlanForHandoff(milestoneId, roadmapFile);
+    ctx.ui.notify(formatAcceptedDiscussHandoffMessage(milestoneId, contextFile, hasExecutablePlan), "success");
     if (entry.startAuto !== false) {
         scheduleAutoStartAfterIdle(ctx, pi, basePath, false, { step: step ?? true });
     }

package/dist/resources/extensions/gsd/milestone-closeout.js

@@ -15,6 +15,7 @@ import { extractVerdict, isAcceptableUatVerdict } from "./verdict-parser.js";
 import { logWarning } from "./workflow-logger.js";
 import { hasImplementationArtifacts } from "./milestone-implementation-evidence.js";
 import { buildCompleteMilestonePrompt } from "./auto-prompts.js";
+import { checkCloseoutConsistencyGate } from "./closeout-consistency-gate.js";
 import { commitPendingMilestoneCloseoutChanges, findMissingSummaries, isVerificationNotApplicable, readUatGateVerdict, } from "./auto-dispatch.js";
 const COMPLETE_MILESTONE_DB_SETTLE_MS = 1500;
 const COMPLETE_MILESTONE_DB_SETTLE_POLL_MS = 100;
@@ -28,7 +29,8 @@ export async function isMilestoneCloseoutSettled(mid, basePath) {
         if (isDbAvailable()) {
             const milestone = getMilestone(mid);
             if (milestone && isClosedStatus(milestone.status)) {
-                if (verifyExpectedArtifact("complete-milestone", mid, basePath)) {
+                const closeoutGate = checkCloseoutConsistencyGate(mid, { refreshFromDisk: true });
+                if (closeoutGate.ok && verifyExpectedArtifact("complete-milestone", mid, basePath)) {
                     return true;
                 }
             }

package/dist/resources/extensions/gsd/pending-auto-start.js

@@ -23,7 +23,6 @@ export function setPendingAutoStart(basePath, entry) {
     const scope = scopeMilestone(ws, entry.milestoneId);
     pendingAutoStartMap.set(basePath, {
         createdAt: Date.now(),
-        planBlockedRecoveryCount: 0,
         r3bRecoveryCount: 0,
         ...entry,
         scope,

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

@@ -75,24 +75,10 @@ verdict: "PASS" | "FAIL" | "PARTIAL",
 notes: "<one sentence overall verdict rationale>",
 ```
 
-Use this exact `presentation` shape in the save call so the audit can verify the run-uat tool surface without retrying missing fields one by one:
+Use this canonical `presentation` object in the save call so the audit can verify the run-uat tool surface without retrying missing fields one by one. Keep `toolPresentationPlanId` as `{{toolPresentationPlanId}}`. If browser tools were actually presented for this run, add those concrete browser tool names to `presentedTools`; otherwise reuse this object exactly:
 
-```ts
-presentation: {
-  surface: "mcp",
-  presentedTools: [
-    "gsd_uat_exec",
-    "gsd_uat_result_save",
-    "gsd_resume",
-    "gsd_milestone_status",
-    "gsd_journal_query",
-  ],
-  blockedTools: [
-    { name: "gsd_exec", reason: "forbidden during run-uat" },
-    { name: "gsd_summary_save", reason: "forbidden during run-uat" },
-    { name: "gsd_save_gate_result", reason: "forbidden during run-uat" },
-  ],
-}
+```json
+{{canonicalPresentation}}
 ```
 
 Pass `checks` with this logical shape:

package/dist/resources/extensions/gsd/recovery-classification.js

@@ -19,6 +19,14 @@ export function classifyFailure(input) {
                 exitReason: "tool-schema",
                 remediation: "Fix the Unit Tool Contract or tool schema before retrying.",
             };
+        case "tool-contract":
+            return {
+                failureKind,
+                action: "stop",
+                reason: `Tool Contract failure${unitSuffix(input)}: ${message}`,
+                exitReason: "tool-contract",
+                remediation: "Fix the Unit Tool Contract or prompt so the Unit is only asked to use tools owned by its phase.",
+            };
         case "deterministic-policy":
             return {
                 failureKind,
@@ -27,6 +35,14 @@ export function classifyFailure(input) {
                 exitReason: "deterministic-policy",
                 remediation: "Resolve the policy blocker; retrying the same Unit will repeat the failure.",
             };
+        case "lifecycle-progression":
+            return {
+                failureKind,
+                action: "stop",
+                reason: `Lifecycle progression failure${unitSuffix(input)}: ${message}`,
+                exitReason: "lifecycle-progression",
+                remediation: "Route to the required owning Unit or restore the missing artifact before advancing lifecycle state.",
+            };
         case "stale-worker":
             return {
                 failureKind,
@@ -83,6 +99,10 @@ export function classifyFailure(input) {
     }
 }
 function inferFailureKind(message) {
+    if (/tool contract|auto-unit tool scope|phase-boundary gate|not permitted.*own/i.test(message))
+        return "tool-contract";
+    if (/lifecycle progression|required artifact|missing .*assessment|missing .*closeout|cannot legally (?:advance|progress)/i.test(message))
+        return "lifecycle-progression";
     if (/schema|invalid.*tool|tool.*invalid|enum/i.test(message))
         return "tool-schema";
     if (/deterministic policy|policy rejection|write gate|blocked by policy/i.test(message))

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,6 +14,8 @@ export function compileUnitToolContract(unitType) {
         };
     }
     const requiredWorkflowTools = getRequiredWorkflowToolsForAutoUnit(unitType);
+    const forbiddenWorkflowTools = Object.entries(surfaceContract?.forbiddenGsdTools ?? {})
+        .map(([name, reason]) => ({ name, reason }));
     const closeoutTools = requiredWorkflowTools.filter((tool) => /^gsd_(?:task|slice|milestone|complete|validate|save|summary)/.test(tool));
     if (requiresCloseoutTool(unitType) && closeoutTools.length === 0) {
         return {
@@ -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_READ_ONLY_TOOL_NAMES, RUN_UAT_TOOL_PRESENTATION_PLAN_ID, RUN_UAT_WORKFLOW_TOOL_NAMES, } from "./unit-tool-contracts.js";
+export { 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,24 @@ 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 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/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 { buildRunUatResultPresentation, 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,
         };
     }
@@ -808,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: buildRunUatResultPresentation() };
+    }
+    return params;
+}
+function mergeCanonicalPresentation(params) {
+    const canonicalPresentation = buildRunUatResultPresentation();
+    const providedPresentation = params.presentation;
+    return {
+        ...params,
+        presentation: {
+            ...providedPresentation,
+            surface: providedPresentation.surface ?? canonicalPresentation.surface,
+            presentedTools: mergePresentedTools(providedPresentation.presentedTools, canonicalPresentation.presentedTools),
+            blockedTools: mergeBlockedTools(providedPresentation.blockedTools, canonicalPresentation.blockedTools),
+            toolPresentationPlanId: RUN_UAT_TOOL_PRESENTATION_PLAN_ID,
+        },
+    };
+}
+const VALID_UAT_TYPES = [
+    "artifact-driven",
+    "browser-executable",
+    "runtime-executable",
+    "live-runtime",
+    "mixed",
+    "human-experience",
+];
 function ensureUatRequiredFields(params) {
     if (!isNonEmptyString(params.milestoneId))
         return "milestoneId is required";
@@ -815,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)
@@ -951,6 +1008,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");
@@ -1087,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");