@opengsd/gsd-pi 1.2.0-dev.955e4da0 → 1.2.0-dev.a6376d75

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

@@ -26,12 +26,11 @@ import { gsdProjectionRoot, clearPathCache, resolveMilestoneFile } from "../path
 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";
@@ -91,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;
   }
@@ -355,10 +356,18 @@ 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.`,
     };
   }
 
@@ -470,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) {
@@ -527,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}`);
   }

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

@@ -10,6 +10,7 @@
  * back committed DB state.
  */
 
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 
 import type { CompleteTaskParams, EscalationArtifact } from "../types.js";
@@ -35,7 +36,8 @@ 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 { renderAllProjections, renderSummaryContent } from "../workflow-projections.js";
+import { renderSummaryContent } 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";
@@ -85,6 +87,49 @@ function taskSummaryPath(
   );
 }
 
+async function repairMissingTaskSummaryProjection(
+  artifactBasePath: string,
+  taskRow: TaskRow,
+): Promise<{ summaryPath: string; stale: boolean }> {
+  const summaryPath = taskSummaryPath(
+    artifactBasePath,
+    taskRow.milestone_id,
+    taskRow.slice_id,
+    taskRow.id,
+  );
+  const summaryMd = renderSummaryContent(taskRow, taskRow.slice_id, taskRow.milestone_id, []);
+  let stale = false;
+
+  try {
+    await saveFile(summaryPath, summaryMd);
+    await renderPlanCheckboxes(artifactBasePath, taskRow.milestone_id, taskRow.slice_id);
+  } catch (renderErr) {
+    stale = true;
+    logWarning(
+      "projection",
+      `complete_task missing-summary repair failed for ${taskRow.milestone_id}/${taskRow.slice_id}/${taskRow.id}`,
+      { error: (renderErr as Error).message },
+    );
+  }
+
+  invalidateStateCache();
+  clearPathCache();
+  clearParseCache();
+
+  try {
+    await flushWorkflowProjections(artifactBasePath, { milestoneId: taskRow.milestone_id });
+  } catch (projErr) {
+    logWarning("tool", `complete-task repair projection warning: ${(projErr as Error).message}`);
+  }
+  try {
+    writeManifest(artifactBasePath);
+  } catch (mfErr) {
+    logWarning("tool", `complete-task repair manifest warning: ${(mfErr as Error).message}`);
+  }
+
+  return { summaryPath, stale };
+}
+
 /**
  * Map an execute-task-owned gate id to the CompleteTaskParams field whose
  * presence drives `pass` vs. `omitted`. Keep in lockstep with the gates
@@ -207,6 +252,7 @@ export async function handleCompleteTask(
   const completedAt = new Date().toISOString();
   let guardError: string | null = null;
   let summaryMd = "";
+  let repairTaskSummaryRow: TaskRow | 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
@@ -271,6 +317,17 @@ export async function handleCompleteTask(
         guardError = "__stale_duplicate__";
         return;
       }
+      const existingSummaryPath = taskSummaryPath(
+        artifactBasePath,
+        params.milestoneId,
+        params.sliceId,
+        params.taskId,
+      );
+      if (existingTask.full_summary_md.trim() && !existsSync(existingSummaryPath)) {
+        repairTaskSummaryRow = existingTask;
+        guardError = "__repair_missing_summary__";
+        return;
+      }
       guardError = `task ${params.taskId} is already complete — use gsd_task_reopen first if you need to redo it`;
       return;
     }
@@ -336,6 +393,18 @@ export async function handleCompleteTask(
     };
   }
 
+  if (guardError === "__repair_missing_summary__" && repairTaskSummaryRow) {
+    const repair = await repairMissingTaskSummaryProjection(artifactBasePath, repairTaskSummaryRow);
+    return {
+      taskId: params.taskId,
+      sliceId: params.sliceId,
+      milestoneId: params.milestoneId,
+      summaryPath: repair.summaryPath,
+      duplicate: true,
+      ...(repair.stale ? { stale: true } : {}),
+    };
+  }
+
   if (guardError) {
     return { error: guardError };
   }
@@ -452,6 +521,25 @@ export async function handleCompleteTask(
       }
     }
   } else if (params.escalation && !escalationWriteEnabled) {
+    if (params.escalation.continueWithDefault === false) {
+      const msg = `complete-task received a hard-blocker escalation (continueWithDefault=false) but phases.mid_execution_escalation is disabled for ${params.milestoneId}/${params.sliceId}/${params.taskId}; reverting to pending instead of silently advancing.`;
+      logWarning("tool", msg);
+      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} because hard-blocker escalation handling is disabled; SUMMARY.md left on disk for retry.`,
+        );
+      } catch (rollbackErr) {
+        logWarning(
+          "tool",
+          `complete-task rollback failed after disabled hard-blocker escalation for ${params.milestoneId}/${params.sliceId}/${params.taskId}: ${(rollbackErr as Error).message}`,
+        );
+      }
+      return { error: msg };
+    }
     logWarning(
       "tool",
       `complete-task received escalation payload but phases.mid_execution_escalation is not enabled; ignoring (${params.milestoneId}/${params.sliceId}/${params.taskId})`,
@@ -467,7 +555,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 renderAllProjections(artifactBasePath, params.milestoneId);
+    await flushWorkflowProjections(artifactBasePath, { milestoneId: params.milestoneId });
   } catch (projErr) {
     logWarning("tool", `complete-task projection warning: ${(projErr as Error).message}`);
   }

package/src/resources/extensions/gsd/tools/exec-tool.ts

@@ -11,7 +11,7 @@ import {
 import { realpathSync } from "node:fs";
 import path from "node:path";
 import { isContextModeEnabled, type ContextModeConfig } from "../preferences-types.js";
-import { findWorktreeSegment } from "../worktree-root.js";
+import { projectRootFromWorktreePath } from "../worktree-root.js";
 import { contextModeDisabledResult, type ToolExecutionResult } from "./context-mode-tool-result.js";
 
 export interface ExecToolParams {
@@ -202,12 +202,9 @@ function normalizeScanPath(value: string): string {
 
 function parseWorktreeBase(baseDir: string): { originalRoot: string; worktreeRoot: string } | null {
   const normalizedBase = normalizeScanPath(baseDir);
-  const segment = findWorktreeSegment(normalizedBase);
-  if (!segment || segment.gsdIdx <= 0) return null;
-  return {
-    originalRoot: normalizedBase.slice(0, segment.gsdIdx),
-    worktreeRoot: normalizedBase,
-  };
+  const originalRoot = projectRootFromWorktreePath(normalizedBase);
+  if (!originalRoot) return null;
+  return { originalRoot, worktreeRoot: normalizedBase };
 }
 
 function pathInside(parent: string, target: string): boolean {
@@ -427,6 +424,7 @@ function formatResult(result: ExecSandboxResult): ToolExecutionResult {
       exit_code: result.exit_code,
       signal: result.signal,
       timed_out: result.timed_out,
+      force_resolved: result.force_resolved,
       duration_ms: result.duration_ms,
       stdout_bytes: result.stdout_bytes,
       stderr_bytes: result.stderr_bytes,
@@ -441,6 +439,9 @@ function formatResult(result: ExecSandboxResult): ToolExecutionResult {
 }
 
 function formatExit(result: ExecSandboxResult): string {
+  // force_resolved means a non-closing (D-state) child was force-resolved past its
+  // hard deadline rather than observed exiting; distinguish it from a clean timeout.
+  if (result.force_resolved) return "timeout(force-killed)";
   if (result.timed_out) return "timeout";
   if (result.signal) return `signal:${result.signal}`;
   if (result.exit_code === null) return "null";

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

@@ -21,13 +21,14 @@ import {
 import type { GateEvaluationConfig, GateId } from "../types.js";
 import { invalidateStateCache } from "../state.js";
 import { renderPlanFromDb } from "../markdown-renderer.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 } from "../workflow-logger.js";
 import { validatePathOnlyPlanningFields, validatePlanningPathScope } from "../planning-path-scope.js";
-import { checkFilePathConsistency, checkTaskOrdering } from "../pre-execution-checks.js";
+import { runTaskPathChecks } from "../pre-execution-checks.js";
 import type { TaskRow } from "../db-task-slice-rows.js";
+import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { buildTaskFileName, gsdProjectionRoot } from "../paths.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { createRepositoryRegistryFromPreferences, defaultRepositoryTargets, type RepositoryRegistry } from "../repository-registry.js";
@@ -268,11 +269,16 @@ function validateTaskPathsBeforePersist(
   const additionalRoots = allowedRoots
     .map((root) => resolve(root))
     .filter((root) => root !== baseRoot);
-  const context = additionalRoots.length > 0 ? { additionalRoots } : undefined;
-  const checks = [
-    ...checkFilePathConsistency(taskRows, basePath, context),
-    ...checkTaskOrdering(taskRows, basePath, context),
-  ];
+  const resolvedCanonicalRoot = resolve(resolveWorktreeProjectRoot(basePath));
+  const canonicalProjectRoot = resolvedCanonicalRoot !== baseRoot ? resolvedCanonicalRoot : undefined;
+  const hasContext = additionalRoots.length > 0 || canonicalProjectRoot !== undefined;
+  const context = hasContext
+    ? {
+        ...(additionalRoots.length > 0 ? { additionalRoots } : {}),
+        ...(canonicalProjectRoot !== undefined ? { canonicalProjectRoot } : {}),
+      }
+    : undefined;
+  const checks = runTaskPathChecks(taskRows, basePath, context);
   const blocking = checks.filter((check) => !check.passed && check.blocking);
 
   if (blocking.length === 0) return null;
@@ -462,7 +468,7 @@ export async function handlePlanSlice(
 
     // ── Post-mutation hook: projections, manifest, event log ─────────────
     try {
-      await renderAllProjections(basePath, params.milestoneId);
+      await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
       writeManifest(basePath);
       appendEvent(basePath, {
         cmd: "plan-slice",

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

@@ -4,7 +4,7 @@ import { isNonEmptyString, validateStringArray } from "../validation.js";
 import { transaction, getSlice, getTask, insertTask, upsertTaskPlanning } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { renderTaskPlanFromDb } from "../markdown-renderer.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 } from "../workflow-logger.js";
@@ -142,7 +142,7 @@ export async function handlePlanTask(
 
     // ── Post-mutation hook: projections, manifest, event log ─────────────
     try {
-      await renderAllProjections(basePath, params.milestoneId);
+      await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
       writeManifest(basePath);
       appendEvent(basePath, {
         cmd: "plan-task",

package/src/resources/extensions/gsd/tools/reassess-roadmap.ts

@@ -16,7 +16,7 @@ import {
 } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { renderRoadmapFromDb, renderAssessmentFromDb } from "../markdown-renderer.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 } from "../workflow-logger.js";
@@ -306,7 +306,7 @@ export async function handleReassessRoadmap(
 
     // ── Post-mutation hook: projections, manifest, event log ─────
     try {
-      await renderAllProjections(basePath, params.milestoneId);
+      await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
       writeManifest(basePath);
       appendEvent(basePath, {
         cmd: "reassess-roadmap",

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

@@ -15,7 +15,7 @@ import {
   reopenMilestoneCascade,
 } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.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 } from "../workflow-logger.js";
@@ -98,7 +98,7 @@ export async function handleReopenMilestone(
 
   // ── Post-mutation hook ───────────────────────────────────────────────────
   try {
-    await renderAllProjections(basePath, params.milestoneId);
+    await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
     writeManifest(basePath);
     appendEvent(basePath, {
       cmd: "reopen-milestone",

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

@@ -16,7 +16,7 @@ import {
   reopenSliceCascade,
 } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.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 } from "../workflow-logger.js";
@@ -97,7 +97,7 @@ export async function handleReopenSlice(
 
   // ── Post-mutation hook ───────────────────────────────────────────────────
   try {
-    await renderAllProjections(basePath, params.milestoneId);
+    await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
     writeManifest(basePath);
     appendEvent(basePath, {
       cmd: "reopen-slice",

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

@@ -19,7 +19,7 @@ import {
 } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { isClosedStatus } from "../status-guards.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 } from "../workflow-logger.js";
@@ -119,7 +119,7 @@ export async function handleReopenTask(
 
   // ── Post-mutation hook ───────────────────────────────────────────────────
   try {
-    await renderAllProjections(basePath, params.milestoneId);
+    await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
     writeManifest(basePath);
     appendEvent(basePath, {
       cmd: "reopen-task",

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

@@ -13,7 +13,7 @@ import { invalidateStateCache } from "../state.js";
 import { isClosedStatus } from "../status-guards.js";
 import { isNonEmptyString } from "../validation.js";
 import { renderPlanFromDb, renderReplanFromDb } from "../markdown-renderer.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 } from "../workflow-logger.js";
@@ -216,7 +216,7 @@ export async function handleReplanSlice(
 
     // ── Post-mutation hook: projections, manifest, event log ─────
     try {
-      await renderAllProjections(basePath, params.milestoneId);
+      await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
       writeManifest(basePath);
       appendEvent(basePath, {
         cmd: "replan-slice",