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

package/src/resources/extensions/gsd/auto-prompts.ts

@@ -24,7 +24,7 @@ import { isContextModeEnabled } from "./preferences-types.js";
 import { parseRoadmap } from "./parsers-legacy.js";
 import type { GSDState, InlineLevel } from "./types.js";
 import type { GSDPreferences } from "./preferences.js";
-import { join, basename } from "node:path";
+import { join, basename, relative } from "node:path";
 import { existsSync } from "node:fs";
 import { computeBudgets, resolveExecutorContextWindow, truncateAtSectionBoundary, type MinimalModelRegistry } from "./context-budget.js";
 import { getPendingGates, getPendingGatesForTurn } from "./gsd-db.js";
@@ -36,8 +36,20 @@ import {
 } from "./gate-registry.js";
 import { formatDecisionsCompact, formatRequirementsCompact } from "./structured-data-formatter.js";
 import { readPhaseAnchor, formatAnchorForPrompt } from "./phase-anchor.js";
-import { composeContextModeInstructions, composeInlinedContext, composeUnitContext, type ArtifactResolver, type ContextModeRenderMode, type ExcerptResolver } from "./unit-context-composer.js";
-import { resolveManifest } from "./unit-context-manifest.js";
+import {
+  composeContextModeInstructions,
+  composeContractedUnitContext,
+  composeInlinedContext,
+  composeToolSurfaceInstructions,
+  composeUnitContext,
+  type ArtifactResolver,
+  type ComposedUnitContextBlock,
+  type ContextModeRenderMode,
+  type ExcerptResolver,
+} from "./unit-context-composer.js";
+import { resolveManifest, type ArtifactKey } from "./unit-context-manifest.js";
+import { resolveExpectedArtifactPath } from "./auto-artifact-paths.js";
+import { compileUnitContextContract, type UnitPromptContextContract } from "./tool-contract.js";
 import { readCompactionSnapshot } from "./compaction-snapshot.js";
 import { logWarning } from "./workflow-logger.js";
 import { inlineGraphSubgraph } from "./graph-context.js";
@@ -47,7 +59,12 @@ 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, type UatType } from "./uat-policy.js";
+import {
+  classifyUatContentForRun,
+  shouldDispatchUatForContent,
+  type UatType,
+} from "./uat-policy.js";
+import { buildWebAppUatGuidanceBlock } from "./web-app-uat.js";
 
 export { buildSkillActivationBlock, buildSkillDiscoveryVars };
 
@@ -281,10 +298,79 @@ function prependContextModeToBlock(
   block: string,
   renderMode: ContextModeRenderMode = "standalone",
 ): string {
+  const toolSurface = composeToolSurfaceInstructions(unitType, { renderMode });
   const contextMode = renderContextModeBlockForPrompt(unitType, base, renderMode);
-  if (!contextMode) return block;
-  if (!block.trim()) return contextMode;
-  return `${contextMode}\n\n${block}`;
+  const guidance = [toolSurface, contextMode].filter(Boolean).join("\n\n");
+  if (!guidance) return block;
+  if (!block.trim()) return guidance;
+  return `${guidance}\n\n${block}`;
+}
+
+function requireUnitPromptContextContract(unitType: string): UnitPromptContextContract {
+  const result = compileUnitContextContract(unitType);
+  if (result.ok) return result.contract;
+  throw new Error(result.detail);
+}
+
+function requireComposedArtifactBlock(
+  blocks: readonly ComposedUnitContextBlock[],
+  unitType: string,
+  key: ArtifactKey,
+): string {
+  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;
+}
+
+interface ExecuteTaskOnDemandResult {
+  /** Rendered block for the prompt; empty string when not shown. */
+  text: string;
+  /**
+   * Telemetry skip reason when the block was suppressed; null when the block
+   * is included. Callers pass this directly to `trackPromptContext`.
+   */
+  skipReason: string | null;
+}
+
+function renderExecuteTaskOnDemandContext(
+  base: string,
+  mid: string,
+  sid: string,
+  artifacts: readonly ArtifactKey[],
+): ExecuteTaskOnDemandResult {
+  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: string | null = 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 ─────────────────────────────────────────────────────
@@ -925,7 +1011,7 @@ export async function inlineDecisionsFromDb(
 
 /**
  * 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: string, milestoneId?: string, sliceId?: string, level?: InlineLevel,
@@ -935,14 +1021,28 @@ export async function inlineRequirementsFromDb(
     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) {
     logWarning("prompt", `inlineRequirementsFromDb failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -1278,22 +1378,33 @@ export function extractSliceExecutionExcerpt(content: string | null, relPath: st
 
 // ─── Prior Task Summaries ──────────────────────────────────────────────────
 
+/** Resolve where task SUMMARY files live (legacy tasks/ subdir or flat-phase phase dir). */
+function resolveTaskSummariesLocation(
+  base: string, mid: string, sid: string,
+): { dir: string; relPrefix: string } | null {
+  const slicePath = resolveSlicePath(base, mid, sid);
+  if (!slicePath) return null;
+  const tDir = resolveTasksDir(base, mid, sid);
+  const sRel = relSlicePath(base, mid, sid);
+  if (tDir) return { dir: tDir, relPrefix: `${sRel}/tasks` };
+  return { dir: slicePath, relPrefix: sRel };
+}
+
 export async function getPriorTaskSummaryPaths(
   mid: string, sid: string, currentTid: string, base: string,
 ): Promise<string[]> {
-  const tDir = resolveTasksDir(base, mid, sid);
-  if (!tDir) return [];
+  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}`);
 }
 
 /**
@@ -1315,11 +1426,10 @@ export async function getDependencyTaskSummaryPaths(
     return getPriorTaskSummaryPaths(mid, sid, currentTid, base);
   }
 
-  const tDir = resolveTasksDir(base, mid, sid);
-  if (!tDir) return [];
+  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
@@ -1328,7 +1438,7 @@ export async function getDependencyTaskSummaryPaths(
       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 ────────────────────────────────────────────
@@ -1398,6 +1508,40 @@ export async function checkNeedsReassessment(
  * - 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: string,
+  mid: string,
+  sliceId: string,
+  uatContent: string,
+): Promise<UatType> {
+  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: string, mid: string, state: GSDState, prefs: GSDPreferences | undefined,
 ): Promise<{ sliceId: string; uatType: UatType } | null> {
@@ -1426,7 +1570,8 @@ export async function checkNeedsRunUat(
             if (assessmentContent && hasVerdict(assessmentContent)) continue;
           }
           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;
       }
@@ -1459,7 +1604,8 @@ export async function checkNeedsRunUat(
       if (assessmentContentFb && hasVerdict(assessmentContentFb)) continue;
     }
     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;
 }
@@ -1580,7 +1726,13 @@ export async function buildDiscussMilestonePrompt(
   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;
@@ -1859,7 +2011,7 @@ export async function buildResearchMilestonePrompt(mid: string, midTitle: string
   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,
@@ -1976,6 +2128,12 @@ export async function buildPlanMilestonePrompt(mid: string, midTitle: string, ba
   } 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"));
@@ -2010,7 +2168,7 @@ export async function buildPlanMilestonePrompt(mid: string, midTitle: string, ba
   return loadPrompt("plan-milestone", {
     workingDirectory: base,
     milestoneId: mid, milestoneTitle: midTitle,
-    milestonePath: relMilestonePath(base, mid),
+    milestonePath: relMilestonePath(base, mid, midTitle),
     contextPath: contextRel,
     researchPath: researchRel,
     researchOutputPath,
@@ -2306,6 +2464,14 @@ async function renderSlicePrompt(options: {
     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);
@@ -2412,6 +2578,9 @@ export async function buildPlanSlicePrompt(
       `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` +
@@ -2510,7 +2679,7 @@ export async function buildExecuteTaskPrompt(
   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}\``,
@@ -2521,12 +2690,12 @@ export async function buildExecuteTaskPrompt(
       "## 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");
@@ -2657,6 +2826,38 @@ export async function buildExecuteTaskPrompt(
   }
   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,
@@ -2668,11 +2869,12 @@ export async function buildExecuteTaskPrompt(
     taskPlanPath: taskPlanRelPath,
     taskPlanInline,
     slicePlanExcerpt,
-    carryForwardSection: finalCarryForward,
+    carryForwardSection: contractedCarryForward,
     resumeSection,
     priorTaskLines: priorLines,
+    onDemandContext,
     taskSummaryPath,
-    inlinedTemplates,
+    inlinedTemplates: contractedTemplates,
     verificationBudget,
     gatesToClose,
     skillActivation: buildSkillActivationBlock({
@@ -2683,7 +2885,7 @@ export async function buildExecuteTaskPrompt(
       taskId: tid,
       taskTitle: tTitle,
       taskPlanContent,
-      extraContext: [taskPlanInline, slicePlanExcerpt, finalCarryForward, resumeSection],
+      extraContext: [taskPlanInline, slicePlanExcerpt, contractedCarryForward, resumeSection],
       unitType: "execute-task",
     }),
   });
@@ -2736,17 +2938,16 @@ export async function buildCompleteSlicePrompt(
           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: string[] = [];
         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));
         }
@@ -2803,6 +3004,14 @@ export async function buildCompleteSlicePrompt(
     }
   }
 
+  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).
@@ -3020,9 +3229,11 @@ export async function buildCompleteMilestonePrompt(
   );
   emitPromptContextTelemetry("complete-milestone", contextTelemetry, inlinedContext);
 
-  const milestoneSummaryPath = join(base, `${relMilestonePath(base, mid)}/${mid}-SUMMARY.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 = join(relMilestonePath(base, mid), `${mid}-LEARNINGS.md`);
+  const learningsRelPath = relMilestoneFile(base, mid, "LEARNINGS");
   const learningsAbsPath = join(base, learningsRelPath);
   const extractLearningsSteps = buildExtractionStepsBlock({
     milestoneId: mid,
@@ -3259,8 +3470,9 @@ export async function buildValidateMilestonePrompt(
   );
   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
@@ -3309,16 +3521,15 @@ export async function buildReplanSlicePrompt(
 
   // 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 }));
@@ -3339,7 +3550,7 @@ export async function buildReplanSlicePrompt(
     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)";
@@ -3456,15 +3667,30 @@ export async function buildRunUatPrompt(
     null,
     cappedInlinedContext.length < rawInlinedContext.length ? `dropped ${rawInlinedContext.length - cappedInlinedContext.length} chars` : "within budget",
   );
+  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,
-    cappedInlinedContext,
+    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", {
@@ -3718,7 +3944,11 @@ export async function buildReactiveExecutePrompt(
     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.",
       "",
@@ -3749,18 +3979,22 @@ export async function buildReactiveExecutePrompt(
   const inlinedTemplates = inlineTemplate("task-summary", "Task Summary");
   trackPromptContext(contextTelemetry, "templates", "inline", inlinedTemplates);
 
-  const prompt = loadPrompt("reactive-execute", {
-    workingDirectory: base,
-    milestoneId: mid,
-    milestoneTitle: midTitle,
-    sliceId: sid,
-    sliceTitle: sTitle,
-    graphContext: prependContextModeToBlock("reactive-execute", base, graphContext),
-    readyTaskCount: String(readyTaskIds.length),
-    readyTaskList: readyTaskListLines.join("\n"),
-    subagentPrompts: subagentSections.join("\n\n---\n\n"),
-    inlinedTemplates,
-  });
+  const prompt = prependContextModeToBlock(
+    "reactive-execute",
+    base,
+    loadPrompt("reactive-execute", {
+      workingDirectory: base,
+      milestoneId: mid,
+      milestoneTitle: midTitle,
+      sliceId: sid,
+      sliceTitle: sTitle,
+      graphContext,
+      readyTaskCount: String(readyTaskIds.length),
+      readyTaskList: readyTaskListLines.join("\n"),
+      subagentPrompts: subagentSections.join("\n\n---\n\n"),
+      inlinedTemplates,
+    }),
+  );
   emitPromptContextTelemetry("reactive-execute", contextTelemetry, prompt);
   return prompt;
 }
@@ -3939,17 +4173,21 @@ export async function buildGateEvaluatePrompt(
     ].join("\n"));
   }
 
-  return loadPrompt("gate-evaluate", {
-    workingDirectory: base,
-    milestoneId: mid,
-    milestoneTitle: midTitle,
-    sliceId: sid,
-    sliceTitle: sTitle,
-    slicePlanContent: prependContextModeToBlock("gate-evaluate", base, planContent),
-    gateCount: String(pending.length),
-    gateList: gateListLines.join("\n"),
-    subagentPrompts: subagentSections.join("\n\n---\n\n"),
-  });
+  return prependContextModeToBlock(
+    "gate-evaluate",
+    base,
+    loadPrompt("gate-evaluate", {
+      workingDirectory: base,
+      milestoneId: mid,
+      milestoneTitle: midTitle,
+      sliceId: sid,
+      sliceTitle: sTitle,
+      slicePlanContent: planContent,
+      gateCount: String(pending.length),
+      gateList: gateListLines.join("\n"),
+      subagentPrompts: subagentSections.join("\n\n---\n\n"),
+    }),
+  );
 }
 
 export async function buildRewriteDocsPrompt(