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

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/uat-policy.ts

@@ -4,6 +4,7 @@
 import { extractUatType } 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";
 
@@ -122,31 +123,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 (canonicalName.startsWith("browser_")) 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 {

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

@@ -103,7 +103,7 @@ function mergeBlockedTools(
 ): UatPresentationInput["blockedTools"] {
   const merged = new Map<string, { name: string; reason: string }>();
   for (const entry of [...(current ?? []), ...canonical]) {
-    merged.set(canonicalWorkflowToolName(parseMcpToolName(entry.name)?.tool ?? entry.name), entry);
+    merged.set(canonicalWorkflowToolName(parseMcpToolName(entry.name)?.toolName ?? entry.name), entry);
   }
   return [...merged.values()];
 }
@@ -299,22 +299,18 @@ function quoteToolNames(toolNames: readonly string[]): string {
 }
 
 function validateCanonicalPresentation(params: UatResultSaveParams): string | null {
-  const aliasHints: Record<string, string> = {
-    gsd_save_summary: "gsd_summary_save",
-    gsd_complete_task: "gsd_task_complete",
-    gsd_complete_slice: "gsd_slice_complete",
-    gsd_milestone_complete: "gsd_complete_milestone",
-  };
   const errors: string[] = [];
   for (const toolName of params.presentation.presentedTools) {
-    const baseName = parseMcpToolName(toolName)?.tool ?? toolName;
-    const canonical = aliasHints[baseName];
-    if (canonical) errors.push(`presentation tool "${toolName}" uses an alias; use canonical "${canonical}"`);
+    const baseName = parseMcpToolName(toolName)?.toolName ?? toolName;
+    const canonical = canonicalWorkflowToolName(baseName);
+    if (canonical !== baseName) {
+      errors.push(`presentation tool "${toolName}" uses an alias; use canonical "${canonical}"`);
+    }
   }
 
   const presentedCanonical = new Set(
     params.presentation.presentedTools.map((toolName) =>
-      canonicalWorkflowToolName(parseMcpToolName(toolName)?.tool ?? toolName)
+      canonicalWorkflowToolName(parseMcpToolName(toolName)?.toolName ?? toolName)
     ),
   );
   const missingRequiredTools = RUN_UAT_WORKFLOW_TOOL_NAMES.filter(
@@ -329,11 +325,11 @@ function validateCanonicalPresentation(params: UatResultSaveParams): string | nu
   const forbiddenCanonical = new Set(
     RUN_UAT_FORBIDDEN_TOOL_NAMES
       .filter((toolName) => !toolName.includes("*"))
-      .map((toolName) => canonicalWorkflowToolName(parseMcpToolName(toolName)?.tool ?? toolName)),
+      .map((toolName) => canonicalWorkflowToolName(parseMcpToolName(toolName)?.toolName ?? toolName)),
   );
   const forbiddenPresentedTools: string[] = [];
   for (const toolName of params.presentation.presentedTools) {
-    const canonical = canonicalWorkflowToolName(parseMcpToolName(toolName)?.tool ?? toolName);
+    const canonical = canonicalWorkflowToolName(parseMcpToolName(toolName)?.toolName ?? toolName);
     if (toolName === "mcp__gsd-workflow__*" || forbiddenCanonical.has(canonical)) {
       forbiddenPresentedTools.push(toolName);
     }
@@ -346,7 +342,7 @@ function validateCanonicalPresentation(params: UatResultSaveParams): string | nu
 
   const blockedCanonical = new Set(
     params.presentation.blockedTools.map((entry) =>
-      canonicalWorkflowToolName(parseMcpToolName(entry.name)?.tool ?? entry.name)
+      canonicalWorkflowToolName(parseMcpToolName(entry.name)?.toolName ?? entry.name)
     ),
   );
   const missingBlockedTools = ["gsd_exec", "gsd_summary_save", "gsd_save_gate_result"].filter(

package/src/resources/extensions/gsd/unit-context-composer.ts

@@ -45,6 +45,7 @@ import {
   type ContextModePolicy,
   type UnitContextManifest,
 } from "./unit-context-manifest.js";
+import type { UnitPromptContextContract } from "./tool-contract.js";
 
 /**
  * Async function mapping an artifact key to its inlined-content string,
@@ -195,8 +196,32 @@ export interface ComposedUnitContext {
   readonly inline: string;
 }
 
+export type UnitContextBlockMode = "prepend" | "inline" | "excerpt" | "computed";
+
+export interface ComposedUnitContextBlock {
+  readonly key: string;
+  readonly mode: UnitContextBlockMode;
+  readonly body: string;
+}
+
+export interface ComposedContractedUnitContext extends ComposedUnitContext {
+  readonly blocks: readonly ComposedUnitContextBlock[];
+  readonly onDemand: readonly ArtifactKey[];
+}
+
 const SECTION_SEPARATOR = "\n\n---\n\n";
 
+interface UnitContextCompositionContract {
+  readonly unitType: string;
+  readonly artifacts: {
+    readonly inline: readonly ArtifactKey[];
+    readonly excerpt: readonly ArtifactKey[];
+    readonly onDemand: readonly ArtifactKey[];
+    readonly computed: readonly ComputedArtifactId[];
+    readonly prepend: readonly ComputedArtifactId[];
+  };
+}
+
 /**
  * Compose all manifest-declared context for a unit type using the v2
  * surface. Walks `prepend` first (computed-only), then the `inline` list
@@ -220,36 +245,73 @@ export async function composeUnitContext(
   const manifest: UnitContextManifest | null = resolveManifest(unitType);
   if (!manifest) return { prepend: "", inline: "" };
 
-  // Single-source `unitType`: the manifest is resolved against the
+  const composed = await composeDeclaredUnitContext({
+    unitType,
+    artifacts: {
+      inline: manifest.artifacts.inline,
+      excerpt: manifest.artifacts.excerpt,
+      onDemand: manifest.artifacts.onDemand,
+      computed: manifest.artifacts.computed ?? [],
+      prepend: manifest.prepend ?? [],
+    },
+  }, opts);
+  return {
+    prepend: composed.prepend,
+    inline: composed.inline,
+  };
+}
+
+export async function composeContractedUnitContext(
+  contract: UnitPromptContextContract,
+  opts: ComposeUnitContextOptions,
+): Promise<ComposedContractedUnitContext> {
+  return composeDeclaredUnitContext(contract, opts);
+}
+
+async function composeDeclaredUnitContext(
+  contract: UnitContextCompositionContract,
+  opts: ComposeUnitContextOptions,
+): Promise<ComposedContractedUnitContext> {
+  // Single-source `unitType`: contract/manifest selection comes from the
   // function arg, but computed builders read it from `base.unitType`.
-  // If those ever diverge (caller passes one type to composeUnitContext
-  // but a different one in opts.base), the composer would silently
-  // mix one unit's manifest with another unit's computed context.
-  // Normalize here so the composer dispatches a consistent identity
-  // through to every builder.
+  // Normalize here so every builder sees the same Unit identity.
   const normalizedOpts: ComposeUnitContextOptions = {
     ...opts,
-    base: { ...opts.base, unitType },
+    base: { ...opts.base, unitType: contract.unitType },
   };
 
-  const prependBlocks = await runComputed(manifest.prepend ?? [], normalizedOpts);
-  const inlineBlocks: string[] = [];
+  const prependBlocks = await runComputedBlocks(
+    contract.artifacts.prepend,
+    normalizedOpts,
+    "prepend",
+  );
+  const inlineBlocks: ComposedUnitContextBlock[] = [];
 
-  for (const key of manifest.artifacts.inline) {
+  for (const key of contract.artifacts.inline) {
     if (!normalizedOpts.resolveArtifact) break;
     const body = await normalizedOpts.resolveArtifact(key);
-    if (body && body.length > 0) inlineBlocks.push(body);
+    if (body && body.length > 0) {
+      inlineBlocks.push({ key, mode: "inline", body });
+    }
   }
-  for (const key of manifest.artifacts.excerpt) {
+  for (const key of contract.artifacts.excerpt) {
     if (!normalizedOpts.resolveExcerpt) break;
     const body = await normalizedOpts.resolveExcerpt(key);
-    if (body && body.length > 0) inlineBlocks.push(body);
+    if (body && body.length > 0) {
+      inlineBlocks.push({ key, mode: "excerpt", body });
+    }
   }
-  inlineBlocks.push(...await runComputed(manifest.artifacts.computed ?? [], normalizedOpts));
+  inlineBlocks.push(...await runComputedBlocks(
+    contract.artifacts.computed,
+    normalizedOpts,
+    "computed",
+  ));
 
   return {
-    prepend: prependBlocks.join(SECTION_SEPARATOR),
-    inline: inlineBlocks.join(SECTION_SEPARATOR),
+    prepend: prependBlocks.map((block) => block.body).join(SECTION_SEPARATOR),
+    inline: inlineBlocks.map((block) => block.body).join(SECTION_SEPARATOR),
+    blocks: [...prependBlocks, ...inlineBlocks],
+    onDemand: contract.artifacts.onDemand,
   };
 }
 
@@ -258,10 +320,11 @@ export async function composeUnitContext(
  * Missing registry entries (manifest declares the id but caller didn't
  * register it) are skipped silently — see composeUnitContext rationale.
  */
-async function runComputed(
+async function runComputedBlocks(
   ids: readonly ComputedArtifactId[],
   opts: ComposeUnitContextOptions,
-): Promise<string[]> {
+  mode: Extract<UnitContextBlockMode, "prepend" | "computed">,
+): Promise<ComposedUnitContextBlock[]> {
   if (ids.length === 0 || !opts.computed) return [];
   // Type safety lives at the registration boundary (caller-supplied
   // `computed` is typed against ComputedArtifactInputs[K] per id). Inside
@@ -274,12 +337,14 @@ async function runComputed(
     inputs: unknown;
   };
   const registry = opts.computed as Record<string, AnyEntry | undefined>;
-  const out: string[] = [];
+  const out: ComposedUnitContextBlock[] = [];
   for (const id of ids) {
     const entry = registry[id];
     if (!entry) continue;
     const body = await entry.build(entry.inputs, opts.base);
-    if (body && body.length > 0) out.push(body);
+    if (body && body.length > 0) {
+      out.push({ key: id, mode, body });
+    }
   }
   return out;
 }

package/src/resources/extensions/gsd/unit-runtime.ts

@@ -10,7 +10,8 @@ import {
 } from "./paths.js";
 import { loadFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.js";
 import { parseUnitId } from "./unit-id.js";
-import { getTask, isDbAvailable, refreshOpenDatabaseFromDisk } from "./gsd-db.js";
+import { getTask, isDbAvailable } from "./gsd-db.js";
+import { refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 import { isClosedStatus } from "./status-guards.js";
 
 // Per-record advisory lock — prevents read-modify-write races between
@@ -218,7 +219,7 @@ export async function inspectExecuteTaskDurability(
   const nextActionAdvanced = !new RegExp(`Execute ${tid}\\b`).test(stateContent);
   let dbComplete = false;
   if (isDbAvailable()) {
-    refreshOpenDatabaseFromDisk();
+    refreshWorkflowDatabaseFromDisk();
     const task = getTask(mid, sid, tid);
     dbComplete = !!task && isClosedStatus(task.status);
   }

package/src/resources/extensions/gsd/unit-tool-contracts.ts

@@ -71,6 +71,7 @@ export const UNIT_TOOL_CONTRACTS: Record<string, UnitToolSurfaceContract> = {
       "gsd_milestone_generate_id",
     ],
     requiredWorkflowTools: [
+      "ask_user_questions",
       "gsd_summary_save",
       "gsd_requirement_save",
       "gsd_requirement_update",
@@ -80,7 +81,7 @@ export const UNIT_TOOL_CONTRACTS: Record<string, UnitToolSurfaceContract> = {
   },
   "discuss-slice": {
     allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
-    requiredWorkflowTools: ["gsd_summary_save"],
+    requiredWorkflowTools: ["ask_user_questions", "gsd_summary_save"],
   },
   "validate-milestone": {
     allowedGsdTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap", "subagent"],

package/src/resources/extensions/gsd/user-input-boundary.ts

@@ -183,6 +183,24 @@ export function isAwaitingApprovalBoundary(messages: unknown[] | undefined): boo
   return hasApprovalQuestion(text);
 }
 
+/** True when an assistant message already has an in-flight ask_user_questions tool call. */
+export function messageHasPendingAskUserQuestionsTool(message: unknown): boolean {
+  if (!message || typeof message !== "object") return false;
+  const content = (message as { content?: unknown }).content;
+  if (!Array.isArray(content)) return false;
+  return content.some((block) => {
+    if (!block || typeof block !== "object") return false;
+    // Claude Code marks completion by attaching externalResult, not by setting state.
+    // Streaming blocks often carry no state; serverToolUse is the claude-code-cli MCP path.
+    const tool = block as { type?: string; name?: string; state?: string; externalResult?: unknown };
+    if (tool.type !== "toolCall" && tool.type !== "serverToolUse") return false;
+    const name = String(tool.name ?? "").toLowerCase();
+    if (!name.includes("ask_user_questions")) return false;
+    if (tool.externalResult !== undefined) return false;
+    return tool.state !== "completed" && tool.state !== "done";
+  });
+}
+
 export function shouldPauseForUserApprovalQuestion(
   unitType: string | undefined,
   messages: unknown[] | undefined,

package/src/resources/extensions/gsd/validation-block-guard.ts

@@ -5,6 +5,7 @@ import { existsSync } from "node:fs";
 
 import { getAutoWorktreePath, isInAutoWorktree } from "./auto-worktree.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
+import { refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 import { getIsolationMode } from "./preferences.js";
 import { deriveState } from "./state.js";
 import type { GSDState } from "./types.js";
@@ -91,6 +92,7 @@ export async function getValidationBlockMessageForBase(
   attemptedCommand = "",
 ): Promise<string | null> {
   await ensureDbOpen(base);
+  refreshWorkflowDatabaseFromDisk();
   let state = await deriveState(base);
 
   if (

package/src/resources/extensions/gsd/web-app-uat.ts

@@ -0,0 +1,101 @@
+// Project/App: gsd-pi
+// File Purpose: Web-app detection and Playwright/UAT guidance for planning and slice closeout.
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { detectWebApp } from "../browser-tools/web-app-detect.js";
+
+export { detectWebApp };
+
+interface MinimalPackageJson {
+  dependencies?: Record<string, unknown>;
+  devDependencies?: Record<string, unknown>;
+  scripts?: Record<string, unknown>;
+}
+
+function readPackageJson(projectRoot: string): MinimalPackageJson | null {
+  const packageJsonPath = resolve(projectRoot, "package.json");
+  if (!existsSync(packageJsonPath)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as unknown;
+    return parsed && typeof parsed === "object" ? (parsed as MinimalPackageJson) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function hasPlaywrightTestDependency(projectRoot: string): boolean {
+  const pkg = readPackageJson(projectRoot);
+  if (!pkg) return false;
+  const names = [
+    ...Object.keys(pkg.dependencies ?? {}),
+    ...Object.keys(pkg.devDependencies ?? {}),
+  ];
+  return names.some((name) => name === "playwright" || name === "@playwright/test");
+}
+
+export function findPlaywrightTestScript(projectRoot: string): string | null {
+  const pkg = readPackageJson(projectRoot);
+  if (!pkg?.scripts) return null;
+  for (const [name, value] of Object.entries(pkg.scripts)) {
+    if (typeof value !== "string") continue;
+    if (/\bplaywright\s+test\b/.test(value)) {
+      return `npm run ${name}`;
+    }
+  }
+  return null;
+}
+
+/**
+ * Markdown block injected into plan/complete-slice prompts when the project
+ * looks browser-facing. Returns null for CLI/library-only repos.
+ */
+export function buildWebAppUatGuidanceBlock(projectRoot: string): string | null {
+  if (!detectWebApp(projectRoot)) return null;
+
+  const playwrightScript = findPlaywrightTestScript(projectRoot);
+  const hasPlaywright = hasPlaywrightTestDependency(projectRoot) || playwrightScript !== null;
+  const lines = [
+    "### Web App UAT (detected)",
+    "",
+    "This project looks browser-facing. GSD exposes Playwright-backed `browser_*` tools by default for run-uat.",
+    "",
+    "**UAT modes (pick one per slice — do not use `artifact-driven` for browser steps):**",
+    "- `browser-executable` — navigate to `http://localhost:…`, click, screenshot, assert via `browser_*` tools during run-uat",
+    "- `runtime-executable` — run an automated browser test command via `gsd_uat_exec` (for example `npx playwright test`)",
+    "- `mixed` / `live-runtime` — combine runtime startup checks with interactive browser verification",
+    "",
+    "**Planning / closeout rules:**",
+    "- Preconditions must name the dev-server command and URL (for example `npm run dev` → `http://localhost:3000`)",
+    "- Slice Verification and UAT test cases must not say \"open in browser\" under `artifact-driven` — complete-slice rejects that",
+    "- Milestone `Verification Classes` → UAT row must describe browser-observable acceptance, not \"manual spot check\" alone",
+  ];
+
+  if (hasPlaywright) {
+    lines.push(
+      "",
+      "**Playwright:** dependency detected.",
+    );
+    if (playwrightScript) {
+      lines.push(
+        `- Prefer slice verification and runtime-executable UAT referencing \`${playwrightScript}\` or a focused \`npx playwright test <spec>\` command`,
+      );
+    } else {
+      lines.push(
+        "- Prefer runtime-executable UAT with `npx playwright test` (or a focused spec path) when UI behavior is covered by specs",
+      );
+    }
+    lines.push("- Name concrete spec paths in slice Verification (for example `e2e/smoke.spec.ts`)");
+  } else {
+    lines.push(
+      "",
+      "**Playwright scaffolding (first UI slice):** no `playwright` / `@playwright/test` dependency yet.",
+      "- Add a planning task that installs Playwright, adds `playwright.config.ts`, and creates a minimal smoke spec (for example `e2e/smoke.spec.ts`)",
+      "- Task `verify` should run `npx playwright test` (or the focused spec) with a safe, simple command",
+      "- Until specs exist, use `browser-executable` UAT with localhost preconditions and interactive `browser_*` checks at slice closeout",
+    );
+  }
+
+  return lines.join("\n");
+}