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

package/dist/resources/extensions/gsd/tool-surface-readiness.js

@@ -1,6 +1,10 @@
 // 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, } 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";
@@ -13,7 +17,36 @@ 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) {
+    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) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 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;
@@ -25,6 +58,50 @@ function resolveWorkflowMcpPreflightTimeoutMs(unitType) {
 export function probeCoversRequiredWorkflowTools(tools, required) {
     return required.every((tool) => tools.some((name) => name === tool || mcpToolMatchesBaseName(name, tool)));
 }
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function stringArray(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const strings = value.filter((entry) => typeof entry === "string");
+    return strings.length > 0 ? strings : undefined;
+}
+function stringRecord(value) {
+    if (!isRecord(value))
+        return undefined;
+    const entries = Object.entries(value).filter((entry) => typeof entry[1] === "string");
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+function normalizeInlineWorkflowMcpServerConfig(serverName, config) {
+    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 } : {}),
+        envWarnings: collectMcpEnvWarnings([
+            ["url", url],
+            ...Object.entries(env ?? {}).map(([key, value]) => [`env.${key}`, value]),
+            ...Object.entries(headers ?? {}).map(([key, value]) => [`headers.${key}`, value]),
+        ]),
+    };
+}
 export async function awaitWorkflowMcpToolRegistration(input) {
     const { unitType, workflowServerName, projectRoot } = input;
     if (!unitType || !workflowServerName)
@@ -32,26 +109,138 @@ 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;
+    let reusableTransport;
+    let reusableServerConfig;
+    let readReusableStderr;
+    const closeReusableConnection = async () => {
+        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) => {
+        const message = error instanceof Error ? error.message : String(error);
+        const stderr = readReusableStderr?.() ?? "";
+        return stderr ? `${message}\nStderr:\n${stderr}` : message;
+    };
+    const captureReusableStderr = (transport) => {
+        const maxBytes = 4096;
+        const chunks = [];
+        let totalBytes = 0;
+        transport.stderr?.on("data", (chunk) => {
+            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;
+                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;
-    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;
+    let lastProbeError;
+    try {
+        while (Date.now() < deadline) {
+            throwIfAborted(input.signal);
+            const result = await probe(workflowServerName, projectRoot, input.workflowServerConfig).catch((err) => {
+                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);
     }
-    return `${TOOL_SURFACE_NOT_READY} for ${unitType}: MCP server "${workflowServerName}" did not register required tools before session start: ${required.join(", ")}`;
+    finally {
+        await closeReusableConnection();
+    }
+    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() {
     const error = new Error("AbortError: The operation was aborted");

package/dist/resources/extensions/gsd/tools/complete-milestone.js

@@ -11,7 +11,7 @@
 import { join } from "node:path";
 import { existsSync } from "node:fs";
 import { transaction, getMilestone, getMilestoneSlices, getSliceTasks, getLatestAssessmentByScope, updateMilestoneStatus, } from "../gsd-db.js";
-import { gsdProjectionRoot, clearPathCache } from "../paths.js";
+import { clearPathCache, relMilestoneFile } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { isClosedStatus } from "../status-guards.js";
 import { saveFile, clearParseCache } from "../files.js";
@@ -142,7 +142,9 @@ export async function handleCompleteMilestone(params, basePath) {
     }
     // ── 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
     // completion already wrote the file. Overwriting would silently destroy the

package/dist/resources/extensions/gsd/tools/complete-slice.js

@@ -13,7 +13,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { completeSliceCascade, setSliceSummaryMd, saveGateResult, 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";
@@ -39,7 +39,11 @@ function sliceGateFieldForId(id, params) {
     }
 }
 function sliceSummaryPath(basePath, milestoneId, sliceId) {
-    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, milestoneId, sliceId) {
     clearPathCache();
@@ -397,6 +401,12 @@ export async function handleCompleteSlice(params, basePath) {
         await saveFile(uatPath, uatMd);
         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/dist/resources/extensions/gsd/tools/complete-task.js

@@ -13,7 +13,7 @@ import { join } from "node:path";
 import { isClosedStatus } from "../status-guards.js";
 import { transaction, insertMilestone, insertSlice, insertTask, insertVerificationEvidence, getMilestone, getSlice, getTask, updateTaskStatus, deleteVerificationEvidence, saveGateResult, 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";
@@ -28,6 +28,20 @@ import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { isStaleWrite } from "../auto/turn-epoch.js";
 import { buildEscalationArtifact, writeEscalationArtifact } from "../escalation.js";
 function taskSummaryPath(basePath, milestoneId, sliceId, taskId) {
+    // 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", milestoneId, "slices", sliceId, "tasks", `${taskId}-SUMMARY.md`);
 }
 async function repairMissingTaskSummaryProjection(artifactBasePath, taskRow) {

package/dist/resources/extensions/gsd/tools/exec-tool.js

@@ -1,10 +1,8 @@
 // Project/App: gsd-pi
 // File Purpose: Executor for the gsd_exec MCP tool.
 import { EXEC_DEFAULTS, runExecSandbox, } from "../exec-sandbox.js";
-import { realpathSync } from "node:fs";
-import path from "node:path";
 import { isContextModeEnabled } from "../preferences-types.js";
-import { projectRootFromWorktreePath } from "../worktree-root.js";
+import { bashReferencesProjectRootOutsideWorktree } from "../worktree-shell-guard.js";
 import { contextModeDisabledResult } from "./context-mode-tool-result.js";
 const UAT_EXEC_INTENTS = [
     "uat-artifact-check",
@@ -131,110 +129,6 @@ function rejectUatScript(script) {
 function isToolExecutionResult(value) {
     return typeof value === "object" && value !== null && Array.isArray(value.content);
 }
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-function normalizeScanPath(value) {
-    const normalized = value.replace(/\\/g, "/").replace(/\/+$/, "");
-    return normalized.startsWith("/private/var/")
-        ? normalized.slice("/private".length)
-        : normalized;
-}
-function parseWorktreeBase(baseDir) {
-    const normalizedBase = normalizeScanPath(baseDir);
-    const originalRoot = projectRootFromWorktreePath(normalizedBase);
-    if (!originalRoot)
-        return null;
-    return { originalRoot, worktreeRoot: normalizedBase };
-}
-function pathInside(parent, target) {
-    const parentWithSep = parent.endsWith("/") ? parent : `${parent}/`;
-    return target === parent || target.startsWith(parentWithSep);
-}
-function comparablePathVariants(value) {
-    const variants = new Set();
-    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, targets) {
-    return targets.some((target) => parents.some((parent) => pathInside(parent, target)));
-}
-function stripWrappingQuotes(value) {
-    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) {
-    const values = [];
-    const push = (candidate) => {
-        const cleaned = stripWrappingQuotes(candidate).trim();
-        if (!cleaned)
-            return;
-        values.push(cleaned);
-    };
-    const pushQuotedLiterals = (source, 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, baseDir) {
-    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, baseDir) {
-    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, deps) {
     if (!isEnabled(deps.preferences))
         return contextModeDisabledResult("gsd_exec");
@@ -247,8 +141,7 @@ export async function executeGsdExec(params, deps) {
     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");
     }
     const opts = buildExecOptions(deps.baseDir, deps.preferences?.context_mode, { env: deps.env, now: deps.now, generateId: deps.generateId });

package/dist/resources/extensions/gsd/tools/plan-slice.js

@@ -7,7 +7,6 @@ import { getGateIdsForTurn } from "../gate-registry.js";
 import { transaction, getMilestone, getSlice, getSliceTasks, insertTask, upsertSlicePlanning, upsertTaskPlanning, insertGateRow, updateSliceStatus, setSliceSketchFlag, deleteTask, deleteArtifactByPath, } from "../gsd-db.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";
@@ -365,9 +364,8 @@ export async function handlePlanSlice(rawParams, basePath) {
         setSliceSketchFlag(params.milestoneId, params.sliceId, false);
         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/dist/resources/extensions/gsd/tools/plan-task.js

@@ -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";
@@ -106,6 +107,20 @@ export async function handlePlanTask(rawParams, basePath) {
     }
     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.message}`);
+        }
         invalidateStateCache();
         clearParseCache();
         // ── Post-mutation hook: projections, manifest, event log ─────────────

package/dist/resources/extensions/gsd/tools/reassess-roadmap.js

@@ -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";
@@ -74,8 +75,9 @@ export async function handleReassessRoadmap(rawParams, basePath) {
         return { error: `validation failed: ${err.message}` };
     }
     // ── 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
     // change between the read and the write (#2723).
@@ -210,6 +212,9 @@ export async function handleReassessRoadmap(rawParams, basePath) {
     // ── 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,
@@ -220,7 +225,8 @@ export async function handleReassessRoadmap(rawParams, basePath) {
             params.sliceChanges.modified.length > 0 ||
             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);

package/dist/resources/extensions/gsd/tools/validate-milestone.js

@@ -12,7 +12,7 @@
  */
 import { join } from "node:path";
 import { transaction, insertAssessment, getMilestoneSlices, getMilestone, } from "../gsd-db.js";
-import { gsdProjectionRoot, clearPathCache } from "../paths.js";
+import { clearPathCache, relMilestoneFile } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { saveFile, clearParseCache } from "../files.js";
@@ -113,7 +113,11 @@ export async function handleValidateMilestone(params, basePath, opts) {
     // worktree exists for this milestone, validation reads/writes the
     // worktree's artifacts instead of stale project-root state.
     const validationMd = renderValidationMarkdown(effectiveParams);
-    const validationPath = join(gsdProjectionRoot(artifactBasePath), "milestones", effectiveParams.milestoneId, `${effectiveParams.milestoneId}-VALIDATION.md`);
+    // Layout-aware: flat-phase → phases/NN-slug/NN-VALIDATION.md;
+    // legacy → milestones/MID/MID-VALIDATION.md.
+    // join(artifactBasePath, relMilestoneFile) gives the absolute path; relMilestoneFile
+    // returns ".gsd/..."-relative so joining with basePath (project/worktree root) is correct.
+    const validationPath = join(artifactBasePath, relMilestoneFile(artifactBasePath, effectiveParams.milestoneId, "VALIDATION"));
     // ── DB write first — matches complete-task/complete-slice pattern ───
     // Write DB before disk so a crash between the two leaves a recoverable
     // state: the DB row exists but the file is missing, which projection
@@ -143,7 +147,8 @@ export async function handleValidateMilestone(params, basePath, opts) {
         await saveFile(validationPath, validationMd);
         const projectRoot = resolveWorktreeProjectRoot(basePath);
         if (projectRoot !== artifactBasePath) {
-            const projectValidationPath = join(gsdProjectionRoot(projectRoot), "milestones", effectiveParams.milestoneId, `${effectiveParams.milestoneId}-VALIDATION.md`);
+            // Mirror to project root using the project root's layout (same logic as above).
+            const projectValidationPath = join(projectRoot, relMilestoneFile(projectRoot, effectiveParams.milestoneId, "VALIDATION"));
             try {
                 await saveFile(projectValidationPath, validationMd);
             }