@tekyzinc/gsd-t 3.21.12 → 3.22.11

package/CHANGELOG.md

@@ -2,6 +2,70 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [3.22.11] - 2026-05-06
+
+### Fixed — viewer Playwright specs are now actually rigorous + adversarially proven (M51)
+
+The 5 viewer specs shipped in M50 used substring/existence assertions that would pass on a broken implementation — exactly the M48 BUG-3 LOW pattern that was flagged but never propagated forward. M51 strengthens all 5 specs to outcome-based assertions and proves they catch broken implementations via an adversarial Red Team that writes deliberately-broken viewer code and verifies the specs fail.
+
+**Changes:**
+- `e2e/viewer/title.spec.ts`: exact `<title>` equality (not regex); literal `$&` backref defence positive test using a fixture dir literally renamed to contain `$&`.
+- `e2e/viewer/timestamps.spec.ts`: `distinct.size === 3` exactly (not `>= 2`); each rendered timestamp matches the actual `frame.ts` wall-clock value; new missing-`ts` fallback test exercises `arrivedAt` branch.
+- `e2e/viewer/chat-bubbles.spec.ts`: CSS class membership assertions (`.frame.user.user-turn`, `.frame.assistant-turn`, etc.); structural assertions on `.body`/`.prefix`/`.badge`/`.truncated-tag`; `tool_use` 4th renderer coverage.
+- `e2e/viewer/dual-pane.spec.ts`: TEST-M50-001 fix — `MutationObserver` per pane attributes frames by DOM target instead of filtering raw URLs (top pane's `connectMain` URL legitimately contains the in-session id); positive top-pane SSE assertion; hashchange-doesn't-pin-bottom test.
+- `e2e/viewer/lazy-dashboard.spec.ts`: exact regex on banner shape (not substring); dead-pid branch coverage (today's spec only had live + missing).
+- `.gsd-t/red-team-report.md`: new "M51 RED TEAM FINDINGS" section enumerating 5 broken-viewer adversary attempts and confirming all 5 caught.
+- Bonus: fixture port allocation switched from `Math.random()*100` to `port: 0` + `server.address().port` readback (eliminates EADDRINUSE collisions across parallel Playwright workers).
+
+**Adversarial Red Team result:** 5 broken viewer impls written, 5 caught by strengthened specs. Production viewer code unchanged — this was pure test-suite rigor work, no real app bugs found behind adversary patches.
+
+**Suite:** 2166/2166 pass; E2E 19/19 pass (was 9 — 5 specs grew from 9 tests to 19).
+
+**Migration:** none. Specs are stricter; existing v3.22.10 viewer continues to pass.
+
+## [3.22.10] — M50 Universal Playwright Bootstrap + Deterministic UI Enforcement
+
+### Added — three deterministic enforcement layers replace prose-only Playwright Readiness Guard
+
+Closes the gap that allowed M48 viewer fixes to ship without Playwright tests despite the existing prose Readiness Guard. Prior pattern was prose in `~/.claude/CLAUDE.md` + per-command-file reminders that agents could read and decide to skip. M50 converts every layer to executable code so agents cannot self-approve their way around it.
+
+**Layer 1 — Bootstrap library (D1):**
+- `bin/playwright-bootstrap.cjs` (new) — `hasPlaywright`, `detectPackageManager`, `installPlaywright`, `installPlaywrightSync`, `verifyPlaywrightHealth`. Idempotent installer: detects package manager (npm/pnpm/yarn/bun), installs `@playwright/test` + chromium, writes `playwright.config.ts` from a single-source template (contract §6), scaffolds `e2e/__placeholder.spec.ts`. Preserves existing config + e2e contents on re-run. Error classifier maps subprocess stderr to `{package-manager-not-found, network, chromium, disk}` with caller-actionable hints; chromium-failure surfaces `partial: true`. Zero external runtime deps.
+- `bin/ui-detection.cjs` (new) — `hasUI`, `detectUIFlavor`. Synchronous, depth-bounded ≤3 BFS, never throws. Detects React/Vue/Svelte/Next/Angular/Flutter/Tailwind via `package.json`, `pubspec.yaml`, `tailwind.config.{js,ts,mjs,cjs}`, or any UI extension (`.tsx`/`.jsx`/`.vue`/`.svelte`/`.css`/`.scss`).
+- `bin/gsd-t.js`: inline `hasPlaywright` (was lines 201-204) replaced with `require('./playwright-bootstrap.cjs')`. `init` flow auto-installs Playwright when `hasUI && !hasPlaywright`. `update-all` auto-installs across all registered UI projects + reports counts (`Auto-installed Playwright in: N project(s)`). New `gsd-t setup-playwright [path] [--force]` subcommand. New `gsd-t doctor --install-playwright` flag. New `gsd-t doctor --install-hooks` flag (D2).
+
+**Layer 2 — Spawn-time gate (D2):**
+- `bin/headless-auto-spawn.cjs::autoSpawnHeadless()`: new gate runs before the spawn. When the command is in the `TESTING_OR_UI_COMMANDS` whitelist (9 commands: execute, test-sync, verify, quick, wave, milestone, complete-milestone, debug, integrate) AND `hasUI(projectDir)` AND `!hasPlaywright(projectDir)`, the gate calls `installPlaywrightSync(projectDir)` synchronously. On install failure, writes `mode: 'blocked-needs-human'` + `reason: 'playwright-install-failed'` to the headless session-state file and exits 4. Hot path: three filesystem checks; no install attempt when gate doesn't fire.
+
+**Layer 3 — Commit-time gate (D2):**
+- `scripts/hooks/pre-commit-playwright-gate` (new, executable bash) — opt-in via `gsd-t doctor --install-hooks`. Reads `.gsd-t/.last-playwright-pass` (Unix epoch ms in a single line). Detects staged viewer-source files (`scripts/gsd-t-transcript.html`, `scripts/gsd-t-dashboard-server.js`, `e2e/viewer/**`); if any file's mtime exceeds the last-pass timestamp, blocks the commit (exit 1 + clear stderr message). Fails open on missing/corrupt timestamps — broken hook is worse than a permissive one.
+
+**E2E specs delivered (the M47/M48/M49 viewer specs we owed):**
+- `playwright.config.ts` (root) — testDir `./e2e`, chromium project, `webServer` omitted (specs manage their own server lifecycle).
+- `e2e/viewer/title.spec.ts` — M48 Bug 1 regression (project basename in `<title>` + header `.title` for `/transcripts` and `/transcripts/{spawn-id}`).
+- `e2e/viewer/timestamps.spec.ts` — M48 Bug 2 regression (per-frame `frame.ts`, not per-batch `new Date()`).
+- `e2e/viewer/chat-bubbles.spec.ts` — M48 Bug 3 regression (`user_turn`/`assistant_turn`/`session_start`/`tool_use_line` render as bubbles, not JSON.stringify dumps).
+- `e2e/viewer/dual-pane.spec.ts` — M48 Bug 4 regression (bottom pane never connects to in-session-* SSE).
+- `e2e/viewer/lazy-dashboard.spec.ts` — M49 banner regression (file-path + visualize hint when no dashboard; URL when alive).
+
+**Tests:**
+- `test/m50-d1-ui-detection.test.js` — 18 unit tests (8 mandatory fixtures + 4 hardening + 6 Red Team regressions).
+- `test/m50-d1-playwright-bootstrap.test.js` — 20 unit tests (`hasPlaywright`, `detectPackageManager`, `verifyPlaywrightHealth`, 9 install-path branches).
+- `test/m50-d1-cli-integration.test.js` — 5 CLI wire-up tests (re-export, init gate, doctor flag, setup-playwright).
+- `test/m50-d2-viewer-specs-smoke.test.js` — 4 meta-tests (config + scripts + zero-runtime-dep invariant).
+- `test/m50-d2-spawn-gate.test.js` — 9 gate-firing matrix tests (whitelist + 5 firing scenarios + hot-path overhead).
+- `test/m50-d2-pre-commit-hook.test.js` — 6 hook-behavior tests (clean / blocked / fresh / missing / corrupt / e2e/viewer pattern).
+
+Total: 62 new M50 tests; full suite 2163/2166 (3 pre-existing env-flakes preserved). Zero regressions.
+
+**Doc-ripple:**
+- `~/.claude/CLAUDE.md` § Playwright Readiness Guard — collapsed to a layered referral.
+- `templates/CLAUDE-global.md` — mirror.
+- `commands/gsd-t-init.md` Step 11 — points at `installPlaywright()` instead of carrying inline package-manager commands.
+- `docs/architecture.md` — new "Playwright Deterministic Enforcement (M50)" subsection.
+- `.gsd-t/contracts/playwright-bootstrap-contract.md` v1.0.0 — new contract.
+- `.gsd-t/contracts/m50-integration-points.md` — D1→D2 checkpoint flipped to PUBLISHED.
+
 ## [3.21.12] - 2026-05-06
 
 ### Fixed — dashboard orphan accumulation (M49 lazy autostart + idle-TTL + doctor-prune)

package/README.md

@@ -16,6 +16,7 @@ A methodology for reliable, parallelizable development using Claude Code with op
 **External Task Orchestrator + Streaming Watcher UI (M40, v3.14.10)** — JS orchestrator drives `claude -p` one task per spawn: short-lived, fresh context, architecturally compaction-free. Benchmarks 0.72× wall-clock vs in-session on 20-task/3-wave workloads. Paired with a zero-Claude-cost local streaming UI at `127.0.0.1:7842` that renders all workers' stream-json output as a continuous claude.ai-style feed — task/wave banners, duration + usage chips, token corner bar, localStorage filters, replay via `WS /feed?from=N`. Recovery: `--resume` reconciles interrupted runs using commit + progress.md evidence; ambiguous tasks (commit without progress entry) are flagged for operator triage, never silently claimed done. CLI: `gsd-t orchestrate`, `gsd-t benchmark-orchestrator`, `gsd-t stream-feed`. Contracts: `stream-json-sink-contract.md` v1.1.0, `wave-join-contract.md`, `completion-signal-contract.md`, `metrics-schema-contract.md`.
 **Always-Headless Spawn (M43 D4, v3.16.x+) — Channel Separation** — every GSD-T command spawns detached, unconditionally. No `--watch`, no `--in-session`, no `--headless` opt-in, no context-meter threshold that reroutes. The dialog channel is reserved for human↔Claude conversation; every workflow turn is a detached headless child. Interactive session shows a launch banner + live-transcript URL + event-stream path, then exits — results surface via the read-back banner on the user's next message. Detached workers emit JSONL events to `.gsd-t/events/YYYY-MM-DD.jsonl` at every phase boundary — shared by dashboard and (historically) the watch command. The only in-session surface is the `/gsd` router (for dialog-only exploratory turns). See `.gsd-t/contracts/headless-default-contract.md` v2.0.0 and `unattended-event-stream-contract.md` v1.0.0.
 **Live Transcript as Primary Surface (M43 D6, v3.16.13 — extended in M47, v3.21.10)** — every detached spawn prints a one-line banner (`▶ Live transcript: http://127.0.0.1:{port}/transcript/{id}`) pointing at a browser viewer that SSE-streams the child's stdout and renders a collapsible "Tool Cost" sidebar panel showing per-tool attributed tokens and cost (sourced from `/transcript/:id/tool-cost`, which proxies to the M43 D2 tool-attribution library). The dashboard server auto-starts (`scripts/gsd-t-dashboard-autostart.cjs`) idempotently on each spawn — a port probe backs off when a server is already running, otherwise a fork-detach writes `.gsd-t/.dashboard.pid`. Port is project-scoped via `projectScopedDefaultPort(projectDir)` so multi-project workflows don't clobber each other.
+**Universal Playwright Bootstrap + Deterministic UI Enforcement (M50, v3.22.10)** — converts the prose-only "Playwright Readiness Guard" into three executable enforcement layers so agents cannot skip UI tests. Layer 1: `bin/playwright-bootstrap.cjs` + `bin/ui-detection.cjs` wired into `init`/`update-all`/`doctor`/new `gsd-t setup-playwright [path]` subcommand — idempotent installer detects package manager, installs `@playwright/test` + chromium, writes config from a contract-locked template, scaffolds `e2e/`. Layer 2: `bin/headless-auto-spawn.cjs::autoSpawnHeadless()` auto-installs before any of 9 whitelisted testing/UI commands when `hasUI && !hasPlaywright`; install failure → `mode: 'blocked-needs-human'` exit-4. Layer 3: `scripts/hooks/pre-commit-playwright-gate` (opt-in via `gsd-t doctor --install-hooks`) reads `.gsd-t/.last-playwright-pass` and blocks viewer-source commits when staged files are newer than the last playwright test pass. Also ships the M47/M48/M49 E2E viewer specs (`e2e/viewer/title`, `timestamps`, `chat-bubbles`, `dual-pane`, `lazy-dashboard`). 62 new unit tests; E2E 8/9 pass.
 **Focused Visualizer Redesign (M47, v3.21.10)** — `/transcripts` opens directly to a dual-pane focused view: the **top pane** auto-streams the orchestrator's main in-session conversation (zero clicks — fetched via new `GET /api/main-session`), and the **bottom pane** streams whichever spawn the user clicks. A keyboard- and mouse-resizable splitter sits between them, with position persisted in `sessionStorage` (along with selection, completed-section toggle, and right-rail collapsed state). The left rail splits into three sections — `★ Main Session`, `Live Spawns`, and `Completed` (last 100 spawns, newest first, status-badged, collapsible). When a spawn transitions running → completed it moves rail sections live without a full reload, and stays selected if focused. The right rail (Spawn Plan / Parallelism / Tool Cost) is preserved under a new collapsible toggle. Bookmarks to `/transcript/:spawnId` continue to land that spawn pre-selected in the bottom pane. Contract: `dashboard-server-contract.md` v1.3.0 (additive — `status: 'active' \| 'completed'` field on in-session entries, derived from a 30s mtime window; `/api/main-session` endpoint with path-traversal guard + `Cache-Control: no-store`).
 - **Surgical model selection** — `bin/model-selector.js` assigns haiku/sonnet/opus per phase via a declarative rules table; `/advisor` escalation path with convention-based fallback.
 - **Per-spawn token telemetry** — `.gsd-t/token-metrics.jsonl` records one 18-field row per Task subagent spawn.

package/bin/gsd-t.js

@@ -198,10 +198,15 @@ function copyFile(src, dest, label) {
   }
 }
 
-function hasPlaywright(projectDir) {
-  const configs = ["playwright.config.ts", "playwright.config.js", "playwright.config.mjs"];
-  return configs.some((f) => fs.existsSync(path.join(projectDir, f)));
-}
+// M50 D1: hasPlaywright migrated to bin/playwright-bootstrap.cjs.
+// Re-exported here for back-compat with any caller still requiring it via
+// bin/gsd-t.js. See .gsd-t/contracts/playwright-bootstrap-contract.md §3.
+const {
+  hasPlaywright,
+  installPlaywright,
+  detectPackageManager: _detectPlaywrightPackageManager,
+} = require("./playwright-bootstrap.cjs");
+const { hasUI } = require("./ui-detection.cjs");
 
 function readProjectDeps(projectDir) {
   const pkgPath = path.join(projectDir, "package.json");
@@ -571,6 +576,47 @@ function installContextMeter(projectDir) {
 // to .git/hooks/pre-commit; if the file doesn't exist, copies our stock
 // script. Never overwrites an existing hook.
 const CAPTURE_LINT_HOOK_MARKER = "# GSD-T capture lint";
+// M50 D2 — Playwright pre-commit gate marker. Installed via
+// `gsd-t doctor --install-hooks`. Idempotent: appends a delimited block to
+// `.git/hooks/pre-commit` if the marker isn't already present.
+const PLAYWRIGHT_GATE_HOOK_MARKER = "# GSD-T playwright gate";
+
+function installPlaywrightGateHook(projectDir) {
+  const gitDir = path.join(projectDir, ".git");
+  if (!fs.existsSync(gitDir)) {
+    warn("No .git directory — not a git repo; skipping playwright-gate install");
+    return false;
+  }
+  const hooksDir = path.join(gitDir, "hooks");
+  try { fs.mkdirSync(hooksDir, { recursive: true }); } catch (_) {}
+  const hookPath = path.join(hooksDir, "pre-commit");
+  const stockSrc = path.join(PKG_ROOT, "scripts", "hooks", "pre-commit-playwright-gate");
+  let stock = "";
+  try { stock = fs.readFileSync(stockSrc, "utf8"); } catch (_) {
+    warn("Could not read pre-commit-playwright-gate script from package");
+    return false;
+  }
+  if (!fs.existsSync(hookPath)) {
+    fs.writeFileSync(hookPath, stock);
+    try { fs.chmodSync(hookPath, 0o755); } catch (_) {}
+    success(`Playwright gate installed at ${path.relative(projectDir, hookPath)}`);
+    info("The hook reads .gsd-t/.last-playwright-pass to gate viewer-source commits");
+    return true;
+  }
+  const existing = fs.readFileSync(hookPath, "utf8");
+  if (existing.includes(PLAYWRIGHT_GATE_HOOK_MARKER)) {
+    info("Playwright-gate block already present in pre-commit hook — no change");
+    return true;
+  }
+  const appended = existing.trimEnd() +
+    "\n\n" + PLAYWRIGHT_GATE_HOOK_MARKER + "\n" +
+    stock.replace(/^#!.*\n/, "") + "\n";
+  fs.writeFileSync(hookPath, appended);
+  try { fs.chmodSync(hookPath, 0o755); } catch (_) {}
+  success(`Playwright-gate block appended to ${path.relative(projectDir, hookPath)}`);
+  return true;
+}
+
 function installCaptureLintHook(projectDir) {
   const gitDir = path.join(projectDir, ".git");
   if (!fs.existsSync(gitDir)) {
@@ -1655,6 +1701,25 @@ async function doInit(projectName) {
 
   if (registerProject(projectDir)) success("Registered in ~/.claude/.gsd-t-projects");
 
+  // M50 D1: Universal Playwright bootstrap. If the project has UI signal but
+  // no playwright.config.*, install @playwright/test + chromium and scaffold
+  // playwright.config.ts + e2e/. See playwright-bootstrap-contract.md §5.
+  if (hasUI(projectDir) && !hasPlaywright(projectDir)) {
+    info("Installing Playwright (chromium)…");
+    try {
+      const r = await installPlaywright(projectDir);
+      if (r.ok) {
+        success("Playwright installed (playwright.config.ts + e2e/ scaffold)");
+      } else {
+        warn(`Playwright install failed: ${r.err}`);
+        if (r.hint) info(r.hint);
+      }
+    } catch (e) {
+      warn(`Playwright install errored: ${e.message || e}`);
+      info("Re-run with: gsd-t doctor --install-playwright");
+    }
+  }
+
   showInitTree(projectDir);
 }
 
@@ -1968,10 +2033,12 @@ function createProjectChangelog(projectDir, projectName) {
   }
 }
 
-function checkProjectHealth(projects) {
+async function checkProjectHealth(projects) {
   heading("Project Health");
   const playwrightMissing = [];
   const swaggerMissing = [];
+  const playwrightAutoInstalled = [];
+  const playwrightInstallFailed = [];
 
   for (const projectDir of projects) {
     if (!fs.existsSync(projectDir)) continue;
@@ -1980,19 +2047,56 @@ function checkProjectHealth(projects) {
     if (hasApi(projectDir) && !hasSwagger(projectDir)) swaggerMissing.push(name);
   }
 
+  // M50 D1: auto-install Playwright for any UI project that's missing it.
+  // Non-UI projects stay missing — they don't need Playwright.
+  for (const projectDir of projects) {
+    if (!fs.existsSync(projectDir)) continue;
+    if (hasPlaywright(projectDir)) continue;
+    if (!hasUI(projectDir)) continue;
+    const name = path.basename(projectDir);
+    try {
+      const r = await installPlaywright(projectDir);
+      if (r.ok) playwrightAutoInstalled.push(name);
+      else playwrightInstallFailed.push({ name, err: r.err, hint: r.hint });
+    } catch (e) {
+      playwrightInstallFailed.push({ name, err: e.message || String(e) });
+    }
+  }
+
   if (playwrightMissing.length === 0 && swaggerMissing.length === 0) {
     success("All projects have Playwright and Swagger configured");
   } else {
     if (playwrightMissing.length > 0) {
       warn(`Playwright missing: ${playwrightMissing.join(", ")}`);
-      info("Playwright will be auto-installed when you run a GSD-T command in each project");
+      if (playwrightAutoInstalled.length > 0) {
+        success(`Auto-installed Playwright in: ${playwrightAutoInstalled.join(", ")}`);
+      }
+      if (playwrightInstallFailed.length > 0) {
+        for (const f of playwrightInstallFailed) {
+          warn(`  ${f.name} — install failed: ${f.err}`);
+          if (f.hint) info(`  ${f.hint}`);
+        }
+      }
+      const stillMissing = playwrightMissing.filter(
+        (n) => !playwrightAutoInstalled.includes(n),
+      );
+      if (stillMissing.length > 0) {
+        info(
+          `Remaining (no UI signal — skipped): ${stillMissing.join(", ")}`,
+        );
+      }
     }
     if (swaggerMissing.length > 0) {
       warn(`Swagger/OpenAPI missing (API detected): ${swaggerMissing.join(", ")}`);
       info("Swagger will be auto-configured when an API endpoint is created or modified");
     }
   }
-  return { playwrightMissing, swaggerMissing };
+  return {
+    playwrightMissing,
+    swaggerMissing,
+    playwrightAutoInstalled,
+    playwrightInstallFailed,
+  };
 }
 
 // ── Global Rule Sync (M27) ──────────────────────────────────────────────────
@@ -2163,8 +2267,19 @@ async function doUpdateAll() {
   // Global rule sync — propagate proven rules across projects
   const syncCount = syncGlobalRules(projects);
 
-  const { playwrightMissing, swaggerMissing } = checkProjectHealth(projects);
-  showUpdateAllSummary(projects.length, counts, playwrightMissing, swaggerMissing, syncCount);
+  const {
+    playwrightMissing,
+    swaggerMissing,
+    playwrightAutoInstalled,
+  } = await checkProjectHealth(projects);
+  showUpdateAllSummary(
+    projects.length,
+    counts,
+    playwrightMissing,
+    swaggerMissing,
+    syncCount,
+    playwrightAutoInstalled,
+  );
 }
 
 // Upgrade the globally-installed @tekyzinc/gsd-t to @latest. Returns
@@ -2510,7 +2625,14 @@ function ensureUnattendedGitignore(projectDir, projectName) {
   return added;
 }
 
-function showUpdateAllSummary(total, counts, playwrightMissing, swaggerMissing, syncCount) {
+function showUpdateAllSummary(
+  total,
+  counts,
+  playwrightMissing,
+  swaggerMissing,
+  syncCount,
+  playwrightAutoInstalled,
+) {
   log("");
   heading("Update All Complete");
   log(`  Projects registered: ${total}`);
@@ -2519,6 +2641,9 @@ function showUpdateAllSummary(total, counts, playwrightMissing, swaggerMissing,
   if (counts.missing > 0) log(`  Not found:           ${counts.missing}`);
   if (counts.errors > 0) log(`  Errors:              ${counts.errors}`);
   if (playwrightMissing.length > 0) log(`  Missing Playwright:  ${playwrightMissing.length}`);
+  if (Array.isArray(playwrightAutoInstalled) && playwrightAutoInstalled.length > 0) {
+    log(`  Auto-installed Playwright in: ${playwrightAutoInstalled.length} project(s)`);
+  }
   if (swaggerMissing.length > 0) log(`  Missing Swagger:     ${swaggerMissing.length}`);
   if (syncCount > 0) log(`  Global rules synced: ${syncCount}`);
   log("");
@@ -2604,14 +2729,32 @@ function checkDoctorEncoding(installed) {
   return 0;
 }
 
-function checkDoctorProject() {
+async function checkDoctorProject(opts) {
   let issues = 0;
   const cwd = process.cwd();
+  const installFlag = !!(opts && opts.installPlaywright);
   if (hasPlaywright(cwd)) {
     success("Playwright configured");
+  } else if (installFlag && hasUI(cwd)) {
+    info("Installing Playwright (chromium)…");
+    try {
+      const r = await installPlaywright(cwd);
+      if (r.ok) {
+        success("Playwright installed (playwright.config.ts + e2e/ scaffold)");
+      } else {
+        error(`Playwright install failed: ${r.err}`);
+        if (r.hint) info(r.hint);
+        issues++;
+      }
+    } catch (e) {
+      error(`Playwright install errored: ${e.message || e}`);
+      issues++;
+    }
+  } else if (installFlag && !hasUI(cwd)) {
+    info("Playwright skipped — no UI signal in this project");
   } else {
     warn("Playwright not configured in this project");
-    info("Will be auto-installed when you run a GSD-T testing command");
+    info("Re-run with --install-playwright, or run any GSD-T testing command (auto-install)");
     issues++;
   }
   if (hasApi(cwd)) {
@@ -2902,10 +3045,16 @@ async function doDoctor(opts) {
   let issues = 0;
   issues += checkDoctorEnvironment();
   issues += checkDoctorInstallation();
-  issues += checkDoctorProject();
+  issues += await checkDoctorProject(opts);
   issues += checkDoctorCgc();
   issues += await checkDoctorContextMeter(process.cwd());
   issues += checkDoctorDashboardOrphans(opts);
+  // M50 D2: opt-in install of the playwright-gate pre-commit hook.
+  if (opts && opts.installHooks) {
+    log("");
+    heading("Installing pre-commit hooks");
+    installPlaywrightGateHook(process.cwd());
+  }
   log("");
   if (issues === 0) {
     log(`${GREEN}${BOLD}  All checks passed!${RESET}`);
@@ -4176,13 +4325,51 @@ if (require.main === module) {
       doUninstall();
       break;
     case "doctor": {
-      const doctorOpts = { prune: false };
+      const doctorOpts = { prune: false, installPlaywright: false, installHooks: false };
       for (let i = 1; i < args.length; i++) {
         if (args[i] === "--prune") doctorOpts.prune = true;
+        if (args[i] === "--install-playwright") doctorOpts.installPlaywright = true;
+        if (args[i] === "--install-hooks") doctorOpts.installHooks = true;
       }
       doDoctor(doctorOpts).catch((e) => { error(e.message || String(e)); process.exit(1); });
       break;
     }
+    case "setup-playwright": {
+      // Single-project explicit installer. Thin wrapper around installPlaywright().
+      const targetDir = args[1] && !args[1].startsWith("-") ? path.resolve(args[1]) : process.cwd();
+      heading(`Setup Playwright: ${targetDir}`);
+      log("");
+      if (!fs.existsSync(targetDir)) {
+        error(`Path not found: ${targetDir}`);
+        process.exit(1);
+      }
+      if (hasPlaywright(targetDir)) {
+        info("Playwright already configured (playwright.config.* present)");
+        process.exit(0);
+      }
+      if (!hasUI(targetDir)) {
+        warn("No UI signal detected. Installing anyway? Re-run with --force to install regardless.");
+        const force = args.includes("--force");
+        if (!force) {
+          info("Skipping. Use --force to install Playwright in a non-UI project.");
+          process.exit(0);
+        }
+      }
+      info("Installing Playwright (chromium)…");
+      installPlaywright(targetDir)
+        .then((r) => {
+          if (r.ok) {
+            success("Playwright installed (playwright.config.ts + e2e/ scaffold)");
+            process.exit(0);
+          } else {
+            error(`Playwright install failed: ${r.err}`);
+            if (r.hint) info(r.hint);
+            process.exit(1);
+          }
+        })
+        .catch((e) => { error(e.message || String(e)); process.exit(1); });
+      break;
+    }
     case "changelog":
       doChangelog();
       break;

package/bin/headless-auto-spawn.cjs

@@ -42,6 +42,31 @@ const {
 const SESSIONS_DIR_REL = path.join(".gsd-t", "headless-sessions");
 const LOG_DIR_REL = ".gsd-t"; // headless-{id}.log lives directly in .gsd-t
 
+// M50 D2 — Whitelist of commands that touch UI / tests. Centralized constant
+// referenced by the spawn-gate (`_isTestingOrUICommand`). When any of these
+// commands is about to spawn for a project where `hasUI(projectDir) === true`
+// and `hasPlaywright(projectDir) === false`, the gate auto-installs Playwright
+// before the spawn proceeds. See playwright-bootstrap-contract.md §3 +
+// m50-integration-points.md "E2E Specs Server Lifecycle".
+const TESTING_OR_UI_COMMANDS = new Set([
+  "gsd-t-execute",
+  "gsd-t-test-sync",
+  "gsd-t-verify",
+  "gsd-t-quick",
+  "gsd-t-wave",
+  "gsd-t-milestone",
+  "gsd-t-complete-milestone",
+  "gsd-t-debug",
+  "gsd-t-integrate",
+]);
+
+function _isTestingOrUICommand(command) {
+  if (typeof command !== "string" || !command) return false;
+  // Accept both raw command names and prefixed variants ("execute" or "gsd-t-execute").
+  const normalized = command.startsWith("gsd-t-") ? command : `gsd-t-${command}`;
+  return TESTING_OR_UI_COMMANDS.has(normalized);
+}
+
 // ── Exports ──────────────────────────────────────────────────────────────────
 
 module.exports = {
@@ -57,6 +82,9 @@ module.exports = {
   shouldSpawnHeadless: () => true,
   // M49 — exported for tests. Synchronous probe; never throws.
   _probeDashboardLazy,
+  // M50 D2 — exported for tests. Whitelist + classifier, both synchronous.
+  TESTING_OR_UI_COMMANDS,
+  _isTestingOrUICommand,
 };
 
 // M43 D4 — one-shot deprecation banner when a caller still passes `watch`
@@ -121,6 +149,99 @@ function autoSpawnHeadless(opts) {
     );
   }
 
+  // M50 D2 — Spawn-time Playwright gate. When the command being spawned is a
+  // testing/UI-touching command AND the project has a UI signal AND there's
+  // no playwright.config.* yet, auto-install Playwright before the spawn
+  // proceeds. On install failure, write a `mode: 'blocked-needs-human'`
+  // session-state file (read by gsd-t-resume Step 0 + read-back banner) and
+  // exit 4. See playwright-bootstrap-contract.md §3 + §8 and
+  // m50-integration-points.md for the full protocol.
+  //
+  // Hot path: the gate evaluates `_isTestingOrUICommand` (Set lookup) →
+  // `hasUI` (depth-bounded fs walk) → `hasPlaywright` (existsSync). When the
+  // gate does NOT fire (non-testing command, non-UI project, or already
+  // configured), overhead is the cost of three fast filesystem checks.
+  // Tests inject `opts._gateInstaller` to substitute a stub installer; tests
+  // also inject `opts._gateProbes` to override `hasUI`/`hasPlaywright` for
+  // non-fixture-based assertions.
+  if (_isTestingOrUICommand(command)) {
+    const probes = (opts && opts._gateProbes) || null;
+    let projectHasUI;
+    let projectHasPlaywright;
+    try {
+      const ui = probes && probes.hasUI ? probes.hasUI : require("./ui-detection.cjs").hasUI;
+      const pw = probes && probes.hasPlaywright ? probes.hasPlaywright : require("./playwright-bootstrap.cjs").hasPlaywright;
+      projectHasUI = !!ui(projectDir);
+      projectHasPlaywright = !!pw(projectDir);
+    } catch (_e) {
+      // Probe failure → fail open: skip the gate. A broken probe is worse
+      // than a permissive one (we don't want to block every spawn on a stale
+      // import path).
+      projectHasUI = false;
+      projectHasPlaywright = true;
+    }
+    if (projectHasUI && !projectHasPlaywright) {
+      let installer;
+      try {
+        installer = (opts && opts._gateInstaller) ||
+          require("./playwright-bootstrap.cjs").installPlaywrightSync;
+      } catch (_e) {
+        installer = null;
+      }
+      if (typeof installer === "function") {
+        const result = installer(projectDir);
+        if (result && result.ok) {
+          try {
+            // Concise stdout signal so the user sees the gate fired.
+            process.stdout.write(
+              `▶ Playwright auto-installed (${path.relative(projectDir, path.join(projectDir, "playwright.config.ts"))})\n`,
+            );
+          } catch (_) { /* best-effort */ }
+        } else {
+          // Install failed → mode: 'blocked-needs-human', exit 4.
+          const blockedId = makeSessionId(command, new Date());
+          try {
+            ensureDir(path.join(projectDir, SESSIONS_DIR_REL));
+            writeSessionFile(projectDir, {
+              id: blockedId,
+              pid: null,
+              logPath: null,
+              startTimestamp: new Date().toISOString(),
+              command,
+              args,
+              status: "blocked",
+              mode: "blocked-needs-human",
+              reason: "playwright-install-failed",
+              err: (result && result.err) || "unknown",
+              hint: (result && result.hint) || null,
+              continueFromPath: continue_from,
+              surfaced: false,
+            });
+          } catch (_) { /* best-effort */ }
+          try {
+            process.stderr.write(
+              `[m50-spawn-gate] Playwright install failed (${(result && result.err) || "unknown"}). ` +
+              `Run \`gsd-t doctor --install-playwright\` to retry. Spawn aborted.\n`,
+            );
+          } catch (_) { /* best-effort */ }
+          // In test runs we don't want to actually exit the test harness;
+          // tests inject `opts._gateExit` to capture the exit instead.
+          if (opts && typeof opts._gateExit === "function") {
+            opts._gateExit(4);
+            return {
+              id: blockedId,
+              pid: null,
+              logPath: null,
+              timestamp: new Date().toISOString(),
+              mode: "blocked-needs-human",
+            };
+          }
+          process.exit(4);
+        }
+      }
+    }
+  }
+
   const timestamp = new Date().toISOString();
   const id = makeSessionId(command, new Date());
   const logPath = path.join(projectDir, LOG_DIR_REL, `headless-${id}.log`);

package/bin/playwright-bootstrap.cjs

@@ -0,0 +1,315 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { exec, spawn, spawnSync } = require('child_process');
+
+function hasPlaywright(projectDir) {
+  const configs = ['playwright.config.ts', 'playwright.config.js', 'playwright.config.mjs'];
+  try {
+    return configs.some((f) => fs.existsSync(path.join(projectDir, f)));
+  } catch (_) {
+    return false;
+  }
+}
+
+function detectPackageManager(projectDir) {
+  try {
+    if (fs.existsSync(path.join(projectDir, 'pnpm-lock.yaml'))) return 'pnpm';
+    if (fs.existsSync(path.join(projectDir, 'yarn.lock'))) return 'yarn';
+    if (fs.existsSync(path.join(projectDir, 'bun.lockb'))) return 'bun';
+  } catch (_) {
+    // fall through to default
+  }
+  return 'npm';
+}
+
+function verifyPlaywrightHealth(projectDir) {
+  return new Promise((resolve) => {
+    const child = exec(
+      'npx playwright --version',
+      { cwd: projectDir, timeout: 5000 },
+      (err, stdout, stderr) => {
+        if (err) {
+          resolve({ ok: false, error: stderr || err.message || String(err) });
+          return;
+        }
+        const match = (stdout || '').match(/Version\s+([\d.]+)/i);
+        if (match) {
+          resolve({ ok: true, version: match[1] });
+        } else {
+          resolve({ ok: false, error: 'Could not parse version from: ' + stdout.trim() });
+        }
+      },
+    );
+    // Belt-and-suspenders: exec timeout option should handle this, but guard anyway
+    child.on('error', (err) => {
+      resolve({ ok: false, error: err.message || String(err) });
+    });
+  });
+}
+
+// ── installPlaywright ────────────────────────────────────────────────────────
+//
+// Idempotent installer. Per playwright-bootstrap-contract.md §3 + §6 + §7 + §8.
+// Returns { ok: true } on success, { ok: false, err, hint } on failure.
+
+const PLAYWRIGHT_CONFIG_TEMPLATE = `import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: 'html',
+  use: {
+    baseURL: process.env.PLAYWRIGHT_BASE_URL ?? 'http://localhost:3000',
+    trace: 'on-first-retry',
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+  ],
+  // webServer is intentionally omitted — projects manage their own server lifecycle.
+});
+`;
+
+const PLACEHOLDER_SPEC_TEMPLATE = `import { test } from '@playwright/test';
+
+// Placeholder spec — replace with real specs when UI tests land.
+test.skip('placeholder', () => {});
+`;
+
+const INSTALL_COMMANDS = {
+  npm: { cmd: 'npm', args: ['install', '-D', '@playwright/test'] },
+  pnpm: { cmd: 'pnpm', args: ['add', '-D', '@playwright/test'] },
+  yarn: { cmd: 'yarn', args: ['add', '-D', '@playwright/test'] },
+  bun: { cmd: 'bun', args: ['add', '-d', '@playwright/test'] },
+};
+
+function _classifyError(stderr, code, command) {
+  const text = String(stderr || '').toLowerCase();
+  if (code === 127 || /command not found|enoent|not recognized|spawn .* enoent/i.test(text)) {
+    return {
+      err: 'package-manager-not-found',
+      hint: 'Install the package manager (' + command + ') and re-run: gsd-t doctor --install-playwright',
+    };
+  }
+  if (/network|registry|getaddrinfo|enotfound|econnrefused|etimedout|enetunreach/i.test(text)) {
+    return {
+      err: stderr || 'network-failure',
+      hint: 'Check network connectivity and retry: gsd-t doctor --install-playwright',
+    };
+  }
+  if (/chromium|browsers? could not be downloaded|browser.*download/i.test(text)) {
+    return {
+      err: stderr || 'chromium-download-failed',
+      hint: 'Run npx playwright install chromium manually',
+    };
+  }
+  if (/eacces|eperm|permission|read-only|enospc|disk/i.test(text)) {
+    return {
+      err: stderr || 'disk-write-failed',
+      hint: 'Check filesystem permissions',
+    };
+  }
+  return {
+    err: stderr || 'install-failed',
+    hint: 'Run gsd-t doctor --install-playwright to retry',
+  };
+}
+
+function _runSubprocess(cmd, args, cwd) {
+  return new Promise((resolve) => {
+    let stdout = '';
+    let stderr = '';
+    let child;
+    try {
+      child = spawn(cmd, args, {
+        cwd,
+        env: process.env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch (err) {
+      resolve({ code: 127, stdout: '', stderr: err.message || String(err) });
+      return;
+    }
+    child.stdout.on('data', (d) => { stdout += d.toString(); });
+    child.stderr.on('data', (d) => { stderr += d.toString(); });
+    child.on('error', (err) => {
+      resolve({ code: 127, stdout, stderr: stderr + (err.message || String(err)) });
+    });
+    child.on('close', (code) => {
+      resolve({ code: code == null ? 1 : code, stdout, stderr });
+    });
+  });
+}
+
+function _writeIfAbsent(filePath, content) {
+  try {
+    if (fs.existsSync(filePath)) return { ok: true, wrote: false };
+    fs.writeFileSync(filePath, content);
+    return { ok: true, wrote: true };
+  } catch (err) {
+    return { ok: false, error: err.message || String(err) };
+  }
+}
+
+function _ensureE2EPlaceholder(projectDir) {
+  try {
+    const e2eDir = path.join(projectDir, 'e2e');
+    let dirExists = false;
+    try {
+      dirExists = fs.statSync(e2eDir).isDirectory();
+    } catch (_e) {
+      dirExists = false;
+    }
+    if (!dirExists) {
+      fs.mkdirSync(e2eDir, { recursive: true });
+    } else {
+      // If e2e exists and is non-empty, do not overwrite.
+      const entries = fs.readdirSync(e2eDir);
+      if (entries.length > 0) return { ok: true, wrote: false };
+    }
+    const specPath = path.join(e2eDir, '__placeholder.spec.ts');
+    if (!fs.existsSync(specPath)) {
+      fs.writeFileSync(specPath, PLACEHOLDER_SPEC_TEMPLATE);
+      return { ok: true, wrote: true };
+    }
+    return { ok: true, wrote: false };
+  } catch (err) {
+    return { ok: false, error: err.message || String(err) };
+  }
+}
+
+async function installPlaywright(projectDir, opts) {
+  // Idempotent short-circuit: already configured.
+  if (hasPlaywright(projectDir)) return { ok: true };
+
+  const pm = detectPackageManager(projectDir);
+  const install = INSTALL_COMMANDS[pm] || INSTALL_COMMANDS.npm;
+
+  // Tests use opts.runner to inject a stub of `_runSubprocess` so we can
+  // exercise each package-manager branch and error path without actually
+  // hitting npm/pnpm/yarn/bun. Production callers omit it.
+  const runner = (opts && opts.runner) || _runSubprocess;
+
+  // Step 3: install @playwright/test as a devDependency
+  let r = await runner(install.cmd, install.args, projectDir);
+  if (r.code !== 0) {
+    const c = _classifyError(r.stderr, r.code, install.cmd);
+    return { ok: false, err: c.err, hint: c.hint };
+  }
+
+  // Step 4: install chromium browser
+  r = await runner('npx', ['playwright', 'install', 'chromium'], projectDir);
+  if (r.code !== 0) {
+    const c = _classifyError(r.stderr, r.code, 'npx');
+    // Partial install: @playwright/test landed, chromium did not. Surface that.
+    return {
+      ok: false,
+      err: c.err,
+      hint: c.hint,
+      partial: true,
+    };
+  }
+
+  // Step 5: write playwright.config.ts (idempotent — does not overwrite)
+  const configPath = path.join(projectDir, 'playwright.config.ts');
+  const cfgWrite = _writeIfAbsent(configPath, PLAYWRIGHT_CONFIG_TEMPLATE);
+  if (!cfgWrite.ok) {
+    const c = _classifyError(cfgWrite.error, 1, 'fs.writeFile');
+    return { ok: false, err: c.err, hint: c.hint };
+  }
+
+  // Step 6: e2e/ scaffolding (idempotent — does not overwrite existing files)
+  const placeholderWrite = _ensureE2EPlaceholder(projectDir);
+  if (!placeholderWrite.ok) {
+    const c = _classifyError(placeholderWrite.error, 1, 'fs.writeFile');
+    return { ok: false, err: c.err, hint: c.hint };
+  }
+
+  return { ok: true };
+}
+
+// ── installPlaywrightSync ────────────────────────────────────────────────────
+//
+// Synchronous variant of installPlaywright(). Same idempotency + template +
+// error-classifier semantics as the async form, implemented with `spawnSync`
+// so it can be embedded inside synchronous code paths (notably the M50 D2
+// spawn-gate in bin/headless-auto-spawn.cjs::autoSpawnHeadless, which must
+// remain sync to preserve the existing return-value contract relied on by
+// bin/gsd-t-parallel.cjs::runDispatch).
+//
+// Returns the same shape as installPlaywright(): {ok: true} or
+// {ok: false, err, hint, partial?: true}. Tests inject opts.runner the same
+// way; production callers omit it.
+
+function _runSubprocessSync(cmd, args, cwd) {
+  let res;
+  try {
+    res = spawnSync(cmd, args, {
+      cwd,
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf8',
+    });
+  } catch (err) {
+    return { code: 127, stdout: '', stderr: err.message || String(err) };
+  }
+  if (res.error) {
+    return { code: 127, stdout: '', stderr: res.error.message || String(res.error) };
+  }
+  return {
+    code: res.status == null ? 1 : res.status,
+    stdout: res.stdout || '',
+    stderr: res.stderr || '',
+  };
+}
+
+function installPlaywrightSync(projectDir, opts) {
+  if (hasPlaywright(projectDir)) return { ok: true };
+
+  const pm = detectPackageManager(projectDir);
+  const install = INSTALL_COMMANDS[pm] || INSTALL_COMMANDS.npm;
+  const runner = (opts && opts.runner) || _runSubprocessSync;
+
+  let r = runner(install.cmd, install.args, projectDir);
+  if (r.code !== 0) {
+    const c = _classifyError(r.stderr, r.code, install.cmd);
+    return { ok: false, err: c.err, hint: c.hint };
+  }
+
+  r = runner('npx', ['playwright', 'install', 'chromium'], projectDir);
+  if (r.code !== 0) {
+    const c = _classifyError(r.stderr, r.code, 'npx');
+    return { ok: false, err: c.err, hint: c.hint, partial: true };
+  }
+
+  const configPath = path.join(projectDir, 'playwright.config.ts');
+  const cfgWrite = _writeIfAbsent(configPath, PLAYWRIGHT_CONFIG_TEMPLATE);
+  if (!cfgWrite.ok) {
+    const c = _classifyError(cfgWrite.error, 1, 'fs.writeFile');
+    return { ok: false, err: c.err, hint: c.hint };
+  }
+
+  const placeholderWrite = _ensureE2EPlaceholder(projectDir);
+  if (!placeholderWrite.ok) {
+    const c = _classifyError(placeholderWrite.error, 1, 'fs.writeFile');
+    return { ok: false, err: c.err, hint: c.hint };
+  }
+
+  return { ok: true };
+}
+
+module.exports = {
+  hasPlaywright,
+  detectPackageManager,
+  verifyPlaywrightHealth,
+  installPlaywright,
+  installPlaywrightSync,
+  // Exposed for tests; treat as private.
+  _PLAYWRIGHT_CONFIG_TEMPLATE: PLAYWRIGHT_CONFIG_TEMPLATE,
+  _PLACEHOLDER_SPEC_TEMPLATE: PLACEHOLDER_SPEC_TEMPLATE,
+  _INSTALL_COMMANDS: INSTALL_COMMANDS,
+};

package/bin/ui-detection.cjs

@@ -0,0 +1,151 @@
+"use strict";
+
+// UI detection probe — synchronous, never throws, depth-bounded.
+// Contract: .gsd-t/contracts/playwright-bootstrap-contract.md §4
+//
+// hasUI(projectDir): true iff the project has any UI signal.
+//   Probe order (first match wins, short-circuit):
+//     1. package.json deps/devDeps include react/vue/svelte/next/@angular/core/@vue/runtime-core
+//     2. pubspec.yaml at project root (Flutter)
+//     3. tailwind.config.{js,ts}
+//     4. any .tsx/.jsx/.vue/.svelte/.css/.scss within depth 3, excluding ignored dirs
+//
+// detectUIFlavor(projectDir): more specific category, or null when hasUI() is false.
+
+const fs = require("fs");
+const path = require("path");
+
+const FRAMEWORK_DEPS = {
+  next: "next",
+  angular: "@angular/core",
+  react: "react",
+  vue: "vue",
+  svelte: "svelte",
+  // @vue/runtime-core implies vue
+  "vue-runtime": "@vue/runtime-core",
+};
+
+const UI_FILE_EXTS = new Set([".tsx", ".jsx", ".vue", ".svelte", ".css", ".scss"]);
+
+const IGNORED_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".next",
+  ".nuxt",
+  "coverage",
+  ".gsd-t",
+]);
+
+const MAX_WALK_DEPTH = 3;
+
+function _readPkgDeps(projectDir) {
+  const pkgPath = path.join(projectDir, "package.json");
+  if (!fs.existsSync(pkgPath)) return null;
+  try {
+    const raw = fs.readFileSync(pkgPath, "utf8");
+    const pkg = JSON.parse(raw);
+    const deps = Object.assign({}, pkg.dependencies || {}, pkg.devDependencies || {});
+    return deps;
+  } catch (_e) {
+    return null;
+  }
+}
+
+function _frameworkFromDeps(deps) {
+  if (!deps) return null;
+  // Order matters: next before react (Next ships with react), vue-runtime → vue, angular, svelte.
+  if (deps[FRAMEWORK_DEPS.next]) return "next";
+  if (deps[FRAMEWORK_DEPS.angular]) return "angular";
+  if (deps[FRAMEWORK_DEPS.vue] || deps[FRAMEWORK_DEPS["vue-runtime"]]) return "vue";
+  if (deps[FRAMEWORK_DEPS.svelte]) return "svelte";
+  if (deps[FRAMEWORK_DEPS.react]) return "react";
+  return null;
+}
+
+function _isFile(p) {
+  try {
+    const st = fs.statSync(p, { throwIfNoEntry: false });
+    return !!(st && st.isFile());
+  } catch (_e) {
+    return false;
+  }
+}
+
+function _hasFlutter(projectDir) {
+  return _isFile(path.join(projectDir, "pubspec.yaml"));
+}
+
+function _hasTailwindConfig(projectDir) {
+  return (
+    _isFile(path.join(projectDir, "tailwind.config.js")) ||
+    _isFile(path.join(projectDir, "tailwind.config.ts")) ||
+    _isFile(path.join(projectDir, "tailwind.config.mjs")) ||
+    _isFile(path.join(projectDir, "tailwind.config.cjs"))
+  );
+}
+
+// Depth-bounded short-circuit walk. Returns true on first UI file found.
+function _findUIFileWithinDepth(rootDir, maxDepth) {
+  // BFS-style iterative walk (avoid recursion depth + stack issues on weird trees).
+  const stack = [{ dir: rootDir, depth: 0 }];
+  while (stack.length > 0) {
+    const { dir, depth } = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (_e) {
+      continue;
+    }
+    for (const entry of entries) {
+      const name = entry.name;
+      if (entry.isFile()) {
+        const ext = path.extname(name).toLowerCase();
+        if (UI_FILE_EXTS.has(ext)) return true;
+      } else if (entry.isDirectory()) {
+        // Contract §4 enumerates the exclusion set — do not over-exclude
+        // dot-prefixed dirs (e.g. .storybook houses real UI code).
+        if (IGNORED_DIRS.has(name)) continue;
+        if (depth + 1 <= maxDepth) {
+          stack.push({ dir: path.join(dir, name), depth: depth + 1 });
+        }
+      }
+    }
+  }
+  return false;
+}
+
+function hasUI(projectDir) {
+  if (typeof projectDir !== "string" || projectDir.length === 0) return false;
+  try {
+    const deps = _readPkgDeps(projectDir);
+    if (_frameworkFromDeps(deps) !== null) return true;
+    if (_hasFlutter(projectDir)) return true;
+    if (_hasTailwindConfig(projectDir)) return true;
+    if (_findUIFileWithinDepth(projectDir, MAX_WALK_DEPTH)) return true;
+    return false;
+  } catch (_e) {
+    return false;
+  }
+}
+
+function detectUIFlavor(projectDir) {
+  if (typeof projectDir !== "string" || projectDir.length === 0) return null;
+  try {
+    const deps = _readPkgDeps(projectDir);
+    const framework = _frameworkFromDeps(deps);
+    if (framework !== null) return framework;
+    if (_hasFlutter(projectDir)) return "flutter";
+    if (_hasTailwindConfig(projectDir)) return "css-only";
+    if (_findUIFileWithinDepth(projectDir, MAX_WALK_DEPTH)) return "css-only";
+    return null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+module.exports = {
+  hasUI,
+  detectUIFlavor,
+};

package/commands/gsd-t-init.md

@@ -332,25 +332,23 @@ After initialization, verify all created documentation is consistent:
 
 ## Step 11: Playwright Setup (MANDATORY)
 
-Every GSD-T project must have Playwright ready for E2E testing. If `playwright.config.*` does not exist:
-
-1. **Detect package manager**: Check for `bun.lockb` (bun), `yarn.lock` (yarn), `pnpm-lock.yaml` (pnpm), `package-lock.json` or `package.json` (npm), `requirements.txt`/`pyproject.toml` (Python)
-2. **Install Playwright**:
-   - bun: `bun add -d @playwright/test && bunx playwright install chromium`
-   - npm: `npm install -D @playwright/test && npx playwright install chromium`
-   - yarn: `yarn add -D @playwright/test && yarn playwright install chromium`
-   - pnpm: `pnpm add -D @playwright/test && pnpm exec playwright install chromium`
-   - Python: `pip install playwright && playwright install chromium`
-   - No package manager detected: `npm init -y && npm install -D @playwright/test && npx playwright install chromium`
-3. **Create `playwright.config.ts`** (or `.js` if not using TypeScript) with sensible defaults:
-   - `testDir: './e2e'` (or `./tests/e2e`)
-   - `use: { baseURL: 'http://localhost:3000' }` (adjust based on project)
-   - Chromium only (keep it fast; user can add more browsers later)
-   - Screenshot on failure enabled
-4. **Create the E2E test directory** (`e2e/` or `tests/e2e/`) with a placeholder spec
-5. **Add test script** to `package.json` if it exists: `"test:e2e": "playwright test"`
-
-Skip silently if `playwright.config.*` already exists.
+M50: this step is now executable code, not prose. The `bin/gsd-t.js init` flow calls `installPlaywright(projectDir)` from `bin/playwright-bootstrap.cjs` automatically when `hasUI(projectDir) && !hasPlaywright(projectDir)`. See `.gsd-t/contracts/playwright-bootstrap-contract.md`.
+
+The installer:
+1. Detects the package manager via `detectPackageManager(projectDir)` (`pnpm-lock.yaml` → `pnpm`; `yarn.lock` → `yarn`; `bun.lockb` → `bun`; default `npm`).
+2. Installs `@playwright/test` as a devDependency + `npx playwright install chromium`.
+3. Writes `playwright.config.ts` (testDir `./e2e`, chromium project) idempotently — does NOT overwrite an existing config.
+4. Creates `e2e/__placeholder.spec.ts` (empty `test.skip`) when `e2e/` is absent or empty.
+
+Fallback (when not running through `bin/gsd-t.js init`):
+- bun: `bun add -d @playwright/test && bunx playwright install chromium`
+- npm: `npm install -D @playwright/test && npx playwright install chromium`
+- yarn: `yarn add -D @playwright/test && yarn playwright install chromium`
+- pnpm: `pnpm add -D @playwright/test && pnpm exec playwright install chromium`
+
+Operator overrides: `gsd-t setup-playwright [path]` (explicit single-project install) or `gsd-t doctor --install-playwright`.
+
+The spawn-time gate in `bin/headless-auto-spawn.cjs` re-runs the install on first need if the project skipped this step (e.g., older project that pre-dates M50).
 
 ## Step 12: Test Verification
 

package/docs/architecture.md

@@ -1086,3 +1086,17 @@ Contract: `.gsd-t/contracts/headless-default-contract.md` v2.1.0 §Worker Sub-Di
 The production main loop currently runs exactly one iter per pass (`batchSize === 1`) always, unless a caller explicitly threads `opts.maxIterParallel` as a number through `_computeIterBatchSize` — which today's supervisor CLI does not. The four helpers are exported via `module.exports.__test__` so the T7 unit suite and any future caller can exercise batched iteration deterministically, but iter-parallelism at this layer is **scaffolded, not engaged in production**. The gate is intentional: `_runOneIter` mutates shared `state` fields (`state.iter`, heartbeat bookkeeping, the `writeState` side effect) that are not safe to execute concurrently against the same state object. Backlog #24 tracks the follow-up to make `_runOneIter` state-clone-safe and lift the production gate so the supervisor CLI can set a non-1 default.
 
 Contract: `.gsd-t/contracts/iter-parallel-contract.md` v1.0.0.
+
+## Playwright Deterministic Enforcement (M50, v3.21.x+)
+
+M50 retires the prose-only "Playwright Readiness Guard" in favor of executable enforcement. Three layers, each runnable from the CLI or from any caller via the exported library:
+
+1. **Bootstrap library** (`bin/playwright-bootstrap.cjs` + `bin/ui-detection.cjs`) — single-source library exposing `hasPlaywright`, `detectPackageManager`, `installPlaywright`, `installPlaywrightSync`, `verifyPlaywrightHealth`, `hasUI`, `detectUIFlavor`. Zero external runtime dependencies. The async + sync install variants share the same template, error classifier, and idempotency invariants per `playwright-bootstrap-contract.md` §3-§8.
+
+2. **Spawn-time gate** (`bin/headless-auto-spawn.cjs::autoSpawnHeadless`) — when the command being spawned is in the `TESTING_OR_UI_COMMANDS` whitelist (`gsd-t-execute`, `gsd-t-test-sync`, `gsd-t-verify`, `gsd-t-quick`, `gsd-t-wave`, `gsd-t-milestone`, `gsd-t-complete-milestone`, `gsd-t-debug`, `gsd-t-integrate`) AND `hasUI(projectDir)` AND `!hasPlaywright(projectDir)`, the gate auto-installs via `installPlaywrightSync`. On install failure, the gate writes `mode: 'blocked-needs-human'` to the headless session-state file and exits with code 4. Hot-path overhead: three filesystem checks (Set lookup + depth-bounded fs walk + existsSync).
+
+3. **Commit-time gate** (`scripts/hooks/pre-commit-playwright-gate`) — opt-in via `gsd-t doctor --install-hooks`. The bash hook reads `.gsd-t/.last-playwright-pass` (Unix epoch ms) and blocks commits that touch viewer-source files (`scripts/gsd-t-transcript.html`, `scripts/gsd-t-dashboard-server.js`, `e2e/viewer/**`) when any staged file's mtime exceeds the recorded pass. Fails open on missing/corrupt timestamps — a broken hook is worse than a permissive one.
+
+CLI surface added in M50: `gsd-t setup-playwright [path]` (single-project explicit installer), `gsd-t doctor --install-playwright` (fix-it-now flag), `gsd-t doctor --install-hooks` (pre-commit-gate installer). `gsd-t init` and `gsd-t update-all` invoke `installPlaywright` automatically for any UI project that's missing it.
+
+Contract: `.gsd-t/contracts/playwright-bootstrap-contract.md` v1.0.0.

package/docs/requirements.md

@@ -700,3 +700,30 @@ Acceptance:
 | REQ-M47-D2-02 | New `GET /api/main-session` endpoint returns `{ filename, sessionId, mtimeMs }` for the most-recently-modified `in-session-*.ndjson` (or `{ null, null, null }` when none exist); path-traversal-guarded; no caching. | m47-d2-server-helpers | T2, T5 | done |
 | REQ-M47-D2-03 | `dashboard-server-contract.md` bumped to v1.3.0 documenting the additive `status` field semantics + `/api/main-session` schema; module exports updated. | m47-d2-server-helpers | T3 | done |
 | REQ-M47-D2-04 | Test suite passes baseline 2045/2047 + new M47 tests (D1 + D2 net add); no NEW regressions in the 7 existing viewer-route/HTML tests (success criterion 5). | m47-d1-viewer-redesign + m47-d2-server-helpers | D1 T7, D2 T4–T5 | done |
+
+
+## M50 Universal Playwright Bootstrap + Deterministic UI Enforcement (planned — 2026-05-06)
+
+| REQ-ID | Requirement Summary | Domain | Task(s) | Status |
+|--------|---------------------|--------|---------|--------|
+| REQ-M50-D1-01 | `bin/playwright-bootstrap.cjs` exports `hasPlaywright`, `detectPackageManager`, `installPlaywright` (idempotent), `verifyPlaywrightHealth`. Zero external runtime deps. | m50-bootstrap-and-detection | T2, T3 | done |
+| REQ-M50-D1-02 | `bin/ui-detection.cjs` exports `hasUI` (depth-bounded, short-circuits on first hit) + `detectUIFlavor`. Recognizes React/Vue/Svelte/Next/Angular/Flutter/Tailwind/css-only. | m50-bootstrap-and-detection | T1 | done |
+| REQ-M50-D1-03 | `bin/gsd-t.js` migrates inline `hasPlaywright` (line 201-204) to `require('./playwright-bootstrap.cjs')`; `init`/`update-all`/`doctor` invoke `installPlaywright` when `hasUI && !hasPlaywright`. | m50-bootstrap-and-detection | T4 | done |
+| REQ-M50-D1-04 | New `gsd-t setup-playwright` subcommand: explicit one-shot `installPlaywright(cwd)` invocation with verbose output. | m50-bootstrap-and-detection | T4 | done |
+| REQ-M50-D1-05 | New flag `gsd-t doctor --install-playwright` directly invokes `installPlaywright(cwd)`. Fixes all 14 of 19 registered projects flagged Playwright-missing in one command. | m50-bootstrap-and-detection | T4 | done |
+| REQ-M50-D1-06 | ~25 unit tests across `test/m50-d1-playwright-bootstrap.test.js` + `test/m50-d1-ui-detection.test.js` + `test/m50-d1-cli-integration.test.js` pass. | m50-bootstrap-and-detection | T1, T2, T3, T4, T5 | done |
+| REQ-M50-D2-01 | `bin/headless-auto-spawn.cjs::autoSpawnHeadless()` inserts a spawn-gate: when `isTestingOrUICommand && hasUI && !hasPlaywright`, auto-installs; on install fail, exits with `mode: 'blocked-needs-human'` (exit code 4). Hot-path overhead ≤ 10ms when no install is needed. | m50-gates-and-specs | T2 | done |
+| REQ-M50-D2-02 | `scripts/hooks/pre-commit-playwright-gate` (opt-in via `gsd-t doctor --install-hooks`) reads `.gsd-t/.last-playwright-pass` and blocks viewer-source commits when any touched viewer-source file's mtime > the timestamp. Fail-open on config errors. | m50-gates-and-specs | T3 | done |
+| REQ-M50-D2-03 | `playwright.config.ts` at GSD-T project root with `testDir: 'e2e'`, chromium project, `webServer: undefined` (specs manage their own server lifecycle). | m50-gates-and-specs | T1 | done |
+| REQ-M50-D2-04 | `e2e/viewer/title.spec.ts` regression-tests M48 Bug 1 (project basename in `<title>` + header `.title` for `/transcripts` and `/transcripts/{spawnId}`). | m50-gates-and-specs | T4 | done |
+| REQ-M50-D2-05 | `e2e/viewer/timestamps.spec.ts` regression-tests M48 Bug 2 (per-frame timestamps from `frame.ts`, not per-batch `new Date()`). | m50-gates-and-specs | T5 | done |
+| REQ-M50-D2-06 | `e2e/viewer/chat-bubbles.spec.ts` regression-tests M48 Bug 3 (`user_turn`/`assistant_turn`/`session_start`/`tool_use_line` render as styled bubbles, not `JSON.stringify` dumps). | m50-gates-and-specs | T6 | done |
+| REQ-M50-D2-07 | `e2e/viewer/dual-pane.spec.ts` regression-tests M48 Bug 4 (clicking `in-session-*` rail entry pins to top pane only; bottom pane stays on its own SSE stream). | m50-gates-and-specs | T7 | done |
+| REQ-M50-D2-08 | `e2e/viewer/lazy-dashboard.spec.ts` regression-tests M49 banner (URL banner when dashboard alive; fallback "Transcript file:" banner when not). | m50-gates-and-specs | T8 | done |
+| REQ-M50-D2-09 | ~14 unit tests across `test/m50-d2-spawn-gate.test.js` + `test/m50-d2-pre-commit-hook.test.js` + `test/m50-d2-viewer-specs-smoke.test.js` pass. | m50-gates-and-specs | T1, T2, T3 | done |
+| REQ-M50-D2-10 | Doc-ripple: `~/.claude/CLAUDE.md` + `templates/CLAUDE-global.md` + 8 command files (`gsd-t-execute`, `gsd-t-test-sync`, `gsd-t-verify`, `gsd-t-quick`, `gsd-t-wave`, `gsd-t-milestone`, `gsd-t-complete-milestone`, `gsd-t-debug`) + `docs/architecture.md` + `CHANGELOG.md`. Replace prose Playwright reminders with referrals to `playwright-bootstrap-contract.md`. | m50-gates-and-specs | T9 | done |
+| REQ-M50-VERIFY | Full unit suite: 2104 baseline + ~25 D1 + ~14 D2 = ~2143 expected, ≥2141 passing (preserves 2 known env-sensitive flakes). All 5 E2E specs pass. Spawn-gate fixture + pre-commit-hook fixture pass. | both | T10 (D2) | done |
+
+Supporting contracts:
+- `.gsd-t/contracts/playwright-bootstrap-contract.md` v1.0.0 — D1 library API + CLI wiring + idempotency invariants + error-path contract.
+- `.gsd-t/contracts/m50-integration-points.md` — D1↔D2 cross-domain checkpoint, the `bin/gsd-t.js` file-overlap coordination rules, and the doc-ripple ordering.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "3.21.12",
+  "version": "3.22.11",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",
@@ -23,8 +23,13 @@
   },
   "scripts": {
     "test": "node --test",
+    "e2e": "playwright test",
+    "e2e:install": "playwright install chromium",
     "prepublishOnly": "npm test"
   },
+  "devDependencies": {
+    "@playwright/test": "^1.55.0"
+  },
   "files": [
     "bin/",
     "commands/",

package/scripts/hooks/pre-commit-playwright-gate

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# GSD-T Playwright gate (M50 D2)
+# Blocks commits that touch viewer/UI source files when Playwright tests have
+# not passed since the most recent change. Reads `.gsd-t/.last-playwright-pass`
+# (Unix epoch ms in a single line) — written by `npx playwright test` post-pass.
+#
+# Install (opt-in):  gsd-t doctor --install-hooks
+# Remove:            rm .git/hooks/pre-commit  (or remove this block if merged
+#                    into an existing hook)
+#
+# Exit codes:
+#   0 — clean (no viewer-source files staged, OR fresh pass, OR fail-open path)
+#   1 — blocked (viewer-source modified after the last playwright pass)
+#
+# Fail-open philosophy (per m50 D2 constraints): a broken hook is worse than a
+# permissive one. Missing or corrupt `.last-playwright-pass` → exit 0 with a
+# stderr warning, never block.
+
+set -e
+
+# Resolve the project root (the dir that contains the repository's .git).
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+PASS_FILE="$ROOT/.gsd-t/.last-playwright-pass"
+
+# Patterns that count as "viewer/UI source" for gating purposes. Globs are
+# checked against the staged file list returned by git.
+VIEWER_SOURCE_PATTERNS=(
+  "scripts/gsd-t-transcript.html"
+  "scripts/gsd-t-dashboard-server.js"
+  "e2e/viewer/"
+)
+
+# Load staged file list (only added/modified — deletions don't need testing).
+STAGED="$(git diff --cached --name-only --diff-filter=AM 2>/dev/null || true)"
+
+# Quick exit when nothing is staged.
+[ -z "$STAGED" ] && exit 0
+
+# Find any staged path matching a viewer-source pattern.
+matches=""
+while IFS= read -r f; do
+  for p in "${VIEWER_SOURCE_PATTERNS[@]}"; do
+    case "$f" in
+      "$p"|"$p"*) matches="$matches $f"; break ;;
+    esac
+  done
+done <<EOF
+$STAGED
+EOF
+
+# No viewer-source files staged → silent pass.
+if [ -z "$matches" ]; then
+  exit 0
+fi
+
+# Viewer-source staged. Now require a fresh pass.
+if [ ! -f "$PASS_FILE" ]; then
+  echo "[playwright-gate] WARNING: .gsd-t/.last-playwright-pass missing — fail-open. Run 'npx playwright test' to record a pass." >&2
+  exit 0
+fi
+
+# Read timestamp; fail-open on corrupt content.
+LAST_PASS="$(tr -d '[:space:]' < "$PASS_FILE")"
+if ! echo "$LAST_PASS" | grep -Eq '^[0-9]+$'; then
+  echo "[playwright-gate] WARNING: .gsd-t/.last-playwright-pass is not a valid timestamp — fail-open." >&2
+  exit 0
+fi
+
+# Compare each staged viewer-source file's mtime (in ms) against LAST_PASS.
+# If any file has mtime > LAST_PASS, block.
+stale=""
+for f in $matches; do
+  fpath="$ROOT/$f"
+  if [ -f "$fpath" ]; then
+    # GNU stat: -c %Y (seconds); BSD stat: -f %m. We want milliseconds.
+    if mtime_s=$(stat -c %Y "$fpath" 2>/dev/null) || mtime_s=$(stat -f %m "$fpath" 2>/dev/null); then
+      mtime_ms=$((mtime_s * 1000))
+      if [ "$mtime_ms" -gt "$LAST_PASS" ]; then
+        stale="$stale $f"
+      fi
+    fi
+  fi
+done
+
+if [ -n "$stale" ]; then
+  echo "[playwright-gate] BLOCKED: viewer-source modified since last playwright pass." >&2
+  echo "  Stale files:$stale" >&2
+  echo "  Last pass:  $(date -r "$((LAST_PASS / 1000))" 2>/dev/null || echo "$LAST_PASS")" >&2
+  echo "" >&2
+  echo "  Run 'npx playwright test' before committing, or run 'gsd-t doctor --install-playwright' if Playwright isn't set up." >&2
+  exit 1
+fi
+
+exit 0

package/templates/CLAUDE-global.md

@@ -194,15 +194,19 @@ If any are missing:
 
 **Exempt commands** (do not trigger auto-init): `gsd-t-init`, `gsd-t-init-scan-setup`, `gsd-t-help`, `gsd-t-version-update`, `gsd-t-version-update-all`.
 
-## Playwright Readiness Guard
+## Playwright Readiness Guard (M50 — deterministic enforcement)
 
-Before any command that involves testing (`gsd-t-execute`, `gsd-t-test-sync`, `gsd-t-verify`, `gsd-t-quick`, `gsd-t-wave`, `gsd-t-milestone`, `gsd-t-complete-milestone`, `gsd-t-debug`), check if `playwright.config.*` exists in the project. If it does not:
-1. Detect the package manager and install Playwright (`@playwright/test` + chromium)
-2. Create a basic `playwright.config.ts` with sensible defaults
-3. Create the E2E test directory with a placeholder spec
-4. Then continue with the original command
+Playwright readiness is enforced by executable code, not prose. Three layers:
 
-Playwright must always be ready before any testing occurs. Do not skip this check. Do not defer setup to "later."
+1. **Bootstrap library** — `bin/playwright-bootstrap.cjs` exports `hasPlaywright`, `detectPackageManager`, `installPlaywright`, `verifyPlaywrightHealth`. `bin/ui-detection.cjs` exports `hasUI`, `detectUIFlavor`. See `.gsd-t/contracts/playwright-bootstrap-contract.md`.
+2. **Spawn-time gate** — `bin/headless-auto-spawn.cjs::autoSpawnHeadless()` auto-installs Playwright before the spawn proceeds, when the command being run is in the testing/UI whitelist (`gsd-t-execute`, `gsd-t-test-sync`, `gsd-t-verify`, `gsd-t-quick`, `gsd-t-wave`, `gsd-t-milestone`, `gsd-t-complete-milestone`, `gsd-t-debug`, `gsd-t-integrate`) AND `hasUI(projectDir)` AND `!hasPlaywright(projectDir)`. On install failure, the gate writes `mode: 'blocked-needs-human'` to the headless session-state file and exits 4.
+3. **Commit-time gate** — `scripts/hooks/pre-commit-playwright-gate` (opt-in via `gsd-t doctor --install-hooks`) blocks commits that touch viewer/UI source files when Playwright tests have not passed since the most recent change. Reads `.gsd-t/.last-playwright-pass`; fails open on missing/corrupt timestamps.
+
+Operator overrides:
+- Manual install: `gsd-t setup-playwright [path]` (or `gsd-t doctor --install-playwright`).
+- Health check: `gsd-t doctor` reports `playwright missing` for any UI project without `playwright.config.*`.
+
+You no longer need to run a check yourself before testing commands — the gate runs every spawn.
 
 ### Playwright Cleanup