@opengsd/gsd-pi 1.1.1-dev.b2556262 → 1.2.0-dev.0b870afa

package/src/resources/extensions/gsd/tools/validate-milestone.ts

@@ -19,11 +19,11 @@ import {
   insertAssessment,
   getMilestoneSlices,
   getMilestone,
-  getArtifact,
 } from "../gsd-db.js";
-import { gsdProjectionRoot, clearPathCache, resolveSliceFile } from "../paths.js";
+import { gsdProjectionRoot, clearPathCache } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
-import { saveFile, clearParseCache, loadFile } from "../files.js";
+import { resolveWorktreeProjectRoot } from "../worktree-root.js";
+import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { VALIDATION_VERDICTS, isValidMilestoneVerdict } from "../verdict-parser.js";
 import { insertMilestoneValidationGates } from "../milestone-validation-gates.js";
@@ -31,7 +31,10 @@ import { logWarning } from "../workflow-logger.js";
 import { UokGateRunner } from "../uok/gate-runner.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { resolveUokFlags } from "../uok/flags.js";
-import { compactTextParts, hasBrowserEvidenceText, hasBrowserRequiredText } from "../browser-evidence.js";
+import {
+  applyBrowserEvidenceGate,
+  browserEvidenceGateRequiresAttention,
+} from "../milestone-validation-evidence.js";
 
 export interface ValidateMilestoneParams {
   milestoneId: string;
@@ -78,86 +81,6 @@ function getRequiredVerificationClasses(milestoneId: string): string[] {
   return required;
 }
 
-function hasRuntimeExecutableUatEvidenceText(text: string): boolean {
-  if (!/\buatType:\s*runtime-executable\b/i.test(text)) return false;
-  if (!/\bverdict:\s*PASS\b/i.test(text)) return false;
-  return /^\|\s*[^|\n]+\s*\|\s*runtime\s*\|\s*PASS\s*\|[^|\n]*\bgsd_uat_exec\b/mi.test(text);
-}
-
-async function browserEvidenceGateRequiresAttention(
-  params: ValidateMilestoneParams,
-  basePath: string,
-): Promise<boolean> {
-  if (params.verdict !== "pass") return false;
-
-  const milestone = getMilestone(params.milestoneId);
-  const slices = getMilestoneSlices(params.milestoneId);
-  const requirementText = compactTextParts([
-    milestone?.vision,
-    milestone?.success_criteria,
-    milestone?.verification_uat,
-    params.successCriteriaChecklist,
-    params.verificationClasses,
-    ...slices.flatMap((slice) => [
-      slice.demo,
-      slice.goal,
-      slice.success_criteria,
-    ]),
-  ]);
-  if (!hasBrowserRequiredText(requirementText)) return false;
-
-  // Collect per-slice evidence so the runtime bypass is checked independently
-  // for each slice. Concatenating all slices before checking would allow runtime
-  // evidence from one slice to cover another slice's browser requirements.
-  const sliceEvidencePairs: Array<{ sliceRequirementText: string; evidenceText: string }> = [];
-  for (const slice of slices) {
-    const chunks: string[] = [];
-    const artifactPath = `milestones/${params.milestoneId}/slices/${slice.id}/${slice.id}-ASSESSMENT.md`;
-    const artifact = getArtifact(artifactPath);
-    if (artifact?.full_content) chunks.push(artifact.full_content);
-    const assessmentPath = resolveSliceFile(basePath, params.milestoneId, slice.id, "ASSESSMENT");
-    const assessmentContent = assessmentPath ? await loadFile(assessmentPath) : null;
-    if (assessmentContent) chunks.push(assessmentContent);
-    sliceEvidencePairs.push({
-      sliceRequirementText: compactTextParts([slice.demo, slice.goal, slice.success_criteria]),
-      evidenceText: chunks.join("\n\n"),
-    });
-  }
-  const persistedEvidence = sliceEvidencePairs.map((s) => s.evidenceText).join("\n\n");
-
-  // Runtime bypass: each slice whose own requirement text has browser-observable
-  // criteria must have its own runtime-executable UAT evidence. When no individual
-  // slice has slice-level browser requirements (e.g., they come from milestone-level
-  // fields only), fall back to checking whether any slice has runtime evidence.
-  const browserRequiringSlices = sliceEvidencePairs.filter((s) =>
-    hasBrowserRequiredText(s.sliceRequirementText),
-  );
-  const runtimeBypasses =
-    browserRequiringSlices.length > 0
-      ? browserRequiringSlices.every((s) => hasRuntimeExecutableUatEvidenceText(s.evidenceText))
-      : sliceEvidencePairs.some((s) => hasRuntimeExecutableUatEvidenceText(s.evidenceText));
-  if (runtimeBypasses) return false;
-
-  const validationEvidence = compactTextParts([
-    params.successCriteriaChecklist,
-    params.verificationClasses,
-    params.verdictRationale,
-    params.remediationPlan,
-  ]);
-  return !hasBrowserEvidenceText(`${persistedEvidence}\n\n${validationEvidence}`);
-}
-
-function applyBrowserEvidenceGate(params: ValidateMilestoneParams): ValidateMilestoneParams {
-  const note = "Browser evidence gate: Browser-observable acceptance criteria were detected, but no persisted ASSESSMENT or validation evidence recorded browser actions with assertions. Downgraded from pass to needs-attention.";
-  return {
-    ...params,
-    verdict: "needs-attention",
-    verdictRationale: params.verdictRationale.trim()
-      ? `${params.verdictRationale.trim()}\n\n${note}`
-      : note,
-  };
-}
-
 function renderValidationMarkdown(params: ValidateMilestoneParams): string {
   let md = `---
 verdict: ${params.verdict}
@@ -279,6 +202,24 @@ export async function handleValidateMilestone(
   let projectionStale = false;
   try {
     await saveFile(validationPath, validationMd);
+    const projectRoot = resolveWorktreeProjectRoot(basePath);
+    if (projectRoot !== artifactBasePath) {
+      const projectValidationPath = join(
+        gsdProjectionRoot(projectRoot),
+        "milestones",
+        effectiveParams.milestoneId,
+        `${effectiveParams.milestoneId}-VALIDATION.md`,
+      );
+      try {
+        await saveFile(projectValidationPath, validationMd);
+      } catch (mirrorErr) {
+        logWarning(
+          "projection",
+          `validate_milestone project-root VALIDATION mirror failed for ${effectiveParams.milestoneId}`,
+          { error: (mirrorErr as Error).message },
+        );
+      }
+    }
   } catch (renderErr) {
     projectionStale = true;
     logWarning("projection", `validate_milestone projection write failed for ${effectiveParams.milestoneId}; DB validation remains committed`, {

package/src/resources/extensions/gsd/tools/workflow-tool-executors.ts

@@ -6,10 +6,11 @@ import { sanitizeCompleteMilestoneParams } from "../bootstrap/sanitize-complete-
 import { loadWriteGateSnapshot, shouldBlockContextArtifactSaveInSnapshot, shouldBlockRootArtifactSaveInSnapshot } from "../bootstrap/write-gate.js";
 import {
   getActiveRequirements,
-  insertMilestone,
+  getAllMilestones,
   getMilestone,
   getSliceStatusSummary,
   getSliceTaskCounts,
+  insertMilestone,
   insertAssessment,
   insertGateRun,
   readTransaction,
@@ -18,9 +19,10 @@ import {
 } from "../gsd-db.js";
 import { GATE_REGISTRY } from "../gate-registry.js";
 import { generateRequirementsMd, saveArtifactToDb } from "../db-writer.js";
-import { clearPathCache, relSliceFile, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
+import { clearPathCache, normalizeRealPath, relSliceFile, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { unlinkSync } from "node:fs";
+import { hostname } from "node:os";
 import { join } from "node:path";
 import type { CompleteMilestoneParams } from "./complete-milestone.js";
 import { handleCompleteMilestone } from "./complete-milestone.js";
@@ -47,13 +49,21 @@ import { logError, logWarning } from "../workflow-logger.js";
 import { invalidateStateCache } from "../state.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { parseProject } from "../schemas/parsers.js";
-import { getAutoRuntimeSnapshot } from "../auto-runtime-state.js";
+import { autoSession, getAutoRuntimeSnapshot, isAutoActive } from "../auto-runtime-state.js";
 import { renderPlanFromDb } from "../markdown-renderer.js";
 import {
   prepareUatRun,
   saveUatAttemptArtifact,
   type UatResultSaveParams,
 } from "../uat-run.js";
+import { registerAutoWorker, markWorkerStopping, getAutoWorker } from "../db/auto-workers.js";
+import {
+  claimMilestoneLease,
+  releaseMilestoneLease,
+  getMilestoneLease,
+  refreshMilestoneLease,
+  milestoneLeaseTtlSeconds,
+} from "../db/milestone-leases.js";
 export type {
   UatCheckResultInput,
   UatEvidenceRef,
@@ -104,6 +114,24 @@ function blockIfWrongAutoUnit(requiredUnitType: string, operation: string): Tool
   };
 }
 
+function milestoneLeaseConflictResult(
+  milestoneId: string,
+  byWorker: string,
+  expiresAt: string,
+): ToolExecutionResult {
+  return {
+    content: [{ type: "text", text: `Milestone ${milestoneId} is currently leased by ${byWorker}. Retry after ${expiresAt}.` }],
+    details: {
+      operation: "plan_milestone",
+      error: "milestone_lease_conflict",
+      milestoneId,
+      byWorker,
+      expiresAt,
+    },
+    isError: true,
+  };
+}
+
 export interface SummarySaveParams {
   milestone_id?: string;
   slice_id?: string;
@@ -126,6 +154,111 @@ function registerProjectMilestoneSequence(content: string): string[] {
   return registered;
 }
 
+/** Minimal shape of a DB milestone row needed to re-render the sequence section. */
+interface MilestoneSeqRow {
+  id: string;
+  title: string;
+  status: string;
+  vision: string;
+}
+
+/**
+ * Best-effort recovery of the human one-liner for each milestone id from a
+ * (possibly malformed) Milestone Sequence body. Deliberately lenient: tolerates
+ * any separator the canonical MILESTONE_LINE_RE rejects (en-dash, " : ", a
+ * missing checkbox, etc.) so a model formatting slip does not discard the prose.
+ */
+function recoverMilestoneTails(sequenceBody: string): Map<string, string> {
+  const out = new Map<string, string>();
+  const lenient = /^\s*(?:-\s*)?(?:\[[ xX]\]\s*)?(M\d{3})\b\s*[:.\-–—]*\s*(.*)$/;
+  for (const rawLine of sequenceBody.split("\n")) {
+    const m = rawLine.match(lenient);
+    if (m) out.set(m[1], m[2].trim());
+  }
+  return out;
+}
+
+function firstSentence(text: string): string {
+  const trimmed = text.trim();
+  if (!trimmed) return "";
+  const idx = trimmed.search(/[.!?](\s|$)/);
+  return (idx >= 0 ? trimmed.slice(0, idx + 1) : trimmed).trim();
+}
+
+/** Render one canonical, parseable milestone line for the given DB row. */
+function renderMilestoneLine(m: MilestoneSeqRow, recoveredTail: string): string {
+  const done = m.status === "complete";
+  let oneLiner = recoveredTail;
+  // The recovered tail often still carries the title (e.g. "Foo — bar" or
+  // "Foo : bar"). Strip a leading repetition of the title, then any separator.
+  if (oneLiner.toLowerCase().startsWith(m.title.toLowerCase())) {
+    oneLiner = oneLiner.slice(m.title.length).replace(/^\s*[:.\-–—]+\s*/, "").trim();
+  } else {
+    const sep = oneLiner.match(/\s+(?:—|–|--|-|:)\s+/);
+    if (sep && sep.index !== undefined) oneLiner = oneLiner.slice(sep.index + sep[0].length).trim();
+  }
+  // MILESTONE_LINE_RE requires non-empty prose after the separator.
+  if (!oneLiner) oneLiner = firstSentence(m.vision) || (done ? "Completed." : "Planned.");
+  return `- [${done ? "x" : " "}] ${m.id}: ${m.title} — ${oneLiner}`;
+}
+
+/**
+ * Rebuild the "## Milestone Sequence" section from authoritative DB rows when a
+ * model-authored PROJECT.md projection parsed to zero milestone lines but the DB
+ * already holds milestones. The DB is the source of truth (markdown is a
+ * projection), so this repairs the projection rather than failing the save.
+ * Preserves a leading HTML comment in the section and recovers one-liners
+ * best-effort. The returned content parses cleanly under MILESTONE_LINE_RE.
+ */
+function rebuildMilestoneSequenceSection(content: string, milestones: MilestoneSeqRow[]): string {
+  const lines = content.split("\n");
+  const headerIdx = lines.findIndex(l => /^##\s+Milestone Sequence\s*$/.test(l));
+
+  const canonicalLines = (() => {
+    // Recover tails from the existing (malformed) body when the section exists.
+    let body = "";
+    if (headerIdx !== -1) {
+      let end = headerIdx + 1;
+      while (end < lines.length && !/^##\s+/.test(lines[end])) end++;
+      body = lines.slice(headerIdx + 1, end).join("\n");
+    }
+    const tails = recoverMilestoneTails(body);
+    return milestones.map(m => renderMilestoneLine(m, tails.get(m.id) ?? ""));
+  })();
+
+  if (headerIdx === -1) {
+    // No section at all — append a fresh, canonical one.
+    const sep = content.endsWith("\n") ? "" : "\n";
+    return `${content}${sep}\n## Milestone Sequence\n\n${canonicalLines.join("\n")}\n`;
+  }
+
+  let bodyEnd = headerIdx + 1;
+  while (bodyEnd < lines.length && !/^##\s+/.test(lines[bodyEnd])) bodyEnd++;
+  const existingBody = lines.slice(headerIdx + 1, bodyEnd);
+
+  // Preserve a contiguous leading HTML comment block (the "Check off…" hint).
+  let i = 0;
+  while (i < existingBody.length && existingBody[i].trim() === "") i++;
+  const preserved: string[] = [];
+  if (i < existingBody.length && existingBody[i].trim().startsWith("<!--")) {
+    while (i < existingBody.length) {
+      preserved.push(existingBody[i]);
+      const closed = existingBody[i].includes("-->");
+      i++;
+      if (closed) break;
+    }
+  }
+
+  return [
+    ...lines.slice(0, headerIdx + 1),
+    "",
+    ...(preserved.length ? [...preserved, ""] : []),
+    ...canonicalLines,
+    "",
+    ...lines.slice(bodyEnd),
+  ].join("\n");
+}
+
 async function mirrorArtifactToActiveWorktreeProjection(
   basePath: string,
   relativePath: string,
@@ -260,6 +393,7 @@ export async function executeSummarySave(
     await mirrorArtifactToActiveWorktreeProjection(basePath, relativePath, contentToSave);
 
     let registeredMilestones: string[] = [];
+    let milestoneSequenceSelfHealed = false;
     if (params.artifact_type === "PROJECT") {
       try {
         registeredMilestones = registerProjectMilestoneSequence(contentToSave);
@@ -294,29 +428,83 @@ export async function executeSummarySave(
         };
       }
       if (registeredMilestones.length === 0) {
-        logError("tool", `gsd_summary_save: PROJECT.md saved to ${relativePath} but parsed zero milestones — registration produced no DB rows`, {
+        const existingMilestones = getAllMilestones();
+        if (existingMilestones.length === 0) {
+          // Genuine first-save failure: no milestones parsed AND none in the DB.
+          // /gsd really would report "No Active Milestone" — hard-fail so the
+          // caller rewrites the sequence before proceeding.
+          logError("tool", `gsd_summary_save: PROJECT.md saved to ${relativePath} but parsed zero milestones — registration produced no DB rows`, {
+            tool: "gsd_summary_save",
+          });
+          // PROJECT.md was persisted; invalidate so subsequent reads see the new
+          // artifacts row even though no milestones registered.
+          invalidateStateCache();
+          return {
+            content: [{
+              type: "text",
+              text:
+                `Error: PROJECT.md was saved to ${relativePath} but contains zero parseable milestone lines, ` +
+                `so no milestones were registered in the DB. /gsd will report "No Active Milestone". ` +
+                `Rewrite PROJECT.md so the "Milestone Sequence" section uses canonical lines: ` +
+                `\`- [ ] M001: <Title> — <One-liner>\` (em-dash, double-dash \`--\`, or single-dash \`-\` separator), then re-call gsd_summary_save(PROJECT).`,
+            }],
+            details: {
+              operation: "save_summary",
+              path: relativePath,
+              artifact_type: params.artifact_type,
+              error: "milestone_registration_empty_parse",
+            },
+            isError: true,
+          };
+        }
+
+        // Existing DB rows mean this is projection drift, not data loss. Rebuild
+        // the section from DB state and re-persist a parseable projection.
+        logWarning("tool", `gsd_summary_save: PROJECT.md parsed zero milestone lines but DB has ${existingMilestones.length} — rebuilding Milestone Sequence from DB (projection self-heal)`, {
           tool: "gsd_summary_save",
+          path: relativePath,
         });
-        // PROJECT.md was persisted; invalidate so subsequent reads see the new
-        // artifacts row even though no milestones registered.
-        invalidateStateCache();
-        return {
-          content: [{
-            type: "text",
-            text:
-              `Error: PROJECT.md was saved to ${relativePath} but contains zero parseable milestone lines, ` +
-              `so no milestones were registered in the DB. /gsd will report "No Active Milestone". ` +
-              `Rewrite PROJECT.md so the "Milestone Sequence" section uses canonical lines: ` +
-              `\`- [ ] M001: <Title> — <One-liner>\` (em-dash, double-dash \`--\`, or single-dash \`-\` separator), then re-call gsd_summary_save(PROJECT).`,
-          }],
-          details: {
-            operation: "save_summary",
+        try {
+          const healed = rebuildMilestoneSequenceSection(contentToSave, existingMilestones);
+          await saveArtifactToDb(
+            { path: relativePath, artifact_type: params.artifact_type, content: healed },
+            basePath,
+          );
+          await mirrorArtifactToActiveWorktreeProjection(basePath, relativePath, healed);
+          const healedRegisteredMilestones = registerProjectMilestoneSequence(healed);
+          if (healedRegisteredMilestones.length === 0) {
+            throw new Error("self-healed PROJECT.md still parsed zero milestone lines");
+          }
+          registeredMilestones = healedRegisteredMilestones;
+          milestoneSequenceSelfHealed = true;
+        } catch (healErr) {
+          const msg = healErr instanceof Error ? healErr.message : String(healErr);
+          logError("tool", `gsd_summary_save: Milestone Sequence self-heal failed: ${msg}`, {
+            tool: "gsd_summary_save",
             path: relativePath,
-            artifact_type: params.artifact_type,
-            error: "milestone_registration_empty_parse",
-          },
-          isError: true,
-        };
+            error: msg,
+          });
+          invalidateStateCache();
+          return {
+            content: [{
+              type: "text",
+              text:
+                `Error: PROJECT.md was saved to ${relativePath} but contains zero parseable milestone lines, ` +
+                `and automatic DB-backed Milestone Sequence repair failed: ${msg}. ` +
+                `Rewrite PROJECT.md so the "Milestone Sequence" section uses canonical lines: ` +
+                `\`- [ ] M001: <Title> — <One-liner>\`, then re-call gsd_summary_save(PROJECT).`,
+            }],
+            details: {
+              operation: "save_summary",
+              path: relativePath,
+              artifact_type: params.artifact_type,
+              error: "milestone_sequence_self_heal_failed",
+              self_heal_error: msg,
+            },
+            isError: true,
+          };
+        }
+        invalidateStateCache();
       }
     }
 
@@ -339,6 +527,7 @@ export async function executeSummarySave(
         artifact_type: params.artifact_type,
         content_source: contentSource,
         ...(registeredMilestones.length > 0 ? { registeredMilestones } : {}),
+        ...(milestoneSequenceSelfHealed ? { milestoneSequenceSelfHealed: true } : {}),
       },
     };
   } catch (err) {
@@ -1082,7 +1271,48 @@ export async function executePlanMilestone(
     isError: true,
       };
   }
+  let workerId: string | null = null;
+  let acquiredToken: number | null = null;
+  let leaseRefreshTimer: ReturnType<typeof setInterval> | undefined;
   try {
+    // Re-read at the gate so a peer-created milestone is not treated as fresh.
+    const milestoneExists = getMilestone(params.milestoneId) !== null;
+    if (milestoneExists) {
+      const heldLease = getMilestoneLease(params.milestoneId);
+      if (heldLease?.status === "held" && Date.parse(heldLease.expires_at) > Date.now()) {
+        const holder = getAutoWorker(heldLease.worker_id);
+        // Let the one-shot claim path recover stale same-process worker rows.
+        const projectRoot = normalizeRealPath(basePath);
+        const isOurAutoLease = isAutoActive() && heldLease.worker_id === autoSession.workerId;
+        const holderIsOneShotReentrantPeer = !isAutoActive()
+          && !!holder
+          && holder.host === hostname()
+          && holder.pid === process.pid
+          && holder.project_root_realpath === projectRoot;
+        if (holder?.status === "active" && !isOurAutoLease && !holderIsOneShotReentrantPeer) {
+          return milestoneLeaseConflictResult(params.milestoneId, heldLease.worker_id, heldLease.expires_at);
+        }
+      }
+    }
+
+    // Fresh creation cannot claim a lease because the FK row does not exist.
+    // In-process auto already owns its lease; re-claiming would bump its token.
+    if (!isAutoActive() && milestoneExists) {
+      workerId = registerAutoWorker({ projectRootRealpath: normalizeRealPath(basePath) });
+      const lease = claimMilestoneLease(workerId, params.milestoneId);
+      if (!lease.ok) {
+        return milestoneLeaseConflictResult(params.milestoneId, lease.byWorker, lease.expiresAt);
+      }
+      acquiredToken = lease.token;
+
+      const leaseRefreshMs = (milestoneLeaseTtlSeconds() / 2) * 1000;
+      leaseRefreshTimer = setInterval(() => {
+        if (acquiredToken !== null && workerId !== null) {
+          refreshMilestoneLease(workerId, params.milestoneId, acquiredToken);
+        }
+      }, leaseRefreshMs);
+    }
+
     const result = await handlePlanMilestone(params, basePath);
     if ("error" in result) {
       return {
@@ -1108,6 +1338,17 @@ export async function executePlanMilestone(
     isError: true,
       };
   }
+  finally {
+    if (leaseRefreshTimer !== undefined) {
+      clearInterval(leaseRefreshTimer);
+    }
+    if (workerId !== null && acquiredToken !== null) {
+      releaseMilestoneLease(workerId, params.milestoneId, acquiredToken);
+    }
+    if (workerId !== null) {
+      markWorkerStopping(workerId);
+    }
+  }
 }
 
 export async function executePlanSlice(

package/src/resources/extensions/gsd/uat-policy.ts

@@ -1,9 +1,11 @@
 // Project/App: gsd-pi
 // File Purpose: Central UAT mode policy for dispatch, tool presentation, and result validation.
 
-import { extractUatType } from "./files.js";
+import { hasBrowserContractPrefix } from "../shared/browser-contract.js";
+import { extractUatType, UAT_TYPE_KEYWORDS } from "./files.js";
 import type { UatType } from "./files.js";
 import { hasBrowserRequiredText } from "./browser-evidence.js";
+import { parseMcpToolName } from "./mcp-tool-name.js";
 
 export type { UatType } from "./files.js";
 
@@ -26,19 +28,14 @@ export interface UatModePolicy {
 
 export interface UatContentPolicy {
   declaredType: UatType;
+  /** False when no parseable `UAT mode:` declaration exists and declaredType defaulted to artifact-driven. */
+  modeDeclared: boolean;
   effectiveType: UatType;
   browserRequired: boolean;
   shouldDispatchByDefault: boolean;
 }
 
-export const UAT_TYPES: readonly UatType[] = [
-  "artifact-driven",
-  "browser-executable",
-  "runtime-executable",
-  "live-runtime",
-  "mixed",
-  "human-experience",
-] as const;
+export const UAT_TYPES: readonly UatType[] = UAT_TYPE_KEYWORDS;
 
 export const UAT_MODE_POLICIES: Readonly<Record<UatType, UatModePolicy>> = {
   "artifact-driven": {
@@ -87,26 +84,76 @@ export function getDeclaredUatType(content: string): UatType {
   return extractUatType(content) ?? "artifact-driven";
 }
 
-export function classifyUatContent(content: string): UatContentPolicy {
-  const declaredType = getDeclaredUatType(content);
-  const browserRequired = hasBrowserRequiredText(content);
-  const effectiveType = declaredType === "artifact-driven" && browserRequired
+/** Self-contained browser UAT harnesses that manage server lifecycle internally. */
+const SELF_CONTAINED_RUNTIME_UAT_COMMAND_RE =
+  /\b(?:npm run test:uat|node\s+(?:--check\s+\S+\s+&&\s+)*tests\/browser\/search-uat\.mjs|npx playwright test(?:\s+\S+)?)\b/i;
+
+export function hasSelfContainedRuntimeUatCommand(content: string): boolean {
+  return SELF_CONTAINED_RUNTIME_UAT_COMMAND_RE.test(content);
+}
+
+function resolveEffectiveUatTypeFromPolicy(
+  declaredType: UatType,
+  browserRequired: boolean,
+  content: string,
+): UatType {
+  let effectiveType = declaredType === "artifact-driven" && browserRequired
     ? "browser-executable"
     : declaredType;
 
+  // M006/S01 regression: specs often declare browser-executable with localhost
+  // preconditions while the Evidence section names a runtime harness such as
+  // `npm run test:uat`. Interactive browser_* checks then race a fixed port
+  // against the script's own ephemeral server — run the harness instead.
+  if (
+    effectiveType === "browser-executable" &&
+    hasSelfContainedRuntimeUatCommand(content)
+  ) {
+    effectiveType = "runtime-executable";
+  }
+
+  return effectiveType;
+}
+
+export function classifyUatContent(content: string): UatContentPolicy {
+  return classifyUatContentForRun(content);
+}
+
+/**
+ * Classify UAT mode for run-uat dispatch. Supplemental context (slice summary,
+ * verification excerpts) can name a self-contained harness even when the UAT
+ * file only documents a separate server command such as `npm run test:server`.
+ */
+export function classifyUatContentForRun(content: string, supplementalContext = ""): UatContentPolicy {
+  const parsedType = extractUatType(content);
+  const declaredType = parsedType ?? "artifact-driven";
+  const browserRequired = hasBrowserRequiredText(content);
+  const combinedForHarness = supplementalContext.trim()
+    ? `${content}\n\n${supplementalContext}`
+    : content;
+  const effectiveType = resolveEffectiveUatTypeFromPolicy(
+    declaredType,
+    browserRequired,
+    combinedForHarness,
+  );
+
   return {
     declaredType,
+    modeDeclared: parsedType !== undefined,
     effectiveType,
     browserRequired,
     shouldDispatchByDefault: effectiveType !== "artifact-driven" || browserRequired,
   };
 }
 
-export function shouldEscalateArtifactUatToBrowser(content: string): boolean {
-  const policy = classifyUatContent(content);
+export function escalatesArtifactUatToBrowser(policy: UatContentPolicy): boolean {
   return policy.declaredType === "artifact-driven" && policy.browserRequired;
 }
 
+export function shouldEscalateArtifactUatToBrowser(content: string): boolean {
+  return escalatesArtifactUatToBrowser(classifyUatContent(content));
+}
+
 export function resolveEffectiveUatType(content: string): UatType {
   return classifyUatContent(content).effectiveType;
 }
@@ -122,31 +169,39 @@ export function uatTypeIncludesBrowser(uatType: string | undefined): boolean {
   return isUatType(uatType) && UAT_MODE_POLICIES[uatType].browserTools;
 }
 
-function canonicalPresentedToolName(toolName: string): string {
-  if (!toolName.startsWith("mcp__")) return toolName;
-  const toolSeparator = toolName.indexOf("__", "mcp__".length);
-  return toolSeparator >= 0 ? toolName.slice(toolSeparator + 2) : toolName;
-}
-
 export function isUatBrowserToolName(toolName: string): boolean {
-  return canonicalPresentedToolName(toolName).startsWith("browser_");
+  const parsed = parseMcpToolName(toolName);
+  const canonicalName = parsed?.toolName ?? toolName;
+  if (hasBrowserContractPrefix(canonicalName)) return true;
+  return parsed?.toolName === "*" && parsed.serverName.toLowerCase().includes("browser");
 }
 
 export function hasUatBrowserToolSurface(activeTools: readonly string[] | undefined): boolean {
   return Array.isArray(activeTools) && activeTools.some(isUatBrowserToolName);
 }
 
+export function resolveUatBrowserToolSurface(options: {
+  activeTools: readonly string[] | undefined;
+  registeredTools?: readonly string[] | undefined;
+}): readonly string[] | undefined {
+  const surfaces = [options.activeTools, options.registeredTools].filter(Array.isArray);
+  if (surfaces.length === 0) return undefined;
+  return [...new Set(surfaces.flat())];
+}
+
 export function getUatBrowserToolSupportError(options: {
   uatType: UatType;
   activeTools: readonly string[] | undefined;
+  registeredTools?: readonly string[] | undefined;
   milestoneId: string;
   sliceId: string;
 }): string | null {
   if (!uatTypeIncludesBrowser(options.uatType)) return null;
-  if (!Array.isArray(options.activeTools)) return null;
-  if (hasUatBrowserToolSurface(options.activeTools)) return null;
+  const toolSurface = resolveUatBrowserToolSurface(options);
+  if (!toolSurface) return null;
+  if (hasUatBrowserToolSurface(toolSurface)) return null;
 
-  return `Cannot dispatch browser-backed run-uat for ${options.milestoneId}/${options.sliceId}: UAT mode "${options.uatType}" requires browser tools, but the active tool surface has none. Enable browser tools or change the UAT to a runtime-executable Playwright command, then rerun /gsd auto.`;
+  return `Cannot dispatch browser-backed run-uat for ${options.milestoneId}/${options.sliceId}: UAT mode "${options.uatType}" requires browser tools, but the run-uat tool surface has none. Enable browser tools or change the UAT to a runtime-executable Playwright command, then rerun /gsd auto.`;
 }
 
 export function isPartialEligibleUatType(uatType: UatType | undefined): boolean {