@opengsd/gsd-pi 1.2.0-dev.4c756166 → 1.2.0-dev.6ccd27b3

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

@@ -24,6 +24,7 @@ import {
   setQueuePhaseActive,
 } from '../index.ts';
 import {
+  childWriteGateAdapter,
   markDepthVerified,
   isMilestoneDepthVerified,
   markApprovalGateVerified,
@@ -317,7 +318,11 @@ test('write-gate: reopening a gate revokes its previous verified approval', () =
       'precondition: verified approval unlocks the final project artifact',
     );
 
-    setPendingGate('depth_verification_project_confirm', base);
+    // A genuine re-ask originates from the workflow MCP child (where
+    // ask_user_questions executes): the child adapter arms unconditionally,
+    // revoking the prior approval. Host-side setPendingGate is guarded
+    // (verified-on-disk wins) and would deliberately suppress this arm.
+    childWriteGateAdapter.setPending('depth_verification_project_confirm', base);
     clearPendingGate(base);
 
     assert.strictEqual(
@@ -458,6 +463,66 @@ test('write-gate: applyAskUserQuestionsGateResult verifies confirmed pending gat
   }
 });
 
+test('write-gate: applyAskUserQuestionsGateResult reports declined pending gate (consent-verdict semantics)', () => {
+  const base = join(tmpdir(), `gsd-write-gate-ask-declined-${randomUUID()}`);
+  const gateId = 'depth_verification_M001_confirm';
+
+  try {
+    mkdirSync(base, { recursive: true });
+    clearDiscussionFlowState(base);
+    setPendingGate(gateId, base);
+
+    const result = applyAskUserQuestionsGateResult({
+      basePath: base,
+      questions: [{
+        id: gateId,
+        options: [{ label: 'Confirm depth (Recommended)' }, { label: 'Needs adjustment' }],
+      }],
+      details: {
+        response: { answers: { [gateId]: { selected: 'Needs adjustment' } } },
+      },
+    });
+
+    assert.deepEqual(result, { status: 'declined', gateId });
+    assert.strictEqual(getPendingGate(base), gateId, 'declined gate must stay pending');
+    assert.strictEqual(isMilestoneDepthVerified('M001', base), false, 'declined gate must not verify depth');
+  } finally {
+    clearDiscussionFlowState(base);
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test('write-gate: applyAskUserQuestionsGateResult keeps empty-selection pending gate waiting (consent-verdict semantics)', () => {
+  // An empty selection is never an answer (fail-closed): the round used to
+  // report "answered" here, silently treating a missing selection as resolved.
+  const base = join(tmpdir(), `gsd-write-gate-ask-empty-${randomUUID()}`);
+  const gateId = 'depth_verification_M001_confirm';
+
+  try {
+    mkdirSync(base, { recursive: true });
+    clearDiscussionFlowState(base);
+    setPendingGate(gateId, base);
+
+    const result = applyAskUserQuestionsGateResult({
+      basePath: base,
+      questions: [{
+        id: gateId,
+        options: [{ label: 'Confirm depth (Recommended)' }, { label: 'Needs adjustment' }],
+      }],
+      details: {
+        response: { answers: { [gateId]: { selected: '' } } },
+      },
+    });
+
+    assert.deepEqual(result, { status: 'waiting', pendingGateId: gateId, interrupted: false });
+    assert.strictEqual(getPendingGate(base), gateId, 'unanswered gate must stay pending');
+    assert.strictEqual(isMilestoneDepthVerified('M001', base), false, 'unanswered gate must not verify depth');
+  } finally {
+    clearDiscussionFlowState(base);
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
 // ─── Scenario 21: shouldBlockPendingGate blocks non-safe tools when gate is pending ──
 
 test('write-gate: shouldBlockPendingGate blocks write/edit during pending gate', () => {
@@ -789,6 +854,7 @@ test('write-gate: resetWriteGateState persists through dangling .gsd symlink', (
       verifiedApprovalGates: [],
       activeQueuePhase: false,
       pendingGateId: null,
+      writer: 'host',
     });
   } finally {
     if (originalEnv === undefined) {
@@ -803,3 +869,45 @@ test('write-gate: resetWriteGateState persists through dangling .gsd symlink', (
     } catch { /* swallow */ }
   }
 });
+
+// ─── Scenario 31: hydrate in-memory gate state from persisted snapshot (MCP subprocess) ──
+
+test('write-gate: getPendingGate hydrates from disk when workflow MCP verified gate in child process', () => {
+  const base = join(tmpdir(), `gsd-write-gate-mcp-hydrate-${randomUUID()}`);
+  const stateFilePath = join(base, '.gsd', 'runtime', 'write-gate-state.json');
+  const originalEnv = process.env.GSD_PERSIST_WRITE_GATE_STATE;
+  const gateId = 'depth_verification_M005_confirm';
+
+  try {
+    process.env.GSD_PERSIST_WRITE_GATE_STATE = '1';
+    mkdirSync(join(base, '.gsd', 'runtime'), { recursive: true });
+    clearDiscussionFlowState(base);
+    setPendingGate(gateId, base);
+
+    writeFileSync(stateFilePath, JSON.stringify({
+      verifiedDepthMilestones: ['M005'],
+      verifiedApprovalGates: [gateId],
+      activeQueuePhase: false,
+      pendingGateId: null,
+    }, null, 2), 'utf-8');
+
+    assert.strictEqual(getPendingGate(base), null, 'stale in-memory pending must refresh from disk');
+    assert.strictEqual(isMilestoneDepthVerified('M005', base), true, 'verified milestone must hydrate from disk');
+    assert.deepEqual(loadWriteGateSnapshot(base), {
+      verifiedDepthMilestones: ['M005'],
+      verifiedApprovalGates: [gateId],
+      activeQueuePhase: false,
+      pendingGateId: null,
+    });
+  } finally {
+    if (originalEnv === undefined) {
+      delete process.env.GSD_PERSIST_WRITE_GATE_STATE;
+    } else {
+      process.env.GSD_PERSIST_WRITE_GATE_STATE = originalEnv;
+    }
+    clearDiscussionFlowState(base);
+    try {
+      rmSync(base, { recursive: true, force: true });
+    } catch { /* swallow */ }
+  }
+});

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

@@ -9,8 +9,14 @@ import {
   type ToolsPolicy,
   type UnitContextManifest,
 } from "./unit-context-manifest.js";
-import { getRequiredWorkflowToolsForAutoUnit } from "./workflow-mcp.js";
-import { getUnitToolSurfaceContract } from "./unit-tool-contracts.js";
+import {
+  getWorkflowTransportSupportError,
+  type WorkflowCapabilityOptions,
+} from "./workflow-mcp.js";
+import {
+  getRequiredWorkflowToolsForUnit,
+  getUnitToolSurfaceContract,
+} from "./unit-tool-contracts.js";
 import {
   WHOLE_FILE_OBSERVATION_MAX_BYTES,
   WHOLE_FILE_OBSERVATION_MAX_LINES,
@@ -68,6 +74,17 @@ export type UnitContextContractResult =
   | { ok: true; contract: UnitPromptContextContract }
   | { ok: false; reason: "unknown-unit-type"; detail: string };
 
+export interface UnitWorkflowDispatchReadinessInput {
+  provider?: string;
+  unitType: string;
+  projectRoot?: string;
+  env?: NodeJS.ProcessEnv;
+  surface?: string;
+  authMode?: WorkflowCapabilityOptions["authMode"];
+  baseUrl?: string;
+  activeTools?: string[];
+}
+
 export function compileUnitContextContract(unitType: string): UnitContextContractResult {
   const manifest = resolveManifest(unitType);
   if (!manifest) {
@@ -80,6 +97,24 @@ export function compileUnitContextContract(unitType: string): UnitContextContrac
   return { ok: true, contract: buildPromptContextContract(unitType, manifest) };
 }
 
+export function getUnitWorkflowDispatchReadinessError(
+  input: UnitWorkflowDispatchReadinessInput,
+): string | null {
+  return getWorkflowTransportSupportError(
+    input.provider,
+    getRequiredWorkflowToolsForUnit(input.unitType),
+    {
+      projectRoot: input.projectRoot,
+      env: input.env,
+      surface: input.surface,
+      unitType: input.unitType,
+      authMode: input.authMode,
+      baseUrl: input.baseUrl,
+      activeTools: input.activeTools,
+    },
+  );
+}
+
 export function compileUnitToolContract(unitType: string): ToolContractResult {
   const manifest = resolveManifest(unitType);
   const surfaceContract = getUnitToolSurfaceContract(unitType);
@@ -91,7 +126,7 @@ export function compileUnitToolContract(unitType: string): ToolContractResult {
     };
   }
 
-  const requiredWorkflowTools = getRequiredWorkflowToolsForAutoUnit(unitType);
+  const requiredWorkflowTools = getRequiredWorkflowToolsForUnit(unitType);
   const forbiddenWorkflowTools = Object.entries(surfaceContract?.forbiddenGsdTools ?? {})
     .map(([name, reason]) => ({ name, reason }));
   const closeoutTools = requiredWorkflowTools.filter((tool) =>

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

@@ -10,7 +10,7 @@ import {
 import { parseMcpToolName, toMcpToolName } from "./mcp-tool-name.js";
 import { createToolSurfaceSnapshot, type ToolSurfaceSnapshot } from "./tool-surface-snapshot.js";
 import { uatTypeIncludesBrowser } from "./uat-policy.js";
-import { canonicalWorkflowSurfaceToolName } from "./workflow-tool-surface.js";
+import { canonicalWorkflowToolName } from "./engine-hook-contract.js";
 
 export {
   RUN_UAT_BROWSER_TOOL_NAMES,
@@ -66,9 +66,9 @@ export const RUN_UAT_CLAUDE_NATIVE_TOOL_NAMES = [
   "Grep",
 ] as const;
 
-export function canonicalWorkflowToolName(toolName: string): string {
-  return canonicalWorkflowSurfaceToolName(toolName);
-}
+// Normalizer seam lives in engine-hook-contract.ts; re-exported here for
+// existing presentation importers (uat-run.ts).
+export { canonicalWorkflowToolName };
 
 export { parseMcpToolName } from "./mcp-tool-name.js";
 

package/src/resources/extensions/gsd/tool-surface-readiness.ts

@@ -0,0 +1,183 @@
+// Project/App: gsd-pi
+// File Purpose: Tool Contract module's runtime face — verify the live SDK tool surface covers a Unit's required workflow tools.
+
+import { testMcpServerConnection } from "../mcp-client/manager.js";
+import { mcpToolMatchesBaseName } from "./mcp-tool-name.js";
+import { getRequiredWorkflowToolsForUnit } from "./unit-tool-contracts.js";
+import {
+  recordWorkflowMcpProbe,
+  WORKFLOW_MCP_PROBE_TIMEOUT_MS,
+} from "./workflow-mcp-readiness-cache.js";
+import { resolveWorkflowMcpProjectRoot } from "./workflow-mcp.js";
+import { isWorkflowToolSurfaceName } from "./workflow-tool-surface.js";
+
+/**
+ * Stable phrase recognized as transient by auto-tool-tracking's
+ * isToolUnavailableError and error-classifier's transient buckets,
+ * which build their matchers from this constant.
+ */
+export const TOOL_SURFACE_NOT_READY = "workflow tool surface not ready";
+
+/** MCP server statuses that will not self-heal within the session. */
+const TERMINAL_MCP_SERVER_STATUSES = new Set(["failed", "needs-auth", "disabled"]);
+
+export interface LiveToolSurfaceObservation {
+  /** Tool names the session reported at init (MCP tools appear as mcp__<server>__<tool>). */
+  tools: readonly string[];
+  /** MCP server connection statuses the session reported at init. */
+  mcpServers: readonly { name: string; status: string }[];
+}
+
+/**
+ * Verify the live tool surface observed at SDK session init covers the Unit's
+ * required workflow tools. Complements the static pre-dispatch gate
+ * (getWorkflowTransportSupportError), which only proves the MCP launch config
+ * is discoverable — the workflow server connects asynchronously after session
+ * start, so the static gate cannot see whether the tools actually registered.
+ *
+ * Returns a transient, recovery-classifiable error (kind tool-unavailable →
+ * retry) when the workflow server failed or has not yet registered a required
+ * tool, so dispatch aborts before the first model turn instead of letting the
+ * Unit improvise around "No such tool available". Returns null when no
+ * workflow server is part of this session (native tool path), when the Unit
+ * requires no workflow tools, or when the surface is ready.
+ */
+export interface WorkflowMcpToolProbeResult {
+  ok: boolean;
+  tools: readonly string[];
+}
+
+export type WorkflowMcpToolProbe = (
+  serverName: string,
+  projectRoot: string,
+) => Promise<WorkflowMcpToolProbeResult>;
+
+export const DEFAULT_WORKFLOW_MCP_PREFLIGHT_TIMEOUT_MS = 30_000;
+export const DEFAULT_WORKFLOW_MCP_PREFLIGHT_POLL_MS = 200;
+const RUN_UAT_PREFLIGHT_TIMEOUT_MS = 90_000;
+
+function resolveWorkflowMcpPreflightTimeoutMs(unitType: string | undefined): number {
+  if (unitType === "run-uat") return RUN_UAT_PREFLIGHT_TIMEOUT_MS;
+  return DEFAULT_WORKFLOW_MCP_PREFLIGHT_TIMEOUT_MS;
+}
+
+export function probeCoversRequiredWorkflowTools(
+  tools: readonly string[],
+  required: readonly string[],
+): boolean {
+  return required.every((tool) =>
+    tools.some((name) => name === tool || mcpToolMatchesBaseName(name, tool)),
+  );
+}
+
+export async function awaitWorkflowMcpToolRegistration(input: {
+  unitType: string | undefined;
+  workflowServerName: string | undefined;
+  projectRoot: string;
+  timeoutMs?: number;
+  pollMs?: number;
+  probe?: WorkflowMcpToolProbe;
+  signal?: AbortSignal;
+}): Promise<string | null> {
+  const { unitType, workflowServerName, projectRoot } = input;
+  if (!unitType || !workflowServerName) return null;
+
+  const required = getRequiredWorkflowToolsForUnit(unitType).filter(isWorkflowToolSurfaceName);
+  if (required.length === 0) return null;
+
+  const probe = input.probe ?? (async (serverName, root) => {
+    const result = await testMcpServerConnection(serverName, {
+      projectDir: resolveWorkflowMcpProjectRoot(root),
+      timeoutMs: WORKFLOW_MCP_PROBE_TIMEOUT_MS,
+    });
+    return { ok: result.ok, tools: result.tools };
+  });
+
+  const deadline = Date.now() + (input.timeoutMs ?? resolveWorkflowMcpPreflightTimeoutMs(unitType));
+  const pollMs = input.pollMs ?? DEFAULT_WORKFLOW_MCP_PREFLIGHT_POLL_MS;
+
+  while (Date.now() < deadline) {
+    throwIfAborted(input.signal);
+    const result = await probe(workflowServerName, projectRoot);
+    throwIfAborted(input.signal);
+    if (result.ok && probeCoversRequiredWorkflowTools(result.tools, required)) {
+      recordWorkflowMcpProbe(projectRoot, workflowServerName, result.tools);
+      return null;
+    }
+    await sleep(pollMs, input.signal);
+  }
+
+  return `${TOOL_SURFACE_NOT_READY} for ${unitType}: MCP server "${workflowServerName}" did not register required tools before session start: ${required.join(", ")}`;
+}
+
+function makeAbortError(): Error {
+  const error = new Error("AbortError: The operation was aborted");
+  error.name = "AbortError";
+  return error;
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw makeAbortError();
+}
+
+function sleep(ms: number, signal: AbortSignal | undefined): Promise<void> {
+  throwIfAborted(signal);
+
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = (): void => {
+      clearTimeout(timeout);
+      reject(makeAbortError());
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/** Brief pause after a successful preflight before SDK query (race with MCP attach). */
+export const POST_PREFLIGHT_SDK_SETTLE_MS = 750;
+
+export const POST_PREFLIGHT_READINESS_RETRY_DELAYS_MS = [
+  1_000, 2_000, 3_000, 5_000, 8_000, 10_000, 15_000, 15_000, 15_000, 15_000,
+] as const;
+
+export function getToolSurfaceReadinessError(input: {
+  unitType: string | undefined;
+  workflowServerName: string | undefined;
+  observation: LiveToolSurfaceObservation;
+  projectRoot?: string | undefined;
+}): string | null {
+  const { unitType, workflowServerName, observation } = input;
+  if (!unitType || !workflowServerName) return null;
+
+  const required = getRequiredWorkflowToolsForUnit(unitType).filter(isWorkflowToolSurfaceName);
+  if (required.length === 0) return null;
+
+  const server = observation.mcpServers.find((entry) => entry.name === workflowServerName);
+  if (server && TERMINAL_MCP_SERVER_STATUSES.has(server.status)) {
+    const missing = required.filter(
+      (tool) => !observation.tools.some((name) => name === tool || mcpToolMatchesBaseName(name, tool)),
+    );
+    const tools = missing.length > 0 ? missing : required;
+    return `${TOOL_SURFACE_NOT_READY} for ${unitType}: MCP server "${workflowServerName}" status is "${server.status}" (terminal) — cannot register: ${tools.join(", ")}`;
+  }
+
+  const missing = required.filter(
+    (tool) => !observation.tools.some((name) => name === tool || mcpToolMatchesBaseName(name, tool)),
+  );
+  if (missing.length === 0) {
+    return null;
+  }
+
+  if (!server) {
+    return `${TOOL_SURFACE_NOT_READY} for ${unitType}: MCP server "${workflowServerName}" is absent from the init surface (not yet connected): ${missing.join(", ")}`;
+  }
+
+  if (server.status !== "connected") {
+    return `${TOOL_SURFACE_NOT_READY} for ${unitType}: MCP server "${workflowServerName}" status is "${server.status}" (not yet connected): ${missing.join(", ")}`;
+  }
+
+  return `${TOOL_SURFACE_NOT_READY} for ${unitType}: MCP server "${workflowServerName}" is connected but has not registered: ${missing.join(", ")}`;
+}

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

@@ -26,7 +26,8 @@ import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { isClosedStatus } from "../status-guards.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
-import { renderAllProjections, stripIdPrefix } from "../workflow-projections.js";
+import { stripIdPrefix } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
@@ -240,7 +241,7 @@ export async function handleCompleteMilestone(
   // Separate try/catch per step so a projection failure doesn't prevent
   // the event log entry (critical for worktree reconciliation).
   try {
-    await renderAllProjections(artifactBasePath, params.milestoneId);
+    await flushWorkflowProjections(artifactBasePath, { milestoneId: params.milestoneId });
   } catch (projErr) {
     logWarning("tool", `complete-milestone projection warning: ${(projErr as Error).message}`);
   }

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

@@ -15,32 +15,22 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import type { CompleteSliceParams } from "../types.js";
-import { isClosedStatus } from "../status-guards.js";
 import {
-  transaction,
-  insertMilestone,
-  insertSlice,
-  getSlice,
-  getSliceTasks,
-  getMilestone,
-  updateSliceStatus,
+  completeSliceCascade,
   setSliceSummaryMd,
   saveGateResult,
   getPendingGatesForTurn,
-  getMilestoneSlices,
-  updateMilestoneStatus,
 } from "../gsd-db.js";
 import { getGatesForTurn } from "../gate-registry.js";
 import { gsdProjectionRoot, clearPathCache, resolveMilestoneFile } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { checkOwnership, sliceUnitKey } from "../unit-ownership.js";
 import { saveFile, clearParseCache } from "../files.js";
-import { getDeclaredUatType, shouldEscalateArtifactUatToBrowser } from "../uat-policy.js";
+import { classifyUatContent, escalatesArtifactUatToBrowser } from "../uat-policy.js";
 import { invalidateStateCache } from "../state.js";
-import { renderRoadmapFromDb } from "../markdown-renderer.js";
-import { parseRoadmap } from "../parsers-legacy.js";
+import { renderRoadmapFromDb, roadmapRenderMarksSliceDone } from "../markdown-renderer.js";
 import { isStaleWrite } from "../auto/turn-epoch.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
@@ -100,9 +90,11 @@ function hasCompleteSliceArtifactContract(basePath: string, milestoneId: string,
     join(gsdProjectionRoot(basePath), "milestones", milestoneId, `${milestoneId}-ROADMAP.md`);
   if (!existsSync(roadmapPath)) return false;
 
+  // Projection-completeness check (ADR-017): the DB has already recorded the
+  // duplicate completion; this only verifies the rendered markdown artifacts
+  // exist and reflect it, deciding whether re-rendering is needed.
   try {
-    const roadmap = parseRoadmap(readFileSync(roadmapPath, "utf-8"));
-    return roadmap.slices.some((slice) => slice.id === sliceId && slice.done);
+    return roadmapRenderMarksSliceDone(readFileSync(roadmapPath, "utf-8"), sliceId);
   } catch {
     return false;
   }
@@ -364,67 +356,49 @@ export async function handleCompleteSlice(
   // `npx playwright test` via gsd_uat_exec, and live-runtime/mixed/
   // browser-executable receive browser tools (UAT_MODE_POLICIES).
   const uatContent = params.uatContent || "";
-  const declaredUatMode = getDeclaredUatType(uatContent);
-  if (shouldEscalateArtifactUatToBrowser(uatContent)) {
+  const uatPolicy = classifyUatContent(uatContent);
+  if (escalatesArtifactUatToBrowser(uatPolicy)) {
+    // Distinguish an explicit artifact-driven declaration from a missing or
+    // unparseable one that merely *defaulted* to artifact-driven — telling an
+    // agent it "declared artifact-driven" when its declaration simply failed
+    // to parse sends it into a rewrite loop with the same unparseable format.
+    const staticOnlyClause = `which only runs static/file checks and would defer the browser work to a human`;
+    const modeClause = uatPolicy.modeDeclared
+      ? `declares "UAT mode: artifact-driven", ${staticOnlyClause}`
+      : `has no parseable UAT mode declaration in its "## UAT Type" section (the declaration must be a bullet exactly like "- UAT mode: browser-executable"), so it defaults to "artifact-driven", ${staticOnlyClause}`;
     return {
-      error: `UAT requires browser verification (opening a page in a browser, navigating to a page or localhost, screenshots) but declares "UAT mode: artifact-driven", which only runs static/file checks and would defer the browser work to a human. Use a mode that actually verifies the UI: "browser-executable" (interactive browser tools), "runtime-executable" (a browser test command such as playwright), or a browser-inclusive "mixed"/"live-runtime". Re-author the UAT Type section and complete the slice again.`,
+      error: `UAT requires browser verification (opening a page in a browser, navigating to a page or localhost, screenshots) but ${modeClause}. Use a mode that actually verifies the UI: "browser-executable" (interactive browser tools), "runtime-executable" (a browser test command such as playwright), or a browser-inclusive "mixed"/"live-runtime". Re-author the UAT Type section and complete the slice again.`,
     };
   }
 
-  // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
+  // ── Atomic completion cascade (guards + writes in one transaction) ───────
   const completedAt = new Date().toISOString();
   let guardError: string | null = null;
   let existingSummaryMd = "";
   let duplicateComplete = false;
 
-  transaction(() => {
-    // State machine preconditions (inside txn for atomicity).
-    // Milestone/slice not existing is OK — insertMilestone/insertSlice below will auto-create.
-    // Only block if they exist and are closed.
-    const milestone = getMilestone(params.milestoneId);
-    if (milestone && isClosedStatus(milestone.status)) {
-      guardError = `cannot complete slice in a closed milestone: ${params.milestoneId} (status: ${milestone.status})`;
-      return;
-    }
-
-    const slice = getSlice(params.milestoneId, params.sliceId);
-    existingSummaryMd = slice?.full_summary_md?.trim() ?? "";
-    if (slice && isClosedStatus(slice.status)) {
-      duplicateComplete = true;
-      return;
-    }
-
-    // Verify all tasks are complete
-    const tasks = getSliceTasks(params.milestoneId, params.sliceId);
-    if (tasks.length === 0) {
-      guardError = `no tasks found for slice ${params.sliceId} in milestone ${params.milestoneId}`;
-      return;
-    }
-
-    const incompleteTasks = tasks.filter(t => !isClosedStatus(t.status));
-    if (incompleteTasks.length > 0) {
-      const incompleteIds = incompleteTasks.map(t => `${t.id} (status: ${t.status})`).join(", ");
-      guardError = `incomplete tasks: ${incompleteIds}`;
-      return;
-    }
-
-    // All guards passed — perform writes. Preserve existing planning metadata:
-    // completion should not overwrite title/risk/depends/demo/sequence.
-    insertMilestone({ id: params.milestoneId, title: params.milestoneId });
-    if (!slice) {
-      insertSlice({ id: params.sliceId, milestoneId: params.milestoneId, title: params.sliceTitle || params.sliceId });
-    }
-    updateSliceStatus(params.milestoneId, params.sliceId, "complete", completedAt);
-
-    const updatedSlices = getMilestoneSlices(params.milestoneId);
-    if (
-      milestone?.status === "planned" &&
-      updatedSlices.length > 0 &&
-      updatedSlices.every((s) => isClosedStatus(s.status))
-    ) {
-      updateMilestoneStatus(params.milestoneId, "active");
-    }
+  const outcome = completeSliceCascade(params.milestoneId, params.sliceId, {
+    sliceTitle: params.sliceTitle,
+    completedAt,
   });
+  if (outcome.ok) {
+    existingSummaryMd = outcome.existingSummaryMd;
+    duplicateComplete = outcome.duplicate;
+  } else {
+    switch (outcome.reason) {
+      case "milestone-closed":
+        guardError = `cannot complete slice in a closed milestone: ${params.milestoneId} (status: ${outcome.status})`;
+        break;
+      case "no-tasks":
+        guardError = `no tasks found for slice ${params.sliceId} in milestone ${params.milestoneId}`;
+        break;
+      case "incomplete-tasks": {
+        const incompleteIds = outcome.incomplete.map((t) => `${t.id} (status: ${t.status})`).join(", ");
+        guardError = `incomplete tasks: ${incompleteIds}`;
+        break;
+      }
+    }
+  }
 
   if (duplicateComplete) {
     const staleSummaryPath = sliceSummaryPath(
@@ -505,8 +479,9 @@ export async function handleCompleteSlice(
 
     const roadmap = await renderRoadmapFromDb(artifactBasePath, params.milestoneId);
     clearParseCache();
-    const roadmapSlice = parseRoadmap(roadmap.content).slices.find((slice) => slice.id === params.sliceId);
-    if (!roadmapSlice?.done) {
+    // Render verification (ADR-017): confirms the just-written projection
+    // reflects the DB completion; the DB row is already committed.
+    if (!roadmapRenderMarksSliceDone(roadmap.content, params.sliceId)) {
       throw new Error(`roadmap render did not mark ${params.milestoneId}/${params.sliceId} complete`);
     }
   } catch (renderErr) {
@@ -562,7 +537,7 @@ export async function handleCompleteSlice(
   // Separate try/catch per step so a projection failure doesn't prevent
   // the event log entry (critical for worktree reconciliation).
   try {
-    await renderAllProjections(artifactBasePath, params.milestoneId);
+    await flushWorkflowProjections(artifactBasePath, { milestoneId: params.milestoneId });
   } catch (projErr) {
     logWarning("tool", `complete-slice projection warning for ${params.milestoneId}/${params.sliceId}: ${(projErr as Error).message}`);
   }