@opengsd/gsd-pi 1.1.1-dev.b2556262 → 1.2.0-dev.4813ead6

package/dist/resources/extensions/gsd/auto/phases.js

@@ -33,7 +33,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";
@@ -49,7 +50,7 @@ import { resolveSafetyHarnessConfig } from "../safety/safety-harness.js";
 import { getContextPauseAction } from "../auto-budget.js";
 import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForAutoUnit, 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 { resolveManifest } from "../unit-context-manifest.js";
 import { createWorktreeSafetyModule } from "../worktree-safety.js";
 import { isSuspiciousGhostCompletion } from "../auto-unit-closeout.js";
@@ -156,7 +157,7 @@ function rememberRetryDispatch(s, unit, iterData) {
 function getAlreadyClosedDispatchReason(unitType, unitId) {
     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);
@@ -447,6 +448,14 @@ export async function _runMilestoneMergeWithStashRestore(ic, milestoneId, option
     const exitResult = deps.lifecycle.exitMilestone(milestoneId, { merge: true }, ctx.ui);
     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}`);
@@ -929,6 +938,19 @@ export async function runPreDispatch(ic, loopState) {
         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) {
         s.currentMilestoneId = mid;
@@ -1082,6 +1104,7 @@ export async function runDispatch(ic, preData, loopState) {
     // 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
@@ -1105,6 +1128,7 @@ export async function runDispatch(ic, preData, loopState) {
         sessionProvider: ctx.model?.provider,
         modelRegistry: ctx.modelRegistry,
         activeTools,
+        registeredTools,
         sessionBaseUrl: ctx.model?.baseUrl,
         sessionAuthMode: authMode,
     });
@@ -1131,6 +1155,7 @@ export async function runDispatch(ic, preData, loopState) {
             sessionProvider: ctx.model?.provider,
             modelRegistry: ctx.modelRegistry,
             activeTools,
+            registeredTools,
             sessionBaseUrl: ctx.model?.baseUrl,
             sessionAuthMode: authMode,
         });

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

@@ -95,7 +95,8 @@ export async function runUnit(ctx, pi, s, unitType, unitId, prompt) {
             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/dist/resources/extensions/gsd/auto/session.js

@@ -143,6 +143,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 = null;
     // #4765 — slice-cadence collapse: main-branch SHAs at the moment each
     // milestone's first slice merge began. Used by resquashMilestoneOnMain at
     // milestone completion to collapse N slice commits into one. Cleared when
@@ -311,6 +313,7 @@ export class AutoSession {
         this.strandedRecoveryIsolationMode = null;
         this.rootWriteBaseline = null;
         this.milestoneMergedInPhases = false;
+        this.milestoneSettlement = null;
         this.milestoneStartShas = new Map();
         this.checkpointSha = null;
         // Signal handler

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

@@ -16,6 +16,7 @@ import { parseUnitId } from "./unit-id.js";
 import { logWarning } from "./workflow-logger.js";
 import { formattedShortcutPair } from "./shortcut-defs.js";
 import { readUnitRuntimeRecord } from "./unit-runtime.js";
+import { describeMilestoneReadinessPhase } from "./milestone-readiness.js";
 const ACTIVE_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 // ─── UAT Slice Extraction ─────────────────────────────────────────────────────
 /**
@@ -84,6 +85,18 @@ export function unitPhaseLabel(unitType) {
         default: return unitType.toUpperCase();
     }
 }
+export function formatToolSurfaceSnapshot(snapshot) {
+    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, state) {
     // Show active hook info in progress display
     const activeHookState = getActiveHook();
@@ -118,11 +131,10 @@ export function describeNextUnit(state) {
     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/dist/resources/extensions/gsd/auto-dispatch.js

@@ -37,7 +37,7 @@ import { probeGitConflictState } from "./git-conflict-state.js";
 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";
+import { formatCloseoutProofBlock, proveMilestoneCloseout, } from "./milestone-closeout-proof.js";
 function resolveExistingExpectedArtifact(unitType, unitId, basePath) {
     const artifactPath = resolveExpectedArtifactPath(unitType, unitId, basePath);
     return artifactPath && existsSync(artifactPath) ? artifactPath : null;
@@ -518,7 +518,7 @@ export const DISPATCH_RULES = [
     },
     {
         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;
@@ -533,6 +533,7 @@ export const DISPATCH_RULES = [
             const browserToolError = getUatBrowserToolSupportError({
                 uatType,
                 activeTools,
+                registeredTools,
                 milestoneId: mid,
                 sliceId,
             });
@@ -1425,11 +1426,11 @@ export const DISPATCH_RULES = [
                     };
                 }
                 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/dist/resources/extensions/gsd/auto-model-selection.js

@@ -90,6 +90,14 @@ export function getToolBaselineSnapshot(pi) {
         return live;
     return [...new Set([...baseline, ...live])];
 }
+export function getRegisteredToolSnapshot(pi) {
+    if (typeof pi.getAllTools !== "function")
+        return getToolBaselineSnapshot(pi);
+    const names = pi.getAllTools()
+        .map((tool) => tool.name)
+        .filter((name) => 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/dist/resources/extensions/gsd/auto-post-unit.js

@@ -28,7 +28,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";
@@ -1052,9 +1053,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");
         }

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

@@ -21,7 +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, 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,6 +34,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 } from "./uat-policy.js";
+import { buildWebAppUatGuidanceBlock } from "./web-app-uat.js";
 export { buildSkillActivationBlock, buildSkillDiscoveryVars };
 // ─── Preamble Cap ─────────────────────────────────────────────────────────────
 /**
@@ -228,6 +231,29 @@ function prependContextModeToBlock(unitType, base, block, renderMode = "standalo
         return contextMode;
     return `${contextMode}\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 ─────────────────────────────────────────────────────
 /**
  * Format executor context constraints for injection into the plan-slice prompt.
@@ -1451,6 +1477,75 @@ export async function buildDiscussRequirementsPrompt(base, structuredQuestionsAv
         commitInstruction: "Do not commit planning artifacts — .gsd/ is managed externally.",
     }));
 }
+/**
+ * Bounded codebase snapshot for research-milestone grounding (ADR-029).
+ *
+ * Reuses the in-process, ~millisecond `analyzeCodebase` / `formatCodebaseBrief`
+ * machinery that powers the guided-discuss Preparation Snapshot, so research
+ * grounds on current code reality instead of running an open-ended `rg`/`find`/
+ * `scout` survey on every dispatch (the auto-mode counterpart to ADR-028).
+ *
+ * Gated on the manifest's `codebaseMap` flag (previously a dead policy flag)
+ * and the `discuss_preparation` opt-out. Failures degrade silently — research
+ * still runs, it just falls back to on-demand reads.
+ */
+async function buildResearchCodebaseSnapshot(base) {
+    const manifest = resolveManifest("research-milestone");
+    if (!manifest?.codebaseMap)
+        return null;
+    const prefs = loadEffectiveGSDPreferences(base)?.preferences;
+    if (prefs?.discuss_preparation === false)
+        return null;
+    try {
+        const { analyzeCodebase, formatCodebaseBrief } = await import("./preparation.js");
+        const brief = await analyzeCodebase(base);
+        const formatted = formatCodebaseBrief(brief).trim();
+        if (!formatted)
+            return null;
+        return [
+            "### Codebase Snapshot (current code reality)",
+            "Source: in-process bounded scan of the working tree.",
+            "",
+            "This snapshot describes what already exists. Treat it as authoritative for current code reality and do NOT re-survey the tree to rediscover it. Read a specific file only when a research question hinges on its exact contents.",
+            "",
+            formatted,
+        ].join("\n");
+    }
+    catch (err) {
+        logWarning("prompt", `buildResearchCodebaseSnapshot failed: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+/**
+ * Lightweight research resume block (ADR-029).
+ *
+ * When a prior attempt for this milestone left durable output — a partial
+ * RESEARCH artifact and/or a research phase anchor — inline it under a
+ * "continue, do not redo" banner so a re-dispatched research unit extends
+ * prior work instead of re-running every command from scratch (the
+ * restart-from-scratch pattern observed in the 789 run trace). No new state
+ * machine: the partial RESEARCH file and the existing phase anchor are the
+ * durable signals. Returns null when there is nothing to resume.
+ */
+async function buildResearchResumeBlock(base, mid) {
+    const researchPath = resolveMilestoneFile(base, mid, "RESEARCH");
+    const researchRel = relMilestoneFile(base, mid, "RESEARCH");
+    const partial = await inlineFileOptional(researchPath, researchRel, "Prior Partial Research");
+    const anchor = readPhaseAnchor(base, mid, "research-milestone");
+    if (!partial && !anchor)
+        return null;
+    const lines = [
+        "### Resume — Prior Partial Research (continue, do not redo)",
+        "",
+        "A previous research attempt for this milestone left the durable output below. **Build on it — do not restart from scratch.** Re-run a command only when its prior result is missing or stale, and persist progress incrementally with `gsd_summary_save` so any interruption keeps your findings.",
+        "",
+    ];
+    if (anchor)
+        lines.push(formatAnchorForPrompt(anchor), "");
+    if (partial)
+        lines.push(partial);
+    return lines.join("\n").trimEnd();
+}
 export async function buildResearchMilestonePrompt(mid, midTitle, base) {
     const contextTelemetry = [];
     // Keep research milestone prompts focused on the milestone brief and
@@ -1490,6 +1585,32 @@ export async function buildResearchMilestonePrompt(mid, midTitle, base) {
     const parts = [];
     if (composed.prepend)
         parts.push(composed.prepend);
+    // Resume grounding (ADR-029): if a prior attempt left partial research or a
+    // phase anchor, inline it prominently so a re-dispatched unit continues
+    // rather than re-running every command from scratch.
+    const resumeBlock = await buildResearchResumeBlock(base, mid);
+    if (resumeBlock) {
+        parts.push(resumeBlock);
+        trackPromptContext(contextTelemetry, "research-resume", "inline", resumeBlock);
+    }
+    else {
+        trackPromptContext(contextTelemetry, "research-resume", "skipped", null, "no prior partial research");
+    }
+    // Project-size signal (ADR-029): same classification plan-milestone gets, so
+    // research right-sizes effort on tiny projects instead of over-researching.
+    const classificationBlock = formatProjectClassificationForPlanning(classifyProject(base));
+    parts.push(classificationBlock);
+    trackPromptContext(contextTelemetry, "project-classification", "inline", classificationBlock);
+    // Codebase snapshot (ADR-029): bounded, in-process code-reality grounding so
+    // research does not open-endedly survey the tree (auto-mode ADR-028).
+    const codebaseSnapshot = await buildResearchCodebaseSnapshot(base);
+    if (codebaseSnapshot) {
+        parts.push(codebaseSnapshot);
+        trackPromptContext(contextTelemetry, "codebase-snapshot", "inline", codebaseSnapshot);
+    }
+    else {
+        trackPromptContext(contextTelemetry, "codebase-snapshot", "skipped", null, "disabled, empty, or scan failed");
+    }
     if (knowledgeInlineRM && composed.inline) {
         const idx = composed.inline.lastIndexOf("### Output Template:");
         if (idx > 0) {
@@ -1649,6 +1770,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"));
@@ -1936,6 +2064,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);
@@ -2077,7 +2213,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}\``,
@@ -2088,11 +2224,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);
@@ -2191,6 +2327,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,
@@ -2202,11 +2362,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({
@@ -2217,7 +2378,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",
         }),
     });
@@ -2328,6 +2489,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).
@@ -3190,6 +3359,17 @@ opts) {
 // gate-registry.ts so that prompt builders, dispatch rules, state
 // derivation, and tool handlers all consult the same source of truth.
 // See gate-registry.ts for the full ownership map.
+/**
+ * Adapt gate-registry guidance for section-close phases.
+ *
+ * Gate-registry text is shared with the gate-evaluate subagent, where
+ * "Return verdict ..." is literal. Section-close units write artifact sections
+ * instead, so translate that wording at render time without mutating the
+ * canonical guidance.
+ */
+function sectionModeGuidance(guidance) {
+    return guidance.replace(/Return verdict '([^']+)'/g, (_match, verdict) => verdict === "omitted" ? "Leave the section empty" : `Record a \`${verdict}\``);
+}
 /**
  * Render a "Gates to Close" block for turns like `complete-slice` and
  * `validate-milestone` that own gates which are closed as a side-effect
@@ -3208,12 +3388,14 @@ function renderGatesToCloseBlock(gates, opts) {
     lines.push("");
     lines.push("These quality gates are still pending for this unit. You MUST address every one before calling the closing tool — the handler closes the DB row based on whether the corresponding artifact section is present.");
     lines.push("");
+    lines.push("**Do NOT call `gsd_save_gate_result` (or any gate-result tool) for these gates** — that tool belongs to a different phase and the call will be blocked. You close each gate purely by writing its named section: a populated section records `pass`, an empty section records `omitted`, and the completion handler persists the verdict for you. Treat any \"return verdict\" wording in the guidance below as describing that section outcome, not as an instruction to call a tool.");
+    lines.push("");
     for (const def of applicable) {
         lines.push(`### ${def.id} — ${def.promptSection}`);
         lines.push("");
         lines.push(`**Question:** ${def.question}`);
         lines.push("");
-        lines.push(def.guidance);
+        lines.push(sectionModeGuidance(def.guidance));
         if (opts.allowOmit) {
             lines.push("");
             lines.push(`If this gate genuinely does not apply to this unit, leave the **${def.promptSection}** section empty and the handler will record it as \`omitted\`. Otherwise, fill the section with concrete evidence.`);