@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.eed73bea

package/dist/resources/extensions/gsd/auto-prompts.js

@@ -14,15 +14,17 @@ import { resolveMilestoneFile, resolveSliceFile, resolveSlicePath, resolveTasksD
 import { resolveInlineLevel, loadEffectiveGSDPreferences } from "./preferences.js";
 import { isContextModeEnabled } from "./preferences-types.js";
 import { parseRoadmap } from "./parsers-legacy.js";
-import { join } from "node:path";
+import { join, relative } from "node:path";
 import { existsSync } from "node:fs";
 import { computeBudgets, resolveExecutorContextWindow, truncateAtSectionBoundary } from "./context-budget.js";
 import { getPendingGatesForTurn } from "./gsd-db.js";
 import { assertGateCoverage, getGatesForTurn, } from "./gate-registry.js";
 import { formatDecisionsCompact, formatRequirementsCompact } from "./structured-data-formatter.js";
 import { readPhaseAnchor, formatAnchorForPrompt } from "./phase-anchor.js";
-import { composeContextModeInstructions, composeInlinedContext, composeUnitContext } from "./unit-context-composer.js";
+import { composeContextModeInstructions, composeContractedUnitContext, composeInlinedContext, composeToolSurfaceInstructions, composeUnitContext, } from "./unit-context-composer.js";
 import { resolveManifest } from "./unit-context-manifest.js";
+import { resolveExpectedArtifactPath } from "./auto-artifact-paths.js";
+import { compileUnitContextContract } from "./tool-contract.js";
 import { readCompactionSnapshot } from "./compaction-snapshot.js";
 import { logWarning } from "./workflow-logger.js";
 import { inlineGraphSubgraph } from "./graph-context.js";
@@ -32,7 +34,8 @@ import { debugLog } from "./debug-logger.js";
 import { buildSkillActivationBlock, buildSkillDiscoveryVars } from "./skill-activation.js";
 import { findMilestoneIds } from "./milestone-ids.js";
 import { buildRunUatPresentationForType, RUN_UAT_TOOL_PRESENTATION_PLAN_ID } from "./tool-presentation-plan.js";
-import { resolveEffectiveUatType, shouldDispatchUatForContent } from "./uat-policy.js";
+import { classifyUatContentForRun, shouldDispatchUatForContent, } from "./uat-policy.js";
+import { buildWebAppUatGuidanceBlock } from "./web-app-uat.js";
 export { buildSkillActivationBlock, buildSkillDiscoveryVars };
 // ─── Preamble Cap ─────────────────────────────────────────────────────────────
 /**
@@ -222,12 +225,60 @@ function renderContextModeBlockForPrompt(unitType, base, renderMode = "standalon
     return `${contextMode}\n\n## Context Snapshot\nSource: \`.gsd/last-snapshot.md\`\n\n${snapshot.trimEnd()}`;
 }
 function prependContextModeToBlock(unitType, base, block, renderMode = "standalone") {
+    const toolSurface = composeToolSurfaceInstructions(unitType, { renderMode });
     const contextMode = renderContextModeBlockForPrompt(unitType, base, renderMode);
-    if (!contextMode)
+    const guidance = [toolSurface, contextMode].filter(Boolean).join("\n\n");
+    if (!guidance)
         return block;
     if (!block.trim())
-        return contextMode;
-    return `${contextMode}\n\n${block}`;
+        return guidance;
+    return `${guidance}\n\n${block}`;
+}
+function requireUnitPromptContextContract(unitType) {
+    const result = compileUnitContextContract(unitType);
+    if (result.ok)
+        return result.contract;
+    throw new Error(result.detail);
+}
+function requireComposedArtifactBlock(blocks, unitType, key) {
+    const block = blocks.find((item) => item.key === key);
+    if (!block) {
+        throw new Error(`Unit Context Contract for ${unitType} did not compose required artifact ${key}`);
+    }
+    return block.body;
+}
+function renderExecuteTaskOnDemandContext(base, mid, sid, artifacts) {
+    if (!artifacts.includes("slice-research")) {
+        return { text: "", skipReason: "not declared by contract" };
+    }
+    // Mirror dispatch's dual-resolution logic: worktree projection path first,
+    // then the authoritative project-root path via resolveExpectedArtifactPath.
+    // In worktree layouts the RESEARCH file may live under the project-root .gsd
+    // and not have been copied into the worktree projection, so resolveSliceFile
+    // (which looks only at gsdProjectionRoot) would miss it while dispatch would
+    // still treat research as satisfied.
+    const projectedFile = resolveSliceFile(base, mid, sid, "RESEARCH");
+    const researchFile = projectedFile ?? (() => {
+        const p = resolveExpectedArtifactPath("research-slice", `${mid}/${sid}`, base);
+        return p && existsSync(p) ? p : null;
+    })();
+    if (!researchFile) {
+        return { text: "", skipReason: "missing" };
+    }
+    // Use the layout-aware relative path when the file is in the worktree
+    // projection (relSliceFile), or fall back to node:path relative() when the
+    // file was only found via the project-root resolution path.
+    const researchPath = projectedFile
+        ? relSliceFile(base, mid, sid, "RESEARCH")
+        : relative(base, researchFile);
+    return {
+        text: [
+            "## On-demand Context",
+            "",
+            `Slice research is available at \`${researchPath}\`. Read it only if the inlined task plan, slice plan excerpt, and carry-forward context do not explain a required implementation detail.`,
+        ].join("\n"),
+        skipReason: null,
+    };
 }
 // ─── Executor Constraints ─────────────────────────────────────────────────────
 /**
@@ -816,7 +867,7 @@ export async function inlineDecisionsFromDb(base, milestoneId, scope, level) {
 }
 /**
  * Inline requirements with optional milestone and slice scoping from the DB.
- * Falls back to filesystem via inlineGsdRootFile when DB unavailable or empty.
+ * Falls back to filesystem via inlineGsdRootFile only when DB is unavailable.
  */
 export async function inlineRequirementsFromDb(base, milestoneId, sliceId, level) {
     const inlineLevel = level ?? resolveInlineLevel();
@@ -824,14 +875,28 @@ export async function inlineRequirementsFromDb(base, milestoneId, sliceId, level
         const { isDbAvailable } = await import("./gsd-db.js");
         if (isDbAvailable()) {
             const { queryRequirements, formatRequirementsForPrompt } = await import("./context-store.js");
-            const requirements = queryRequirements({ milestoneId, sliceId });
+            let requirements = queryRequirements({ milestoneId, sliceId });
+            let broadenedScope = false;
+            if (requirements.length === 0 && sliceId) {
+                requirements = queryRequirements({ milestoneId });
+                broadenedScope = true;
+            }
+            if (requirements.length === 0 && milestoneId) {
+                requirements = queryRequirements({ status: "active" });
+                broadenedScope = true;
+            }
             if (requirements.length > 0) {
-                // Use compact format for non-full levels to save ~40% tokens
-                const formatted = inlineLevel !== "full"
+                // Use compact format for non-full levels, milestone-scoped calls, and
+                // any cascade stage that broadened past the originally requested scope —
+                // a slice-scoped "full" call that fell through to the project-wide
+                // active fallback must not format those rows as full requirements.
+                const useCompact = inlineLevel !== "full" || !sliceId || broadenedScope;
+                const formatted = useCompact
                     ? formatRequirementsCompact(requirements)
                     : formatRequirementsForPrompt(requirements);
                 return `### Requirements\nSource: \`.gsd/REQUIREMENTS.md\`\n\n${formatted}`;
             }
+            return null;
         }
     }
     catch (err) {
@@ -1126,19 +1191,29 @@ export function extractSliceExecutionExcerpt(content, relPath) {
     return parts.join("\n");
 }
 // ─── Prior Task Summaries ──────────────────────────────────────────────────
-export async function getPriorTaskSummaryPaths(mid, sid, currentTid, base) {
+/** Resolve where task SUMMARY files live (legacy tasks/ subdir or flat-phase phase dir). */
+function resolveTaskSummariesLocation(base, mid, sid) {
+    const slicePath = resolveSlicePath(base, mid, sid);
+    if (!slicePath)
+        return null;
     const tDir = resolveTasksDir(base, mid, sid);
-    if (!tDir)
+    const sRel = relSlicePath(base, mid, sid);
+    if (tDir)
+        return { dir: tDir, relPrefix: `${sRel}/tasks` };
+    return { dir: slicePath, relPrefix: sRel };
+}
+export async function getPriorTaskSummaryPaths(mid, sid, currentTid, base) {
+    const loc = resolveTaskSummariesLocation(base, mid, sid);
+    if (!loc)
         return [];
-    const summaryFiles = resolveTaskFiles(tDir, "SUMMARY");
+    const summaryFiles = resolveTaskFiles(loc.dir, "SUMMARY");
     const currentNum = parseInt(currentTid.replace(/^T/, ""), 10);
-    const sRel = relSlicePath(base, mid, sid);
     return summaryFiles
         .filter(f => {
         const num = parseInt(f.replace(/^T/, ""), 10);
         return num < currentNum;
     })
-        .map(f => `${sRel}/tasks/${f}`);
+        .map(f => `${loc.relPrefix}/${f}`);
 }
 /**
  * Get carry-forward summary paths scoped to a task's derived dependencies.
@@ -1155,11 +1230,10 @@ export async function getDependencyTaskSummaryPaths(mid, sid, currentTid, depend
     if (dependsOn.length === 0) {
         return getPriorTaskSummaryPaths(mid, sid, currentTid, base);
     }
-    const tDir = resolveTasksDir(base, mid, sid);
-    if (!tDir)
+    const loc = resolveTaskSummariesLocation(base, mid, sid);
+    if (!loc)
         return [];
-    const summaryFiles = resolveTaskFiles(tDir, "SUMMARY");
-    const sRel = relSlicePath(base, mid, sid);
+    const summaryFiles = resolveTaskFiles(loc.dir, "SUMMARY");
     const depSet = new Set(dependsOn.map((d) => d.toUpperCase()));
     return summaryFiles
         .filter((f) => {
@@ -1167,7 +1241,7 @@ export async function getDependencyTaskSummaryPaths(mid, sid, currentTid, depend
         const tid = f.replace(/-SUMMARY\.md$/i, "").toUpperCase();
         return depSet.has(tid);
     })
-        .map((f) => `${sRel}/tasks/${f}`);
+        .map((f) => `${loc.relPrefix}/${f}`);
 }
 // ─── Adaptive Replanning Checks ────────────────────────────────────────────
 /**
@@ -1240,6 +1314,32 @@ export async function checkNeedsReassessment(base, mid, state) {
  * - No UAT file exists for the slice
  * - UAT result file already exists (idempotent — already ran)
  */
+/**
+ * Resolve the effective UAT mode for the dispatch gate the same way
+ * `buildRunUatPrompt` does: classify the UAT body with the slice's SUMMARY as
+ * supplemental context, so a `browser-executable` UAT whose slice references a
+ * self-contained harness (`npm run test:uat`, `search-uat.mjs`, `npx
+ * playwright test`) is promoted to `runtime-executable` for the gate too.
+ *
+ * Without this, `checkNeedsRunUat` returns `browser-executable` while the
+ * prompt instructs runtime-only execution, causing the dispatch gate to
+ * require browser tools / warm up the browser daemon (or stop dispatch when
+ * browser MCP is unavailable) for UAT runs that never touch the browser. See
+ * cursor[bot] review on PR #696 for the M007/S01 regression.
+ */
+async function resolveRunUatEffectiveType(base, mid, sliceId, uatContent) {
+    let summaryContent = "";
+    try {
+        const summaryPath = resolveSliceFile(base, mid, sliceId, "SUMMARY");
+        if (summaryPath) {
+            summaryContent = (await loadFile(summaryPath)) ?? "";
+        }
+    }
+    catch (err) {
+        logWarning("prompt", `resolveRunUatEffectiveType SUMMARY load failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return classifyUatContentForRun(uatContent, summaryContent).effectiveType;
+}
 export async function checkNeedsRunUat(base, mid, state, prefs) {
     // DB primary path — fall through to file-based when DB has no data for this milestone
     try {
@@ -1272,7 +1372,8 @@ export async function checkNeedsRunUat(base, mid, state, prefs) {
                     }
                     if (!shouldDispatchUatForContent(uatContent, prefs))
                         continue;
-                    return { sliceId: sid, uatType: resolveEffectiveUatType(uatContent) };
+                    const uatType = await resolveRunUatEffectiveType(base, mid, sid, uatContent);
+                    return { sliceId: sid, uatType };
                 }
                 return null;
             }
@@ -1313,7 +1414,8 @@ export async function checkNeedsRunUat(base, mid, state, prefs) {
         }
         if (!shouldDispatchUatForContent(uatContentFb, prefs))
             continue;
-        return { sliceId: uatSid, uatType: resolveEffectiveUatType(uatContentFb) };
+        const uatType = await resolveRunUatEffectiveType(base, mid, uatSid, uatContentFb);
+        return { sliceId: uatSid, uatType };
     }
     return null;
 }
@@ -1381,7 +1483,13 @@ export async function buildDiscussMilestonePrompt(mid, midTitle, base, structure
     const draftPath = resolveMilestoneFile(base, mid, "CONTEXT-DRAFT");
     const draftContent = draftPath ? await loadFile(draftPath) : null;
     if (includeDraftSeed && draftContent) {
-        return `${promptWithContextMode}\n\n## Prior Discussion (Draft Seed)\n\nThe following draft was captured from a prior multi-milestone discussion. Use it as seed material — the user has already provided this context. Start with a brief reflection on what the draft covers, then probe for any gaps or open questions before writing the full CONTEXT.md.\n\n${draftContent}`;
+        const draftRelPath = relMilestoneFile(base, mid, "CONTEXT-DRAFT");
+        const draftSeed = `### Prior Discussion Draft\nSource: \`${draftRelPath}\`\n\n${draftContent.trim()}`;
+        const cappedDraftSeed = capPreamble(draftSeed);
+        const truncationNote = cappedDraftSeed !== draftSeed
+            ? `\n\n_(Draft seed truncated; read the full draft at \`${draftRelPath}\` if needed.)_`
+            : "";
+        return `${promptWithContextMode}\n\n## Prior Discussion (Draft Seed)\n\nThe following draft was captured from a prior multi-milestone discussion. Use it as seed material — the user has already provided this context. Start with a brief reflection on what the draft covers, then probe for any gaps or open questions before writing the full CONTEXT.md.\n\n${cappedDraftSeed}${truncationNote}`;
     }
     return promptWithContextMode;
 }
@@ -1627,7 +1735,7 @@ export async function buildResearchMilestonePrompt(mid, midTitle, base) {
     return loadPrompt("research-milestone", {
         workingDirectory: base,
         milestoneId: mid, milestoneTitle: midTitle,
-        milestonePath: relMilestonePath(base, mid),
+        milestonePath: relMilestonePath(base, mid, midTitle),
         contextPath: relMilestoneFile(base, mid, "CONTEXT"),
         outputPath: join(base, outputRelPath),
         inlinedContext,
@@ -1745,6 +1853,13 @@ export async function buildPlanMilestonePrompt(mid, midTitle, base, level) {
     else {
         trackPromptContext(contextTelemetry, "knowledge", "skipped", null, "missing");
     }
+    const webAppUatGuidance = buildWebAppUatGuidanceBlock(base);
+    if (webAppUatGuidance) {
+        pushTracked("web-app-uat", webAppUatGuidance);
+    }
+    else {
+        trackPromptContext(contextTelemetry, "web-app-uat", "skipped", null, "not a web app");
+    }
     pushTracked("templates", inlineTemplate("roadmap", "Roadmap"));
     if (inlineLevel === "full") {
         pushTracked("templates", inlineTemplate("decisions", "Decisions"));
@@ -1768,7 +1883,7 @@ export async function buildPlanMilestonePrompt(mid, midTitle, base, level) {
     return loadPrompt("plan-milestone", {
         workingDirectory: base,
         milestoneId: mid, milestoneTitle: midTitle,
-        milestonePath: relMilestonePath(base, mid),
+        milestonePath: relMilestonePath(base, mid, midTitle),
         contextPath: contextRel,
         researchPath: researchRel,
         researchOutputPath,
@@ -2032,6 +2147,14 @@ async function renderSlicePrompt(options) {
     else {
         trackPromptContext(contextTelemetry, "graph-subgraph", "skipped", null, "missing");
     }
+    const webAppUatGuidance = buildWebAppUatGuidanceBlock(base);
+    if (webAppUatGuidance) {
+        inlined.push(webAppUatGuidance);
+        trackPromptContext(contextTelemetry, "web-app-uat", "inline", webAppUatGuidance);
+    }
+    else {
+        trackPromptContext(contextTelemetry, "web-app-uat", "skipped", null, "not a web app");
+    }
     const planTemplateInline = level === "minimal" ? inlineCompactTemplate("plan", "Slice Plan") : inlineTemplate("plan", "Slice Plan");
     inlined.push(planTemplateInline);
     trackPromptContext(contextTelemetry, "templates", "inline", planTemplateInline);
@@ -2106,6 +2229,9 @@ export async function buildPlanSlicePrompt(mid, _midTitle, sid, sTitle, base, le
             `Either (a) add an earlier task that creates X on disk before the task that needs it, ` +
             `or (b) if this task IS the one that creates X, move X from inputs to expected_output. ` +
             `Do NOT put X in a task's expected_output if that task only reads or verifies X — only tasks that actually write X to disk should list it in expected_output.\n` +
+            `- **"[file] X: ... GSD planning artifacts are projections preloaded as context / written by workflow tools"**: ` +
+            `Remove X from the task's inputs, files, and expectedOutput entirely. Planning artifacts (anything under .gsd/, .planning/, or .audits/, or names like M001-CONTEXT.md / S01-PLAN.md) are preloaded as context and written by workflow tools — ` +
+            `do NOT add a task that creates X and do NOT move X to expectedOutput.\n` +
             `- **"[file] X: Task T_early reads X but it's created by task T_late (sequence violation)"**: ` +
             `Either (a) reorder tasks so T_late (the creator) runs before T_early (the reader), ` +
             `or (b) if T_late doesn't actually create X (it only reads/tests it), remove X from T_late's expected_output entirely.\n` +
@@ -2173,7 +2299,7 @@ export async function buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, base
     const taskPlanPath = resolveTaskFile(base, mid, sid, tid, "PLAN");
     const taskPlanContent = taskPlanPath ? await loadFile(taskPlanPath) : null;
     const taskPlanRelPath = relSlicePath(base, mid, sid) + `/tasks/${tid}-PLAN.md`;
-    const taskPlanInline = taskPlanContent
+    const taskPlanContext = taskPlanContent
         ? [
             "## Inlined Task Plan (authoritative local execution contract)",
             `Source: \`${taskPlanRelPath}\``,
@@ -2184,11 +2310,11 @@ export async function buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, base
             "## Inlined Task Plan (authoritative local execution contract)",
             `Task plan not found at dispatch time. Read \`${taskPlanRelPath}\` before executing.`,
         ].join("\n");
-    trackPromptContext(contextTelemetry, "task-plan", taskPlanContent ? "inline" : "on-demand", taskPlanInline, taskPlanContent ? undefined : "missing at dispatch");
+    trackPromptContext(contextTelemetry, "task-plan", taskPlanContent ? "inline" : "on-demand", taskPlanContext, taskPlanContent ? undefined : "missing at dispatch");
     const slicePlanPath = resolveSliceFile(base, mid, sid, "PLAN");
     const slicePlanContent = slicePlanPath ? await loadFile(slicePlanPath) : null;
-    const slicePlanExcerpt = extractSliceExecutionExcerpt(slicePlanContent, relSliceFile(base, mid, sid, "PLAN"));
-    trackPromptContext(contextTelemetry, "slice-plan", slicePlanExcerpt ? "excerpt" : "skipped", slicePlanExcerpt, slicePlanExcerpt ? undefined : "missing");
+    const slicePlanContext = extractSliceExecutionExcerpt(slicePlanContent, relSliceFile(base, mid, sid, "PLAN"));
+    trackPromptContext(contextTelemetry, "slice-plan", slicePlanContext ? "excerpt" : "skipped", slicePlanContext, slicePlanContext ? undefined : "missing");
     // Check for continue file (new naming or legacy)
     const continueFile = resolveSliceFile(base, mid, sid, "CONTINUE");
     const legacyContinueDir = resolveSlicePath(base, mid, sid);
@@ -2287,6 +2413,31 @@ export async function buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, base
         trackPromptContext(contextTelemetry, "decisions-template", "on-demand", decisionsOnDemandET);
     }
     trackPromptContext(contextTelemetry, "templates", "inline", inlinedTemplates, inlineLevel);
+    const contextContract = requireUnitPromptContextContract("execute-task");
+    const contractedContext = await composeContractedUnitContext(contextContract, {
+        base: { unitType: "execute-task", basePath: base, milestoneId: mid, sliceId: sid, taskId: tid },
+        resolveArtifact: async (key) => {
+            switch (key) {
+                case "task-plan":
+                    return taskPlanContext;
+                case "slice-plan":
+                    return slicePlanContext;
+                case "prior-task-summaries":
+                    return finalCarryForward;
+                case "templates":
+                    return inlinedTemplates;
+                default:
+                    return null;
+            }
+        },
+    });
+    const taskPlanInline = requireComposedArtifactBlock(contractedContext.blocks, "execute-task", "task-plan");
+    const slicePlanExcerpt = requireComposedArtifactBlock(contractedContext.blocks, "execute-task", "slice-plan");
+    const contractedCarryForward = requireComposedArtifactBlock(contractedContext.blocks, "execute-task", "prior-task-summaries");
+    const contractedTemplates = requireComposedArtifactBlock(contractedContext.blocks, "execute-task", "templates");
+    const onDemandResult = renderExecuteTaskOnDemandContext(base, mid, sid, contractedContext.onDemand);
+    const onDemandContext = onDemandResult.text;
+    trackPromptContext(contextTelemetry, "slice-research", onDemandContext ? "on-demand" : "skipped", onDemandContext, onDemandContext ? undefined : onDemandResult.skipReason ?? undefined);
     const prompt = loadPrompt("execute-task", {
         overridesSection,
         runtimeContext,
@@ -2298,11 +2449,12 @@ export async function buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, base
         taskPlanPath: taskPlanRelPath,
         taskPlanInline,
         slicePlanExcerpt,
-        carryForwardSection: finalCarryForward,
+        carryForwardSection: contractedCarryForward,
         resumeSection,
         priorTaskLines: priorLines,
+        onDemandContext,
         taskSummaryPath,
-        inlinedTemplates,
+        inlinedTemplates: contractedTemplates,
         verificationBudget,
         gatesToClose,
         skillActivation: buildSkillActivationBlock({
@@ -2313,7 +2465,7 @@ export async function buildExecuteTaskPrompt(mid, sid, sTitle, tid, tTitle, base
             taskId: tid,
             taskTitle: tTitle,
             taskPlanContent,
-            extraContext: [taskPlanInline, slicePlanExcerpt, finalCarryForward, resumeSection],
+            extraContext: [taskPlanInline, slicePlanExcerpt, contractedCarryForward, resumeSection],
             unitType: "execute-task",
         }),
     });
@@ -2362,17 +2514,16 @@ export async function buildCompleteSlicePrompt(mid, midTitle, sid, sTitle, base,
                     return body;
                 }
             case "prior-task-summaries": {
-                const tDir = resolveTasksDir(base, mid, sid);
-                if (!tDir) {
+                const loc = resolveTaskSummariesLocation(base, mid, sid);
+                if (!loc) {
                     trackPromptContext(contextTelemetry, "prior-task-summaries", "skipped", null, "missing tasks dir");
                     return null;
                 }
-                const summaryFiles = resolveTaskFiles(tDir, "SUMMARY").sort();
-                const sRel = relSlicePath(base, mid, sid);
+                const summaryFiles = resolveTaskFiles(loc.dir, "SUMMARY").sort();
                 const blocks = [];
                 for (const file of summaryFiles) {
-                    const absPath = join(tDir, file);
-                    const relPath = `${sRel}/tasks/${file}`;
+                    const absPath = join(loc.dir, file);
+                    const relPath = `${loc.relPrefix}/${file}`;
                     const taskId = file.replace(/-SUMMARY\.md$/i, "");
                     blocks.push(await buildTaskSummaryExcerpt(absPath, relPath, taskId));
                 }
@@ -2424,6 +2575,14 @@ export async function buildCompleteSlicePrompt(mid, midTitle, sid, sTitle, base,
             body = `${body}\n\n---\n\n${knowledgeInlineCS}`;
         }
     }
+    const webAppUatGuidance = buildWebAppUatGuidanceBlock(base);
+    if (webAppUatGuidance && body) {
+        body = `${webAppUatGuidance}\n\n---\n\n${body}`;
+        trackPromptContext(contextTelemetry, "web-app-uat", "inline", webAppUatGuidance);
+    }
+    else {
+        trackPromptContext(contextTelemetry, "web-app-uat", "skipped", null, webAppUatGuidance ? "missing composed body" : "not a web app");
+    }
     // Overrides section prepends to the top of the inlined context —
     // standard pattern for slice-level builders (until composer v2 lands
     // the prepend contract).
@@ -2614,8 +2773,10 @@ export async function buildCompleteMilestonePrompt(mid, midTitle, base, level) {
     trackPromptContext(contextTelemetry, "cap", cappedInlinedContext.length < rawInlinedContext.length ? "skipped" : "inline", null, cappedInlinedContext.length < rawInlinedContext.length ? `dropped ${rawInlinedContext.length - cappedInlinedContext.length} chars` : "within budget");
     const inlinedContext = prependContextModeToBlock("complete-milestone", base, cappedInlinedContext);
     emitPromptContextTelemetry("complete-milestone", contextTelemetry, inlinedContext);
-    const milestoneSummaryPath = join(base, `${relMilestonePath(base, mid)}/${mid}-SUMMARY.md`);
-    const learningsRelPath = join(relMilestonePath(base, mid), `${mid}-LEARNINGS.md`);
+    // Use relMilestoneFile to get the layout-aware filename (NN-SUFFIX.md for flat-phase,
+    // M001-SUFFIX.md for legacy) rather than manually appending the raw milestone id.
+    const milestoneSummaryPath = join(base, relMilestoneFile(base, mid, "SUMMARY"));
+    const learningsRelPath = relMilestoneFile(base, mid, "LEARNINGS");
     const learningsAbsPath = join(base, learningsRelPath);
     const extractLearningsSteps = buildExtractionStepsBlock({
         milestoneId: mid,
@@ -2845,8 +3006,9 @@ export async function buildValidateMilestonePrompt(mid, midTitle, base, level) {
     trackPromptContext(contextTelemetry, "cap", cappedInlinedContext.length < rawInlinedContext.length ? "skipped" : "inline", null, cappedInlinedContext.length < rawInlinedContext.length ? `dropped ${rawInlinedContext.length - cappedInlinedContext.length} chars` : "within budget");
     const inlinedContext = prependContextModeToBlock("validate-milestone", base, cappedInlinedContext);
     emitPromptContextTelemetry("validate-milestone", contextTelemetry, inlinedContext);
-    const validationOutputPath = join(base, `${relMilestonePath(base, mid)}/${mid}-VALIDATION.md`);
-    const roadmapOutputPath = `${relMilestonePath(base, mid)}/${mid}-ROADMAP.md`;
+    // Use relMilestoneFile for layout-aware filenames (NN-SUFFIX.md flat-phase, M001-SUFFIX.md legacy).
+    const validationOutputPath = join(base, relMilestoneFile(base, mid, "VALIDATION"));
+    const roadmapOutputPath = relMilestoneFile(base, mid, "ROADMAP");
     // Every milestone validation turn owns MV01–MV04 unconditionally: the
     // registry is the source of truth for which gates the validator must
     // address, and the block below is what the template renders so the
@@ -2889,17 +3051,16 @@ export async function buildReplanSlicePrompt(mid, midTitle, sid, sTitle, base) {
     inlined.push(await inlineFile(slicePlanPath, slicePlanRel, "Current Slice Plan"));
     // Find the blocker task summary — the completed task with blocker_discovered: true
     let blockerTaskId = "";
-    const tDir = resolveTasksDir(base, mid, sid);
-    if (tDir) {
-        const summaryFiles = resolveTaskFiles(tDir, "SUMMARY").sort();
+    const summaryLoc = resolveTaskSummariesLocation(base, mid, sid);
+    if (summaryLoc) {
+        const summaryFiles = resolveTaskFiles(summaryLoc.dir, "SUMMARY").sort();
         for (const file of summaryFiles) {
-            const absPath = join(tDir, file);
+            const absPath = join(summaryLoc.dir, file);
             const content = await loadFile(absPath);
             if (!content)
                 continue;
             const summary = parseSummary(content);
-            const sRel = relSlicePath(base, mid, sid);
-            const relPath = `${sRel}/tasks/${file}`;
+            const relPath = `${summaryLoc.relPrefix}/${file}`;
             if (summary.frontmatter.blocker_discovered) {
                 blockerTaskId = summary.frontmatter.id || file.replace(/-SUMMARY\.md$/i, "");
                 inlined.push(await buildTaskSummaryExcerpt(absPath, relPath, blockerTaskId, { blocker: true }));
@@ -2915,7 +3076,7 @@ export async function buildReplanSlicePrompt(mid, midTitle, sid, sTitle, base) {
     if (replanOverridesInline)
         inlined.unshift(replanOverridesInline);
     const inlinedContext = prependContextModeToBlock("replan-slice", base, capPreamble(`## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`));
-    const replanPath = join(base, `${relSlicePath(base, mid, sid)}/${sid}-REPLAN.md`);
+    const replanPath = join(base, relSliceFile(base, mid, sid, "REPLAN"));
     // Build capture context for replan prompt (captures that triggered this replan)
     let captureContext = "(none)";
     try {
@@ -3021,10 +3182,25 @@ export async function buildRunUatPrompt(mid, sliceId, uatPath, uatContent, base)
     const rawInlinedContext = `## Inlined Context (preloaded — do not re-read these files)\n\n${composedBody}`;
     const cappedInlinedContext = capPreamble(rawInlinedContext);
     trackPromptContext(contextTelemetry, "cap", cappedInlinedContext.length < rawInlinedContext.length ? "skipped" : "inline", null, cappedInlinedContext.length < rawInlinedContext.length ? `dropped ${rawInlinedContext.length - cappedInlinedContext.length} chars` : "within budget");
-    const inlinedContext = prependContextModeToBlock("run-uat", base, cappedInlinedContext);
+    const uatPolicy = classifyUatContentForRun(uatContent, cappedInlinedContext);
+    const uatType = uatPolicy.effectiveType;
+    const runtimeHarnessOverride = uatPolicy.declaredType === "browser-executable" && uatType === "runtime-executable"
+        ? [
+            "## Runtime harness override",
+            "",
+            "This UAT declares `browser-executable` but the slice references a self-contained verification command (`npm run test:uat`, `search-uat.mjs`, or similar).",
+            "Run **only** that command via `gsd_uat_exec` with `uat-runtime-check` intent.",
+            "Do **not** call `uat-service-start`, do **not** run `npm run start`, `npm run test:server`, or any separate server command.",
+            "Do **not** use `browser_navigate` or other `browser_*` tools — the harness already exercises the browser.",
+            "When the harness exits 0, save **PASS** with `uatType: \"runtime-executable\"` (the effective mode above, not the UAT file header) and **runtime** check modes only.",
+            "",
+        ].join("\n")
+        : "";
+    const inlinedContext = prependContextModeToBlock("run-uat", base, runtimeHarnessOverride
+        ? `${runtimeHarnessOverride}\n${cappedInlinedContext}`
+        : cappedInlinedContext);
     emitPromptContextTelemetry("run-uat", contextTelemetry, inlinedContext);
     const uatResultPath = join(base, relSliceFile(base, mid, sliceId, "ASSESSMENT"));
-    const uatType = resolveEffectiveUatType(uatContent);
     const canonicalPresentation = JSON.stringify(buildRunUatPresentationForType(uatType), null, 2);
     return loadPrompt("run-uat", {
         workingDirectory: base,
@@ -3237,7 +3413,11 @@ opts) {
         const taskPrompt = [
             `## UNIT: Execute Task ${tid} ("${tTitle}")`,
             "",
-            "Work only in the repository root.",
+            "## Working Directory",
+            "",
+            `Your working directory is \`${base}\`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT \`cd\` to any other directory.`,
+            `If any inlined plan names an absolute path outside \`${base}\`, treat it as stale — use the equivalent path under \`${base}\` before reading, writing, or executing.`,
+            "",
             "Implement from the inlined task plan below. Verify changes, then call `gsd_task_complete`.",
             "Do not run git commands.",
             "",
@@ -3265,18 +3445,18 @@ opts) {
     }
     const inlinedTemplates = inlineTemplate("task-summary", "Task Summary");
     trackPromptContext(contextTelemetry, "templates", "inline", inlinedTemplates);
-    const prompt = loadPrompt("reactive-execute", {
+    const prompt = prependContextModeToBlock("reactive-execute", base, loadPrompt("reactive-execute", {
         workingDirectory: base,
         milestoneId: mid,
         milestoneTitle: midTitle,
         sliceId: sid,
         sliceTitle: sTitle,
-        graphContext: prependContextModeToBlock("reactive-execute", base, graphContext),
+        graphContext,
         readyTaskCount: String(readyTaskIds.length),
         readyTaskList: readyTaskListLines.join("\n"),
         subagentPrompts: subagentSections.join("\n\n---\n\n"),
         inlinedTemplates,
-    });
+    }));
     emitPromptContextTelemetry("reactive-execute", contextTelemetry, prompt);
     return prompt;
 }
@@ -3416,17 +3596,17 @@ export async function buildGateEvaluatePrompt(mid, midTitle, sid, sTitle, base,
             "```",
         ].join("\n"));
     }
-    return loadPrompt("gate-evaluate", {
+    return prependContextModeToBlock("gate-evaluate", base, loadPrompt("gate-evaluate", {
         workingDirectory: base,
         milestoneId: mid,
         milestoneTitle: midTitle,
         sliceId: sid,
         sliceTitle: sTitle,
-        slicePlanContent: prependContextModeToBlock("gate-evaluate", base, planContent),
+        slicePlanContent: planContent,
         gateCount: String(pending.length),
         gateList: gateListLines.join("\n"),
         subagentPrompts: subagentSections.join("\n\n---\n\n"),
-    });
+    }));
 }
 export async function buildRewriteDocsPrompt(mid, midTitle, activeSlice, base, overrides) {
     const sid = activeSlice?.id;