@opengsd/gsd-pi 1.2.0-dev.fbdca60b → 1.3.0-dev.65546769

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,7 +21,7 @@ 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 { saveFile, clearParseCache } from "../files.js";
@@ -209,12 +209,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";
@@ -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)) {

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

@@ -30,7 +30,7 @@ import {
   getPendingGatesForTurn,
 } from "../gsd-db.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";
@@ -76,6 +76,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",

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

@@ -8,10 +8,8 @@ import {
   type ExecSandboxRequest,
   type ExecSandboxResult,
 } from "../exec-sandbox.js";
-import { realpathSync } from "node:fs";
-import path from "node:path";
 import { isContextModeEnabled, type ContextModeConfig } from "../preferences-types.js";
-import { projectRootFromWorktreePath } from "../worktree-root.js";
+import { bashReferencesProjectRootOutsideWorktree } from "../worktree-shell-guard.js";
 import { contextModeDisabledResult, type ToolExecutionResult } from "./context-mode-tool-result.js";
 
 export interface ExecToolParams {
@@ -189,117 +187,6 @@ function isToolExecutionResult(value: unknown): value is ToolExecutionResult {
   return typeof value === "object" && value !== null && Array.isArray((value as { content?: unknown }).content);
 }
 
-function escapeRegExp(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-function normalizeScanPath(value: string): string {
-  const normalized = value.replace(/\\/g, "/").replace(/\/+$/, "");
-  return normalized.startsWith("/private/var/")
-    ? normalized.slice("/private".length)
-    : normalized;
-}
-
-function parseWorktreeBase(baseDir: string): { originalRoot: string; worktreeRoot: string } | null {
-  const normalizedBase = normalizeScanPath(baseDir);
-  const originalRoot = projectRootFromWorktreePath(normalizedBase);
-  if (!originalRoot) return null;
-  return { originalRoot, worktreeRoot: normalizedBase };
-}
-
-function pathInside(parent: string, target: string): boolean {
-  const parentWithSep = parent.endsWith("/") ? parent : `${parent}/`;
-  return target === parent || target.startsWith(parentWithSep);
-}
-
-function comparablePathVariants(value: string): string[] {
-  const variants = new Set<string>();
-  const normalized = normalizeScanPath(path.resolve(value));
-  variants.add(normalized);
-  try {
-    variants.add(normalizeScanPath(realpathSync(normalized)));
-  } catch {
-    // Nonexistent paths are still compared lexically.
-  }
-  if (normalized.startsWith("/private/var/")) {
-    variants.add(normalized.replace(/^\/private\/var\//, "/var/"));
-  } else if (normalized.startsWith("/var/")) {
-    variants.add(`/private${normalized}`);
-  }
-  return [...variants];
-}
-
-function pathInsideAny(parents: readonly string[], targets: readonly string[]): boolean {
-  return targets.some((target) => parents.some((parent) => pathInside(parent, target)));
-}
-
-function stripWrappingQuotes(value: string): string {
-  const trimmed = value.trim();
-  if (trimmed.length < 2) return trimmed;
-  const first = trimmed[0];
-  const last = trimmed[trimmed.length - 1];
-  if ((first === "'" || first === '"' || first === "`") && last === first) {
-    return trimmed.slice(1, -1).trim();
-  }
-  return trimmed;
-}
-
-function extractPathLikeValues(script: string): string[] {
-  const values: string[] = [];
-  const push = (candidate: string) => {
-    const cleaned = stripWrappingQuotes(candidate).trim();
-    if (!cleaned) return;
-    values.push(cleaned);
-  };
-  const pushQuotedLiterals = (source: string, depth = 0) => {
-    for (const match of source.matchAll(/(["'`])((?:\\.|(?!\1).)*)\1/g)) {
-      push(match[2]);
-      if (depth < 2 && /["'`]/.test(match[2])) {
-        pushQuotedLiterals(match[2], depth + 1);
-      }
-    }
-  };
-
-  for (const match of script.matchAll(/(?:^|[;\n\r]|\&\&|\|\|)\s*cd\s+([^\n\r;|&]+)/g)) {
-    push(match[1]);
-  }
-  for (const match of script.matchAll(/process\.chdir\(\s*([^\n\r;]+?)\s*\)/g)) {
-    push(match[1]);
-    pushQuotedLiterals(match[1]);
-  }
-  pushQuotedLiterals(script);
-  return values;
-}
-
-function resolvesToOriginalRootOutsideWorktree(script: string, baseDir: string): boolean {
-  const parsed = parseWorktreeBase(baseDir);
-  if (!parsed) return false;
-
-  const normalizedWorktree = normalizeScanPath(path.resolve(parsed.worktreeRoot));
-  const normalizedOriginalRoot = normalizeScanPath(path.resolve(parsed.originalRoot));
-  const worktreeRoots = comparablePathVariants(normalizedWorktree);
-  const originalRoots = comparablePathVariants(normalizedOriginalRoot);
-  for (const value of extractPathLikeValues(script)) {
-    const resolved = comparablePathVariants(path.resolve(normalizedWorktree, value));
-    if (pathInsideAny(originalRoots, resolved) && !pathInsideAny(worktreeRoots, resolved)) {
-      return true;
-    }
-  }
-  return false;
-}
-
-function scriptReferencesOriginalRootFromWorktree(script: string, baseDir: string): boolean {
-  const parsed = parseWorktreeBase(baseDir);
-  if (!parsed) return false;
-  const normalizedScript = script.replace(/\\/g, "/");
-  return comparablePathVariants(parsed.originalRoot).some((originalRoot) => {
-    const originalRootPattern = new RegExp(
-      `${escapeRegExp(originalRoot)}(?=$|[\\s'"\\\`;)&|<>]|/(?!\\.gsd(?:-worktrees|/worktrees)(?:/|$)))`,
-    );
-    return originalRootPattern.test(normalizedScript);
-  });
-}
-
 export async function executeGsdExec(
   params: ExecToolParams,
   deps: ExecToolDeps,
@@ -313,10 +200,7 @@ export async function executeGsdExec(
   if (Buffer.byteLength(script, "utf8") > 200_000) {
     return paramError("script exceeds the 200 KB length limit");
   }
-  if (
-    resolvesToOriginalRootOutsideWorktree(script, deps.baseDir)
-    || scriptReferencesOriginalRootFromWorktree(script, deps.baseDir)
-  ) {
+  if (bashReferencesProjectRootOutsideWorktree(script, deps.baseDir)) {
     return paramError(
       "script references the original project root while running inside a milestone worktree; use the active worktree path or relative paths",
     );

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

@@ -21,7 +21,6 @@ import {
 import type { GateEvaluationConfig, GateId } from "../types.js";
 import { invalidateStateCache } from "../state.js";
 import { renderPlanFromDb } from "../markdown-renderer.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";
@@ -466,9 +465,8 @@ export async function handlePlanSlice(
     invalidateStateCache();
     clearParseCache();
 
-    // ── Post-mutation hook: projections, manifest, event log ─────────────
+    // ── Post-mutation hook: manifest, event log ─────────────────────────
     try {
-      await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
       writeManifest(basePath);
       appendEvent(basePath, {
         cmd: "plan-slice",

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

@@ -3,7 +3,8 @@ import { isClosedStatus } from "../status-guards.js";
 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 { renderTaskPlanFromDb, renderPlanFromDb } from "../markdown-renderer.js";
+import { resolveSliceFile, resolveTasksDir } from "../paths.js";
 import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
@@ -137,6 +138,21 @@ export async function handlePlanTask(
 
   try {
     const renderResult = await renderTaskPlanFromDb(basePath, params.milestoneId, params.sliceId, params.taskId);
+
+    // Flat-phase: tasks live as checkboxes in the slice plan's <tasks> block,
+    // not as standalone TID-PLAN.md files. Re-render the slice plan so the
+    // new/updated task appears in the plan file that gsd-core reads.
+    // Guard: resolveTasksDir is null in flat-phase (no tasks/ subdir exists);
+    //        only sync if a slice plan already exists (guards pre-plan-slice calls).
+    try {
+      const tDir = resolveTasksDir(basePath, params.milestoneId, params.sliceId);
+      if (!tDir && resolveSliceFile(basePath, params.milestoneId, params.sliceId, "PLAN")) {
+        await renderPlanFromDb(basePath, params.milestoneId, params.sliceId);
+      }
+    } catch (syncErr) {
+      logWarning("tool", `plan-task: slice-plan sync failed: ${(syncErr as Error).message}`);
+    }
+
     invalidateStateCache();
     clearParseCache();
 

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

@@ -1,5 +1,6 @@
 import { join } from "node:path";
 import { existsSync, unlinkSync } from "node:fs";
+import { relSliceFile, relMilestoneFile } from "../paths.js";
 import { clearParseCache } from "../files.js";
 import { isClosedStatus } from "../status-guards.js";
 import { isNonEmptyString } from "../validation.js";
@@ -119,12 +120,9 @@ export async function handleReassessRoadmap(
   }
 
   // ── Compute assessment artifact path ──────────────────────────────
-  // Assessment lives in the completed slice's directory
-  const assessmentRelPath = join(
-    ".gsd", "milestones", params.milestoneId,
-    "slices", params.completedSliceId,
-    `${params.completedSliceId}-ASSESSMENT.md`,
-  );
+  // Assessment lives in the completed slice's directory.
+  // Use relSliceFile so the path is layout-aware (flat-phase or legacy).
+  const assessmentRelPath = relSliceFile(basePath, params.milestoneId, params.completedSliceId, "ASSESSMENT");
 
   // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
   // Guards must be inside the transaction so the state they check cannot
@@ -276,6 +274,9 @@ export async function handleReassessRoadmap(
   // ── Render artifacts ──────────────────────────────────────────────
   try {
     const roadmapResult = await renderRoadmapFromDb(basePath, params.milestoneId);
+    if ("skipped" in roadmapResult) {
+      return { error: `roadmap render skipped: milestone ${params.milestoneId} has no planned slices` };
+    }
     const assessmentResult = await renderAssessmentFromDb(basePath, params.milestoneId, params.completedSliceId, {
       verdict: params.verdict,
       assessment: params.assessment,
@@ -289,10 +290,8 @@ export async function handleReassessRoadmap(
       params.sliceChanges.removed.length > 0;
 
     if (hasStructuralChanges) {
-      const validationFile = join(
-        basePath, ".gsd", "milestones", params.milestoneId,
-        `${params.milestoneId}-VALIDATION.md`,
-      );
+      // Layout-aware: flat-phase → phases/NN-slug/NN-VALIDATION.md; legacy → milestones/MID/MID-VALIDATION.md
+      const validationFile = join(basePath, relMilestoneFile(basePath, params.milestoneId, "VALIDATION"));
       try {
         if (existsSync(validationFile)) unlinkSync(validationFile);
       } catch (e) {