@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.8e6112e9

package/dist/resources/extensions/gsd/auto-post-unit.js

@@ -16,7 +16,7 @@ import { deriveState } from "./state.js";
 import { logWarning, logError } from "./workflow-logger.js";
 import { loadFile, parseSummary, resolveAllOverrides } from "./files.js";
 import { loadPrompt } from "./prompt-loader.js";
-import { isAwaitingUserInput } from "./user-input-boundary.js";
+import { isAwaitingUserInput } from "./consent-question.js";
 import { resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveMilestoneFile, resolveTasksDir, buildTaskFileName, } from "./paths.js";
 import { invalidateAllCaches } from "./cache.js";
 import { rebuildState } from "./doctor.js";
@@ -28,9 +28,9 @@ 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 { renderPlanCheckboxes, renderRoadmapFromDb } from "./markdown-renderer.js";
-import { parseRoadmap as parseLegacyRoadmap } from "./parsers-legacy.js";
+import { isDbAvailable, getTask, getSlice, getMilestone, getMilestoneSlices, updateTaskStatus, _getAdapter, getVerificationEvidence } from "./gsd-db.js";
+import { getWorkflowDatabasePath, refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
+import { renderPlanCheckboxes, renderRoadmapFromDb, roadmapRenderMarksSliceDone } from "./markdown-renderer.js";
 import { consumeSignal } from "./session-status-io.js";
 import { checkPostUnitHooks, consumeHookFailure, isRetryPending, consumeRetryTrigger, consumeGateBlock, persistHookState, resolveHookArtifactPath, } from "./post-unit-hooks.js";
 import { hasPendingCaptures, loadPendingCaptures, revertExecutorResolvedCaptures } from "./captures.js";
@@ -38,7 +38,7 @@ import { debugLog } from "./debug-logger.js";
 import { runSafely } from "./auto-utils.js";
 import { isMilestoneCloseoutSettled, runMilestoneCloseoutGitHub, } from "./milestone-closeout.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 } from "./safety/evidence-cross-ref.js";
 import { validateContent } from "./safety/content-validator.js";
 import { resolveSafetyHarnessConfig } from "./safety/safety-harness.js";
@@ -54,11 +54,12 @@ import { writeTurnGitTransaction } from "./uok/gitops.js";
 import { isClosedStatus } from "./status-guards.js";
 import { detectAbandonMilestone } from "./abandon-detect.js";
 import { getPendingGate } from "./bootstrap/write-gate.js";
-import { isDeterministicPolicyError } from "./auto-tool-tracking.js";
+import { isDeterministicPolicyError, isToolUnavailableError } from "./auto-tool-tracking.js";
 import { formatConnectedStepStack, formatPostUnitStatusCard } from "./auto-status-message.js";
 import { clearProjectResearchInflightMarker, finalizeProjectResearchTimeout, } from "./project-research-policy.js";
 import { validateArtifact } from "./schemas/validate.js";
 import { verificationRetryKey } from "./auto/verification-retry-policy.js";
+import { saveCustomVerifyRetryCounts } from "./auto/custom-verify-retry-store.js";
 import { getLedger } from "./metrics.js";
 import { getUnitCostSpikeAction, resolveUnitCostSpikeMultiplier } from "./auto-budget.js";
 import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
@@ -506,9 +507,10 @@ export function _hasExecutionToolCallsInSessionForTest(entries) {
         if (e?.type === "toolCall" && isExecutionToolName(e?.name ?? e?.toolName)) {
             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) {
@@ -720,7 +722,7 @@ export const USER_DRIVEN_DEEP_UNITS = new Set([
     "discuss-milestone",
     "research-decision",
 ]);
-export { isAwaitingUserInput } from "./user-input-boundary.js";
+export { isAwaitingUserInput } from "./consent-question.js";
 function artifactValidationKind(unitType) {
     if (unitType === "discuss-project")
         return "project";
@@ -798,11 +800,13 @@ async function repairCompleteSliceRoadmapProjection(unitType, unitId, basePath)
     if (!summaryPath || !existsSync(summaryPath) || !uatPath || !existsSync(uatPath)) {
         return false;
     }
+    // Stale-render detection (ADR-017): the DB already says the slice is closed;
+    // this only checks whether the rendered ROADMAP projection reflects it, to
+    // decide whether a repair re-render is needed.
     const roadmapPath = resolveMilestoneFile(artifactBase, mid, "ROADMAP");
     if (roadmapPath && existsSync(roadmapPath)) {
         try {
-            const roadmap = parseLegacyRoadmap(readFileSync(roadmapPath, "utf-8"));
-            if (roadmap.slices.find((roadmapSlice) => roadmapSlice.id === sid)?.done) {
+            if (roadmapRenderMarksSliceDone(readFileSync(roadmapPath, "utf-8"), sid)) {
                 return false;
             }
         }
@@ -1052,9 +1056,9 @@ export async function postUnitPreVerification(pctx, opts) {
     if (!opts?.skipSettleDelay) {
         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");
         }
@@ -1288,6 +1292,7 @@ export async function postUnitPreVerification(pctx, opts) {
             const safetyConfig = resolveSafetyHarnessConfig(prefs?.safety_harness);
             if (safetyConfig.enabled) {
                 const { milestone: sMid, slice: sSid, task: sTid } = parseUnitId(s.currentUnit.id);
+                const fileChangeAllowlist = effectiveFileChangeAllowlist(safetyConfig.file_change_allowlist, prefs?.git?.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 {
@@ -1302,7 +1307,7 @@ export async function postUnitPreVerification(pctx, opts) {
                             const plannedFiles = getPlannedKeyFiles(sliceTaskRows.map((taskRow) => ({
                                 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) {
@@ -1318,7 +1323,7 @@ export async function postUnitPreVerification(pctx, opts) {
                             if (taskRow) {
                                 const expectedOutput = taskRow.expected_output ?? [];
                                 const plannedFiles = 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) {
@@ -1698,7 +1703,27 @@ export async function postUnitPreVerification(pctx, opts) {
                 ctx.ui.notify(`Artifact missing for ${s.currentUnit.type} ${s.currentUnit.id} — DB unavailable, skipping retry.${dbSkipDiag ? ` Expected: ${dbSkipDiag}` : ""}`, "error");
             }
             else if (!triggerArtifactVerified) {
-                if (s.lastToolInvocationError) {
+                if (s.lastToolInvocationError && isToolUnavailableError(s.lastToolInvocationError)) {
+                    // Tool-unavailable is transient: the workflow MCP server registers
+                    // its surface asynchronously, so a Unit's first call can race the
+                    // registration. Retry with escalating delay, bounded at 3 attempts.
+                    // ponytail: MAX constant so the guard, log, and display all agree
+                    const MAX_TOOL_UNAVAIL_RETRIES = 3;
+                    if (s.toolUnavailableRetries >= MAX_TOOL_UNAVAIL_RETRIES) {
+                        debugLog("postUnit", { phase: "tool-unavailable-exhausted", unitType: s.currentUnit.type, unitId: s.currentUnit.id, retries: s.toolUnavailableRetries });
+                        ctx.ui.notify(`Tool unavailable for ${s.currentUnit.type} after ${MAX_TOOL_UNAVAIL_RETRIES} retries: ${s.lastToolInvocationError}. MCP server may not be starting — pausing auto-mode.`, "error");
+                        s.lastToolInvocationError = null;
+                        await pauseAuto(ctx, pi);
+                        return "dispatched";
+                    }
+                    s.toolUnavailableRetries++;
+                    const delayMs = s.toolUnavailableRetries * 1000;
+                    debugLog("postUnit", { phase: "tool-unavailable-retry", unitType: s.currentUnit.type, unitId: s.currentUnit.id, error: s.lastToolInvocationError, attempt: s.toolUnavailableRetries, delayMs });
+                    ctx.ui.notify(`Tool unavailable for ${s.currentUnit.type}: ${s.lastToolInvocationError}. Waiting ${delayMs}ms for MCP server — retry ${s.toolUnavailableRetries}/${MAX_TOOL_UNAVAIL_RETRIES}.`, "warning");
+                    s.lastToolInvocationError = null;
+                    await new Promise(r => setTimeout(r, delayMs));
+                }
+                else if (s.lastToolInvocationError) {
                     const isUserSkip = /queued user message/i.test(s.lastToolInvocationError);
                     const errMsg = isUserSkip
                         ? `Tool skipped for ${s.currentUnit.type}: ${s.lastToolInvocationError}. Queued user message interrupted the turn — pausing auto-mode.`
@@ -1786,12 +1811,14 @@ export async function postUnitPreVerification(pctx, opts) {
                             }
                         }
                         s.exhaustedVerificationUnits.add(retryKey);
+                        saveCustomVerifyRetryCounts(s, { logFailure: err => debugLog("postUnit", { phase: "save-verify-retries-failed", error: err instanceof Error ? err.message : String(err) }) });
                         debugLog("postUnit", { phase: "artifact-verify-exhausted", unitType: s.currentUnit.type, unitId: s.currentUnit.id, attempt });
                         ctx.ui.notify(`${failureDetails} Pausing auto-mode after ${MAX_ARTIFACT_VERIFICATION_RETRIES} retries.`, "error");
                         await pauseAuto(ctx, pi);
                         return "dispatched";
                     }
                     s.verificationRetryCount.set(retryKey, attempt);
+                    saveCustomVerifyRetryCounts(s, { logFailure: err => debugLog("postUnit", { phase: "save-verify-retries-failed", error: err instanceof Error ? err.message : String(err) }) });
                     s.pendingVerificationRetry = {
                         unitId: s.currentUnit.id,
                         failureContext: `${failureDetails} (attempt ${attempt}/${MAX_ARTIFACT_VERIFICATION_RETRIES}).`,
@@ -1809,8 +1836,11 @@ export async function postUnitPreVerification(pctx, opts) {
                 if (s.pendingVerificationRetry?.unitId === s.currentUnit.id) {
                     s.pendingVerificationRetry = null;
                 }
+                s.toolUnavailableRetries = 0;
                 s.verificationRetryCount.delete(retryKey);
                 s.verificationRetryFailureHashes.delete(retryKey);
+                s.exhaustedVerificationUnits.delete(retryKey);
+                saveCustomVerifyRetryCounts(s, { logFailure: err => debugLog("postUnit", { phase: "save-verify-retries-failed", error: err instanceof Error ? err.message : String(err) }) });
                 if (s.currentUnit.type === "complete-milestone") {
                     const { milestone: mid } = parseUnitId(s.currentUnit.id);
                     if (mid) {

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

@@ -21,8 +21,9 @@ 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 { 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 +33,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 +224,37 @@ 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 "";
+    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 ─────────────────────────────────────────────────────
 /**
@@ -816,7 +843,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 +851,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) {
@@ -1240,6 +1281,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 +1339,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 +1381,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;
 }
@@ -1745,6 +1814,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"));
@@ -2032,6 +2108,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 +2190,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 +2260,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 +2271,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 +2374,30 @@ 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 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,
@@ -2298,11 +2409,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 +2425,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",
         }),
     });
@@ -2424,6 +2536,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).
@@ -3021,10 +3141,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,
@@ -3265,18 +3400,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 +3551,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;