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

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

@@ -20,6 +20,8 @@ import { getUatBrowserToolSupportError, type UatType } from "./uat-policy.js";
 import {
   isDbAvailable,
   getMilestoneSlices,
+  getMilestoneSliceSummaries,
+  getClosedSliceIds,
   getPendingGatesForTurn,
   markPendingGatesOmittedForTurn,
   getMilestone,
@@ -47,7 +49,6 @@ import {
   buildTaskFileName,
   gsdProjectionRoot,
 } from "./paths.js";
-import { parseRoadmap } from "./parsers-legacy.js";
 import { validateArtifact } from "./schemas/validate.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, readdirSync } from "node:fs";
 import { logWarning, logError } from "./workflow-logger.js";
@@ -84,13 +85,18 @@ import { selectReactiveDispatchBatch } from "./uok/execution-graph.js";
 import { getMilestonePipelineVariant } from "./milestone-scope-classifier.js";
 import { EXECUTION_ENTRY_PHASES, hasFinalizedMilestoneContext } from "./uok/plan-v2.js";
 import { isAutoActive } from "./auto.js";
-import { markDepthVerified } from "./bootstrap/write-gate.js";
+// Host adapter explicitly: auto-dispatch runs in the extension host, and the
+// ambient write-gate exports env-sniff the adapter per call (they are reserved
+// for the workflow MCP child's dynamic-import surface).
+import { hostWriteGateAdapter } from "./bootstrap/write-gate.js";
 import { ensureWorkflowPreferencesCaptured } from "./planning-depth.js";
 import { MILESTONE_ID_RE } from "./milestone-ids.js";
 import {
   getWorkflowTransportSupportError,
   getRequiredWorkflowToolsForAutoUnit,
+  resolveWorkflowMcpProjectRoot,
 } from "./workflow-mcp.js";
+import { prepareBrowserDaemonForUat } from "./browser-daemon-auto-prep.js";
 import {
   PROJECT_RESEARCH_INFLIGHT_MARKER,
 } from "./project-research-policy.js";
@@ -490,27 +496,12 @@ function persistSliceAssessmentBackfill(
 }
 
 function backfillMissingAssessmentsFromSummaries(basePath: string, mid: string): void {
-  const completedSliceIds = new Set<string>();
-  if (isDbAvailable()) {
-    for (const slice of getMilestoneSlices(mid)) {
-      if (slice.status === "complete" || slice.status === "done") {
-        completedSliceIds.add(slice.id);
-      }
-    }
-  } else {
-    const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
-    if (!roadmapFile) return;
-    try {
-      const roadmap = parseRoadmap(readFileSync(roadmapFile, "utf-8"));
-      for (const slice of roadmap.slices) {
-        if (slice.done) completedSliceIds.add(slice.id);
-      }
-    } catch {
-      return;
-    }
-  }
-
-  for (const sliceId of completedSliceIds) {
+  // DB-authoritative (ADR-017): no markdown fallback. Without DB rows there
+  // is nothing to backfill.
+  if (!isDbAvailable()) return;
+  // Canonical closed vocabulary (complete/done/skipped/closed) — a skipped or
+  // closed slice with a SUMMARY gets the same assessment backfill treatment.
+  for (const sliceId of getClosedSliceIds(mid)) {
     const summaryPath = resolveSliceFile(basePath, mid, sliceId, "SUMMARY");
     if (!summaryPath || !existsSync(summaryPath)) continue;
 
@@ -696,7 +687,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
       // deadlock. Deep planning is still user-driven even inside auto-mode,
       // so it must wait for explicit approval instead of taking this bypass.
       if (shouldBypassMilestoneDepthGateInAuto(prefs)) {
-        markDepthVerified(mid, basePath);
+        hostWriteGateAdapter.markDepthVerified(mid, basePath);
       }
       return {
         action: "dispatch",
@@ -772,6 +763,16 @@ export const DISPATCH_RULES: DispatchRule[] = [
       if (browserToolError) {
         return { action: "stop" as const, reason: browserToolError, level: "warning" as const };
       }
+      const browserDaemonError = prepareBrowserDaemonForUat({
+        uatType,
+        sessionProvider,
+        sessionAuthMode,
+        sessionBaseUrl,
+        projectRoot: resolveWorkflowMcpProjectRoot(basePath),
+      });
+      if (browserDaemonError) {
+        return { action: "stop" as const, reason: browserDaemonError, level: "warning" as const };
+      }
 
       // Cap run-uat dispatch attempts to prevent infinite replay (#3624).
       // Check before incrementing so an exhausted counter cannot create a
@@ -808,23 +809,10 @@ export const DISPATCH_RULES: DispatchRule[] = [
       // Only applies when UAT dispatch is enabled
       if (!prefs?.uat_dispatch) return null;
 
-      // DB-first: prefer closed slices from DB; fall back to ROADMAP on disk.
-      let closedSliceIds: string[];
-      if (isDbAvailable()) {
-        closedSliceIds = getMilestoneSlices(mid)
-          .filter(s => isClosedStatus(s.status))
-          .map(s => s.id);
-      } else {
-        // Filesystem fallback for degraded / unmigrated projects.
-        // `slice.done` in the parsed ROADMAP is the disk-level closed signal.
-        const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
-        const roadmapContent = roadmapFile ? await loadFile(roadmapFile) : null;
-        if (!roadmapContent) return null;
-        const roadmap = parseRoadmap(roadmapContent);
-        closedSliceIds = roadmap.slices.filter(s => s.done).map(s => s.id);
-      }
-
-      for (const sliceId of closedSliceIds) {
+      // DB-authoritative (ADR-017): closed slices come from the DB only; the
+      // ROADMAP projection is never parsed for gate decisions.
+      if (!isDbAvailable()) return null;
+      for (const sliceId of getClosedSliceIds(mid)) {
         const result = await readUatGateVerdict(basePath, mid, sliceId);
         if (!result) continue;
         const { verdict, uatType } = result;
@@ -879,7 +867,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
       // H6 fix (#4973): keep the non-deep auto-mode bypass, but do not
       // pre-verify deep planning's user-facing milestone approval gate.
       if (shouldBypassMilestoneDepthGateInAuto(prefs)) {
-        markDepthVerified(mid, basePath);
+        hostWriteGateAdapter.markDepthVerified(mid, basePath);
       }
       return {
         action: "dispatch",
@@ -1050,7 +1038,7 @@ export const DISPATCH_RULES: DispatchRule[] = [
       // H6 fix (#4973): keep the non-deep auto-mode bypass, but do not
       // pre-verify deep planning's user-facing milestone approval gate.
       if (shouldBypassMilestoneDepthGateInAuto(prefs)) {
-        markDepthVerified(mid, basePath);
+        hostWriteGateAdapter.markDepthVerified(mid, basePath);
       }
       return {
         action: "dispatch",
@@ -1128,13 +1116,11 @@ export const DISPATCH_RULES: DispatchRule[] = [
       // behavior.
       if (await getMilestonePipelineVariant(mid) === "trivial") return null;
 
-      // Load roadmap to find all slices
-      const roadmapFile =
-        resolveExistingExpectedArtifact("plan-milestone", mid, basePath) ??
-        resolveMilestoneFile(basePath, mid, "ROADMAP");
-      const roadmapContent = roadmapFile ? await loadFile(roadmapFile) : null;
-      if (!roadmapContent) return null;
-      const roadmap = parseRoadmap(roadmapContent);
+      // DB-authoritative slice list (ADR-017): the ROADMAP projection is
+      // never parsed for dispatch decisions. No DB / no rows → skip this rule.
+      if (!isDbAvailable()) return null;
+      const dbSlices = getMilestoneSliceSummaries(mid);
+      if (dbSlices.length === 0) return null;
 
       // Find slices that need research (no RESEARCH file, dependencies done)
       const milestoneResearchFile =
@@ -1142,14 +1128,14 @@ export const DISPATCH_RULES: DispatchRule[] = [
         resolveMilestoneFile(basePath, mid, "RESEARCH");
       const researchReadySlices: Array<{ id: string; title: string }> = [];
 
-      for (const slice of roadmap.slices) {
+      for (const slice of dbSlices) {
         if (slice.done) continue;
         // Skip S01 when milestone research exists
         if (milestoneResearchFile && slice.id === "S01") continue;
         // Skip if already has research
         if (resolveExistingExpectedArtifact("research-slice", `${mid}/${slice.id}`, basePath)) continue;
         // Skip if dependencies aren't done (check for SUMMARY files)
-        const depsComplete = (slice.depends ?? []).every((depId) =>
+        const depsComplete = slice.depends.every((depId) =>
           !!resolveExistingExpectedArtifact("complete-slice", `${mid}/${depId}`, basePath),
         );
         if (!depsComplete) continue;

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

@@ -1041,16 +1041,36 @@ export function resolveModelId<T extends { id: string; provider: string }>(
     if (providerMatch) return providerMatch;
   }
 
-  // Prefer "anthropic" as the canonical provider for Anthropic models.
-  // Transport-specific tiebreaker (ADR-012): intentionally keys on provider,
-  // not api — we want the plain Anthropic transport when multiple are available.
-  const anthropicMatch = candidates.find(m => m.provider === "anthropic");
-  if (anthropicMatch) return anthropicMatch;
+  // Subscription/OAuth routes beat pay-per-token API when the same model ID
+  // exists on multiple providers. Order matters — first match wins.
+  for (const provider of BARE_ID_SUBSCRIPTION_PROVIDER_PRECEDENCE) {
+    const match = candidates.find(m => m.provider === provider);
+    if (match) return match;
+  }
 
   // Fall back to first non-extension candidate, or any candidate
   return candidates.find(m => !EXTENSION_PROVIDERS.has(m.provider)) ?? candidates[0];
 }
 
+/**
+ * When a bare model ID exists on multiple providers, prefer subscription/OAuth
+ * routes over pay-per-token API keys. Matches PROVIDER_ROUTES in doctor-providers
+ * but applies when *both* sides are authenticated.
+ *
+ * Order rationale:
+ * - openai-codex before github-copilot: ChatGPT-native for shared GPT IDs
+ * - google-gemini-cli before github-copilot: first-party Gemini CLI
+ * - anthropic before github-copilot: first-party Claude API/OAuth over Copilot
+ * - github-copilot before openai/google: Copilot OAuth over platform API keys
+ */
+export const BARE_ID_SUBSCRIPTION_PROVIDER_PRECEDENCE = [
+  "openai-codex",
+  "google-gemini-cli",
+  "anthropic",
+  "github-copilot",
+  "google-antigravity",
+] as const;
+
 /**
  * Flat-rate providers charge the same per request regardless of model.
  * Dynamic routing provides no cost benefit — it only degrades quality (#3453).

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

@@ -18,7 +18,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,
@@ -51,8 +51,7 @@ import { createWorkspace, scopeMilestone } from "./workspace.js";
 import { normalizeWorktreePathForCompare } from "./worktree-root.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 { renderPlanCheckboxes, renderRoadmapFromDb, roadmapRenderMarksSliceDone } from "./markdown-renderer.js";
 import { consumeSignal } from "./session-status-io.js";
 import {
   checkPostUnitHooks,
@@ -88,7 +87,7 @@ 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,
@@ -96,6 +95,7 @@ import {
 } 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";
@@ -901,7 +901,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: string): "project" | "requirements" | null {
   if (unitType === "discuss-project") return "project";
@@ -990,11 +990,13 @@ async function repairCompleteSliceRoadmapProjection(
     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;
       }
     } catch (err) {
@@ -2022,7 +2024,18 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
           "error",
         );
       } else if (!triggerArtifactVerified) {
-        if (s.lastToolInvocationError) {
+        if (s.lastToolInvocationError && isToolUnavailableError(s.lastToolInvocationError)) {
+          // Tool-unavailable is the one transient invocation error: the
+          // workflow MCP server registers its surface asynchronously, so a
+          // Unit's first call can race the registration. Fall through to the
+          // bounded verification retry instead of pausing.
+          debugLog("postUnit", { phase: "tool-unavailable-retry", unitType: s.currentUnit.type, unitId: s.currentUnit.id, error: s.lastToolInvocationError });
+          ctx.ui.notify(
+            `Tool unavailable for ${s.currentUnit.type}: ${s.lastToolInvocationError}. The tool surface may still be registering — retrying.`,
+            "warning",
+          );
+          s.lastToolInvocationError = null;
+        } 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.`
@@ -2148,6 +2161,7 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
               }
             }
             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.`,
@@ -2157,6 +2171,7 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
             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}).`,
@@ -2180,6 +2195,8 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
         }
         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);

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

@@ -40,6 +40,7 @@ import {
   composeContextModeInstructions,
   composeContractedUnitContext,
   composeInlinedContext,
+  composeToolSurfaceInstructions,
   composeUnitContext,
   type ArtifactResolver,
   type ComposedUnitContextBlock,
@@ -57,7 +58,11 @@ import { debugLog } from "./debug-logger.js";
 import { buildSkillActivationBlock, buildSkillDiscoveryVars } from "./skill-activation.js";
 import { findMilestoneIds } from "./milestone-ids.js";
 import { buildRunUatPresentationForType, RUN_UAT_TOOL_PRESENTATION_PLAN_ID } from "./tool-presentation-plan.js";
-import { resolveEffectiveUatType, shouldDispatchUatForContent, type UatType } from "./uat-policy.js";
+import {
+  classifyUatContentForRun,
+  shouldDispatchUatForContent,
+  type UatType,
+} from "./uat-policy.js";
 import { buildWebAppUatGuidanceBlock } from "./web-app-uat.js";
 
 export { buildSkillActivationBlock, buildSkillDiscoveryVars };
@@ -292,10 +297,12 @@ function prependContextModeToBlock(
   block: string,
   renderMode: ContextModeRenderMode = "standalone",
 ): string {
+  const toolSurface = composeToolSurfaceInstructions(unitType, { renderMode });
   const contextMode = renderContextModeBlockForPrompt(unitType, base, renderMode);
-  if (!contextMode) return block;
-  if (!block.trim()) return contextMode;
-  return `${contextMode}\n\n${block}`;
+  const guidance = [toolSurface, contextMode].filter(Boolean).join("\n\n");
+  if (!guidance) return block;
+  if (!block.trim()) return guidance;
+  return `${guidance}\n\n${block}`;
 }
 
 function requireUnitPromptContextContract(unitType: string): UnitPromptContextContract {
@@ -969,7 +976,7 @@ export async function inlineDecisionsFromDb(
 
 /**
  * Inline requirements with optional milestone and slice scoping from the DB.
- * Falls back to filesystem via inlineGsdRootFile when DB unavailable or empty.
+ * Falls back to filesystem via inlineGsdRootFile only when DB is unavailable.
  */
 export async function inlineRequirementsFromDb(
   base: string, milestoneId?: string, sliceId?: string, level?: InlineLevel,
@@ -979,14 +986,28 @@ export async function inlineRequirementsFromDb(
     const { isDbAvailable } = await import("./gsd-db.js");
     if (isDbAvailable()) {
       const { queryRequirements, formatRequirementsForPrompt } = await import("./context-store.js");
-      const requirements = queryRequirements({ milestoneId, sliceId });
+      let requirements = queryRequirements({ milestoneId, sliceId });
+      let broadenedScope = false;
+      if (requirements.length === 0 && sliceId) {
+        requirements = queryRequirements({ milestoneId });
+        broadenedScope = true;
+      }
+      if (requirements.length === 0 && milestoneId) {
+        requirements = queryRequirements({ status: "active" });
+        broadenedScope = true;
+      }
       if (requirements.length > 0) {
-        // Use compact format for non-full levels to save ~40% tokens
-        const formatted = inlineLevel !== "full"
+        // Use compact format for non-full levels, milestone-scoped calls, and
+        // any cascade stage that broadened past the originally requested scope —
+        // a slice-scoped "full" call that fell through to the project-wide
+        // active fallback must not format those rows as full requirements.
+        const useCompact = inlineLevel !== "full" || !sliceId || broadenedScope;
+        const formatted = useCompact
           ? formatRequirementsCompact(requirements)
           : formatRequirementsForPrompt(requirements);
         return `### Requirements\nSource: \`.gsd/REQUIREMENTS.md\`\n\n${formatted}`;
       }
+      return null;
     }
   } catch (err) {
     logWarning("prompt", `inlineRequirementsFromDb failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -1442,6 +1463,40 @@ export async function checkNeedsReassessment(
  * - No UAT file exists for the slice
  * - UAT result file already exists (idempotent — already ran)
  */
+/**
+ * Resolve the effective UAT mode for the dispatch gate the same way
+ * `buildRunUatPrompt` does: classify the UAT body with the slice's SUMMARY as
+ * supplemental context, so a `browser-executable` UAT whose slice references a
+ * self-contained harness (`npm run test:uat`, `search-uat.mjs`, `npx
+ * playwright test`) is promoted to `runtime-executable` for the gate too.
+ *
+ * Without this, `checkNeedsRunUat` returns `browser-executable` while the
+ * prompt instructs runtime-only execution, causing the dispatch gate to
+ * require browser tools / warm up the browser daemon (or stop dispatch when
+ * browser MCP is unavailable) for UAT runs that never touch the browser. See
+ * cursor[bot] review on PR #696 for the M007/S01 regression.
+ */
+async function resolveRunUatEffectiveType(
+  base: string,
+  mid: string,
+  sliceId: string,
+  uatContent: string,
+): Promise<UatType> {
+  let summaryContent = "";
+  try {
+    const summaryPath = resolveSliceFile(base, mid, sliceId, "SUMMARY");
+    if (summaryPath) {
+      summaryContent = (await loadFile(summaryPath)) ?? "";
+    }
+  } catch (err) {
+    logWarning(
+      "prompt",
+      `resolveRunUatEffectiveType SUMMARY load failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  return classifyUatContentForRun(uatContent, summaryContent).effectiveType;
+}
+
 export async function checkNeedsRunUat(
   base: string, mid: string, state: GSDState, prefs: GSDPreferences | undefined,
 ): Promise<{ sliceId: string; uatType: UatType } | null> {
@@ -1470,7 +1525,8 @@ export async function checkNeedsRunUat(
             if (assessmentContent && hasVerdict(assessmentContent)) continue;
           }
           if (!shouldDispatchUatForContent(uatContent, prefs)) continue;
-          return { sliceId: sid, uatType: resolveEffectiveUatType(uatContent) };
+          const uatType = await resolveRunUatEffectiveType(base, mid, sid, uatContent);
+          return { sliceId: sid, uatType };
         }
         return null;
       }
@@ -1503,7 +1559,8 @@ export async function checkNeedsRunUat(
       if (assessmentContentFb && hasVerdict(assessmentContentFb)) continue;
     }
     if (!shouldDispatchUatForContent(uatContentFb, prefs)) continue;
-    return { sliceId: uatSid, uatType: resolveEffectiveUatType(uatContentFb) };
+    const uatType = await resolveRunUatEffectiveType(base, mid, uatSid, uatContentFb);
+    return { sliceId: uatSid, uatType };
   }
   return null;
 }
@@ -2470,6 +2527,9 @@ export async function buildPlanSlicePrompt(
       `Either (a) add an earlier task that creates X on disk before the task that needs it, ` +
       `or (b) if this task IS the one that creates X, move X from inputs to expected_output. ` +
       `Do NOT put X in a task's expected_output if that task only reads or verifies X — only tasks that actually write X to disk should list it in expected_output.\n` +
+      `- **"[file] X: ... GSD planning artifacts are projections preloaded as context / written by workflow tools"**: ` +
+      `Remove X from the task's inputs, files, and expectedOutput entirely. Planning artifacts (anything under .gsd/, .planning/, or .audits/, or names like M001-CONTEXT.md / S01-PLAN.md) are preloaded as context and written by workflow tools — ` +
+      `do NOT add a task that creates X and do NOT move X to expectedOutput.\n` +
       `- **"[file] X: Task T_early reads X but it's created by task T_late (sequence violation)"**: ` +
       `Either (a) reorder tasks so T_late (the creator) runs before T_early (the reader), ` +
       `or (b) if T_late doesn't actually create X (it only reads/tests it), remove X from T_late's expected_output entirely.\n` +
@@ -3554,15 +3614,30 @@ export async function buildRunUatPrompt(
     null,
     cappedInlinedContext.length < rawInlinedContext.length ? `dropped ${rawInlinedContext.length - cappedInlinedContext.length} chars` : "within budget",
   );
+  const uatPolicy = classifyUatContentForRun(uatContent, cappedInlinedContext);
+  const uatType = uatPolicy.effectiveType;
+  const runtimeHarnessOverride = uatPolicy.declaredType === "browser-executable" && uatType === "runtime-executable"
+    ? [
+      "## Runtime harness override",
+      "",
+      "This UAT declares `browser-executable` but the slice references a self-contained verification command (`npm run test:uat`, `search-uat.mjs`, or similar).",
+      "Run **only** that command via `gsd_uat_exec` with `uat-runtime-check` intent.",
+      "Do **not** call `uat-service-start`, do **not** run `npm run start`, `npm run test:server`, or any separate server command.",
+      "Do **not** use `browser_navigate` or other `browser_*` tools — the harness already exercises the browser.",
+      "When the harness exits 0, save **PASS** with `uatType: \"runtime-executable\"` (the effective mode above, not the UAT file header) and **runtime** check modes only.",
+      "",
+    ].join("\n")
+    : "";
   const inlinedContext = prependContextModeToBlock(
     "run-uat",
     base,
-    cappedInlinedContext,
+    runtimeHarnessOverride
+      ? `${runtimeHarnessOverride}\n${cappedInlinedContext}`
+      : cappedInlinedContext,
   );
   emitPromptContextTelemetry("run-uat", contextTelemetry, inlinedContext);
 
   const uatResultPath = join(base, relSliceFile(base, mid, sliceId, "ASSESSMENT"));
-  const uatType = resolveEffectiveUatType(uatContent);
   const canonicalPresentation = JSON.stringify(buildRunUatPresentationForType(uatType), null, 2);
 
   return loadPrompt("run-uat", {
@@ -3847,18 +3922,22 @@ export async function buildReactiveExecutePrompt(
   const inlinedTemplates = inlineTemplate("task-summary", "Task Summary");
   trackPromptContext(contextTelemetry, "templates", "inline", inlinedTemplates);
 
-  const prompt = loadPrompt("reactive-execute", {
-    workingDirectory: base,
-    milestoneId: mid,
-    milestoneTitle: midTitle,
-    sliceId: sid,
-    sliceTitle: sTitle,
-    graphContext: prependContextModeToBlock("reactive-execute", base, graphContext),
-    readyTaskCount: String(readyTaskIds.length),
-    readyTaskList: readyTaskListLines.join("\n"),
-    subagentPrompts: subagentSections.join("\n\n---\n\n"),
-    inlinedTemplates,
-  });
+  const prompt = prependContextModeToBlock(
+    "reactive-execute",
+    base,
+    loadPrompt("reactive-execute", {
+      workingDirectory: base,
+      milestoneId: mid,
+      milestoneTitle: midTitle,
+      sliceId: sid,
+      sliceTitle: sTitle,
+      graphContext,
+      readyTaskCount: String(readyTaskIds.length),
+      readyTaskList: readyTaskListLines.join("\n"),
+      subagentPrompts: subagentSections.join("\n\n---\n\n"),
+      inlinedTemplates,
+    }),
+  );
   emitPromptContextTelemetry("reactive-execute", contextTelemetry, prompt);
   return prompt;
 }
@@ -4037,17 +4116,21 @@ export async function buildGateEvaluatePrompt(
     ].join("\n"));
   }
 
-  return loadPrompt("gate-evaluate", {
-    workingDirectory: base,
-    milestoneId: mid,
-    milestoneTitle: midTitle,
-    sliceId: sid,
-    sliceTitle: sTitle,
-    slicePlanContent: prependContextModeToBlock("gate-evaluate", base, planContent),
-    gateCount: String(pending.length),
-    gateList: gateListLines.join("\n"),
-    subagentPrompts: subagentSections.join("\n\n---\n\n"),
-  });
+  return prependContextModeToBlock(
+    "gate-evaluate",
+    base,
+    loadPrompt("gate-evaluate", {
+      workingDirectory: base,
+      milestoneId: mid,
+      milestoneTitle: midTitle,
+      sliceId: sid,
+      sliceTitle: sTitle,
+      slicePlanContent: planContent,
+      gateCount: String(pending.length),
+      gateList: gateListLines.join("\n"),
+      subagentPrompts: subagentSections.join("\n\n---\n\n"),
+    }),
+  );
 }
 
 export async function buildRewriteDocsPrompt(