@opengsd/gsd-pi 1.1.1-dev.2034b16 → 1.1.1-dev.595401e

package/packages/pi-ai/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd/pi-ai",
-  "version": "1.1.1-dev.2034b16",
+  "version": "1.1.1-dev.595401e",
   "description": "Unified LLM API with automatic model discovery and provider configuration",
   "type": "module",
   "gsd": {

package/packages/pi-coding-agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd/pi-coding-agent",
-  "version": "1.1.1-dev.2034b16",
+  "version": "1.1.1-dev.595401e",
   "description": "Coding agent CLI (vendored from earendil-works/pi)",
   "type": "module",
   "gsd": {
@@ -33,7 +33,7 @@
     "copy-assets": "node scripts/copy-assets.cjs"
   },
   "dependencies": {
-    "@opengsd/contracts": "^1.1.1-dev.2034b16",
+    "@opengsd/contracts": "^1.1.1-dev.595401e",
     "@mariozechner/jiti": "^2.6.2",
     "@silvia-odwyer/photon-node": "0.3.4",
     "chalk": "5.6.2",
@@ -53,11 +53,11 @@
     "typebox": "1.1.38",
     "undici": "7.26.0",
     "yaml": "2.9.0",
-    "@gsd/agent-core": "^1.1.1-dev.2034b16",
-    "@gsd/native": "^1.1.1-dev.2034b16",
-    "@gsd/pi-agent-core": "^1.1.1-dev.2034b16",
-    "@gsd/pi-ai": "^1.1.1-dev.2034b16",
-    "@gsd/pi-tui": "^1.1.1-dev.2034b16",
+    "@gsd/agent-core": "^1.1.1-dev.595401e",
+    "@gsd/native": "^1.1.1-dev.595401e",
+    "@gsd/pi-agent-core": "^1.1.1-dev.595401e",
+    "@gsd/pi-ai": "^1.1.1-dev.595401e",
+    "@gsd/pi-tui": "^1.1.1-dev.595401e",
     "@sinclair/typebox": "^0.34.41"
   },
   "devDependencies": {

package/packages/pi-tui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd/pi-tui",
-  "version": "1.1.1-dev.2034b16",
+  "version": "1.1.1-dev.595401e",
   "description": "Terminal UI library (vendored from earendil-works/pi)",
   "type": "module",
   "gsd": {

package/packages/rpc-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengsd/rpc-client",
-  "version": "1.1.1-dev.2034b16",
+  "version": "1.1.1-dev.595401e",
   "description": "Standalone RPC client SDK for GSD — zero internal dependencies",
   "license": "MIT",
   "gsd": {
@@ -34,7 +34,7 @@
     "test": "node --test dist/rpc-client.test.js"
   },
   "dependencies": {
-    "@opengsd/contracts": "^1.1.1-dev.2034b16"
+    "@opengsd/contracts": "^1.1.1-dev.595401e"
   },
   "engines": {
     "node": ">=22.0.0"

package/pkg/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glittercowboy/gsd",
-  "version": "1.1.1-dev.2034b16",
+  "version": "1.1.1-dev.595401e",
   "piConfig": {
     "name": "gsd",
     "configDir": ".gsd"

package/src/resources/extensions/gsd/auto-post-unit.ts

@@ -55,8 +55,10 @@ import { parseRoadmap as parseLegacyRoadmap } from "./parsers-legacy.js";
 import { consumeSignal } from "./session-status-io.js";
 import {
   checkPostUnitHooks,
+  consumeHookFailure,
   isRetryPending,
   consumeRetryTrigger,
+  consumeGateBlock,
   persistHookState,
   resolveHookArtifactPath,
 } from "./post-unit-hooks.js";
@@ -2227,11 +2229,11 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
   // ── Post-unit hooks ──
   if (s.currentUnit && !s.stepMode) {
     const hookUnit = checkPostUnitHooks(s.currentUnit.type, s.currentUnit.id, s.basePath);
+    persistHookState(s.basePath);
     if (hookUnit) {
       if (s.currentUnit) {
         await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
       }
-      persistHookState(s.basePath);
 
       return enqueueSidecar(
         s, ctx,
@@ -2240,12 +2242,23 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
       );
     }
 
+    const hookFailure = consumeHookFailure();
+    if (hookFailure) {
+      ctx.ui.notify(
+        `Post-unit hook ${hookFailure.hookName} failed for ${hookFailure.unitId}: ${hookFailure.reason}. Pausing auto-mode.`,
+        "warning",
+      );
+      await pauseAuto(ctx, pi);
+      return "stopped";
+    }
+
     // Check if a hook requested a retry of the trigger unit
     if (isRetryPending()) {
       const trigger = consumeRetryTrigger();
       if (trigger) {
+        persistHookState(s.basePath);
         ctx.ui.notify(
-          `Hook requested retry of ${trigger.unitType} ${trigger.unitId} — resetting task state.`,
+          `Hook requested retry of ${trigger.unitType} ${trigger.unitId} — resetting trigger unit state.`,
           "info",
         );
 
@@ -2299,6 +2312,19 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
         // Fall through to normal dispatch — deriveState will re-derive the unit
       }
     }
+
+    const gateBlock = consumeGateBlock();
+    if (gateBlock) {
+      persistHookState(s.basePath);
+      const verdict = gateBlock.verdict ? ` verdict=${gateBlock.verdict};` : "";
+      const artifact = gateBlock.artifact ? ` artifact=${gateBlock.artifact};` : "";
+      const message =
+        `Post-unit gate "${gateBlock.hookName}" blocked ${gateBlock.triggerUnitType} ${gateBlock.triggerUnitId}:` +
+        `${verdict}${artifact} ${gateBlock.reason}. Run /gsd status to inspect, then /gsd auto after recovery.`;
+      ctx.ui.notify(message, "warning");
+      await pauseAuto(ctx, pi);
+      return "stopped";
+    }
   }
 
   // ── Fast-path stop detection (#3487) ──

package/src/resources/extensions/gsd/auto-prompts.ts

@@ -1429,7 +1429,7 @@ export async function checkNeedsRunUat(
           // If the UAT file already contains a verdict, UAT has been run — skip
           if (hasVerdict(uatContent)) continue;
           // Also check the ASSESSMENT file — the run-uat prompt writes the verdict
-          // there (via gsd_summary_save artifact_type:"ASSESSMENT"), not into the
+          // there (via gsd_uat_result_save), not into the
           // UAT spec file. Without this check the unit re-dispatches indefinitely.
           const assessmentFile = resolveSliceFile(base, mid, sid, "ASSESSMENT");
           if (assessmentFile) {
@@ -2986,13 +2986,23 @@ export async function buildValidateMilestonePrompt(
     if (isDbAvailable()) {
       const milestone = getMilestone(mid);
       if (milestone) {
+        const escapeCell = (value: string) =>
+          value.replace(/[\\|]/g, (char) => `\\${char}`).replace(/\r?\n/g, " ");
         const classes: string[] = [];
-        if (milestone.verification_contract) classes.push(`- **Contract:** ${milestone.verification_contract}`);
-        if (milestone.verification_integration) classes.push(`- **Integration:** ${milestone.verification_integration}`);
-        if (milestone.verification_operational) classes.push(`- **Operational:** ${milestone.verification_operational}`);
-        if (milestone.verification_uat) classes.push(`- **UAT:** ${milestone.verification_uat}`);
+        if (milestone.verification_contract) classes.push(`| Contract | ${escapeCell(milestone.verification_contract)} |`);
+        if (milestone.verification_integration) classes.push(`| Integration | ${escapeCell(milestone.verification_integration)} |`);
+        if (milestone.verification_operational) classes.push(`| Operational | ${escapeCell(milestone.verification_operational)} |`);
+        if (milestone.verification_uat) classes.push(`| UAT | ${escapeCell(milestone.verification_uat)} |`);
         if (classes.length > 0) {
-          const verificationClasses = `### Verification Classes (from planning)\n\nThese verification tiers were defined during milestone planning. Each non-empty class must be checked for evidence during validation.\n\n${classes.join("\n")}`;
+          const verificationClasses = [
+            "### Verification Classes (from planning)",
+            "",
+            "These verification tiers were defined during milestone planning. Every row in this table must appear in `verificationClasses` with the same canonical class name.",
+            "",
+            "| Class | Planned Check |",
+            "| --- | --- |",
+            ...classes,
+          ].join("\n");
           inlined.push(verificationClasses);
           trackPromptContext(contextTelemetry, "verification-classes", "inline", verificationClasses);
         }

package/src/resources/extensions/gsd/bootstrap/db-tools.ts

@@ -1095,7 +1095,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     promptGuidelines: [
       "Use gsd_validate_milestone when all slices are done and the milestone needs validation before completion.",
       "Parameters: milestoneId, verdict, remediationRound, successCriteriaChecklist, sliceDeliveryAudit, crossSliceIntegration, requirementCoverage, verificationClasses (optional), verdictRationale, remediationPlan (optional).",
-      "If verification classes were planned, verificationClasses must include canonical class rows using the exact class names Contract, Integration, Operational, and UAT when present in planning.",
+      "If verification classes were planned, verificationClasses must be a complete canonical table with one row for every applicable planned class using the exact class names Contract, Integration, Operational, and UAT. Do not submit a partial table.",
       "Planned verification text marked as none/not required/not applicable/N/A (including suffixed variants such as 'not required - backend-only') is treated as not applicable and does not require a class row.",
       "If verdict is 'needs-remediation', also provide remediationPlan and use gsd_reassess_roadmap to add remediation slices to the roadmap.",
       "On success, returns validationPath where VALIDATION.md was written.",
@@ -1108,7 +1108,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       sliceDeliveryAudit: Type.String({ description: "Markdown table auditing each slice's claimed vs delivered output" }),
       crossSliceIntegration: Type.String({ description: "Markdown describing any cross-slice boundary mismatches" }),
       requirementCoverage: Type.String({ description: "Markdown describing any unaddressed requirements" }),
-      verificationClasses: Type.Optional(Type.String({ description: "Markdown describing verification class compliance and gaps using canonical class names (Contract, Integration, Operational, UAT) for each applicable planned class" })),
+      verificationClasses: Type.Optional(Type.String({ description: "Complete markdown table describing verification class compliance and gaps; include one canonical row for every applicable planned class (Contract, Integration, Operational, UAT)" })),
       verdictRationale: Type.String({ description: "Why this verdict was chosen" }),
       remediationPlan: Type.Optional(Type.String({ description: "Remediation plan (required if verdict is needs-remediation)" })),
     }),

package/src/resources/extensions/gsd/browser-evidence.ts

@@ -1,11 +1,13 @@
 // Project/App: gsd-pi
 // File Purpose: Shared browser-observable UAT requirement and evidence detection.
 
-export const BROWSER_REQUIREMENT_RE = /\b(?:browser|file:\/\/|localhost|dom|localstorage|click(?:ing|ed)?|button|screenshot|snapshot|reload(?:ed)?|page refresh|user-visible|strikethrough|search box)\b/i;
+export const BROWSER_REQUIREMENT_RE = /\b(?:file:\/\/|localhost|playwright|chrome|screenshot|snapshot|browser_(?:assert|batch|find|verify|snapshot_refs))\b|\b(?:open|launch|navigate|load|visit|serve|start)\b.{0,80}\b(?:browser|page|localhost|file:\/\/)\b|\bbrowser\s+(?:check|session|test|uat|tool|automation|interaction|flow)\b/i;
 export const NO_BROWSER_EVIDENCE_RE = /\b(?:no|without|not|wasn'?t|isn'?t)\s+(?:automated\s+)?(?:live\s+)?browser(?:\s+(?:session|test|uat))?|\bno\s+automated\s+browser\b|\bnot\s+conducted\b/i;
 export const BROWSER_RUNTIME_RE = /\b(?:browser|playwright|chrome|camoufox|browser_(?:assert|batch|find|verify|snapshot_refs)|screenshot|snapshot|file:\/\/|localhost)\b/i;
 export const BROWSER_ACTION_RE = /\b(?:open(?:ed)?|navigate(?:d)?|click(?:ed)?|type(?:d)?|reload(?:ed)?|capture(?:d)?|screenshot|snapshot)\b/i;
 export const BROWSER_ASSERTION_RE = /\b(?:assert(?:ed|ion)?|observed|confirmed|verified|expected|visible|text|count|label|strikethrough|localstorage|screenshot|snapshot|passed)\b/i;
+const NON_REQUIREMENT_BROWSER_HEADING_RE = /^(?:not\s+proven|not\s+covered|out\s+of\s+scope|deferred|follow-?ups?|known\s+limitations|notes\s+for\s+tester)\b/i;
+const NON_REQUIREMENT_BROWSER_LINE_RE = /\b(?:deferred|not\s+proven|not\s+covered|out\s+of\s+scope|future\s+slice|follow-?up|no\s+(?:live\s+)?browser|without\s+(?:a\s+)?browser|not\s+(?:a\s+)?browser)\b/i;
 
 export function compactTextParts(parts: Array<string | string[] | null | undefined>): string {
   return parts.flatMap((part) => Array.isArray(part) ? part : [part])
@@ -14,7 +16,29 @@ export function compactTextParts(parts: Array<string | string[] | null | undefin
 }
 
 export function hasBrowserRequiredText(text: string): boolean {
-  return BROWSER_REQUIREMENT_RE.test(text);
+  let inNonRequirementSection = false;
+  let nonRequirementDepth = 0;
+  for (const line of text.split(/\r?\n/)) {
+    const headingMatch = line.match(/^(#{1,6})\s+(.+?)\s*$/);
+    if (headingMatch) {
+      const depth = headingMatch[1]!.length;
+      const title = headingMatch[2] ?? "";
+      // Only update section context when at the same or higher level than the
+      // heading that opened the non-requirement zone. A sub-heading deeper than
+      // the opening heading must not escape or re-enter the zone on its own.
+      if (!inNonRequirementSection || depth <= nonRequirementDepth) {
+        inNonRequirementSection = NON_REQUIREMENT_BROWSER_HEADING_RE.test(title);
+        nonRequirementDepth = inNonRequirementSection ? depth : 0;
+      }
+      // Check the heading title itself — section state is already updated, so
+      // we correctly skip headings that opened a non-requirement zone.
+      if (!inNonRequirementSection && BROWSER_REQUIREMENT_RE.test(title)) return true;
+      continue;
+    }
+    if (inNonRequirementSection || NON_REQUIREMENT_BROWSER_LINE_RE.test(line)) continue;
+    if (BROWSER_REQUIREMENT_RE.test(line)) return true;
+  }
+  return false;
 }
 
 export function hasBrowserEvidenceText(text: string): boolean {

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -305,10 +305,18 @@ This config sets a parent workspace with two child repositories. The implicit `p
   - `max_cycles`: number — max times this hook fires per trigger (default: 1, max: 10).
   - `model`: string — optional model override.
   - `artifact`: string — expected output file name (relative to task/slice dir). Hook is skipped if file already exists (idempotent).
+  - `criticality`: `"advisory"` or `"blocking"` — advisory preserves current best-effort behavior; blocking requires clean hook completion plus a valid outcome verdict before auto-mode advances. Default: `"advisory"`.
   - `retry_on`: string — if this file is produced instead of the artifact, re-run the trigger unit then re-run hooks.
+  - `on_block`: object — optional routing for blocking findings:
+    - `action`: `"retry-unit"`, `"retry-task"`, `"queue-task"`, `"queue-slice"`, or `"pause"`.
+    - `artifact`: string — optional compatibility artifact for retry routing.
   - `agent`: string — agent definition file to use for hook execution.
   - `enabled`: boolean — toggle without removing (default: `true`).
 
+  Blocking hook artifacts must begin with YAML frontmatter containing either `verdict` or `outcome.verdict`.
+  Supported verdicts are `pass`, `advisory`, `needs-rework`, `needs-remediation`, and `needs-attention`.
+  `pass` and `advisory` continue; `needs-rework` retries the trigger unit when routed with `retry-unit`/`retry-task`; `needs-remediation` and `needs-attention` pause with recovery guidance.
+
 - `pre_dispatch_hooks`: array — hooks that fire before a unit is dispatched. Each entry has:
   - `name`: string — unique hook identifier.
   - `before`: string[] — unit types to intercept.

package/src/resources/extensions/gsd/doctor-runtime-checks.ts

@@ -269,14 +269,14 @@ export async function checkRuntimeHealth(
         } catch {
           count = MAX_UAT_ATTEMPTS + 1;
         }
-        if (count <= MAX_UAT_ATTEMPTS) continue;
+        if (count < MAX_UAT_ATTEMPTS) continue;
 
         issues.push({
           severity: "warning",
           code: "uat_retry_exhausted",
           scope: "slice",
           unitId: `${mid}/${sid}`,
-          message: `run-uat for ${mid}/${sid} exhausted ${count - 1} retry attempt(s) without an ASSESSMENT verdict. Reset the retry counter after fixing the underlying UAT/tool issue, then rerun /gsd auto.`,
+          message: `run-uat for ${mid}/${sid} exhausted ${count} attempt(s) without an ASSESSMENT verdict. Reset the retry counter after fixing the underlying UAT/tool issue, then rerun /gsd auto.`,
           file: `.gsd/runtime/${fileName}`,
           fixable: true,
         });

package/src/resources/extensions/gsd/post-unit-hooks.ts

@@ -9,6 +9,7 @@ import type {
   HookDispatchResult,
   PreDispatchResult,
   HookStatusEntry,
+  PostUnitGateBlock,
 } from "./types.js";
 import { getOrCreateRegistry, resolveHookArtifactPath } from "./rule-registry.js";
 
@@ -33,10 +34,22 @@ export function isRetryPending(): boolean {
   return getOrCreateRegistry().isRetryPending();
 }
 
-export function consumeRetryTrigger(): { unitType: string; unitId: string; retryArtifact: string } | null {
+export function consumeRetryTrigger(): { unitType: string; unitId: string; retryArtifact?: string } | null {
   return getOrCreateRegistry().consumeRetryTrigger();
 }
 
+export function consumeHookFailure(): { hookName: string; unitType: string; unitId: string; reason: string } | null {
+  return getOrCreateRegistry().consumeHookFailure();
+}
+
+export function isGateBlockPending(): boolean {
+  return getOrCreateRegistry().isGateBlockPending();
+}
+
+export function consumeGateBlock(): PostUnitGateBlock | null {
+  return getOrCreateRegistry().consumeGateBlock();
+}
+
 export function resetHookState(): void {
   getOrCreateRegistry().resetState();
 }

package/src/resources/extensions/gsd/preferences-validation.ts

@@ -29,6 +29,14 @@ const VALID_UOK_TURN_ACTIONS = new Set<"commit" | "snapshot" | "status-only">([
   "snapshot",
   "status-only",
 ]);
+const VALID_POST_UNIT_HOOK_CRITICALITIES = new Set(["advisory", "blocking"]);
+const VALID_POST_UNIT_HOOK_ON_BLOCK_ACTIONS = new Set([
+  "retry-unit",
+  "retry-task",
+  "queue-task",
+  "queue-slice",
+  "pause",
+]);
 
 export function validatePreferences(preferences: GSDPreferences): {
   preferences: GSDPreferences;
@@ -486,9 +494,37 @@ export function validatePreferences(preferences: GSDPreferences): {
       if (typeof hook.artifact === "string" && hook.artifact.trim()) {
         validHook.artifact = hook.artifact.trim();
       }
+      if (hook.criticality !== undefined) {
+        const criticality = typeof hook.criticality === "string" ? hook.criticality.trim() : "";
+        if (VALID_POST_UNIT_HOOK_CRITICALITIES.has(criticality)) {
+          validHook.criticality = criticality as PostUnitHookConfig["criticality"];
+        } else {
+          errors.push(`post_unit_hooks "${name}" invalid criticality: ${String(hook.criticality)}`);
+        }
+      }
       if (typeof hook.retry_on === "string" && hook.retry_on.trim()) {
         validHook.retry_on = hook.retry_on.trim();
       }
+      if (hook.on_block !== undefined) {
+        if (!hook.on_block || typeof hook.on_block !== "object") {
+          errors.push(`post_unit_hooks "${name}" on_block must be an object`);
+        } else {
+          const onBlock = hook.on_block as unknown as Record<string, unknown>;
+          const action = typeof onBlock.action === "string" ? onBlock.action.trim() : "";
+          if (!VALID_POST_UNIT_HOOK_ON_BLOCK_ACTIONS.has(action)) {
+            errors.push(`post_unit_hooks "${name}" invalid on_block action: ${String(onBlock.action)}`);
+          } else {
+            validHook.on_block = { action: action as NonNullable<PostUnitHookConfig["on_block"]>["action"] };
+            if (typeof onBlock.artifact === "string" && onBlock.artifact.trim()) {
+              validHook.on_block.artifact = onBlock.artifact.trim();
+            }
+          }
+        }
+      }
+      if (validHook.criticality === "blocking" && !validHook.artifact) {
+        errors.push(`post_unit_hooks "${name}" criticality blocking requires artifact`);
+        continue;
+      }
       if (typeof hook.agent === "string" && hook.agent.trim()) {
         validHook.agent = hook.agent.trim();
       }

package/src/resources/extensions/gsd/prompt-loader.ts

@@ -33,6 +33,10 @@ function hasRequiredExtensionAssets(rootDir: string, exists: ExistsFn = existsSy
   );
 }
 
+function isSourceExtensionDir(moduleDir: string): boolean {
+  return moduleDir.replaceAll("\\", "/").endsWith("/src/resources/extensions/gsd");
+}
+
 export function resolveExtensionDirFromCandidates(
   moduleDir: string,
   agentGsdDir: string,
@@ -41,6 +45,10 @@ export function resolveExtensionDirFromCandidates(
   const moduleUsable = hasRequiredExtensionAssets(moduleDir, exists);
   const agentUsable = hasRequiredExtensionAssets(agentGsdDir, exists);
 
+  // Source checkouts must use their own prompt tree. Otherwise local tests and
+  // dev runs can silently render stale prompts from ~/.gsd/agent/extensions/gsd.
+  if (moduleUsable && isSourceExtensionDir(moduleDir)) return moduleDir;
+
   // Prefer the user-local extension tree when both are valid. This avoids
   // leaking npm/global-install paths into prompts on Windows.
   if (agentUsable) return agentGsdDir;

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

@@ -63,35 +63,53 @@ After running all checks, compute the **overall verdict**:
 - `FAIL` — one or more automatable checks failed
 - `PARTIAL` — one or more automatable checks were skipped or returned inconclusive results (not the same as `NEEDS-HUMAN` — use PARTIAL only when the agent itself could not determine pass/fail for a check it was supposed to automate)
 
-Call `gsd_summary_save` with `milestone_id: "{{milestoneId}}"`, `slice_id: "{{sliceId}}"`, `artifact_type: "ASSESSMENT"`, and the full UAT result markdown as `content`. The tool computes the assessment path, persists to DB/disk, and saves the aggregate UAT gate. The content should follow this logical shape:
+Call `gsd_uat_result_save` once after all checks are complete. The tool computes the assessment path, persists to DB/disk, saves attempt history, and saves the aggregate UAT gate.
 
-```markdown
----
-sliceId: {{sliceId}}
-uatType: {{uatType}}
-verdict: PASS | FAIL | PARTIAL
-date: <ISO 8601 timestamp>
----
-
-# UAT Result — {{sliceId}}
-
-## Checks
+Pass these top-level fields:
 
-| Check | Mode | Result | Notes |
-|-------|------|--------|-------|
-| <check description> | artifact / runtime / human-follow-up | PASS / FAIL / NEEDS-HUMAN | <observed output, evidence, or reason> |
-
-## Overall Verdict
-
-<PASS / FAIL / PARTIAL> — <one sentence summary>
+```ts
+milestoneId: "{{milestoneId}}",
+sliceId: "{{sliceId}}",
+uatType: "{{uatType}}",
+verdict: "PASS" | "FAIL" | "PARTIAL",
+notes: "<one sentence overall verdict rationale>",
+```
 
-## Notes
+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:
+
+```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" },
+  ],
+}
+```
 
-<any additional context, errors encountered, screenshots/logs gathered, or manual follow-up still required>
+Pass `checks` with this logical shape:
+
+```ts
+checks: [{
+  id: "<stable check id>",
+  description: "<check description from the UAT file>",
+  mode: "artifact" | "runtime" | "browser" | "human-follow-up",
+  result: "PASS" | "FAIL" | "NEEDS-HUMAN",
+  evidence: [{ kind: "gsd_uat_exec", ref: "<evidence id>" }],
+  notes: "<observed output, evidence, reason, or manual follow-up>",
+}]
 ```
 
 ---
 
-**You MUST call `gsd_summary_save` with `artifact_type: "ASSESSMENT"` and the UAT result content before finishing. Do not write the assessment file directly.**
+**You MUST call `gsd_uat_result_save` before finishing. Do not write the assessment file directly, and do not call `gsd_summary_save` as a substitute.**
 
 When done, say: "UAT {{sliceId}} complete."

package/src/resources/extensions/gsd/prompts/validate-milestone.md

@@ -33,7 +33,7 @@ Prompt: "Review milestone {{milestoneId}} requirements coverage. Working directo
 Prompt: "Review milestone {{milestoneId}} cross-slice integration. Working directory: {{workingDirectory}}. Read `{{roadmapPath}}` and find the boundary map (produces/consumes contracts). For each boundary, confirm producer SUMMARY produced the artifact and consumer SUMMARY consumed it. Output table: Boundary | Producer Summary | Consumer Summary | Status. End with one-line verdict: PASS if all boundaries honored, NEEDS-ATTENTION if any gaps."
 
 **Reviewer C - Assessment & Acceptance Criteria**
-Prompt: "Review milestone {{milestoneId}} assessment evidence and acceptance criteria. Working directory: {{workingDirectory}}. Read `.gsd/milestones/{{milestoneId}}/{{milestoneId}}-CONTEXT.md` for criteria. Check slice SUMMARY and ASSESSMENT files under `.gsd/milestones/{{milestoneId}}/slices/`; UAT files are specs, not evidence. Verify each criterion maps to passing evidence. Then review inlined milestone verification classes. For each non-empty planned class, output table: Class | Planned Check | Evidence | Verdict. Use the exact class names `Contract`, `Integration`, `Operational`, and `UAT` whenever those classes are present. If a planned browser/UAT class has no ASSESSMENT with browser/runtime actions and assertions, return NEEDS-ATTENTION. If no verification classes were planned, say that explicitly. Output sections `Acceptance Criteria` with checklist `[ ] Criterion | Evidence`, and `Verification Classes` with the table. End with one-line verdict: PASS if all criteria and classes are covered by evidence, NEEDS-ATTENTION if gaps exist."
+Prompt: "Review milestone {{milestoneId}} assessment evidence and acceptance criteria. Working directory: {{workingDirectory}}. Read `.gsd/milestones/{{milestoneId}}/{{milestoneId}}-CONTEXT.md` for criteria. Check slice SUMMARY and ASSESSMENT files under `.gsd/milestones/{{milestoneId}}/slices/`; UAT files are specs, not evidence. Verify each criterion maps to passing evidence. Then review the inlined `Verification Classes (from planning)` table. For every planned row in that table, output a `Verification Classes` table with columns `Class | Planned Check | Evidence | Verdict`. Preserve every planned non-empty class row; do not summarize, rename, combine, or omit planned classes. The first cell of each row must be exactly `Contract`, `Integration`, `Operational`, or `UAT` when that class is present in planning. If a planned class lacks evidence, still include its canonical row and mark the verdict NEEDS-ATTENTION or FAIL. If a planned browser/UAT class has no ASSESSMENT with browser/runtime actions and assertions, return NEEDS-ATTENTION. If no verification classes were planned, say that explicitly. Output sections `Acceptance Criteria` with checklist `[ ] Criterion | Evidence`, and `Verification Classes` with the table. End with one-line verdict: PASS if all criteria and classes are covered by evidence, NEEDS-ATTENTION if gaps exist."
 
 ### Step 2 - Synthesize Findings
 
@@ -71,8 +71,8 @@ reviewers: 3
 <if verdict is not pass: specific actions required>
 ```
 
-Call `gsd_validate_milestone` with the camelCase fields `milestoneId`, `verdict`, `remediationRound`, `successCriteriaChecklist`, `sliceDeliveryAudit`, `crossSliceIntegration`, `requirementCoverage`, `verdictRationale`, and `remediationPlan` when needed. If you include verification-class analysis, pass it in `verificationClasses`.
-Extract the `Verification Classes` subsection from Reviewer C and pass it verbatim in `verificationClasses` so the persisted validation output uses the canonical class names `Contract`, `Integration`, `Operational`, and `UAT`.
+Call `gsd_validate_milestone` with the camelCase fields `milestoneId`, `verdict`, `remediationRound`, `successCriteriaChecklist`, `sliceDeliveryAudit`, `crossSliceIntegration`, `requirementCoverage`, `verdictRationale`, and `remediationPlan` when needed. If planning included verification classes, pass a complete canonical table in `verificationClasses`.
+Set `verificationClasses` to the `Verification Classes` subsection from Reviewer C. It must include one canonical row for every non-empty planned class from `Verification Classes (from planning)`: `Contract`, `Integration`, `Operational`, and/or `UAT`. If Reviewer C omitted a planned class, reconstruct the missing row from the planning table, set Evidence to the gap, and use NEEDS-ATTENTION or FAIL. Do not call `gsd_validate_milestone` with a partial `verificationClasses` table.
 
 **DB access safety:** Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')` - the engine owns the WAL connection. Use `gsd_milestone_status` for milestone and slice state. Data is already inlined or available via `gsd_*` tools. Direct DB access risks WAL corruption and bypasses validation.