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

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

@@ -75,6 +75,11 @@ test("closeout executors reject phase escalation from the wrong active auto unit
     const milestone = await executeCompleteMilestone({} as Parameters<typeof executeCompleteMilestone>[0], "/tmp/project");
     assert.equal(milestone.isError, true);
     assert.match(String(milestone.details.error), /complete_milestone may only run from complete-milestone/);
+
+    const uat = await executeUatResultSave({} as Parameters<typeof executeUatResultSave>[0], "/tmp/project");
+    assert.equal(uat.isError, true);
+    assert.match(String(uat.details.error), /save_uat_result may only run from run-uat/);
+    assert.match(String(uat.details.error), /Tool Contract failure/);
   } finally {
     autoSession.reset();
   }
@@ -235,6 +240,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 +648,284 @@ test("executeUatResultSave accepts gsd_uat_exec evidence written in a milestone
   }
 });
 
+test("executeUatResultSave supplies canonical presentation and normalizes verdict casing", async () => {
+  const base = makeTmpBase();
+  const worktree = join(base, ".gsd", "worktrees", "M001");
+  const worktreeExecDir = join(worktree, ".gsd", "exec");
+  const evidenceId = "uat-lowercase-verdict";
+  try {
+    openTestDb(base);
+    seedMilestone("M001", "Milestone One");
+    seedSlice("M001", "S03", "complete");
+    mkdirSync(worktreeExecDir, { recursive: true });
+    writeFileSync(
+      join(worktreeExecDir, `${evidenceId}.meta.json`),
+      JSON.stringify({
+        id: evidenceId,
+        metadata: {
+          kind: "uat_exec",
+          milestoneId: "M001",
+          sliceId: "S03",
+          checkId: "UAT-01",
+          intent: "uat-artifact-check",
+        },
+      }),
+      "utf-8",
+    );
+
+    const result = await inProjectDir(worktree, () => executeUatResultSave({
+      milestoneId: "M001",
+      sliceId: "S03",
+      uatType: "artifact-driven",
+      verdict: "pass",
+      checks: [{
+        id: "UAT-01",
+        description: "Static artifact contract passes",
+        mode: "artifact",
+        result: "PASS",
+        evidence: [{ kind: "gsd_uat_exec", ref: evidenceId }],
+        notes: "Artifact check passed.",
+      }],
+      notes: "UAT passed with canonical presentation supplied by the executor.",
+    } as unknown as Parameters<typeof executeUatResultSave>[0], worktree));
+
+    assert.equal(result.isError, undefined);
+    assert.equal(result.details.verdict, "PASS");
+
+    const attempt = JSON.parse(readFileSync(
+      join(base, ".gsd", "uat", "M001", "S03", "attempt-1.json"),
+      "utf-8",
+    )) as { presentation?: { toolPresentationPlanId?: string; presentedTools?: string[] } };
+    assert.equal(attempt.presentation?.toolPresentationPlanId, "run-uat/default-v1");
+    assert.ok(attempt.presentation?.presentedTools?.includes("gsd_uat_result_save"));
+    assert.ok(attempt.presentation?.presentedTools?.includes("read"));
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executeUatResultSave merges canonical plan ID and read-only tools when presentation lacks plan ID", async () => {
+  const base = makeTmpBase();
+  const worktree = join(base, ".gsd", "worktrees", "M001");
+  const worktreeExecDir = join(worktree, ".gsd", "exec");
+  const evidenceId = "uat-no-plan-id-evidence";
+  try {
+    openTestDb(base);
+    seedMilestone("M001", "Milestone One");
+    seedSlice("M001", "S05", "complete");
+    mkdirSync(worktreeExecDir, { recursive: true });
+    writeFileSync(
+      join(worktreeExecDir, `${evidenceId}.meta.json`),
+      JSON.stringify({
+        id: evidenceId,
+        metadata: {
+          kind: "uat_exec",
+          milestoneId: "M001",
+          sliceId: "S05",
+          checkId: "UAT-01",
+          intent: "uat-artifact-check",
+        },
+      }),
+      "utf-8",
+    );
+
+    const result = await inProjectDir(worktree, () => executeUatResultSave({
+      milestoneId: "M001",
+      sliceId: "S05",
+      uatType: "artifact-driven",
+      verdict: "PASS",
+      checks: [{
+        id: "UAT-01",
+        description: "Presentation plan ID absent from provider call",
+        mode: "artifact",
+        result: "PASS",
+        evidence: [{ kind: "gsd_uat_exec", ref: evidenceId }],
+        notes: "Canonical merge should apply even when toolPresentationPlanId is absent.",
+      }],
+      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: "Provider omitted toolPresentationPlanId; executor must canonicalize.",
+    } as unknown as Parameters<typeof executeUatResultSave>[0], worktree));
+
+    assert.equal(result.isError, undefined);
+    assert.equal(result.details.verdict, "PASS");
+
+    const attempt = JSON.parse(readFileSync(
+      join(base, ".gsd", "uat", "M001", "S05", "attempt-1.json"),
+      "utf-8",
+    )) as { presentation?: { toolPresentationPlanId?: string; presentedTools?: string[] } };
+    assert.equal(attempt.presentation?.toolPresentationPlanId, "run-uat/default-v1");
+    assert.ok(attempt.presentation?.presentedTools?.includes("read"), "read-only tool must be merged in");
+    assert.ok(attempt.presentation?.presentedTools?.includes("gsd_uat_result_save"));
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executeUatResultSave rejects saved UAT without fresh UAT-owned evidence", async () => {
+  const base = makeTmpBase();
+  const worktree = join(base, ".gsd", "worktrees", "M001");
+  const worktreeExecDir = join(worktree, ".gsd", "exec");
+  const evidenceId = "generic-exec-evidence";
+  try {
+    openTestDb(base);
+    seedMilestone("M001", "Milestone One");
+    seedSlice("M001", "S04", "complete");
+    mkdirSync(worktreeExecDir, { recursive: true });
+    writeFileSync(
+      join(worktreeExecDir, `${evidenceId}.meta.json`),
+      JSON.stringify({
+        id: evidenceId,
+        metadata: { kind: "exec" },
+      }),
+      "utf-8",
+    );
+
+    const result = await inProjectDir(worktree, () => executeUatResultSave({
+      milestoneId: "M001",
+      sliceId: "S04",
+      uatType: "artifact-driven",
+      verdict: "PASS",
+      checks: [{
+        id: "UAT-01",
+        description: "Static artifact contract passes",
+        mode: "artifact",
+        result: "PASS",
+        evidence: [{ kind: "gsd_exec", ref: evidenceId }],
+        notes: "Generic evidence should not satisfy fresh UAT evidence.",
+      }],
+      notes: "UAT should not pass without fresh UAT-owned evidence.",
+    } as unknown as Parameters<typeof executeUatResultSave>[0], worktree));
+
+    assert.equal(result.isError, true);
+    assert.match(String(result.content[0]?.text), /fresh gsd_uat_exec evidence/);
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executeUatResultSave rejects an unrecognized uatType", async () => {
+  const base = makeTmpBase();
+  const worktree = join(base, ".gsd", "worktrees", "M001");
+  try {
+    openTestDb(base);
+    mkdirSync(worktree, { recursive: true });
+    seedMilestone("M001", "Milestone One");
+    seedSlice("M001", "S06", "complete");
+
+    const result = await inProjectDir(worktree, () => executeUatResultSave({
+      milestoneId: "M001",
+      sliceId: "S06",
+      uatType: "hallucinated-mode",
+      verdict: "PASS",
+      checks: [{
+        id: "UAT-01",
+        description: "Static artifact contract passes",
+        mode: "artifact",
+        result: "PASS",
+        evidence: [{ kind: "gsd_uat_exec", ref: "some-ref" }],
+      }],
+      notes: "Should fail before evidence validation.",
+    } as unknown as Parameters<typeof executeUatResultSave>[0], worktree));
+
+    assert.equal(result.isError, true);
+    assert.match(String(result.content[0]?.text), /uatType must be one of/);
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+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 {
@@ -1279,6 +1618,10 @@ test("executeSummarySave blocks final root artifacts while approval gate is pend
 
     assert.equal(result.isError, true);
     assert.equal(result.details.error, "root_artifact_write_blocked");
+    assert.equal(
+      result.details.displayReason,
+      "Approval confirmation required before saving final project setup artifacts.",
+    );
     assert.match(result.content[0].text, /has not been confirmed/);
     assert.equal(existsSync(join(base, ".gsd", "REQUIREMENTS.md")), false);
 
@@ -1321,6 +1664,10 @@ test("executeSummarySave requires verified root approval in deep mode", async ()
 
     assert.equal(blocked.isError, true);
     assert.equal(blocked.details.error, "root_artifact_write_blocked");
+    assert.equal(
+      blocked.details.displayReason,
+      "Approval confirmation required before saving final project setup artifacts.",
+    );
     assert.match(blocked.content[0].text, /fail-closed/);
     assert.equal(existsSync(join(base, ".gsd", "PROJECT.md")), false);
 
@@ -1537,6 +1884,10 @@ test("executeSummarySave CONTEXT HARD BLOCK clears after write-gate state file i
       content: "# Context\n\ncontent",
     }, base));
     assert.equal(blocked.isError, true, "should be blocked without depth verification");
+    assert.equal(
+      blocked.details.displayReason,
+      "Depth check required before writing milestone context.",
+    );
     assert.match(
       blocked.content[0].text,
       /HARD BLOCK/,

package/src/resources/extensions/gsd/tests/write-gate-planning-unit.test.ts

@@ -9,6 +9,7 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { join, sep } from 'node:path';
 
+import { GSD_PHASE_SCOPE_DISPLAY_REASON } from '../auto-unit-tool-scope.ts';
 import { ALLOWED_PLANNING_DISPATCH_AGENTS, shouldBlockPlanningUnit } from '../bootstrap/write-gate.ts';
 import { extractSubagentAgentClasses } from '../bootstrap/subagent-input.ts';
 import { isDeterministicPolicyError } from '../auto-tool-tracking.ts';
@@ -65,6 +66,19 @@ test('planning-unit: deterministic block reason is suitable for retry short-circ
   assert.strictEqual(isDeterministicPolicyError(r.reason!), true);
 });
 
+test('planning-unit: blocked tool-policy calls include UI-safe display reason', () => {
+  const r = shouldBlockPlanningUnit(
+    'edit',
+    'src/main.ts',
+    BASE,
+    'discuss-milestone',
+    PLANNING,
+  );
+  assert.strictEqual(r.block, true);
+  assert.match(r.reason!, /HARD BLOCK/);
+  assert.strictEqual(r.displayReason, GSD_PHASE_SCOPE_DISPLAY_REASON);
+});
+
 test('planning-unit: blocks write to user source via relative path', () => {
   const r = shouldBlockPlanningUnit('write', 'src/main.ts', BASE, 'plan-milestone', PLANNING);
   assert.strictEqual(r.block, true);
@@ -367,6 +381,7 @@ test('auto-unit scope: execute-task allows only its task completion lifecycle to
   assert.strictEqual(blocked.block, true);
   assert.match(blocked.reason!, /HARD BLOCK/);
   assert.match(blocked.reason!, /gsd_save_gate_result/);
+  assert.strictEqual(blocked.displayReason, GSD_PHASE_SCOPE_DISPLAY_REASON);
   assert.strictEqual(isDeterministicPolicyError(blocked.reason!), true);
 });
 

package/src/resources/extensions/gsd/tool-contract.ts

@@ -8,12 +8,14 @@ import {
   type ToolsPolicy,
 } from "./unit-context-manifest.js";
 import { getRequiredWorkflowToolsForAutoUnit } from "./workflow-mcp.js";
+import { getUnitToolSurfaceContract } from "./unit-tool-contracts.js";
 
 export interface UnitToolContract {
   unitType: string;
   contextMode: ContextModePolicy;
   toolsPolicy: ToolsPolicy;
   requiredWorkflowTools: readonly string[];
+  forbiddenWorkflowTools: readonly { name: string; reason: string }[];
   promptObligations: readonly string[];
   validationRules: readonly string[];
   closeoutTools: readonly string[];
@@ -30,6 +32,7 @@ export type ToolContractResult =
 
 export function compileUnitToolContract(unitType: string): ToolContractResult {
   const manifest = resolveManifest(unitType);
+  const surfaceContract = getUnitToolSurfaceContract(unitType);
   if (!manifest) {
     return {
       ok: false,
@@ -39,6 +42,8 @@ export function compileUnitToolContract(unitType: string): ToolContractResult {
   }
 
   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),
   );
@@ -58,6 +63,7 @@ export function compileUnitToolContract(unitType: string): ToolContractResult {
       contextMode: manifest.contextMode,
       toolsPolicy: manifest.tools,
       requiredWorkflowTools,
+      forbiddenWorkflowTools,
       promptObligations: [
         `context-mode:${manifest.contextMode}`,
         `tools-policy:${manifest.tools.mode}`,

package/src/resources/extensions/gsd/tool-presentation-plan.ts

@@ -1,6 +1,18 @@
 // Project/App: gsd-pi
 // File Purpose: Resolve phase-aware tool surfaces for GSD model presentations.
 
+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 type ToolPresentationSurface = "provider-tools" | "claude-code-sdk" | "mcp" | "hybrid";
 
 export interface ToolPresentationModel {
@@ -20,14 +32,6 @@ export interface ToolPresentationPlan {
   diagnostics: string[];
 }
 
-export const RUN_UAT_WORKFLOW_TOOL_NAMES = [
-  "gsd_uat_exec",
-  "gsd_uat_result_save",
-  "gsd_resume",
-  "gsd_milestone_status",
-  "gsd_journal_query",
-] as const;
-
 export const RUN_UAT_FORBIDDEN_TOOL_NAMES = [
   "edit",
   "write",
@@ -105,10 +109,36 @@ function addBlockedTool(
 export function buildRunUatCanonicalToolNames(options: { includeBrowserTools?: readonly string[] } = {}): string[] {
   return dedupe([
     ...RUN_UAT_WORKFLOW_TOOL_NAMES,
+    ...RUN_UAT_READ_ONLY_TOOL_NAMES,
     ...(options.includeBrowserTools ?? []),
   ]);
 }
 
+export function buildRunUatResultPresentation(options: {
+  surface?: ToolPresentationSurface;
+  includeBrowserTools?: readonly string[];
+  presentedTools?: readonly string[];
+} = {}): {
+  surface: ToolPresentationSurface;
+  presentedTools: string[];
+  blockedTools: Array<{ name: string; reason: string }>;
+  toolPresentationPlanId: string;
+} {
+  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: {
   phase: string;
   surface: ToolPresentationSurface;

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 } : {}),
   };
 }