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

package/dist/resources/extensions/gsd/unit-registry.js

@@ -0,0 +1,337 @@
+// Project/App: gsd-pi
+// File Purpose: Unit Registry — the single declaration point for what a Unit type is (ADR-033).
+//
+// One Unit Descriptor per Unit type. The previously independent tables —
+// `KNOWN_UNIT_TYPES`/`UnitType` (unit-context-manifest.ts), `UNIT_TOOL_CONTRACTS`
+// (unit-tool-contracts.ts), the scope-class Sets (auto-unit-tool-scope.ts), and
+// the unit→phase switch (preferences-models.ts) — are derived views over this
+// registry. Import paths stay stable: each former home re-exports its view
+// (the `gsd-db.ts` barrel discipline).
+//
+// Behaviour-neutral by construction. The registry preserves the asymmetries the
+// old tables had drifted into, explicitly instead of accidentally:
+//   - `discuss-slice` and `execute-task-simple` had tool contracts and scope-Set
+//     membership but were absent from `KNOWN_UNIT_TYPES` → declared here as
+//     `kind: "variant"` (excluded from the derived `KNOWN_UNIT_TYPES`/`UnitType`).
+//   - `triage-captures` and `quick-task` had manifests but no tool contract and
+//     no phase routing → `toolContract: null`, `phaseChain: null`.
+// The parity test (tests/unit-registry.test.ts) pins every derived view to the
+// pre-registry values.
+//
+// Not yet declared here (remaining ADR-033 steps): the manifest data
+// (`UNIT_MANIFESTS` stays in unit-context-manifest.ts, already type-enforced
+// against the registry's `UnitType`) and prompt-template association (still
+// implicit in auto-prompts.ts builders).
+import { BROWSER_CONTRACT_TOOL_NAMES } from "../shared/browser-contract.js";
+// ─── Shared tool-name constants (used by registry rows) ──────────────────
+export const RUN_UAT_WORKFLOW_TOOL_NAMES = [
+    "gsd_uat_exec",
+    "gsd_uat_result_save",
+    "gsd_resume",
+    "gsd_milestone_status",
+    "gsd_journal_query",
+];
+export const RUN_UAT_READ_ONLY_TOOL_NAMES = [
+    "find",
+    "glob",
+    "grep",
+    "ls",
+    "read",
+];
+/**
+ * Browser tools presented to run-uat. A derived view of the Browser Automation
+ * Contract vocabulary (shared/browser-contract.ts) — the contract module is the
+ * only place browser tool names are declared.
+ */
+export const RUN_UAT_BROWSER_TOOL_NAMES = BROWSER_CONTRACT_TOOL_NAMES;
+// ─── The registry ─────────────────────────────────────────────────────────
+export const UNIT_REGISTRY = {
+    "research-milestone": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["research"],
+        toolContract: {
+            allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+            requiredWorkflowTools: ["gsd_summary_save"],
+        },
+    },
+    "plan-milestone": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["planning"],
+        toolContract: {
+            allowedGsdTools: [
+                "gsd_milestone_status",
+                "gsd_plan_milestone",
+                "gsd_plan_slice",
+                "gsd_decision_save",
+                "gsd_requirement_update",
+            ],
+            requiredWorkflowTools: ["gsd_milestone_status", "gsd_plan_milestone", "gsd_plan_slice"],
+        },
+    },
+    "discuss-milestone": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["discuss", "planning"],
+        toolContract: {
+            allowedGsdTools: [
+                "gsd_summary_save",
+                "gsd_decision_save",
+                "gsd_requirement_save",
+                "gsd_requirement_update",
+                "gsd_plan_milestone",
+                "gsd_milestone_generate_id",
+            ],
+            requiredWorkflowTools: [
+                "ask_user_questions",
+                "gsd_summary_save",
+                "gsd_requirement_save",
+                "gsd_requirement_update",
+                "gsd_plan_milestone",
+                "gsd_milestone_generate_id",
+            ],
+        },
+    },
+    "discuss-slice": {
+        kind: "variant",
+        scopeClass: "standard",
+        phaseChain: ["discuss", "planning"],
+        toolContract: {
+            allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+            requiredWorkflowTools: ["ask_user_questions", "gsd_summary_save"],
+        },
+    },
+    "validate-milestone": {
+        kind: "primary",
+        scopeClass: "section-close",
+        phaseChain: ["validation", "planning"],
+        toolContract: {
+            allowedGsdTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap", "subagent"],
+            requiredWorkflowTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap"],
+        },
+    },
+    "complete-milestone": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["completion"],
+        toolContract: {
+            allowedGsdTools: [
+                "gsd_milestone_status",
+                "gsd_requirement_update",
+                "gsd_summary_save",
+                "gsd_complete_milestone",
+                "subagent",
+            ],
+            requiredWorkflowTools: [
+                "gsd_milestone_status",
+                "gsd_requirement_update",
+                "gsd_summary_save",
+                "gsd_complete_milestone",
+            ],
+        },
+    },
+    "research-slice": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["research"],
+        toolContract: {
+            allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+            requiredWorkflowTools: ["gsd_summary_save"],
+        },
+    },
+    "plan-slice": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["planning"],
+        toolContract: {
+            allowedGsdTools: ["gsd_plan_slice", "gsd_reassess_roadmap", "gsd_decision_save"],
+            requiredWorkflowTools: ["gsd_plan_slice", "gsd_reassess_roadmap"],
+        },
+    },
+    "refine-slice": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["planning"],
+        toolContract: {
+            allowedGsdTools: ["gsd_plan_slice", "gsd_decision_save"],
+            requiredWorkflowTools: ["gsd_plan_slice"],
+        },
+    },
+    "replan-slice": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["planning"],
+        toolContract: {
+            allowedGsdTools: ["gsd_replan_slice", "gsd_decision_save"],
+            requiredWorkflowTools: ["gsd_replan_slice"],
+        },
+    },
+    "complete-slice": {
+        kind: "primary",
+        scopeClass: "section-close",
+        phaseChain: ["completion"],
+        toolContract: {
+            allowedGsdTools: [
+                "gsd_slice_complete",
+                "gsd_task_reopen",
+                "gsd_replan_slice",
+                "gsd_decision_save",
+                "gsd_requirement_update",
+                "gsd_summary_save",
+                "subagent",
+            ],
+            requiredWorkflowTools: [
+                "gsd_slice_complete",
+                "gsd_task_reopen",
+                "gsd_replan_slice",
+                "gsd_requirement_update",
+                "gsd_summary_save",
+            ],
+            forbiddenGsdTools: {
+                gsd_uat_result_save: "Run UAT owns persisted UAT Assessment.",
+            },
+        },
+    },
+    "reassess-roadmap": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["validation", "planning"],
+        toolContract: {
+            allowedGsdTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
+            requiredWorkflowTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
+        },
+    },
+    "execute-task": {
+        kind: "primary",
+        scopeClass: "execute-task",
+        phaseChain: ["execution"],
+        toolContract: {
+            allowedGsdTools: ["gsd_task_complete", "gsd_decision_save"],
+            requiredWorkflowTools: ["gsd_task_complete"],
+        },
+    },
+    "execute-task-simple": {
+        kind: "variant",
+        scopeClass: "execute-task",
+        phaseChain: ["execution_simple", "execution"],
+        toolContract: {
+            allowedGsdTools: ["gsd_task_complete", "gsd_decision_save"],
+            requiredWorkflowTools: ["gsd_task_complete"],
+        },
+    },
+    "reactive-execute": {
+        kind: "primary",
+        scopeClass: "execute-task",
+        phaseChain: ["execution"],
+        toolContract: {
+            allowedGsdTools: ["gsd_task_complete", "gsd_summary_save", "gsd_decision_save"],
+            requiredWorkflowTools: ["gsd_task_complete", "gsd_summary_save"],
+        },
+    },
+    "run-uat": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["uat", "completion"],
+        toolContract: {
+            allowedGsdTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES, "subagent"],
+            requiredWorkflowTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES],
+            forbiddenGsdTools: {
+                gsd_exec: "Use gsd_uat_exec so acceptance evidence is typed as UAT-owned.",
+                gsd_save_gate_result: "gsd_uat_result_save owns the aggregate UAT gate.",
+                gsd_summary_save: "gsd_uat_result_save owns persisted UAT Assessment writes.",
+            },
+        },
+    },
+    "gate-evaluate": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["validation", "planning"],
+        toolContract: {
+            allowedGsdTools: ["gsd_save_gate_result"],
+            requiredWorkflowTools: ["gsd_save_gate_result"],
+        },
+    },
+    "rewrite-docs": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["validation", "planning"],
+        toolContract: {
+            allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+            requiredWorkflowTools: [],
+        },
+    },
+    // Sidecar units (triage, quick-task) — manifests exist, but no scoped tool
+    // contract and no phase routing (today's behaviour, preserved explicitly).
+    "triage-captures": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: null,
+        toolContract: null,
+    },
+    "quick-task": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: null,
+        toolContract: null,
+    },
+    // Deep planning mode (project-level) units
+    "workflow-preferences": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["discuss", "planning"],
+        toolContract: {
+            allowedGsdTools: ["gsd_summary_save"],
+            requiredWorkflowTools: [],
+        },
+    },
+    "discuss-project": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["discuss", "planning"],
+        toolContract: {
+            allowedGsdTools: ["gsd_summary_save", "gsd_decision_save", "gsd_requirement_save"],
+            requiredWorkflowTools: ["ask_user_questions", "gsd_summary_save"],
+        },
+    },
+    "discuss-requirements": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["discuss", "planning"],
+        toolContract: {
+            allowedGsdTools: ["gsd_requirement_save", "gsd_summary_save"],
+            requiredWorkflowTools: ["ask_user_questions", "gsd_requirement_save", "gsd_summary_save"],
+        },
+    },
+    "research-decision": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["discuss", "planning"],
+        toolContract: {
+            allowedGsdTools: ["gsd_summary_save"],
+            requiredWorkflowTools: ["ask_user_questions"],
+        },
+    },
+    "research-project": {
+        kind: "primary",
+        scopeClass: "standard",
+        phaseChain: ["research"],
+        toolContract: {
+            allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+            requiredWorkflowTools: [],
+        },
+    },
+};
+const ALL_UNIT_KEYS = Object.keys(UNIT_REGISTRY);
+export const KNOWN_UNIT_TYPES = Object.freeze(ALL_UNIT_KEYS.filter((t) => UNIT_REGISTRY[t].kind === "primary"));
+export const EXECUTE_TASK_UNIT_TYPES = new Set(ALL_UNIT_KEYS.filter((t) => UNIT_REGISTRY[t].scopeClass === "execute-task"));
+// Execute-task units close gates via summary sections too, so the section-close
+// gate Set is every non-"standard" scope class.
+export const SECTION_CLOSE_GATE_UNIT_TYPES = new Set(ALL_UNIT_KEYS.filter((t) => UNIT_REGISTRY[t].scopeClass !== "standard"));
+export function getUnitDescriptor(unitType) {
+    return UNIT_REGISTRY[unitType];
+}
+/** Phase-bucket fallback chain for a unit type, or null when the registry has no routing for it. */
+export function getUnitPhaseChain(unitType) {
+    return getUnitDescriptor(unitType)?.phaseChain ?? null;
+}

package/dist/resources/extensions/gsd/unit-tool-contracts.js

@@ -1,187 +1,14 @@
 // Project/App: gsd-pi
-// File Purpose: Central Unit-to-tool contracts for phase-aware GSD tool surfaces.
-export const RUN_UAT_WORKFLOW_TOOL_NAMES = [
-    "gsd_uat_exec",
-    "gsd_uat_result_save",
-    "gsd_resume",
-    "gsd_milestone_status",
-    "gsd_journal_query",
-];
-export const RUN_UAT_READ_ONLY_TOOL_NAMES = [
-    "find",
-    "glob",
-    "grep",
-    "ls",
-    "read",
-];
-export const RUN_UAT_BROWSER_TOOL_NAMES = [
-    "browser_navigate",
-    "browser_click",
-    "browser_type",
-    "browser_fill_form",
-    "browser_click_ref",
-    "browser_fill_ref",
-    "browser_wait_for",
-    "browser_assert",
-    "browser_verify",
-    "browser_screenshot",
-    "browser_snapshot_refs",
-    "browser_find",
-    "browser_get_console_logs",
-    "browser_get_network_logs",
-    "browser_evaluate",
-    "browser_reload",
-    "browser_batch",
-    "browser_act",
-];
+// File Purpose: Unit-to-tool contract views derived from the Unit Registry (ADR-033).
+//
+// The contract data lives in unit-registry.ts (one Unit Descriptor per unit
+// type). This file keeps the established import surface: the derived
+// `UNIT_TOOL_CONTRACTS` table and its accessor functions are unchanged for
+// consumers.
+import { UNIT_REGISTRY, } from "./unit-registry.js";
+export { RUN_UAT_WORKFLOW_TOOL_NAMES, RUN_UAT_READ_ONLY_TOOL_NAMES, RUN_UAT_BROWSER_TOOL_NAMES, } from "./unit-registry.js";
 export const RUN_UAT_TOOL_PRESENTATION_PLAN_ID = "run-uat/default-v1";
-export const UNIT_TOOL_CONTRACTS = {
-    "research-milestone": {
-        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_summary_save"],
-    },
-    "plan-milestone": {
-        allowedGsdTools: [
-            "gsd_milestone_status",
-            "gsd_plan_milestone",
-            "gsd_plan_slice",
-            "gsd_decision_save",
-            "gsd_requirement_update",
-        ],
-        requiredWorkflowTools: ["gsd_milestone_status", "gsd_plan_milestone", "gsd_plan_slice"],
-    },
-    "discuss-milestone": {
-        allowedGsdTools: [
-            "gsd_summary_save",
-            "gsd_decision_save",
-            "gsd_requirement_save",
-            "gsd_requirement_update",
-            "gsd_plan_milestone",
-            "gsd_milestone_generate_id",
-        ],
-        requiredWorkflowTools: [
-            "ask_user_questions",
-            "gsd_summary_save",
-            "gsd_requirement_save",
-            "gsd_requirement_update",
-            "gsd_plan_milestone",
-            "gsd_milestone_generate_id",
-        ],
-    },
-    "discuss-slice": {
-        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
-        requiredWorkflowTools: ["ask_user_questions", "gsd_summary_save"],
-    },
-    "validate-milestone": {
-        allowedGsdTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap", "subagent"],
-        requiredWorkflowTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap"],
-    },
-    "complete-milestone": {
-        allowedGsdTools: [
-            "gsd_milestone_status",
-            "gsd_requirement_update",
-            "gsd_summary_save",
-            "gsd_complete_milestone",
-            "subagent",
-        ],
-        requiredWorkflowTools: [
-            "gsd_milestone_status",
-            "gsd_requirement_update",
-            "gsd_summary_save",
-            "gsd_complete_milestone",
-        ],
-    },
-    "research-slice": {
-        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_summary_save"],
-    },
-    "plan-slice": {
-        allowedGsdTools: ["gsd_plan_slice", "gsd_reassess_roadmap", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_plan_slice", "gsd_reassess_roadmap"],
-    },
-    "refine-slice": {
-        allowedGsdTools: ["gsd_plan_slice", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_plan_slice"],
-    },
-    "replan-slice": {
-        allowedGsdTools: ["gsd_replan_slice", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_replan_slice"],
-    },
-    "complete-slice": {
-        allowedGsdTools: [
-            "gsd_slice_complete",
-            "gsd_task_reopen",
-            "gsd_replan_slice",
-            "gsd_decision_save",
-            "gsd_requirement_update",
-            "gsd_summary_save",
-            "subagent",
-        ],
-        requiredWorkflowTools: [
-            "gsd_slice_complete",
-            "gsd_task_reopen",
-            "gsd_replan_slice",
-            "gsd_requirement_update",
-            "gsd_summary_save",
-        ],
-        forbiddenGsdTools: {
-            gsd_uat_result_save: "Run UAT owns persisted UAT Assessment.",
-        },
-    },
-    "reassess-roadmap": {
-        allowedGsdTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
-        requiredWorkflowTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
-    },
-    "execute-task": {
-        allowedGsdTools: ["gsd_task_complete", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_task_complete"],
-    },
-    "execute-task-simple": {
-        allowedGsdTools: ["gsd_task_complete", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_task_complete"],
-    },
-    "reactive-execute": {
-        allowedGsdTools: ["gsd_task_complete", "gsd_summary_save", "gsd_decision_save"],
-        requiredWorkflowTools: ["gsd_task_complete", "gsd_summary_save"],
-    },
-    "run-uat": {
-        allowedGsdTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES, "subagent"],
-        requiredWorkflowTools: [...RUN_UAT_WORKFLOW_TOOL_NAMES],
-        forbiddenGsdTools: {
-            gsd_exec: "Use gsd_uat_exec so acceptance evidence is typed as UAT-owned.",
-            gsd_save_gate_result: "gsd_uat_result_save owns the aggregate UAT gate.",
-            gsd_summary_save: "gsd_uat_result_save owns persisted UAT Assessment writes.",
-        },
-    },
-    "gate-evaluate": {
-        allowedGsdTools: ["gsd_save_gate_result"],
-        requiredWorkflowTools: ["gsd_save_gate_result"],
-    },
-    "rewrite-docs": {
-        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
-        requiredWorkflowTools: [],
-    },
-    "workflow-preferences": {
-        allowedGsdTools: ["gsd_summary_save"],
-        requiredWorkflowTools: [],
-    },
-    "discuss-project": {
-        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save", "gsd_requirement_save"],
-        requiredWorkflowTools: ["ask_user_questions", "gsd_summary_save"],
-    },
-    "discuss-requirements": {
-        allowedGsdTools: ["gsd_requirement_save", "gsd_summary_save"],
-        requiredWorkflowTools: ["ask_user_questions", "gsd_requirement_save", "gsd_summary_save"],
-    },
-    "research-decision": {
-        allowedGsdTools: ["gsd_summary_save"],
-        requiredWorkflowTools: ["ask_user_questions"],
-    },
-    "research-project": {
-        allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
-        requiredWorkflowTools: [],
-    },
-};
+export const UNIT_TOOL_CONTRACTS = Object.fromEntries(Object.entries(UNIT_REGISTRY).flatMap(([unitType, descriptor]) => descriptor.toolContract ? [[unitType, descriptor.toolContract]] : []));
 export const AUTO_UNIT_SCOPED_TOOLS = Object.fromEntries(Object.entries(UNIT_TOOL_CONTRACTS).map(([unitType, contract]) => [unitType, contract.allowedGsdTools]));
 export function getUnitToolSurfaceContract(unitType) {
     return UNIT_TOOL_CONTRACTS[unitType];

package/dist/resources/extensions/gsd/verdict-parser.js

@@ -128,7 +128,7 @@ export function isValidMilestoneVerdict(verdict) {
  * Extract the UAT type from content, defaulting to `"artifact-driven"`.
  *
  * The `"artifact-driven"` fallback is the original default used throughout
- * the codebase when a UAT file lacks an explicit `## UAT Type` section.
+ * the codebase when a UAT file has no parseable UAT mode declaration.
  */
 export function getUatType(content) {
     return getDeclaredUatType(content);

package/dist/resources/extensions/gsd/web-app-uat.js

@@ -1,8 +1,10 @@
 // Project/App: gsd-pi
-// File Purpose: Web-app detection and Playwright/UAT guidance for planning and slice closeout.
+// File Purpose: Web-app detection and browser-UAT guidance for planning and slice closeout.
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { resolveAmbientBrowserEngineResolution } from "../browser-tools/engine/selection.js";
 import { detectWebApp } from "../browser-tools/web-app-detect.js";
+import { UAT_MODE_POLICIES } from "./uat-policy.js";
 export { detectWebApp };
 function readPackageJson(projectRoot) {
     const packageJsonPath = resolve(projectRoot, "package.json");
@@ -39,24 +41,56 @@ export function findPlaywrightTestScript(projectRoot) {
     }
     return null;
 }
+function describeBrowserToolBacking(engineResolution) {
+    switch (engineResolution.engine) {
+        case "gsd-browser":
+            return "This project looks browser-facing. GSD exposes `browser_*` tools backed by the managed gsd-browser engine for run-uat.";
+        case "legacy":
+            return "This project looks browser-facing. GSD exposes Playwright-backed `browser_*` tools for run-uat.";
+        case "off":
+            return "This project looks browser-facing, but Pi browser tools are disabled (GSD_BROWSER_ENGINE=off) — prefer `runtime-executable` UAT with automated browser test commands.";
+    }
+}
+// One bullet per recommended UAT mode; `mode` keys into UAT_MODE_POLICIES so
+// modes that require browser tools drop out of the guidance when the resolved
+// engine provides none (mixed/live-runtime share one bullet and one policy bit).
+const UAT_MODE_GUIDANCE = [
+    {
+        mode: "browser-executable",
+        bullet: "- `browser-executable` — navigate to `http://localhost:…`, click, screenshot, assert via `browser_*` tools during run-uat",
+    },
+    {
+        mode: "runtime-executable",
+        bullet: "- `runtime-executable` — run an automated browser test command via `gsd_uat_exec` (for example `npx playwright test`)",
+    },
+    {
+        mode: "mixed",
+        bullet: "- `mixed` / `live-runtime` — combine runtime startup checks with interactive browser verification",
+    },
+];
 /**
  * Markdown block injected into plan/complete-slice prompts when the project
- * looks browser-facing. Returns null for CLI/library-only repos.
+ * looks browser-facing. Returns null for CLI/library-only repos. Guidance is
+ * composed from the resolved Browser Automation Engine so prompts never claim
+ * an engine the runtime is not using; `engineResolution` is injectable for
+ * tests and defaults to the ambient resolution.
  */
-export function buildWebAppUatGuidanceBlock(projectRoot) {
+export function buildWebAppUatGuidanceBlock(projectRoot, engineResolution) {
     if (!detectWebApp(projectRoot))
         return null;
+    const resolvedEngine = engineResolution ?? resolveAmbientBrowserEngineResolution(projectRoot);
+    const browserToolsAvailable = resolvedEngine.engine !== "off";
     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.",
+        describeBrowserToolBacking(resolvedEngine),
         "",
         "**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",
+        ...UAT_MODE_GUIDANCE
+            .filter(({ mode }) => browserToolsAvailable || !UAT_MODE_POLICIES[mode].browserTools)
+            .map(({ bullet }) => bullet),
         "",
         "**Planning / closeout rules:**",
         "- Preconditions must name the dev-server command and URL (for example `npm run dev` → `http://localhost:3000`)",
@@ -74,7 +108,10 @@ export function buildWebAppUatGuidanceBlock(projectRoot) {
         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");
+        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");
+        if (browserToolsAvailable) {
+            lines.push("- Until specs exist, use `browser-executable` UAT with localhost preconditions and interactive `browser_*` checks at slice closeout");
+        }
     }
     return lines.join("\n");
 }

package/dist/resources/extensions/gsd/workflow-tool-surface.js

@@ -8,7 +8,7 @@ export const WORKFLOW_TOOL_ALIAS_NAMES = CONTRACT_WORKFLOW_TOOL_ALIAS_NAMES;
 export const DB_WORKFLOW_TOOL_NAMES = CONTRACT_WORKFLOW_TOOL_NAMES;
 export const WORKFLOW_TOOL_ALIAS_PAIRS = WORKFLOW_TOOL_CONTRACTS.flatMap((tool) => tool.aliases.map((alias) => ({ canonical: tool.canonicalName, alias })));
 export const WORKFLOW_TOOL_ALIAS_TO_CANONICAL = Object.fromEntries(WORKFLOW_TOOL_ALIAS_PAIRS.map(({ alias, canonical }) => [alias, canonical]));
-const WORKFLOW_MCP_ADAPTER_TOOL_NAMES = [
+export const WORKFLOW_MCP_ADAPTER_TOOL_NAMES = [
     "gsd_cancel",
     "gsd_captures",
     "ask_user_questions",