gsd-pi 2.74.0 → 2.75.0-dev.2203010a0

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

@@ -0,0 +1,310 @@
+/**
+ * workflow-plugins.test.ts — Tests for the unified plugin discovery & resolution.
+ *
+ * Verifies precedence (project > global > bundled), both YAML and markdown
+ * formats, mode defaults, invalid-file handling, and legacy compat with
+ * `.gsd/workflow-defs/`.
+ */
+
+import { describe, it, afterEach, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  rmSync,
+  mkdirSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  discoverPlugins,
+  resolvePlugin,
+  listPluginsFormatted,
+  formatPluginInfo,
+} from "../workflow-plugins.ts";
+
+// ─── Test setup ──────────────────────────────────────────────────────────
+
+const tmpDirs: string[] = [];
+let savedGsdHome: string | undefined;
+
+function makeTmpBase(): string {
+  const dir = mkdtempSync(join(tmpdir(), "wf-plugins-test-"));
+  tmpDirs.push(dir);
+  return dir;
+}
+
+beforeEach(() => {
+  savedGsdHome = process.env.GSD_HOME;
+  const fakeHome = makeTmpBase();
+  process.env.GSD_HOME = fakeHome;
+});
+
+afterEach(() => {
+  if (savedGsdHome === undefined) {
+    delete process.env.GSD_HOME;
+  } else {
+    process.env.GSD_HOME = savedGsdHome;
+  }
+  for (const d of tmpDirs) {
+    try { rmSync(d, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* non-fatal */ }
+  }
+  tmpDirs.length = 0;
+});
+
+function writeFile(path: string, content: string): void {
+  mkdirSync(join(path, "..").replace(/[^/]+$/, ""), { recursive: true });
+  writeFileSync(path, content, "utf-8");
+}
+
+function writeProjectPlugin(basePath: string, filename: string, content: string): void {
+  const dir = join(basePath, ".gsd", "workflows");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, filename), content, "utf-8");
+}
+
+function writeGlobalPlugin(filename: string, content: string): void {
+  const dir = join(process.env.GSD_HOME!, "workflows");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, filename), content, "utf-8");
+}
+
+function writeLegacyDef(basePath: string, filename: string, content: string): void {
+  const dir = join(basePath, ".gsd", "workflow-defs");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, filename), content, "utf-8");
+}
+
+const SIMPLE_YAML = `
+version: 1
+name: sample
+description: A sample YAML plugin
+steps:
+  - id: s1
+    name: Step 1
+    prompt: Do the thing
+`;
+
+const SIMPLE_ONESHOT_YAML = `
+version: 1
+name: oneshot-sample
+mode: oneshot
+description: A oneshot yaml plugin
+steps:
+  - id: only
+    name: Only
+    prompt: Just do it
+`;
+
+const SIMPLE_MD = `# Sample MD Plugin
+
+<template_meta>
+name: sample-md
+version: 1
+mode: markdown-phase
+artifact_dir: .gsd/workflows/samples/
+</template_meta>
+
+<phases>
+1. one
+2. two
+</phases>
+`;
+
+const ONESHOT_MD = `# Oneshot MD Plugin
+
+<template_meta>
+name: oneshot-md
+version: 1
+mode: oneshot
+</template_meta>
+`;
+
+// ─── Bundled discovery ───────────────────────────────────────────────────
+
+describe("discoverPlugins: bundled tier", () => {
+  it("discovers the 8+ bundled templates", () => {
+    const base = makeTmpBase();
+    const plugins = discoverPlugins(base);
+    for (const id of ["bugfix", "hotfix", "spike", "full-project"]) {
+      assert.ok(plugins.has(id), `bundled plugin "${id}" should be discovered`);
+    }
+    assert.equal(plugins.get("bugfix")!.source, "bundled");
+    assert.equal(plugins.get("bugfix")!.format, "md");
+  });
+
+  it("bundled templates have valid mode values", () => {
+    const base = makeTmpBase();
+    const plugins = discoverPlugins(base);
+    const bugfix = plugins.get("bugfix")!;
+    assert.equal(bugfix.meta.mode, "markdown-phase");
+    const fullProject = plugins.get("full-project")!;
+    assert.equal(fullProject.meta.mode, "auto-milestone");
+  });
+});
+
+// ─── Project / Global / Bundled precedence ───────────────────────────────
+
+describe("discoverPlugins: precedence", () => {
+  it("project overrides bundled", () => {
+    const base = makeTmpBase();
+    writeProjectPlugin(base, "bugfix.md", `# Overridden\n\n<template_meta>\nname: bugfix-override\nmode: markdown-phase\n</template_meta>`);
+    const plugins = discoverPlugins(base);
+    const bugfix = plugins.get("bugfix")!;
+    assert.equal(bugfix.source, "project");
+    assert.ok(bugfix.path.includes(".gsd/workflows/bugfix.md"));
+  });
+
+  it("global overrides bundled when project is absent", () => {
+    const base = makeTmpBase();
+    writeGlobalPlugin("bugfix.md", `# Global\n\n<template_meta>\nname: bugfix-global\nmode: markdown-phase\n</template_meta>`);
+    const plugins = discoverPlugins(base);
+    const bugfix = plugins.get("bugfix")!;
+    assert.equal(bugfix.source, "global");
+  });
+
+  it("project overrides global", () => {
+    const base = makeTmpBase();
+    writeGlobalPlugin("foo.yaml", SIMPLE_YAML);
+    writeProjectPlugin(base, "foo.yaml", SIMPLE_YAML.replace("sample", "foo"));
+    const plugins = discoverPlugins(base);
+    assert.equal(plugins.get("foo")!.source, "project");
+  });
+});
+
+// ─── YAML + MD format handling ───────────────────────────────────────────
+
+describe("discoverPlugins: formats", () => {
+  it("loads a project YAML plugin with default mode yaml-step", () => {
+    const base = makeTmpBase();
+    writeProjectPlugin(base, "sample.yaml", SIMPLE_YAML);
+    const plugins = discoverPlugins(base);
+    const p = plugins.get("sample")!;
+    assert.equal(p.format, "yaml");
+    assert.equal(p.meta.mode, "yaml-step");
+    assert.equal(p.meta.displayName, "sample");
+  });
+
+  it("respects mode: oneshot in YAML", () => {
+    const base = makeTmpBase();
+    writeProjectPlugin(base, "oneshot-sample.yaml", SIMPLE_ONESHOT_YAML);
+    const plugins = discoverPlugins(base);
+    assert.equal(plugins.get("oneshot-sample")!.meta.mode, "oneshot");
+  });
+
+  it("loads a project MD plugin with default mode markdown-phase", () => {
+    const base = makeTmpBase();
+    writeProjectPlugin(base, "simple-md.md", `# Plain\n\n<template_meta>\nname: plain\n</template_meta>`);
+    const plugins = discoverPlugins(base);
+    assert.equal(plugins.get("simple-md")!.meta.mode, "markdown-phase");
+  });
+
+  it("respects mode: oneshot in MD", () => {
+    const base = makeTmpBase();
+    writeProjectPlugin(base, "oneshot-md.md", ONESHOT_MD);
+    const plugins = discoverPlugins(base);
+    assert.equal(plugins.get("oneshot-md")!.meta.mode, "oneshot");
+  });
+
+  it("parses phases from MD <phases> block", () => {
+    const base = makeTmpBase();
+    writeProjectPlugin(base, "sample-md.md", SIMPLE_MD);
+    const plugins = discoverPlugins(base);
+    const p = plugins.get("sample-md")!;
+    assert.deepEqual(p.meta.phases, ["one", "two"]);
+  });
+});
+
+// ─── Error handling ──────────────────────────────────────────────────────
+
+describe("discoverPlugins: error handling", () => {
+  it("invalid YAML surfaces as an entry with an error, doesn't crash", () => {
+    const base = makeTmpBase();
+    writeProjectPlugin(base, "broken.yaml", "this: is: not: valid: yaml:\n  - x\n    - y");
+    const plugins = discoverPlugins(base);
+    const p = plugins.get("broken");
+    assert.ok(p, "broken plugin should still appear");
+    if (p!.error) {
+      assert.match(p!.error, /parse|object/i);
+    }
+  });
+
+  it("ignores subdirectories under .gsd/workflows/ (artifact dirs)", () => {
+    const base = makeTmpBase();
+    // Create a subdir — simulates `/gsd start bugfix` artifact dir
+    mkdirSync(join(base, ".gsd", "workflows", "bugfixes", "250101-1-slug"), { recursive: true });
+    writeFileSync(join(base, ".gsd", "workflows", "bugfixes", "250101-1-slug", "STATE.json"), "{}", "utf-8");
+    const plugins = discoverPlugins(base);
+    assert.ok(!plugins.has("bugfixes"), "should not pick up subdir as a plugin");
+  });
+});
+
+// ─── resolvePlugin ───────────────────────────────────────────────────────
+
+describe("resolvePlugin", () => {
+  it("returns the plugin by name", () => {
+    const base = makeTmpBase();
+    writeProjectPlugin(base, "foo.yaml", SIMPLE_YAML);
+    const p = resolvePlugin(base, "foo");
+    assert.ok(p);
+    assert.equal(p!.name, "foo");
+  });
+
+  it("returns null for unknown names", () => {
+    const base = makeTmpBase();
+    assert.equal(resolvePlugin(base, "nonexistent-plugin-xyz"), null);
+  });
+
+  it("resolves bundled templates", () => {
+    const base = makeTmpBase();
+    const p = resolvePlugin(base, "bugfix");
+    assert.ok(p);
+    assert.equal(p!.source, "bundled");
+  });
+});
+
+// ─── Legacy fallback ─────────────────────────────────────────────────────
+
+describe("discoverPlugins: legacy .gsd/workflow-defs/", () => {
+  it("still discovers legacy YAML definitions", () => {
+    const base = makeTmpBase();
+    writeLegacyDef(base, "legacy.yaml", SIMPLE_YAML);
+    const plugins = discoverPlugins(base);
+    assert.ok(plugins.has("legacy"), "legacy definition should be discovered");
+    assert.equal(plugins.get("legacy")!.format, "yaml");
+  });
+
+  it("new .gsd/workflows/ overrides legacy .gsd/workflow-defs/", () => {
+    const base = makeTmpBase();
+    writeLegacyDef(base, "dup.yaml", SIMPLE_YAML);
+    writeProjectPlugin(base, "dup.yaml", SIMPLE_YAML);
+    const plugins = discoverPlugins(base);
+    const p = plugins.get("dup")!;
+    assert.ok(p.path.includes(".gsd/workflows/dup.yaml"));
+  });
+});
+
+// ─── Display ─────────────────────────────────────────────────────────────
+
+describe("listPluginsFormatted", () => {
+  it("produces output grouped by mode with bundled templates", () => {
+    const base = makeTmpBase();
+    const out = listPluginsFormatted(base);
+    assert.match(out, /Workflow Plugins/);
+    assert.match(out, /\[markdown-phase\]/);
+    assert.match(out, /bugfix/);
+  });
+});
+
+describe("formatPluginInfo", () => {
+  it("formats YAML plugin info", () => {
+    const base = makeTmpBase();
+    writeProjectPlugin(base, "foo.yaml", SIMPLE_YAML);
+    const p = resolvePlugin(base, "foo")!;
+    const info = formatPluginInfo(p);
+    assert.match(info, /Plugin:/);
+    assert.match(info, /Mode:\s+yaml-step/);
+    assert.match(info, /Source:\s+project/);
+  });
+});

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

@@ -28,6 +28,8 @@ function makeSlice(overrides: Partial<SliceRow> = {}): SliceRow {
     completed_at: null,
     sequence: 1,
     replan_triggered_at: null,
+    is_sketch: 0,
+    sketch_scope: '',
     ...overrides,
   };
 }
@@ -59,6 +61,11 @@ function makeTask(overrides: Partial<TaskRow> = {}): TaskRow {
     expected_output: [],
     observability_impact: '',
     sequence: 1,
+    blocker_source: '',
+    escalation_pending: 0,
+    escalation_awaiting_review: 0,
+    escalation_artifact_path: null,
+    escalation_override_applied_at: null,
     ...overrides,
   };
 }

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

@@ -36,8 +36,14 @@ console.log('\n── Registry Loading ──');
   for (const [id, entry] of Object.entries(registry.templates)) {
     assert.ok(typeof entry.name === 'string' && entry.name.length > 0, `${id}: name should be non-empty string`);
     assert.ok(typeof entry.description === 'string' && entry.description.length > 0, `${id}: description should be non-empty`);
-    assert.ok(typeof entry.file === 'string' && entry.file.endsWith('.md'), `${id}: file should be a .md path`);
-    assert.ok(Array.isArray(entry.phases) && entry.phases.length > 0, `${id}: phases should be non-empty array`);
+    assert.ok(typeof entry.file === 'string' && (entry.file.endsWith('.md') || entry.file.endsWith('.yaml') || entry.file.endsWith('.yml')), `${id}: file should be a .md or .yaml path`);
+    // Phases are only required for phased modes (markdown-phase, auto-milestone).
+    const isPhased = !entry.mode || entry.mode === 'markdown-phase' || entry.mode === 'auto-milestone';
+    if (isPhased) {
+      assert.ok(Array.isArray(entry.phases) && entry.phases.length > 0, `${id}: phases should be non-empty array for phased mode`);
+    } else {
+      assert.ok(Array.isArray(entry.phases), `${id}: phases should be an array (may be empty for ${entry.mode})`);
+    }
     assert.ok(Array.isArray(entry.triggers) && entry.triggers.length > 0, `${id}: triggers should be non-empty array`);
   }
 }

package/src/resources/extensions/gsd/tests/worktree-journal-events.test.ts

@@ -49,6 +49,7 @@ function makeDeps(
     loadEffectiveGSDPreferences: () => ({ preferences: { git: {} } }),
     invalidateAllCaches: () => {},
     captureIntegrationBranch: () => {},
+    enterBranchModeForMilestone: () => {},
     ...overrides,
   };
   return deps;
@@ -127,7 +128,7 @@ describe("worktree journal events", () => {
 
   test("enterMilestone emits worktree-skip when isolation disabled", () => {
     const s = makeSession({ basePath: tmp, originalBasePath: tmp });
-    const deps = makeDeps({ shouldUseWorktreeIsolation: () => false });
+    const deps = makeDeps({ shouldUseWorktreeIsolation: () => false, getIsolationMode: () => "none" });
     const resolver = new WorktreeResolver(s, deps);
 
     resolver.enterMilestone("M001", makeNotifyCtx());

package/src/resources/extensions/gsd/tests/worktree-resolver.test.ts

@@ -145,6 +145,9 @@ function makeDeps(
         args: [basePath, mid],
       });
     },
+    enterBranchModeForMilestone: (basePath: string, milestoneId: string) => {
+      calls.push({ fn: "enterBranchModeForMilestone", args: [basePath, milestoneId] });
+    },
     ...overrides,
   };
 
@@ -252,10 +255,10 @@ test("enterMilestone enters existing worktree instead of creating", () => {
   assert.equal(findCalls(deps.calls, "createAutoWorktree").length, 0);
 });
 
-test("enterMilestone is no-op when shouldUseWorktreeIsolation is false", () => {
+test("enterMilestone is no-op when isolation mode is none", () => {
   const s = makeSession();
   const deps = makeDeps({
-    shouldUseWorktreeIsolation: () => false,
+    getIsolationMode: () => "none",
   });
   const ctx = makeNotifyCtx();
   const resolver = new WorktreeResolver(s, deps);
@@ -265,6 +268,7 @@ test("enterMilestone is no-op when shouldUseWorktreeIsolation is false", () => {
   assert.equal(s.basePath, "/project"); // unchanged
   assert.equal(findCalls(deps.calls, "createAutoWorktree").length, 0);
   assert.equal(findCalls(deps.calls, "enterAutoWorktree").length, 0);
+  assert.equal(findCalls(deps.calls, "enterBranchModeForMilestone").length, 0);
 });
 
 test("enterMilestone does NOT update basePath on creation failure", () => {
@@ -309,6 +313,77 @@ test("enterMilestone uses originalBasePath as base for worktree ops", () => {
   assert.equal(createdFrom, "/project"); // uses originalBasePath, not current basePath
 });
 
+// ─── enterMilestone Tests (branch mode) ──────────────────────────────────────
+
+test("enterMilestone in branch mode calls enterBranchModeForMilestone and rebuilds GitService", () => {
+  const s = makeSession();
+  const deps = makeDeps({
+    getIsolationMode: () => "branch",
+  });
+  const ctx = makeNotifyCtx();
+  const resolver = new WorktreeResolver(s, deps);
+
+  resolver.enterMilestone("M001", ctx);
+
+  // Branch mode: no worktree created, basePath unchanged
+  assert.equal(s.basePath, "/project");
+  assert.equal(findCalls(deps.calls, "enterBranchModeForMilestone").length, 1);
+  assert.equal(findCalls(deps.calls, "createAutoWorktree").length, 0);
+  assert.equal(findCalls(deps.calls, "enterAutoWorktree").length, 0);
+  assert.equal(findCalls(deps.calls, "GitServiceImpl").length, 1);
+  assert.ok(ctx.messages.some((m) => m.level === "info" && m.msg.includes("milestone/M001")));
+});
+
+test("enterMilestone in branch mode uses originalBasePath as base", () => {
+  const s = makeSession({ basePath: "/project", originalBasePath: "/project" });
+  let calledWith = "";
+  const deps = makeDeps({
+    getIsolationMode: () => "branch",
+    enterBranchModeForMilestone: (basePath: string, _mid: string) => {
+      calledWith = basePath;
+    },
+  });
+  const ctx = makeNotifyCtx();
+  const resolver = new WorktreeResolver(s, deps);
+
+  resolver.enterMilestone("M001", ctx);
+
+  assert.equal(calledWith, "/project");
+});
+
+test("enterMilestone in branch mode degrades isolation on failure", () => {
+  const s = makeSession();
+  const deps = makeDeps({
+    getIsolationMode: () => "branch",
+    enterBranchModeForMilestone: () => {
+      throw new Error("checkout failed");
+    },
+  });
+  const ctx = makeNotifyCtx();
+  const resolver = new WorktreeResolver(s, deps);
+
+  resolver.enterMilestone("M001", ctx);
+
+  assert.equal(s.basePath, "/project"); // unchanged
+  assert.ok(s.isolationDegraded);
+  assert.ok(ctx.messages.some((m) => m.level === "warning" && m.msg.includes("checkout failed")));
+});
+
+test("enterMilestone branch mode is skipped when isolationDegraded", () => {
+  const s = makeSession();
+  s.isolationDegraded = true;
+  const deps = makeDeps({
+    getIsolationMode: () => "branch",
+  });
+  const ctx = makeNotifyCtx();
+  const resolver = new WorktreeResolver(s, deps);
+
+  resolver.enterMilestone("M001", ctx);
+
+  assert.equal(findCalls(deps.calls, "enterBranchModeForMilestone").length, 0);
+  assert.equal(findCalls(deps.calls, "createAutoWorktree").length, 0);
+});
+
 // ─── exitMilestone Tests ─────────────────────────────────────────────────────
 
 test("exitMilestone commits, tears down, and resets basePath", () => {

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

@@ -424,6 +424,32 @@ export async function handleCompleteSlice(
     logError("tool", `complete-slice event log FAILED — completion invisible to reconciliation`, { error: (eventErr as Error).message });
   }
 
+  // Fire-and-forget graph rebuild — must NOT await, must NOT crash slice completion.
+  // Dynamic import of the package name (not a relative path) so it resolves
+  // correctly via package.json#exports in both development and production.
+  // eslint-disable-next-line @typescript-eslint/no-floating-promises
+  (async () => {
+    try {
+      const graphMod = await import("@gsd-build/mcp-server") as unknown as Partial<{
+        buildGraph: (dir: string) => Promise<{ nodes: unknown[]; edges: unknown[]; builtAt: string }>;
+        writeGraph: (gsdRoot: string, graph: unknown) => Promise<void>;
+        resolveGsdRoot: (basePath: string) => string;
+      }>;
+      if (
+        typeof graphMod.buildGraph !== "function"
+        || typeof graphMod.writeGraph !== "function"
+        || typeof graphMod.resolveGsdRoot !== "function"
+      ) {
+        throw new Error("graph helpers unavailable from @gsd-build/mcp-server");
+      }
+      const g = await graphMod.buildGraph(basePath);
+      await graphMod.writeGraph(graphMod.resolveGsdRoot(basePath), g);
+    } catch (graphErr) {
+      // Graph rebuild is best-effort — log at warning level but never propagate
+      logWarning("tool", `complete-slice graph rebuild failed (non-fatal): ${(graphErr as Error).message ?? String(graphErr)}`);
+    }
+  })();
+
   return {
     sliceId: params.sliceId,
     milestoneId: params.milestoneId,

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

@@ -37,6 +37,8 @@ import { renderAllProjections, renderSummaryContent } from "../workflow-projecti
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
+import { loadEffectiveGSDPreferences } from "../preferences.js";
+import { buildEscalationArtifact, writeEscalationArtifact } from "../escalation.js";
 
 export interface CompleteTaskResult {
   taskId: string;
@@ -111,6 +113,11 @@ function paramsToTaskRow(params: CompleteTaskParams, completedAt: string): TaskR
     observability_impact: "",
     full_plan_md: "",
     sequence: 0,
+    blocker_source: "",
+    escalation_pending: 0,
+    escalation_awaiting_review: 0,
+    escalation_artifact_path: null,
+    escalation_override_applied_at: null,
   };
 }
 
@@ -153,6 +160,39 @@ export async function handleCompleteTask(
   const completedAt = new Date().toISOString();
   let guardError: string | null = null;
 
+  // ── ADR-011 Phase 2: validate escalation payload BEFORE any side effects ─
+  // Building the artifact runs the full shape validation (2-4 options, unique
+  // ids, recommendation references a real id). If the payload is malformed
+  // we must reject the call before marking the task complete, writing
+  // SUMMARY.md, flipping the plan checkbox, or closing execute-task gates —
+  // otherwise a rejected payload would leave the task marked complete with
+  // no escalation recorded, and the loop would silently advance past it.
+  // The filesystem write happens later (after side effects) because that's
+  // the cheapest ordering and validation is where 99% of failures live.
+  let validatedEscalationArtifact: ReturnType<typeof buildEscalationArtifact> | null = null;
+  let escalationWriteEnabled = false;
+  if (params.escalation) {
+    escalationWriteEnabled = loadEffectiveGSDPreferences()?.preferences?.phases?.mid_execution_escalation === true;
+    if (escalationWriteEnabled) {
+      try {
+        validatedEscalationArtifact = buildEscalationArtifact({
+          taskId: params.taskId,
+          sliceId: params.sliceId,
+          milestoneId: params.milestoneId,
+          question: params.escalation.question,
+          options: params.escalation.options,
+          recommendation: params.escalation.recommendation,
+          recommendationRationale: params.escalation.recommendationRationale,
+          continueWithDefault: params.escalation.continueWithDefault,
+        });
+      } catch (validationErr) {
+        return {
+          error: `complete-task escalation payload invalid for ${params.milestoneId}/${params.sliceId}/${params.taskId}: ${(validationErr as Error).message}`,
+        };
+      }
+    }
+  }
+
   transaction(() => {
     // State machine preconditions (inside txn for atomicity).
     // Milestone/slice not existing is OK — insertMilestone/insertSlice below will auto-create.
@@ -299,6 +339,53 @@ export async function handleCompleteTask(
     );
   }
 
+  // ── ADR-011 Phase 2: write escalation artifact (opt-in) ────────────────
+  // Validation already happened BEFORE side effects — this block only
+  // performs the disk write for a pre-validated artifact. For
+  // continueWithDefault=false, a write failure here would otherwise leave
+  // the task marked complete with SUMMARY.md + closed gates but no
+  // escalation, which silently advances the loop past a pause the user
+  // asked for. We compensate by reverting the DB-level completion: set
+  // status back to 'pending' and delete the verification_evidence rows
+  // (same shape as the disk-render-failure rollback above). SUMMARY.md
+  // on disk is left in place because the next complete-task retry will
+  // 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.
+  if (validatedEscalationArtifact) {
+    try {
+      writeEscalationArtifact(basePath, validatedEscalationArtifact);
+    } catch (escalationErr) {
+      const msg = `complete-task escalation write failed for ${params.milestoneId}/${params.sliceId}/${params.taskId}: ${(escalationErr as Error).message}`;
+      logWarning("tool", msg);
+      if (validatedEscalationArtifact.continueWithDefault === false) {
+        // Compensating rollback: revert DB completion so the loop pauses on
+        // re-dispatch instead of silently advancing. Mirror the existing
+        // renderErr rollback (line ~261).
+        try {
+          deleteVerificationEvidence(params.milestoneId, params.sliceId, params.taskId);
+          updateTaskStatus(params.milestoneId, params.sliceId, params.taskId, 'pending');
+          invalidateStateCache();
+          logWarning(
+            "tool",
+            `complete-task rolled back DB completion for ${params.milestoneId}/${params.sliceId}/${params.taskId} after escalation write failure; SUMMARY.md left on disk for retry.`,
+          );
+        } catch (rollbackErr) {
+          logWarning(
+            "tool",
+            `complete-task rollback failed after escalation write failure for ${params.milestoneId}/${params.sliceId}/${params.taskId}: ${(rollbackErr as Error).message}`,
+          );
+        }
+        return { error: msg };
+      }
+    }
+  } else if (params.escalation && !escalationWriteEnabled) {
+    logWarning(
+      "tool",
+      `complete-task received escalation payload but phases.mid_execution_escalation is not enabled; ignoring (${params.milestoneId}/${params.sliceId}/${params.taskId})`,
+    );
+  }
+
   // Invalidate all caches
   invalidateStateCache();
   clearPathCache();