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

package/src/resources/extensions/gsd/tools/complete-task.ts

@@ -12,7 +12,7 @@
 
 import { join } from "node:path";
 
-import type { CompleteTaskParams } from "../types.js";
+import type { CompleteTaskParams, EscalationArtifact } from "../types.js";
 import { isClosedStatus } from "../status-guards.js";
 import {
   transaction,
@@ -48,6 +48,14 @@ export interface CompleteTaskResult {
   sliceId: string;
   milestoneId: string;
   summaryPath: string;
+  escalation?: {
+    artifactPath: string;
+    question: string;
+    options: EscalationArtifact["options"];
+    recommendation: string;
+    recommendationRationale: string;
+    continueWithDefault: boolean;
+  };
   /**
    * True when this call re-completed an already-closed task from a turn that
    * had been superseded by timeout recovery or cancellation. The underlying
@@ -407,9 +415,18 @@ export async function handleCompleteTask(
   // 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: CompleteTaskResult["escalation"] | undefined;
   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 as Error).message}`;
       logWarning("tool", msg);
@@ -477,6 +494,7 @@ export async function handleCompleteTask(
     sliceId: params.sliceId,
     milestoneId: params.milestoneId,
     summaryPath,
+    ...(escalationMetadata ? { escalation: escalationMetadata } : {}),
     ...(projectionStale ? { stale: true } : {}),
   };
 }

package/src/resources/extensions/gsd/tools/validate-milestone.ts

@@ -78,18 +78,10 @@ function getRequiredVerificationClasses(milestoneId: string): string[] {
   return required;
 }
 
-async function collectPersistedBrowserEvidence(basePath: string, milestoneId: string): Promise<string> {
-  const chunks: string[] = [];
-  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: string): boolean {
+  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(
@@ -114,7 +106,38 @@ async function browserEvidenceGateRequiresAttention(
   ]);
   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: Array<{ sliceRequirementText: string; evidenceText: string }> = [];
+  for (const slice of slices) {
+    const chunks: string[] = [];
+    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,
@@ -184,14 +207,22 @@ export async function handleValidateMilestone(
   const requiredClasses = getRequiredVerificationClasses(params.milestoneId);
   if (requiredClasses.length > 0) {
     const verificationClasses = params.verificationClasses ?? "";
-    const missingClass = requiredClasses.find(
+    const missingClasses = requiredClasses.filter(
       (className) => !new RegExp(`\\b${className}\\b`, "i").test(verificationClasses),
     );
-    if (missingClass) {
+    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);

package/src/resources/extensions/gsd/tools/workflow-tool-executors.ts

@@ -24,7 +24,7 @@ import { isAbsolute, join, resolve } from "node:path";
 import type { CompleteMilestoneParams } from "./complete-milestone.js";
 import { handleCompleteMilestone } from "./complete-milestone.js";
 import { handleCompleteTask } from "./complete-task.js";
-import type { CompleteSliceParams } from "../types.js";
+import type { CompleteSliceParams, EscalationOption } from "../types.js";
 import { handleCompleteSlice } from "./complete-slice.js";
 import type { PlanMilestoneParams } from "./plan-milestone.js";
 import { handlePlanMilestone } from "./plan-milestone.js";
@@ -48,9 +48,11 @@ import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { parseProject } from "../schemas/parsers.js";
 import { getAutoRuntimeSnapshot } from "../auto-runtime-state.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";
 
@@ -90,7 +92,7 @@ function blockIfWrongAutoUnit(requiredUnitType: string, operation: string): Tool
   if (!snapshot.active || !snapshot.currentUnit) 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 },
@@ -178,7 +180,11 @@ export async function executeSummarySave(
   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,
     };
   }
@@ -191,9 +197,13 @@ export async function executeSummarySave(
   if (contextGuard.block) {
     return {
       content: [{ type: "text", text: `Error saving artifact: ${contextGuard.reason ?? "context write blocked"}` }],
-      details: { operation: "save_summary", error: "context_write_blocked" },
-    isError: true,
-      };
+      details: {
+        operation: "save_summary",
+        error: "context_write_blocked",
+        displayReason: "Depth check required before writing milestone context.",
+      },
+      isError: true,
+    };
   }
   try {
     let relativePath: string;
@@ -347,6 +357,14 @@ type VerificationEvidenceInput =
     }
   | string;
 
+interface TaskEscalationInput {
+  question: string;
+  options: EscalationOption[];
+  recommendation: string;
+  recommendationRationale: string;
+  continueWithDefault: boolean;
+}
+
 export interface TaskCompleteParams {
   taskId: string;
   sliceId: string;
@@ -359,6 +377,7 @@ export interface TaskCompleteParams {
   keyFiles?: string[];
   keyDecisions?: string[];
   blockerDiscovered?: boolean;
+  escalation?: TaskEscalationInput;
   verificationEvidence?: VerificationEvidenceInput[];
 }
 
@@ -432,6 +451,9 @@ export interface UatEvidenceRef {
   kind: "gsd_uat_exec" | "gsd_exec" | "screenshot" | "log" | "url" | "browser";
   ref: string;
   note?: string;
+  unitType?: string;
+  tool?: string;
+  executionId?: string;
 }
 
 export interface UatCheckResultInput {
@@ -511,6 +533,28 @@ export async function executeTaskComplete(
       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: {
@@ -977,10 +1021,68 @@ function isNonEmptyString(value: unknown): value is string {
   return typeof value === "string" && value.trim().length > 0;
 }
 
+function mergeBlockedTools(
+  current: UatPresentationInput["blockedTools"] | undefined,
+  canonical: UatPresentationInput["blockedTools"],
+): UatPresentationInput["blockedTools"] {
+  const merged = new Map<string, { name: string; reason: string }>();
+  for (const entry of [...(current ?? []), ...canonical]) {
+    merged.set(canonicalWorkflowToolName(parseMcpToolName(entry.name)?.tool ?? entry.name), entry);
+  }
+  return [...merged.values()];
+}
+
+function mergePresentedTools(current: readonly string[] | undefined, canonical: readonly string[]): string[] {
+  return [...new Set([...(current ?? []), ...canonical])];
+}
+
+function normalizeUatVerdict(params: UatResultSaveParams): UatResultSaveParams {
+  const raw = params as Partial<UatResultSaveParams> & Record<string, unknown>;
+  if (typeof raw.verdict === "string") {
+    return { ...params, verdict: raw.verdict.toUpperCase() as UatVerdict };
+  }
+  return params;
+}
+
+function supplyDefaultPresentation(params: UatResultSaveParams): UatResultSaveParams {
+  const raw = params as Partial<UatResultSaveParams> & Record<string, unknown>;
+  if (!raw.presentation) {
+    return { ...params, presentation: buildRunUatPresentationForType(params.uatType) };
+  }
+  return params;
+}
+
+function mergeCanonicalPresentation(params: UatResultSaveParams): UatResultSaveParams {
+  const canonicalPresentation = buildRunUatPresentationForType(params.uatType);
+  const providedPresentation = params.presentation as Partial<UatPresentationInput>;
+  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,
+    } as UatPresentationInput,
+  };
+}
+
+const VALID_UAT_TYPES: readonly UatType[] = [
+  "artifact-driven",
+  "browser-executable",
+  "runtime-executable",
+  "live-runtime",
+  "mixed",
+  "human-experience",
+];
+
 function ensureUatRequiredFields(params: UatResultSaveParams): string | null {
   if (!isNonEmptyString(params.milestoneId)) return "milestoneId is required";
   if (!isNonEmptyString(params.sliceId)) return "sliceId is required";
   if (!isNonEmptyString(params.uatType)) return "uatType is required";
+  if (!(VALID_UAT_TYPES as readonly string[]).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) return "checks must contain at least one UAT check";
   if (!params.presentation || !Array.isArray(params.presentation.presentedTools)) return "presentation.presentedTools is required";
@@ -1116,9 +1218,21 @@ function validateUatChecks(basePath: string, params: UatResultSaveParams): strin
   return null;
 }
 
+function validateFreshUatOwnedEvidence(params: UatResultSaveParams): string | null {
+  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: UatResultSaveParams): string | null {
   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" &&
@@ -1136,12 +1250,13 @@ function validateUatMode(params: UatResultSaveParams): string | null {
   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: readonly string[]): string {
+  return toolNames.map((toolName) => `"${toolName}"`).join(", ");
+}
+
 function validateCanonicalPresentation(params: UatResultSaveParams): string | null {
   const aliasHints: Record<string, string> = {
     gsd_save_summary: "gsd_summary_save",
@@ -1149,10 +1264,11 @@ function validateCanonicalPresentation(params: UatResultSaveParams): string | nu
     gsd_complete_slice: "gsd_slice_complete",
     gsd_milestone_complete: "gsd_complete_milestone",
   };
+  const errors: string[] = [];
   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}"`;
+    if (canonical) errors.push(`presentation tool "${toolName}" uses an alias; use canonical "${canonical}"`);
   }
 
   const presentedCanonical = new Set(
@@ -1160,10 +1276,13 @@ function validateCanonicalPresentation(params: UatResultSaveParams): string | nu
       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(
@@ -1171,24 +1290,33 @@ function validateCanonicalPresentation(params: UatResultSaveParams): string | nu
       .filter((toolName) => !toolName.includes("*"))
       .map((toolName) => canonicalWorkflowToolName(parseMcpToolName(toolName)?.tool ?? toolName)),
   );
+  const forbiddenPresentedTools: string[] = [];
   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`);
+  } else if (missingBlockedTools.length > 1) {
+    errors.push(`presentation must record ${quoteToolNames(missingBlockedTools)} as blocked during run-uat`);
   }
-  return null;
+  return errors.length > 0 ? errors.join("; ") : null;
 }
 
 function nextUatAttempt(basePath: string, milestoneId: string, sliceId: string): number {
@@ -1258,15 +1386,30 @@ export async function executeUatResultSave(
   params: UatResultSaveParams,
   basePath: string = process.cwd(),
 ): Promise<ToolExecutionResult> {
+  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/src/resources/extensions/gsd/types.ts

@@ -270,6 +270,29 @@ export interface GSDActiveUnit {
 
 // ─── Post-Unit Hook Types ─────────────────────────────────────────────────
 
+export type PostUnitHookCriticality = "advisory" | "blocking";
+
+export type PostUnitHookOutcomeVerdict =
+  | "pass"
+  | "advisory"
+  | "needs-rework"
+  | "needs-remediation"
+  | "needs-attention";
+
+export type PostUnitHookOnBlockAction =
+  | "retry-unit"
+  | "retry-task"
+  | "queue-task"
+  | "queue-slice"
+  | "pause";
+
+export interface PostUnitHookOnBlockConfig {
+  /** Routing action for blocking hook findings. */
+  action: PostUnitHookOnBlockAction;
+  /** Optional artifact used by compatibility retry routing. */
+  artifact?: string;
+}
+
 export interface PostUnitHookConfig {
   /** Unique hook identifier — used in idempotency keys and logging. */
   name: string;
@@ -283,8 +306,12 @@ export interface PostUnitHookConfig {
   model?: string;
   /** Expected output file name (relative to task/slice dir). Used for idempotency — skip if exists. */
   artifact?: string;
+  /** Whether the hook is advisory or blocks unit advancement. Default advisory. */
+  criticality?: PostUnitHookCriticality;
   /** If this file is produced instead of artifact, re-run the trigger unit then re-run hooks. */
   retry_on?: string;
+  /** Optional routing for blocking findings. */
+  on_block?: PostUnitHookOnBlockConfig;
   /** Agent definition file to use. */
   agent?: string;
   /** Set false to disable without removing config. Default true. */
@@ -317,6 +344,31 @@ export interface HookDispatchResult {
   unitId: string;
 }
 
+export interface PostUnitGateBlock {
+  /** Blocking hook name. */
+  hookName: string;
+  /** The unit type that triggered the gate. */
+  triggerUnitType: string;
+  /** The unit ID that triggered the gate. */
+  triggerUnitId: string;
+  /** Gate artifact name, when configured. */
+  artifact?: string;
+  /** Absolute path to the gate artifact, when known. */
+  artifactPath?: string;
+  /** Parsed blocking verdict, when present. */
+  verdict?: PostUnitHookOutcomeVerdict | "failed";
+  /** Configured routing action that caused the pause. */
+  action: PostUnitHookOnBlockAction;
+  /** Human-readable pause reason. */
+  reason: string;
+  /** Current hook cycle count. */
+  cycle: number;
+  /** Configured max cycle count. */
+  maxCycles: number;
+  /** Optional compatibility retry artifact. */
+  retryArtifact?: string;
+}
+
 // ─── Budget & Notification Types ──────────────────────────────────────────
 
 export type BudgetEnforcementMode = "warn" | "pause" | "halt";
@@ -384,10 +436,10 @@ export interface EscalationArtifact {
   /** Why the executor recommends that option (1-2 sentences). */
   recommendationRationale: string;
   /**
-   * When true, the executor proceeds with the recommendation as the answer
-   * and the loop continues. User's later choice becomes a carry-forward
-   * override for the NEXT task. When false, auto-mode pauses until the
-   * user resolves via `/gsd escalate resolve`.
+   * When true, the recommendation is recorded as the default path but the
+   * loop still pauses until the user explicitly resolves the escalation.
+   * When false, auto-mode also pauses until the user resolves via
+   * `/gsd escalate resolve`.
    */
   continueWithDefault: boolean;
   createdAt: string;
@@ -452,6 +504,15 @@ export interface PreDispatchResult {
 export interface PersistedHookState {
   /** Cycle counts keyed as "hookName/triggerUnitType/triggerUnitId". */
   cycleCounts: Record<string, number>;
+  /** In-flight hook, persisted so blocking gates cannot be skipped after resume. */
+  activeHook?: HookExecutionState | null;
+  /** Remaining hook queue by hook name and trigger unit. */
+  hookQueue?: Array<{
+    hookName: string;
+    triggerUnitType: string;
+    triggerUnitId: string;
+    forceRun?: boolean;
+  }>;
   /** Timestamp of last state save. */
   savedAt: string;
 }
@@ -465,6 +526,8 @@ export interface HookStatusEntry {
   enabled: boolean;
   /** What unit types it targets. */
   targets: string[];
+  /** Whether this post-unit hook is advisory or blocking. */
+  criticality?: PostUnitHookCriticality;
   /** Current cycle counts for active triggers. */
   activeCycles: Record<string, number>;
 }
@@ -644,7 +707,8 @@ export interface CompleteSliceParams {
   sliceTitle: string;
   oneLiner: string;
   narrative: string;
-  verification: string;
+  /** @optional — if omitted, verification section is left blank in summary */
+  verification?: string;
   uatContent: string;
   /** @optional — defaults to [] when omitted by models with limited tool-calling */
   keyFiles?: string[];