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

package/src/resources/extensions/gsd/auto/phases.ts

@@ -20,6 +20,7 @@ import {
   type PreVerificationOpts,
 } from "../auto-post-unit.js";
 import { lastAssistantText } from "../user-input-boundary.js";
+import { resolveEffectiveUnitIsolationMode } from "../preferences.js";
 import type { Phase } from "../types.js";
 import {
   MAX_RECOVERY_CHARS,
@@ -60,7 +61,8 @@ import { writeUnitRuntimeRecord } from "../unit-runtime.js";
 import { withTimeout, FINALIZE_PRE_TIMEOUT_MS, FINALIZE_POST_TIMEOUT_MS } from "./finalize-timeout.js";
 import { getEligibleSlices } from "../slice-parallel-eligibility.js";
 import { isSliceParallelActive, startSliceParallel } from "../slice-parallel-orchestrator.js";
-import { isDbAvailable, getMilestoneSlices, getSlice, getTask, refreshOpenDatabaseFromDisk } from "../gsd-db.js";
+import { isDbAvailable, getMilestoneSlices, getSlice, getTask } from "../gsd-db.js";
+import { refreshWorkflowDatabaseFromDisk } from "../db-workspace.js";
 import { isClosedStatus } from "../status-guards.js";
 import { setRuntimeKv } from "../db/runtime-kv.js";
 import { getLatestForUnit } from "../db/unit-dispatches.js";
@@ -85,7 +87,12 @@ import {
   supportsStructuredQuestions,
 } from "../workflow-mcp.js";
 import { prepareWorkflowMcpForProject } from "../workflow-mcp-auto-prep.js";
-import { getToolBaselineSnapshot, applyThinkingLevelForModel, floorThinkingLevelForUnit } from "../auto-model-selection.js";
+import {
+  applyThinkingLevelForModel,
+  floorThinkingLevelForUnit,
+  getRegisteredToolSnapshot,
+  getToolBaselineSnapshot,
+} from "../auto-model-selection.js";
 import type { DispatchAction } from "../auto-dispatch.js";
 import { resolveManifest } from "../unit-context-manifest.js";
 import { createWorktreeSafetyModule, type WorktreeSafetyResult } from "../worktree-safety.js";
@@ -225,7 +232,7 @@ function rememberRetryDispatch(
 
 function getAlreadyClosedDispatchReason(unitType: string, unitId: string): string | null {
   if (!isDbAvailable()) return null;
-  refreshOpenDatabaseFromDisk();
+  refreshWorkflowDatabaseFromDisk();
   const { milestone, slice, task } = parseUnitId(unitId);
   if (unitType === "execute-task" && milestone && slice && task) {
     const row = getTask(milestone, slice, task);
@@ -356,7 +363,15 @@ async function validateSourceWriteWorktreeSafety(
   if (!writesSource) return null;
 
   const projectRoot = s.canonicalProjectRoot ?? resolveWorktreeProjectRoot(s.basePath, s.originalBasePath);
-  const isolationMode = deps.getIsolationMode(projectRoot);
+  // A degraded session already fell back to the milestone branch in the
+  // project root — validating against the canonical worktree root there
+  // would fail every dispatch with a false invalid-root. The same applies
+  // to a stranded-recovery session that adopted the milestone branch.
+  const isolationMode = resolveEffectiveUnitIsolationMode(
+    deps.getIsolationMode(projectRoot),
+    s.isolationDegraded,
+    s.strandedRecoveryIsolationMode,
+  );
   if (isolationMode !== "worktree") return null;
 
   const safety = createWorktreeSafetyModule();
@@ -624,6 +639,16 @@ export async function _runMilestoneMergeWithStashRestore(
   );
   if (exitResult.ok) {
     s.milestoneMergedInPhases = true;
+    try {
+      const projectRoot = s.originalBasePath || s.canonicalProjectRoot || s.basePath;
+      const { rebuildMarkdownProjectionsFromDb } = await import("../commands-maintenance.js");
+      await rebuildMarkdownProjectionsFromDb(projectRoot);
+    } catch (err) {
+      logWarning(
+        "engine",
+        `markdown projection rebuild after milestone merge failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
   } else {
     mergeError = exitResult.cause ?? new Error(`exit ${exitResult.reason}`);
   }
@@ -1232,6 +1257,19 @@ export async function runPreDispatch(
     } catch (e) {
       logWarning("engine", "STATE.md rebuild failed after milestone transition", { error: String(e) });
     }
+
+    // Re-project ROADMAP/PLAN markdown from the authoritative DB. Worktree DB
+    // reconciliation during merge can leave main-branch markdown stale relative
+    // to gsd.db (the 3M/3S/10T vs 3M/5S/16T drift class at /gsd startup).
+    try {
+      const { rebuildMarkdownProjectionsFromDb } = await import("../commands-maintenance.js");
+      await rebuildMarkdownProjectionsFromDb(s.canonicalProjectRoot);
+      if (s.basePath !== s.canonicalProjectRoot) {
+        await rebuildMarkdownProjectionsFromDb(s.basePath);
+      }
+    } catch (e) {
+      logWarning("engine", "markdown projection rebuild failed after milestone transition", { error: String(e) });
+    }
   }
 
   if (mid) {
@@ -1458,6 +1496,7 @@ export async function runDispatch(
   // Checking a stale-narrowed set causes false transport-preflight warnings
   // that repeat on every /gsd auto resume (#477 follow-up).
   const activeTools = getToolBaselineSnapshot(pi);
+  const registeredTools = getRegisteredToolSnapshot(pi);
   // Deep planning intentionally keeps human checkpoints in plain chat. In
   // Claude Code/local MCP transports, structured question requests can be
   // cancelled outside the normal chat flow, which made approval gates easy to
@@ -1482,6 +1521,7 @@ export async function runDispatch(
     sessionProvider: ctx.model?.provider,
     modelRegistry: ctx.modelRegistry as MinimalModelRegistry | undefined,
     activeTools,
+    registeredTools,
     sessionBaseUrl: ctx.model?.baseUrl,
     sessionAuthMode: authMode,
   });
@@ -1508,6 +1548,7 @@ export async function runDispatch(
       sessionProvider: ctx.model?.provider,
       modelRegistry: ctx.modelRegistry as MinimalModelRegistry | undefined,
       activeTools,
+      registeredTools,
       sessionBaseUrl: ctx.model?.baseUrl,
       sessionAuthMode: authMode,
     });

package/src/resources/extensions/gsd/auto/run-unit.ts

@@ -130,7 +130,8 @@ export async function runUnit(
       unitId,
       error: msg,
     });
-    return { status: "cancelled", errorContext: { message: `Session creation failed: ${msg}`, category: "session-failed", isTransient: true } };
+    const isStructural = sessionErr instanceof TypeError || /is not a function/i.test(msg);
+    return { status: "cancelled", errorContext: { message: `Session creation failed: ${msg}`, category: "session-failed", isTransient: !isStructural } };
   }
   if (sessionTimeoutHandle) clearTimeout(sessionTimeoutHandle);
 

package/src/resources/extensions/gsd/auto/session.ts

@@ -29,6 +29,7 @@ import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { normalizeRealPath } from "../paths.js";
 import type { MilestoneScope } from "../workspace.js";
 import type { RootDirtySnapshot } from "../root-write-leak-guard.js";
+import type { MilestoneSettlementOutcome } from "../milestone-settlement.js";
 
 // ─── Exported Types ──────────────────────────────────────────────────────────
 
@@ -230,6 +231,8 @@ export class AutoSession {
   /** Set to true after phases.ts successfully calls mergeAndExit, so that
    *  stopAuto does not attempt the same merge a second time (#2645). */
   milestoneMergedInPhases = false;
+  /** Last milestone settlement result observed by Auto Orchestration. */
+  milestoneSettlement: MilestoneSettlementOutcome | null = null;
 
   // #4765 — slice-cadence collapse: main-branch SHAs at the moment each
   // milestone's first slice merge began. Used by resquashMilestoneOnMain at
@@ -410,6 +413,7 @@ export class AutoSession {
     this.strandedRecoveryIsolationMode = null;
     this.rootWriteBaseline = null;
     this.milestoneMergedInPhases = false;
+    this.milestoneSettlement = null;
     this.milestoneStartShas = new Map();
     this.checkpointSha = null;
 

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

@@ -44,6 +44,8 @@ import {
 import { logWarning } from "./workflow-logger.js";
 import { formattedShortcutPair } from "./shortcut-defs.js";
 import { readUnitRuntimeRecord, type AutoUnitRuntimeRecord } from "./unit-runtime.js";
+import { describeMilestoneReadinessPhase } from "./milestone-readiness.js";
+import type { ToolSurfaceSnapshot } from "./tool-surface-snapshot.js";
 
 const ACTIVE_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const;
 
@@ -85,6 +87,8 @@ export interface AutoDashboardData {
   rtkEnabled?: boolean;
   /** Cross-process: another auto-mode session detected via auto.lock (PID, startedAt) */
   remoteSession?: { pid: number; startedAt: string; unitType: string; unitId: string };
+  /** Last typed tool-surface snapshot for active auto-mode scoping/debugging. */
+  toolSurface?: ToolSurfaceSnapshot | null;
 }
 
 export interface CompletionDashboardSnapshot {
@@ -189,6 +193,18 @@ export function unitPhaseLabel(unitType: string): string {
   }
 }
 
+export function formatToolSurfaceSnapshot(snapshot: ToolSurfaceSnapshot | null | undefined): string | null {
+  if (!snapshot) return null;
+  const counts = [
+    `model ${snapshot.modelFacingToolNames.length}`,
+    `registered ${snapshot.registeredToolNames.length}`,
+    `scoped ${snapshot.scopedToolNames.length}`,
+    `presented ${snapshot.presentedToolNames.length}`,
+  ];
+  const label = snapshot.unitType ?? snapshot.phase ?? snapshot.source;
+  return `${label}: ${counts.join(" / ")}`;
+}
+
 function peekNext(unitType: string, state: GSDState): string {
   // Show active hook info in progress display
   const activeHookState = getActiveHook();
@@ -224,12 +240,10 @@ export function describeNextUnit(state: GSDState): { label: string; description:
   const sTitle = state.activeSlice?.title;
   const tid = state.activeTask?.id;
   const tTitle = state.activeTask?.title;
+  const readinessDescription = describeMilestoneReadinessPhase(state.phase);
+  if (readinessDescription) return readinessDescription;
 
   switch (state.phase) {
-    case "needs-discussion":
-      return { label: "Discuss milestone draft", description: "Milestone has a draft context — needs discussion before planning." };
-    case "pre-planning":
-      return { label: "Research & plan milestone", description: "Scout the landscape and create the roadmap." };
     case "planning":
       return { label: `Plan ${sid}: ${sTitle}`, description: "Research and decompose into tasks." };
     case "executing":

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

@@ -112,9 +112,9 @@ import { runTurnGitAction } from "./git-service.js";
 import { parseUnitId } from "./unit-id.js";
 import { resolveExpectedArtifactPath } from "./auto-artifact-paths.js";
 import {
-  checkCloseoutConsistencyGate,
-  formatCloseoutConsistencyBlock,
-} from "./closeout-consistency-gate.js";
+  formatCloseoutProofBlock,
+  proveMilestoneCloseout,
+} from "./milestone-closeout-proof.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -153,6 +153,8 @@ export interface DispatchContext {
   sessionProvider?: string;
   /** Active tools in the current session, used for transport preflight checks. */
   activeTools?: string[];
+  /** Registered tools in the current session, used for run-uat tools re-scoped at dispatch. */
+  registeredTools?: string[];
   /** Session model base URL, used for transport preflight checks. */
   sessionBaseUrl?: string;
   /** Session model auth mode, used for transport preflight checks. */
@@ -734,7 +736,17 @@ export const DISPATCH_RULES: DispatchRule[] = [
   },
   {
     name: "run-uat (post-completion)",
-    match: async ({ state, mid, basePath, prefs, sessionProvider, sessionAuthMode, activeTools, sessionBaseUrl }) => {
+    match: async ({
+      state,
+      mid,
+      basePath,
+      prefs,
+      sessionProvider,
+      sessionAuthMode,
+      activeTools,
+      registeredTools,
+      sessionBaseUrl,
+    }) => {
       const needsRunUat = await checkNeedsRunUat(basePath, mid, state, prefs);
       if (!needsRunUat) return null;
       const { sliceId, uatType } = needsRunUat;
@@ -753,6 +765,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
       const browserToolError = getUatBrowserToolSupportError({
         uatType,
         activeTools,
+        registeredTools,
         milestoneId: mid,
         sliceId,
       });
@@ -1745,11 +1758,11 @@ export const DISPATCH_RULES: DispatchRule[] = [
           };
         }
         if (milestone) {
-          const closeoutGate = checkCloseoutConsistencyGate(mid, { refreshFromDisk: true });
-          if (!closeoutGate.ok) {
+          const closeoutProof = proveMilestoneCloseout(mid, { refreshFromDisk: true });
+          if (!closeoutProof.ok) {
             return {
               action: "stop",
-              reason: formatCloseoutConsistencyBlock(closeoutGate),
+              reason: formatCloseoutProofBlock(closeoutProof),
               level: "warning",
             };
           }

package/src/resources/extensions/gsd/auto-model-selection.ts

@@ -122,6 +122,14 @@ export function getToolBaselineSnapshot(pi: ExtensionAPI): string[] {
   return [...new Set([...baseline, ...live])];
 }
 
+export function getRegisteredToolSnapshot(pi: ExtensionAPI): string[] {
+  if (typeof pi.getAllTools !== "function") return getToolBaselineSnapshot(pi);
+  const names = pi.getAllTools()
+    .map((tool) => tool.name)
+    .filter((name): name is string => typeof name === "string" && name.length > 0);
+  return [...new Set(names)];
+}
+
 /**
  * Models eligible for the pre-dispatch policy gate. Prefer registry-available
  * models; when that list is empty (common after worktree resume before registry

package/src/resources/extensions/gsd/auto-post-unit.ts

@@ -49,7 +49,8 @@ import { regenerateIfMissing } from "./workflow-projections.js";
 import { WorktreeStateProjection } from "./worktree-state-projection.js";
 import { createWorkspace, scopeMilestone } from "./workspace.js";
 import { normalizeWorktreePathForCompare } from "./worktree-root.js";
-import { isDbAvailable, getDbPath, refreshOpenDatabaseFromDisk, getTask, getSlice, getMilestone, getMilestoneSlices, updateTaskStatus, _getAdapter, getVerificationEvidence } from "./gsd-db.js";
+import { isDbAvailable, getTask, getSlice, getMilestone, getMilestoneSlices, updateTaskStatus, _getAdapter, getVerificationEvidence } from "./gsd-db.js";
+import { getWorkflowDatabasePath, refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 import { renderPlanCheckboxes, renderRoadmapFromDb } from "./markdown-renderer.js";
 import { parseRoadmap as parseLegacyRoadmap } from "./parsers-legacy.js";
 import { consumeSignal } from "./session-status-io.js";
@@ -71,7 +72,7 @@ import {
 } from "./milestone-closeout.js";
 import type { AutoSession, SidecarItem } from "./auto/session.js";
 import { getEvidence, clearEvidenceFromDisk, isExecutionToolName } from "./safety/evidence-collector.js";
-import { validateFileChanges } from "./safety/file-change-validator.js";
+import { validateFileChanges, effectiveFileChangeAllowlist } from "./safety/file-change-validator.js";
 import { crossReferenceEvidence, type ClaimedEvidence } from "./safety/evidence-cross-ref.js";
 import { validateContent } from "./safety/content-validator.js";
 import { resolveSafetyHarnessConfig } from "./safety/safety-harness.js";
@@ -618,8 +619,10 @@ export function _hasExecutionToolCallsInSessionForTest(entries: readonly unknown
       return true;
     }
 
-    if (e?.type !== "message") continue;
-    const msg = e?.message;
+    // Accept both session-manager entries ({type: "message", message}) and
+    // bare agent-end messages ({role, content}) — the auto loop passes the
+    // latter via opts.agentEndMessages.
+    const msg = e?.type === "message" ? e?.message : e;
     if (!msg || msg.role !== "assistant" || !Array.isArray(msg.content)) continue;
     for (const block of msg.content) {
       if (block?.type !== "toolCall") continue;
@@ -1273,9 +1276,9 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
     await new Promise(r => setTimeout(r, 100));
   }
 
-  const dbPath = getDbPath();
+  const dbPath = getWorkflowDatabasePath();
   if (isDbAvailable() && dbPath && dbPath !== ":memory:") {
-    const refreshed = refreshOpenDatabaseFromDisk();
+    const refreshed = refreshWorkflowDatabaseFromDisk();
     if (!refreshed) {
       logWarning("db", "post-unit database refresh failed; derived state may be stale");
     }
@@ -1534,6 +1537,11 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
       if (safetyConfig.enabled) {
         const { milestone: sMid, slice: sSid, task: sTid } = parseUnitId(s.currentUnit.id);
 
+        const fileChangeAllowlist = effectiveFileChangeAllowlist(
+          safetyConfig.file_change_allowlist,
+          (prefs?.git as { manage_gitignore?: boolean } | undefined)?.manage_gitignore,
+        );
+
         // File change validation (execute-task only, after unit execution)
         if (safetyConfig.file_change_validation && s.currentUnit.type === "execute-task" && sMid && sSid && sTid) {
           try {
@@ -1553,7 +1561,7 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
                   files: taskRow.files,
                 })),
               );
-              const audit = validateFileChanges(s.basePath, expectedOutput, plannedFiles, safetyConfig.file_change_allowlist);
+              const audit = validateFileChanges(s.basePath, expectedOutput, plannedFiles, fileChangeAllowlist);
               if (audit && audit.violations.length > 0) {
                 const warnings = audit.violations.filter(v => v.severity === "warning");
                 for (const v of warnings) {
@@ -1575,7 +1583,7 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
                   s.basePath,
                   expectedOutput,
                   plannedFiles,
-                  safetyConfig.file_change_allowlist,
+                  fileChangeAllowlist,
                 );
                 if (audit && audit.violations.length > 0) {
                   const warnings = audit.violations.filter(v => v.severity === "warning");

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

@@ -36,8 +36,18 @@ 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,
+  composeUnitContext,
+  type ArtifactResolver,
+  type ComposedUnitContextBlock,
+  type ContextModeRenderMode,
+  type ExcerptResolver,
+} from "./unit-context-composer.js";
+import { resolveManifest, type ArtifactKey } from "./unit-context-manifest.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";
@@ -48,6 +58,7 @@ import { buildSkillActivationBlock, buildSkillDiscoveryVars } from "./skill-acti
 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 { buildWebAppUatGuidanceBlock } from "./web-app-uat.js";
 
 export { buildSkillActivationBlock, buildSkillDiscoveryVars };
 
@@ -287,6 +298,39 @@ function prependContextModeToBlock(
   return `${contextMode}\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;
+}
+
+function renderExecuteTaskOnDemandContext(
+  base: string,
+  mid: string,
+  sid: string,
+  artifacts: readonly ArtifactKey[],
+): string {
+  if (!artifacts.includes("slice-research")) return "";
+  const researchPath = relSliceFile(base, mid, sid, "RESEARCH");
+  return [
+    "## 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");
+}
+
 // ─── Executor Constraints ─────────────────────────────────────────────────────
 
 /**
@@ -1976,6 +2020,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"));
@@ -2306,6 +2356,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);
@@ -2510,7 +2568,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 +2579,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 +2715,37 @@ 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 onDemandContext = renderExecuteTaskOnDemandContext(base, mid, sid, contractedContext.onDemand);
+  trackPromptContext(
+    contextTelemetry,
+    "slice-research",
+    onDemandContext ? "on-demand" : "skipped",
+    onDemandContext,
+    onDemandContext ? undefined : "not declared by contract",
+  );
+
   const prompt = loadPrompt("execute-task", {
     overridesSection,
     runtimeContext,
@@ -2668,11 +2757,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 +2773,7 @@ export async function buildExecuteTaskPrompt(
       taskId: tid,
       taskTitle: tTitle,
       taskPlanContent,
-      extraContext: [taskPlanInline, slicePlanExcerpt, finalCarryForward, resumeSection],
+      extraContext: [taskPlanInline, slicePlanExcerpt, contractedCarryForward, resumeSection],
       unitType: "execute-task",
     }),
   });
@@ -2803,6 +2893,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).