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

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

@@ -235,6 +235,62 @@ test("executeTaskComplete derives missing verification from evidence", async ()
   }
 });
 
+test("executeTaskComplete surfaces escalation questions and metadata", async () => {
+  const base = makeTmpBase();
+  try {
+    openTestDb(base);
+    writeFileSync(join(base, ".gsd", "PREFERENCES.md"), [
+      "---",
+      "version: 1",
+      "phases:",
+      "  mid_execution_escalation: true",
+      "---",
+    ].join("\n"));
+    const planDir = join(base, ".gsd", "milestones", "M001", "slices", "S01");
+    mkdirSync(planDir, { recursive: true });
+    writeFileSync(join(planDir, "S01-PLAN.md"), "# S01\n\n- [ ] **T01: Demo** `est:5m`\n");
+
+    const result = await inProjectDir(base, () => executeTaskComplete({
+      milestoneId: "M001",
+      sliceId: "S01",
+      taskId: "T01",
+      oneLiner: "Completed task",
+      narrative: "Did the work but found an ambiguity.",
+      verification: "npm test",
+      escalation: {
+        question: "Should the cache use write-through or write-back?",
+        options: [
+          { id: "A", label: "Write-through", tradeoffs: "Simpler reads; slower writes." },
+          { id: "B", label: "Write-back", tradeoffs: "Faster writes; more flush complexity." },
+        ],
+        recommendation: "A",
+        recommendationRationale: "Current usage favors correctness over write latency.",
+        continueWithDefault: true,
+      },
+    }, base));
+
+    assert.equal(result.details.operation, "complete_task");
+    assert.match(
+      String(result.content[0]?.text),
+      /Task completed with escalation decision required: Should the cache use write-through or write-back\?/,
+    );
+    assert.match(String(result.content[0]?.text), /Resolve with: \/gsd escalate resolve T01/);
+    assert.equal((result.details.escalation as { question?: string }).question, "Should the cache use write-through or write-back?");
+
+    const db = _getAdapter();
+    assert.ok(db, "DB should be open");
+    const row = db!.prepare(
+      "SELECT escalation_pending, escalation_awaiting_review, escalation_artifact_path FROM tasks WHERE milestone_id = ? AND slice_id = ? AND id = ?",
+    ).get("M001", "S01", "T01") as Record<string, unknown> | undefined;
+    assert.equal(row?.escalation_pending, 0);
+    assert.equal(row?.escalation_awaiting_review, 1);
+    assert.ok(String(row?.escalation_artifact_path ?? "").endsWith("T01-ESCALATION.json"));
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
 test("executeTaskComplete returns a tool error when verification cannot be derived", async () => {
   const base = makeTmpBase();
   try {
@@ -587,6 +643,80 @@ test("executeUatResultSave accepts gsd_uat_exec evidence written in a milestone
   }
 });
 
+test("executeUatResultSave rejects artifact-driven PASS with human follow-up checks", async () => {
+  const base = makeTmpBase();
+  const worktree = join(base, ".gsd", "worktrees", "M001");
+  const evidenceId = "uat-artifact-nonautomatable";
+  const worktreeExecDir = join(worktree, ".gsd", "exec");
+  try {
+    openTestDb(base);
+    seedMilestone("M001", "Milestone One");
+    seedSlice("M001", "S01", "complete");
+    mkdirSync(worktreeExecDir, { recursive: true });
+    writeFileSync(
+      join(worktreeExecDir, `${evidenceId}.meta.json`),
+      JSON.stringify({
+        id: evidenceId,
+        metadata: {
+          kind: "uat_exec",
+          milestoneId: "M001",
+          sliceId: "S01",
+          checkId: "UAT-01",
+          intent: "uat-artifact-check",
+        },
+      }),
+      "utf-8",
+    );
+
+    const result = await inProjectDir(worktree, () => executeUatResultSave({
+      milestoneId: "M001",
+      sliceId: "S01",
+      uatType: "artifact-driven",
+      verdict: "PASS",
+      checks: [
+        {
+          id: "UAT-01",
+          description: "Static contract passes",
+          mode: "artifact",
+          result: "PASS",
+          evidence: [{ kind: "gsd_uat_exec", ref: evidenceId }],
+          notes: "Artifact check passed.",
+        },
+        {
+          id: "UAT-02",
+          description: "Browser polish is deferred to the next slice",
+          mode: "human-follow-up",
+          result: "NEEDS-HUMAN",
+          notes: "Out of scope for this artifact-driven UAT.",
+          nonAutomatable: true,
+        },
+      ],
+      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" },
+        ],
+      },
+      notes: "UAT passed; non-automatable browser polish is deferred.",
+    }, worktree));
+
+    assert.equal(result.isError, true);
+    assert.match(String(result.content[0]?.text), /artifact-driven UAT cannot PASS with human-only checks/);
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
 test("executeSliceComplete coerces string enrichment entries and writes summary/UAT artifacts", async () => {
   const base = makeTmpBase();
   try {

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

@@ -217,7 +217,7 @@ ${params.narrative}
 
 ## Verification
 
-${params.verification}
+${params.verification ?? ""}
 
 ## Requirements Advanced
 
@@ -440,6 +440,19 @@ export async function handleCompleteSlice(
       const parsed = parseRequirementSection(existingSummaryMd, "Requirements Invalidated or Re-scoped", "what");
       if (parsed.length > 0) effectiveParams.requirementsInvalidated = parsed as Array<{ id: string; what: string }>;
     }
+    if (effectiveParams.verification === undefined) {
+      const headingLine = "## Verification\n\n";
+      const start = existingSummaryMd.indexOf(headingLine);
+      if (start !== -1) {
+        const contentStart = start + headingLine.length;
+        const nextHeading = existingSummaryMd.indexOf("\n\n## ", contentStart);
+        const prior = nextHeading === -1
+          ? existingSummaryMd.slice(contentStart)
+          : existingSummaryMd.slice(contentStart, nextHeading);
+        const trimmed = prior.trim();
+        if (trimmed) effectiveParams.verification = trimmed;
+      }
+    }
   }
 
   // Render summary markdown

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";
@@ -347,6 +347,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 +367,7 @@ export interface TaskCompleteParams {
   keyFiles?: string[];
   keyDecisions?: string[];
   blockerDiscovered?: boolean;
+  escalation?: TaskEscalationInput;
   verificationEvidence?: VerificationEvidenceInput[];
 }
 
@@ -511,6 +520,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: {
@@ -1119,6 +1150,9 @@ function validateUatChecks(basePath: string, params: UatResultSaveParams): strin
 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 +1170,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 +1184,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 +1196,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 +1210,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 {

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[];