@opengsd/gsd-pi 1.3.0 → 1.4.0

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

@@ -140,6 +140,7 @@ test('write-gate: blocked reason contains depth_verification keyword and anti-by
   );
   assert.strictEqual(result.block, true);
   assert.ok(result.reason!.includes('depth_verification'), 'reason should mention depth_verification question id');
+  assert.ok(result.reason!.includes('depth_verification_M999_confirm'), 'reason should mention the exact milestone gate id');
   assert.ok(result.reason!.includes('ask_user_questions'), 'reason should mention ask_user_questions tool');
   assert.ok(result.reason!.includes('MUST NOT'), 'reason should include anti-bypass language');
   assert.ok(result.reason!.includes('(Recommended)'), 'reason should specify the required confirmation option');
@@ -347,6 +348,7 @@ test('write-gate: reopening a gate revokes its previous verified approval', () =
 import {
   applyAskUserQuestionsGateResult,
   formatPendingAskUserQuestionsGateMessage,
+  formatTimedOutAskUserQuestionsGateMessage,
   isGateQuestionId,
   shouldBlockPendingGate,
   shouldBlockPendingGateBash,
@@ -523,6 +525,107 @@ test('write-gate: applyAskUserQuestionsGateResult keeps empty-selection pending
   }
 });
 
+// ─── Scenario 20d: applyAskUserQuestionsGateResult reports timed_out gate (#852) ──
+//
+// A host elicitation timeout must NOT be laundered into "waiting" (which tells
+// the model to re-ask — that just hits the same timeout again) nor into
+// "verified" (a timeout is never approval). The gate stays pending (fail-
+// closed) but the status is "timeout" so the caller pauses-and-waits.
+
+test('write-gate: applyAskUserQuestionsGateResult reports timed_out pending gate (#852)', () => {
+  const base = join(tmpdir(), `gsd-write-gate-ask-timeout-${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' }],
+      }],
+      // A timed-out round is marked cancelled:true + timed_out:true (the
+      // structuredContent the MCP child returns on host timeout).
+      details: { cancelled: true, timed_out: true, interrupted: false },
+    });
+
+    assert.deepEqual(result, {
+      status: 'timeout',
+      pendingGateId: gateId,
+      interrupted: false,
+    });
+    assert.strictEqual(getPendingGate(base), gateId, 'timed-out gate must stay pending (fail-closed)');
+    assert.strictEqual(isMilestoneDepthVerified('M001', base), false, 'timed-out gate must not verify depth');
+    // The timeout message must NOT tell the model to immediately re-ask.
+    const message = formatTimedOutAskUserQuestionsGateMessage(gateId);
+    assert.match(message, /timed out/, 'message says timed out');
+    assert.doesNotMatch(message, /Re-call ask_user_questions/, 'message must NOT invite immediate re-ask');
+    assert.match(message, /do not re-ask/i, 'message explicitly says do not re-ask');
+  } finally {
+    clearDiscussionFlowState(base);
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test('write-gate: applyAskUserQuestionsGateResult reports timed_out even with interrupted:true', () => {
+  // timed_out wins over the interrupted flag — both are host-side failures,
+  // but timeout is the more specific signal and must reach the caller.
+  const base = join(tmpdir(), `gsd-write-gate-ask-timeout-interrupted-${randomUUID()}`);
+  const gateId = 'depth_verification_M002_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: { cancelled: true, timed_out: true, interrupted: true },
+    });
+
+    assert.deepEqual(result, {
+      status: 'timeout',
+      pendingGateId: gateId,
+      interrupted: true,
+    });
+  } finally {
+    clearDiscussionFlowState(base);
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test('write-gate: timed_out gate with no pending gate returns not-gate', () => {
+  // A timed-out round arriving when no gate is armed (e.g. informational
+  // question) is not a gate concern — fail-open here, matching cancelled.
+  const base = join(tmpdir(), `gsd-write-gate-ask-timeout-nogate-${randomUUID()}`);
+
+  try {
+    mkdirSync(base, { recursive: true });
+    clearDiscussionFlowState(base);
+
+    const result = applyAskUserQuestionsGateResult({
+      basePath: base,
+      questions: [{
+        id: 'depth_verification_M001_confirm',
+        options: [{ label: 'Confirm depth (Recommended)' }, { label: 'Needs adjustment' }],
+      }],
+      details: { cancelled: true, timed_out: true },
+    });
+
+    assert.deepEqual(result, { status: 'not-gate' });
+  } 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', () => {

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

@@ -1,7 +1,20 @@
 // 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 { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+import { buildHttpTransportOpts } from "../mcp-client/auth.js";
+import {
+  buildMcpChildEnv,
+  collectMcpEnvWarnings,
+  detectTransport,
+  getMcpServerConfig,
+  GSD_MCP_PROBE_ENV,
+  resolveMcpString,
+  type ManagedMcpServerConfig,
+} from "../mcp-client/manager.js";
 import { mcpToolMatchesBaseName } from "./mcp-tool-name.js";
 import { getRequiredWorkflowToolsForUnit } from "./unit-tool-contracts.js";
 import {
@@ -19,7 +32,39 @@ import { isWorkflowToolSurfaceName } from "./workflow-tool-surface.js";
 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 const TERMINAL_MCP_SERVER_STATUSES = new Set(["failed", "needs-auth", "disabled"]);
+
+/**
+ * Marker embedded in the terminal readiness error message. The readiness layer
+ * appends it to the terminal branch so the classifier can distinguish a
+ * non-self-healing failure (failed/needs-auth/disabled) from the genuinely
+ * transient not-yet-connected branches, which all share the
+ * {@link TOOL_SURFACE_NOT_READY} prefix.
+ */
+export const TOOL_SURFACE_TERMINAL_MARKER = "(terminal)";
+
+/**
+ * True when a tool-surface readiness error describes a *terminal* MCP server
+ * failure (failed / needs-auth / disabled). These statuses will not self-heal
+ * within the session, so they must not be retried as transient — the caller
+ * should escalate / pause instead of same-model retrying indefinitely.
+ *
+ * Detection is driven by the embedded marker string and the terminal status
+ * set above (single source of truth), not by re-deriving either independently.
+ */
+export function isTerminalToolSurfaceError(errorMsg: string | null | undefined): boolean {
+  if (!errorMsg || !errorMsg.includes(TOOL_SURFACE_NOT_READY)) return false;
+  if (!/\bterminal\b/i.test(errorMsg)) return false;
+  // Belt-and-braces: confirm one of the canonical terminal statuses is present
+  // so a stray "(terminal)" in unrelated text doesn't trigger this.
+  return [...TERMINAL_MCP_SERVER_STATUSES].some(
+    (status) => new RegExp(`status is "${escapeRegExp(status)}"`, "i").test(errorMsg),
+  );
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 
 export interface LiveToolSurfaceObservation {
   /** Tool names the session reported at init (MCP tools appear as mcp__<server>__<tool>). */
@@ -45,11 +90,15 @@ export interface LiveToolSurfaceObservation {
 export interface WorkflowMcpToolProbeResult {
   ok: boolean;
   tools: readonly string[];
+  error?: string;
 }
 
+export type WorkflowMcpInlineServerConfig = Record<string, unknown>;
+
 export type WorkflowMcpToolProbe = (
   serverName: string,
   projectRoot: string,
+  workflowServerConfig?: WorkflowMcpInlineServerConfig,
 ) => Promise<WorkflowMcpToolProbeResult>;
 
 export const DEFAULT_WORKFLOW_MCP_PREFLIGHT_TIMEOUT_MS = 30_000;
@@ -70,10 +119,59 @@ export function probeCoversRequiredWorkflowTools(
   );
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function stringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const strings = value.filter((entry): entry is string => typeof entry === "string");
+  return strings.length > 0 ? strings : undefined;
+}
+
+function stringRecord(value: unknown): Record<string, string> | undefined {
+  if (!isRecord(value)) return undefined;
+  const entries = Object.entries(value).filter((entry): entry is [string, string] => typeof entry[1] === "string");
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+
+function normalizeInlineWorkflowMcpServerConfig(
+  serverName: string,
+  config: WorkflowMcpInlineServerConfig | undefined,
+): ManagedMcpServerConfig | undefined {
+  if (!config) return undefined;
+  const command = typeof config.command === "string" ? config.command : undefined;
+  const url = typeof config.url === "string" ? config.url : undefined;
+  const transport = detectTransport(config);
+  const args = stringArray(config.args);
+  const env = stringRecord(config.env);
+  const headers = stringRecord(config.headers);
+  return {
+    name: serverName,
+    transport,
+    sourcePath: "[inline workflow MCP config]",
+    sourceKind: "project-local",
+    disabled: config.disabled === true,
+    ...(command ? { command } : {}),
+    ...(url ? { url } : {}),
+    ...(args ? { args } : {}),
+    ...(env ? { env } : {}),
+    ...(typeof config.cwd === "string" ? { cwd: config.cwd } : {}),
+    ...(headers ? { headers } : {}),
+    ...(isRecord(config.oauth) ? { oauth: config.oauth as ManagedMcpServerConfig["oauth"] } : {}),
+    envWarnings: collectMcpEnvWarnings([
+      ["url", url],
+      ...Object.entries(env ?? {}).map(([key, value]) => [`env.${key}`, value] as [string, string | undefined]),
+      ...Object.entries(headers ?? {}).map(([key, value]) => [`headers.${key}`, value] as [string, string | undefined]),
+    ]),
+  };
+}
+
 export async function awaitWorkflowMcpToolRegistration(input: {
   unitType: string | undefined;
   workflowServerName: string | undefined;
   projectRoot: string;
+  workflowServerConfig?: WorkflowMcpInlineServerConfig;
   timeoutMs?: number;
   pollMs?: number;
   probe?: WorkflowMcpToolProbe;
@@ -85,29 +183,141 @@ export async function awaitWorkflowMcpToolRegistration(input: {
   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,
+  let reusableClient: Client | undefined;
+  let reusableTransport: StdioClientTransport | StreamableHTTPClientTransport | undefined;
+  let reusableServerConfig: ManagedMcpServerConfig | undefined;
+  let readReusableStderr: (() => string) | undefined;
+
+  const closeReusableConnection = async (): Promise<void> => {
+    if (reusableTransport) {
+      try {
+        await reusableTransport.close();
+      } catch {
+        // Best-effort cleanup after preflight connection probing.
+      }
+    }
+    if (reusableClient) {
+      try {
+        await reusableClient.close();
+      } catch {
+        // Best-effort cleanup after preflight connection probing.
+      }
+    }
+    reusableClient = undefined;
+    reusableTransport = undefined;
+    readReusableStderr = undefined;
+  };
+
+  const formatProbeError = (error: unknown): string => {
+    const message = error instanceof Error ? error.message : String(error);
+    const stderr = readReusableStderr?.() ?? "";
+    return stderr ? `${message}\nStderr:\n${stderr}` : message;
+  };
+
+  const captureReusableStderr = (transport: StdioClientTransport): (() => string) => {
+    const maxBytes = 4096;
+    const chunks: Buffer[] = [];
+    let totalBytes = 0;
+    transport.stderr?.on("data", (chunk: Buffer | string) => {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+      totalBytes += buffer.byteLength;
+      chunks.push(buffer);
+      while (chunks.reduce((sum, entry) => sum + entry.byteLength, 0) > maxBytes) {
+        chunks.shift();
+      }
     });
-    return { ok: result.ok, tools: result.tools };
+
+    return () => {
+      const captured = Buffer.concat(chunks).toString("utf-8").trim();
+      if (!captured) return "";
+      return totalBytes > maxBytes ? `[stderr truncated to last ${maxBytes} bytes]\n${captured}` : captured;
+    };
+  };
+
+  const probe = input.probe ?? (async (serverName, root, workflowServerConfig) => {
+    reusableServerConfig ??=
+      normalizeInlineWorkflowMcpServerConfig(serverName, workflowServerConfig) ??
+      getMcpServerConfig(serverName, {
+        projectDir: resolveWorkflowMcpProjectRoot(root),
+        includeDisabled: true,
+      });
+
+    const config = reusableServerConfig;
+    if (!config) return { ok: false, tools: [], error: "Unknown MCP server." };
+    if (config.disabled) return { ok: false, tools: [], error: "MCP server is disabled." };
+    if (config.transport === "unsupported") return { ok: false, tools: [], error: "MCP server transport is unsupported." };
+    if (config.envWarnings.length > 0) {
+      return { ok: false, tools: [], error: "MCP server config references unset environment variables." };
+    }
+
+    try {
+      if (!reusableClient) {
+        reusableClient = new Client({ name: "gsd", version: "1.0.0" });
+        let transport: StdioClientTransport | StreamableHTTPClientTransport;
+        if (config.transport === "stdio") {
+          transport = new StdioClientTransport({
+            command: config.command ?? "",
+            args: config.args,
+            env: {
+              ...buildMcpChildEnv(config.env),
+              [GSD_MCP_PROBE_ENV]: "1",
+            },
+            cwd: config.cwd,
+            stderr: "pipe",
+          });
+          readReusableStderr = captureReusableStderr(transport);
+        } else {
+          const resolvedUrl = resolveMcpString(config.url ?? "");
+          transport = new StreamableHTTPClientTransport(
+            new URL(resolvedUrl),
+            buildHttpTransportOpts({ headers: config.headers, oauth: config.oauth }),
+          );
+        }
+        reusableTransport = transport;
+        await reusableClient.connect(transport, {
+          signal: input.signal,
+          timeout: WORKFLOW_MCP_PROBE_TIMEOUT_MS,
+        });
+      }
+
+      const result = await reusableClient.listTools(undefined, {
+        signal: input.signal,
+        timeout: WORKFLOW_MCP_PROBE_TIMEOUT_MS,
+      });
+      return { ok: true, tools: (result.tools ?? []).map((tool) => tool.name) };
+    } catch (error) {
+      const formatted = formatProbeError(error);
+      await closeReusableConnection();
+      return { ok: false, tools: [], error: formatted };
+    }
   });
 
   const deadline = Date.now() + (input.timeoutMs ?? resolveWorkflowMcpPreflightTimeoutMs(unitType));
   const pollMs = input.pollMs ?? DEFAULT_WORKFLOW_MCP_PREFLIGHT_POLL_MS;
+  let lastProbeError: string | undefined;
 
-  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;
+  try {
+    while (Date.now() < deadline) {
+      throwIfAborted(input.signal);
+      const result = await probe(workflowServerName, projectRoot, input.workflowServerConfig).catch((err: unknown) => {
+        if (input.signal?.aborted) throw err;
+        lastProbeError = err instanceof Error ? err.message : String(err);
+        return undefined;
+      });
+      throwIfAborted(input.signal);
+      if (result) lastProbeError = result.error;
+      if (result?.ok && probeCoversRequiredWorkflowTools(result.tools, required)) {
+        recordWorkflowMcpProbe(projectRoot, workflowServerName, result.tools);
+        return null;
+      }
+      await sleep(pollMs, input.signal);
     }
-    await sleep(pollMs, input.signal);
+  } finally {
+    await closeReusableConnection();
   }
 
-  return `${TOOL_SURFACE_NOT_READY} for ${unitType}: MCP server "${workflowServerName}" did not register required tools before session start: ${required.join(", ")}`;
+  const probeError = lastProbeError ? `; last probe error: ${lastProbeError}` : "";
+  return `${TOOL_SURFACE_NOT_READY} for ${unitType}: MCP server "${workflowServerName}" did not register required tools before session start: ${required.join(", ")}${probeError}`;
 }
 
 function makeAbortError(): Error {

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

@@ -21,9 +21,9 @@ import {
   getLatestAssessmentByScope,
   updateMilestoneStatus,
 } from "../gsd-db.js";
-import { gsdProjectionRoot, clearPathCache } from "../paths.js";
+import { gsdProjectionRoot, clearPathCache, relMilestoneFile } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
-import { isClosedStatus } from "../status-guards.js";
+import { isClosedStatus, isDeferredStatus } from "../status-guards.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { stripIdPrefix } from "../workflow-projections.js";
@@ -180,7 +180,7 @@ export async function handleCompleteMilestone(
       return;
     }
 
-    const incompleteSlices = slices.filter(s => !isClosedStatus(s.status));
+    const incompleteSlices = slices.filter(s => !isClosedStatus(s.status) && !isDeferredStatus(s.status));
     if (incompleteSlices.length > 0) {
       const incompleteIds = incompleteSlices.map(s => `${s.id} (status: ${s.status})`).join(", ");
       guardError = `incomplete slices: ${incompleteIds}`;
@@ -189,6 +189,7 @@ export async function handleCompleteMilestone(
 
     // Deep check: verify all tasks in all slices are complete
     for (const slice of slices) {
+      if (isDeferredStatus(slice.status)) continue;
       const tasks = getSliceTasks(params.milestoneId, slice.id);
       const incompleteTasks = tasks.filter(t => !isClosedStatus(t.status));
       if (incompleteTasks.length > 0) {
@@ -209,12 +210,9 @@ export async function handleCompleteMilestone(
   // ── Filesystem operations (outside transaction) ─────────────────────────
   const summaryMd = renderMilestoneSummaryMarkdown(params, completedAt);
 
-  const summaryPath = join(
-    gsdProjectionRoot(artifactBasePath),
-    "milestones",
-    params.milestoneId,
-    `${params.milestoneId}-SUMMARY.md`,
-  );
+  // Layout-aware: flat-phase → phases/NN-slug/NN-SUMMARY.md;
+  // legacy → milestones/MID/MID-SUMMARY.md.
+  const summaryPath = join(artifactBasePath, relMilestoneFile(artifactBasePath, params.milestoneId, "SUMMARY"));
 
   // Guard (#4598): if SUMMARY.md already exists on disk, do not overwrite it.
   // This handles re-dispatch scenarios (DB/disk state divergence) where a prior

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

@@ -22,7 +22,7 @@ import {
   getPendingGatesForTurn,
 } from "../gsd-db.js";
 import { getGatesForTurn } from "../gate-registry.js";
-import { gsdProjectionRoot, clearPathCache, resolveMilestoneFile } from "../paths.js";
+import { gsdProjectionRoot, clearPathCache, resolveMilestoneFile, relSliceFile } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { checkOwnership, sliceUnitKey } from "../unit-ownership.js";
 import { saveFile, clearParseCache } from "../files.js";
@@ -30,7 +30,7 @@ import { classifyUatContent, escalatesArtifactUatToBrowser } from "../uat-policy
 import { invalidateStateCache } from "../state.js";
 import { renderRoadmapFromDb, roadmapRenderMarksSliceDone } from "../markdown-renderer.js";
 import { isStaleWrite } from "../auto/turn-epoch.js";
-import { flushWorkflowProjections } from "../projection-flush.js";
+import { renderMilestoneShellProjections } from "../workflow-projections.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
@@ -67,14 +67,11 @@ function sliceGateFieldForId(
 }
 
 function sliceSummaryPath(basePath: string, milestoneId: string, sliceId: string): string {
-  return join(
-    gsdProjectionRoot(basePath),
-    "milestones",
-    milestoneId,
-    "slices",
-    sliceId,
-    `${sliceId}-SUMMARY.md`,
-  );
+  // Layout-aware: flat-phase projects use NN-MM-SUMMARY.md inside the phase dir;
+  // legacy projects use milestones/MID/slices/SID/SID-SUMMARY.md.
+  // relSliceFile returns a path relative to basePath (e.g. ".gsd/phases/01-test/01-01-SUMMARY.md"),
+  // so join with basePath (not gsdProjectionRoot which would double the ".gsd/" segment).
+  return join(basePath, relSliceFile(basePath, milestoneId, sliceId, "SUMMARY"));
 }
 
 function hasCompleteSliceArtifactContract(basePath: string, milestoneId: string, sliceId: string): boolean {
@@ -479,6 +476,12 @@ export async function handleCompleteSlice(
 
     const roadmap = await renderRoadmapFromDb(artifactBasePath, params.milestoneId);
     clearParseCache();
+    // complete-slice runs after a slice is committed in the DB, so the milestone
+    // always has ≥1 slice — the skipped (unplanned) branch is unreachable. Guard
+    // for type-safety so a future invariant surfaces a clear error.
+    if ("skipped" in roadmap) {
+      throw new Error(`roadmap render skipped: milestone ${params.milestoneId} has no planned slices`);
+    }
     // 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)) {
@@ -537,7 +540,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 flushWorkflowProjections(artifactBasePath, { milestoneId: params.milestoneId });
+    await renderMilestoneShellProjections(artifactBasePath, params.milestoneId);
   } catch (projErr) {
     logWarning("tool", `complete-slice projection warning for ${params.milestoneId}/${params.sliceId}: ${(projErr as Error).message}`);
   }

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

@@ -6,11 +6,12 @@
  *
  * Validates inputs, writes task row and rendered SUMMARY.md to DB in a
  * transaction, then renders projections to disk and invalidates caches.
- * Projection write failures are reported as stale projections and do not roll
- * back committed DB state.
+ * If the critical task summary / plan projection write fails, the DB
+ * completion is compensated back to pending so DB state does not drift ahead
+ * of PLAN.md.
  */
 
-import { existsSync } from "node:fs";
+import { existsSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 
 import type { CompleteTaskParams, EscalationArtifact } from "../types.js";
@@ -29,15 +30,18 @@ import {
   saveGateResult,
   getPendingGatesForTurn,
 } from "../gsd-db.js";
+import { getWorkflowDatabasePath, ensureWorkflowDbAtPath } from "../db-workspace.js";
 import { getGatesForTurn } from "../gate-registry.js";
-import { gsdProjectionRoot, clearPathCache } from "../paths.js";
+import { gsdProjectionRoot, clearPathCache, resolveMilestonePath, resolveSlicePath } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { checkOwnership, taskUnitKey } from "../unit-ownership.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { renderPlanCheckboxes } from "../markdown-renderer.js";
-import { renderSummaryContent } from "../workflow-projections.js";
-import { flushWorkflowProjections } from "../projection-flush.js";
+import {
+  renderMilestoneShellProjections,
+  renderSummaryContent,
+} from "../workflow-projections.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
@@ -76,6 +80,20 @@ function taskSummaryPath(
   sliceId: string,
   taskId: string,
 ): string {
+  // Layout-aware: avoid creating a milestones/ directory for flat-phase projects.
+  // When that directory is created as a side effect, milestonesDir() detects it as
+  // a legacy layout and breaks all subsequent path resolution for the session.
+  const slicePath = resolveSlicePath(basePath, milestoneId, sliceId);
+  const phaseDir = resolveMilestonePath(basePath, milestoneId);
+  if (slicePath && phaseDir && slicePath !== phaseDir) {
+    // Legacy layout: the slice has its own slices/SID/ subdir → tasks/ subdir
+    return join(slicePath, "tasks", `${taskId}-SUMMARY.md`);
+  }
+  if (phaseDir) {
+    // Flat-phase: task summaries go in the phase dir (no tasks/ subdir)
+    return join(phaseDir, `${taskId}-SUMMARY.md`);
+  }
+  // Fallback: legacy hardcoded path (milestone/slice dir not on disk yet)
   return join(
     gsdProjectionRoot(basePath),
     "milestones",
@@ -117,7 +135,7 @@ async function repairMissingTaskSummaryProjection(
   clearParseCache();
 
   try {
-    await flushWorkflowProjections(artifactBasePath, { milestoneId: taskRow.milestone_id });
+    await renderMilestoneShellProjections(artifactBasePath, taskRow.milestone_id);
   } catch (projErr) {
     logWarning("tool", `complete-task repair projection warning: ${(projErr as Error).message}`);
   }
@@ -253,6 +271,7 @@ export async function handleCompleteTask(
   let guardError: string | null = null;
   let summaryMd = "";
   let repairTaskSummaryRow: TaskRow | null = null;
+  const rollbackDbPath = getWorkflowDatabasePath();
 
   // ── ADR-011 Phase 2: validate escalation payload BEFORE any side effects ─
   // Building the artifact runs the full shape validation (2-4 options, unique
@@ -409,8 +428,6 @@ export async function handleCompleteTask(
     return { error: guardError };
   }
 
-  let projectionStale = false;
-
   // Resolve and write summary to disk
   const summaryPath = taskSummaryPath(
     artifactBasePath,
@@ -424,12 +441,48 @@ export async function handleCompleteTask(
 
     // Toggle or regenerate the plan projection from DB. Missing projection
     // files are rebuilt by the renderer instead of being skipped.
-    await renderPlanCheckboxes(artifactBasePath, params.milestoneId, params.sliceId);
+    if (!ensureWorkflowDbAtPath(rollbackDbPath)) {
+      throw new Error(`database unavailable before plan projection render for ${params.milestoneId}/${params.sliceId}`);
+    }
+    const wrotePlan = await renderPlanCheckboxes(artifactBasePath, params.milestoneId, params.sliceId);
+    if (!wrotePlan) {
+      throw new Error(`plan projection write returned false for ${params.milestoneId}/${params.sliceId}`);
+    }
   } catch (renderErr) {
-    projectionStale = true;
-    logWarning("projection", `complete_task projection write failed for ${params.milestoneId}/${params.sliceId}/${params.taskId}; DB completion remains committed`, {
-      error: (renderErr as Error).message,
-    });
+    logWarning(
+      "projection",
+      `complete_task projection write failed for ${params.milestoneId}/${params.sliceId}/${params.taskId}`,
+      { error: (renderErr as Error).message },
+    );
+    let rollbackSucceeded = false;
+    try {
+      ensureWorkflowDbAtPath(rollbackDbPath);
+      deleteVerificationEvidence(params.milestoneId, params.sliceId, params.taskId);
+      updateTaskStatus(params.milestoneId, params.sliceId, params.taskId, "pending");
+      invalidateStateCache();
+      rollbackSucceeded = true;
+    } catch (rollbackErr) {
+      logWarning(
+        "projection",
+        `complete_task rollback failed after projection write failure for ${params.milestoneId}/${params.sliceId}/${params.taskId}: ${(rollbackErr as Error).message}`,
+      );
+    }
+    try {
+      if (existsSync(summaryPath)) unlinkSync(summaryPath);
+    } catch (summaryErr) {
+      logWarning(
+        "projection",
+        `complete_task could not remove SUMMARY.md after projection write failure for ${params.milestoneId}/${params.sliceId}/${params.taskId}: ${(summaryErr as Error).message}`,
+      );
+    }
+    // Clear path/parse caches regardless of rollback outcome so stale
+    // entries from the failed write attempt don't leak into subsequent calls.
+    clearPathCache();
+    clearParseCache();
+    const returnMsg = rollbackSucceeded
+      ? `complete_task projection write failed for ${params.milestoneId}/${params.sliceId}/${params.taskId}; rolled completion back to pending`
+      : `complete_task projection write failed for ${params.milestoneId}/${params.sliceId}/${params.taskId}; rollback also failed — task may remain complete with stale plan`;
+    return { error: returnMsg };
   }
 
   // ── Close gates owned by execute-task (Q5/Q6/Q7) for this task ────────
@@ -555,7 +608,7 @@ export async function handleCompleteTask(
   // Separate try/catch per step so a projection failure doesn't prevent
   // the event log entry (critical for worktree reconciliation).
   try {
-    await flushWorkflowProjections(artifactBasePath, { milestoneId: params.milestoneId });
+    await renderMilestoneShellProjections(artifactBasePath, params.milestoneId);
   } catch (projErr) {
     logWarning("tool", `complete-task projection warning: ${(projErr as Error).message}`);
   }
@@ -583,6 +636,5 @@ export async function handleCompleteTask(
     milestoneId: params.milestoneId,
     summaryPath,
     ...(escalationMetadata ? { escalation: escalationMetadata } : {}),
-    ...(projectionStale ? { stale: true } : {}),
   };
 }