@tekyzinc/gsd-t 3.22.10 → 3.23.10

package/CHANGELOG.md

@@ -2,6 +2,83 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [Unreleased]
+
+## [3.23.10] - 2026-05-06
+
+### Added — Rigorous User-Journey Coverage + Anti-Drift Test Quality (M52)
+
+Closes the M48→M49→M50→M51 drift pattern where each test round caught the bug shape the previous round named, never the unnamed shape. M52's architectural fix is two-fold: (a) MECHANICAL coverage via a regex-based listener detector + pre-commit gate that blocks viewer-source commits with uncovered listeners; (b) DOCTRINAL change to what "rigorous" means — journey specs walk every interactive surface end-to-end with assertions on user-visible state, real-data NDJSON fixtures, adversarial Red Team scoped to JOURNEYS not lines.
+
+**D1 — Journey-coverage tooling:**
+- `bin/journey-coverage.cjs` (308 lines) — regex listener detector with single-pass string-mask precomputation (handles JS strings + HTML/JS comments). Recognises 6 listener kinds per contract §3. Zero parser deps. Sub-100ms on the full viewer file set.
+- `bin/journey-coverage-cli.cjs` (107 lines) → `gsd-t check-coverage` — supports `--staged-only`, `--manifest PATH`, `--quiet`. Exit 0 (clean) / 4 (gap or stale) / 2 (manifest missing).
+- `scripts/hooks/pre-commit-journey-coverage` (mode 0755, `set -e`) — viewer-source pattern set per contract §4. Marker block `# >>> GSD-T journey-coverage gate >>>` mirrors M50 idiom. Fail-open on detector internal exception.
+- `bin/gsd-t.js` wiring (+46 lines under 50-line budget): `installJourneyCoverageHook` (idempotent), `gsd-t check-coverage` CLI dispatch, `gsd-t doctor --install-journey-hook` flag. Hook auto-installed by `init` after Playwright install for UI projects.
+- `.gsd-t/contracts/journey-coverage-contract.md` v1.0.0 (PROPOSED → STABLE on D1 task-5).
+
+**D2 — Journey specs + fixtures:**
+- `e2e/journeys/` — 12 inaugural journey specs (`main-session-stream`, `click-completed-conversation`, `click-spawn-entry`, `splitter-drag`, `splitter-keyboard`, `right-rail-toggle`, `completed-collapse-toggle`, `auto-follow-toggle`, `kill-button`, `sessionstorage-persistence`, `keyboard-shortcuts`, `hashchange`). Every assertion verifies state changed / data flowed / content loaded / widget responded — zero `toBeVisible`/`toBeAttached` shallow assertions.
+- `.gsd-t/journey-manifest.json` (new) — 12 entries 1:1 with the spec files; `covers[]` arrays span all 17 distinct viewer listeners (multiple listeners per spec where appropriate).
+- `e2e/fixtures/journeys/` — 3 real-data NDJSONs sliced from captured `in-session-*.ndjson` (~50 / ~150 / ~80 frames). PII scrub: any user content > 200 chars truncated with `[…truncated]` marker.
+- `e2e/fixtures/journeys/replay-helpers.ts` — `startReplayServer({fixture, asSessionId, inSession})` mounts the fixture into a temp project, starts the dashboard server with `port: 0` ephemeral, returns `{baseUrl, dispose}`. Zero new runtime deps.
+- `templates/prompts/red-team-subagent.md` — additive new category "Test Pass-Through — Journey Edition" (existing categories untouched). Adversarial mandate: write ≥5 broken viewer patches, run the journey specs, every patch must be caught.
+
+**Adversarial Red Team result:** 5 broken viewer patches written, all 5 caught by journey specs (P1: splitter:mousedown drag handler stripped → splitter-drag FAILS as expected; P2: `_ssSet(SS_KEY_SPLITTER, ...)` redirected to wrong key → splitter-drag + splitter-keyboard FAIL; P3: right-rail toggle handler stubbed to early-return → right-rail-toggle FAILS; P4: M52 narrowed-guard reverted to broken M48 wide-guard → click-completed-conversation FAILS, catching the M52 root-cause regression itself; P5: auto-follow change handler localStorage write removed → auto-follow-toggle FAILS). VERDICT: GRUDGING PASS. See `.gsd-t/red-team-report.md` § "M52 JOURNEY-EDITION RED TEAM".
+
+**Hook end-to-end exercise:** synthetic `fakeBtn:click` listener appended to `scripts/gsd-t-transcript.html:1617` + staged → `bash .git/hooks/pre-commit` exit 1 with structured GAP report (`GAP: scripts/gsd-t-transcript.html:1617  fakeBtn:click  (addEventListener)  no spec covers this`); manifest extended with covering entry → re-run hook exit 0. Block + unblock paths both logged.
+
+**Suite:** unit 2195/2195 pass (was 2167; +28 from M52 D1 detector + CLI + hook + helpers). E2E 35/35 + 1 skip preserved (was 23/35; +12 journey specs). `gsd-t check-coverage` reports `OK: 20 listeners, 12 specs` (exit 0, zero gaps, zero stale entries).
+
+**Migration:** none. Hook is auto-installed on `gsd-t init` and re-installable via `gsd-t doctor --install-journey-hook`. Existing projects pick it up on next `gsd-t update-all`.
+
+### Fixed — historical in-session conversations are clickable again (M52 quick patch)
+
+The M48 Bug 4 dual-pane mirror prevention was overcorrected: `scripts/gsd-t-transcript.html` early-returned for ANY rail entry whose spawn-id began with `in-session-`. But every COMPLETED rail entry is `in-session-*` (that's how the M45 D2 hook captures conversations), so clicking ANY completed conversation did nothing — there was no pane that would load it.
+
+**Mental model fix:** Top pane is for the LIVE main session (owned by `/api/main-session`). Bottom pane is for ANYTHING else the user clicks — regular spawns OR historical in-session conversations. Only the LIVE main session's spawn id should be blocked from the bottom pane (that's the actual M48 Bug 4 case).
+
+**Source narrowing in `scripts/gsd-t-transcript.html`:**
+- `connectMain(sessionId)` exposes `window.__mainSessionId` so click + hashchange handlers can discriminate.
+- renderRailEntry click handler: `if (isInSession && node.spawnId === ('in-session-' + window.__mainSessionId)) return;` — was `if (isInSession) return;`.
+- hashchange handler: `if (id && id === ('in-session-' + window.__mainSessionId)) { return; }` — was `if (id && id.indexOf('in-session-') === 0) { return; }`.
+- Legacy renderTree click handler: same narrowed pattern.
+- Removed unconditional in-session-* scrub from initial-bottom-id seeding (historical sessionStorage selections survive reload now).
+- Added `fetchMainSession` callback that clears the bottom-pane seed when it collides with the live main session id (preserves M48 Bug 4 mirror prevention).
+
+**New journey spec `e2e/viewer/click-completed.spec.ts` (4 tests):**
+- Rail renders 1 main session + 3 completed in-session entries.
+- Clicking each completed entry loads it into the BOTTOM pane (and TOP pane stays on the live main session).
+- Clicking the live MAIN entry does NOT load it into the bottom pane.
+- sessionStorage persists across reload — bottom pane resumes the previously-clicked entry.
+
+**Adversarial Red Team (3 broken patches, all caught):** (a) revert both checks to `if (isInSession) return;`; (b) `connect(id)` short-circuits on in-session prefix; (c) click handler routes in-session entries to TOP pane via `connectMain(...)` (clobbers main session). See `.gsd-t/red-team-report.md` § M52 RED TEAM FINDINGS.
+
+**Unit-test ripple:** 5 source-pinned assertions in `test/m48-viewer-rendering-fixes.test.js` flipped from "asserts pre-M52 unconditional bail" to "asserts M52 narrowed live-main check". 1 new test for the fetchMainSession seed-collision callback.
+
+**Suite:** 2167/2167 unit pass (added 1); E2E 23/23 + 1 placeholder skip (added 4 journey tests).
+
+## [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

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.
+**Rigorous User-Journey Coverage + Anti-Drift Test Quality (M52, v3.23.10)** — closes the M48→M51 drift pattern where each test round only caught previously-named bug shapes. Two-part fix: (a) `bin/journey-coverage.cjs` regex listener detector + `gsd-t check-coverage` CLI + `scripts/hooks/pre-commit-journey-coverage` commit gate (auto-installed on `gsd-t init`) — blocks viewer-source commits when uncovered listeners exist; (b) 12 inaugural journey specs in `e2e/journeys/` covering all 20 detected viewer listeners with functional assertions (zero `toBeVisible`-only tests). Red Team GRUDGING PASS: 5/5 broken viewer patches caught; hook block-then-unblock exercised. Suite: 2195/2195 unit + 35/35 E2E pass.
 **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.

package/bin/gsd-t.js

@@ -657,6 +657,35 @@ function installCaptureLintHook(projectDir) {
   return true;
 }
 
+// M52 D1 — journey-coverage gate hook installer. Block-delimited so uninstall
+// is a clean string excise. Stock script lives at scripts/hooks/pre-commit-journey-coverage.
+const JOURNEY_COVERAGE_HOOK_BEGIN = "# >>> GSD-T journey-coverage gate >>>";
+const JOURNEY_COVERAGE_HOOK_END = "# <<< GSD-T journey-coverage gate <<<";
+
+function installJourneyCoverageHook(projectDir) {
+  const gitDir = path.join(projectDir, ".git");
+  if (!fs.existsSync(gitDir)) { warn("No .git directory — skipping journey-coverage hook 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-journey-coverage");
+  let stock;
+  try { stock = fs.readFileSync(stockSrc, "utf8"); } catch (_) { warn("Could not read pre-commit-journey-coverage script"); return false; }
+  const block = JOURNEY_COVERAGE_HOOK_BEGIN + "\n" + stock.replace(/^#!.*\n/, "") + "\n" + JOURNEY_COVERAGE_HOOK_END + "\n";
+  if (!fs.existsSync(hookPath)) {
+    fs.writeFileSync(hookPath, "#!/usr/bin/env bash\nset -e\n\n" + block);
+    try { fs.chmodSync(hookPath, 0o755); } catch (_) {}
+    success(`Journey-coverage gate installed at ${path.relative(projectDir, hookPath)}`);
+    return true;
+  }
+  const existing = fs.readFileSync(hookPath, "utf8");
+  if (existing.includes(JOURNEY_COVERAGE_HOOK_BEGIN)) { info("Journey-coverage block already present — no change"); return true; }
+  fs.writeFileSync(hookPath, existing.trimEnd() + "\n\n" + block);
+  try { fs.chmodSync(hookPath, 0o755); } catch (_) {}
+  success(`Journey-coverage block appended to ${path.relative(projectDir, hookPath)}`);
+  return true;
+}
+
 // Idempotent — if an existing hook references CONTEXT_METER_HOOK_MARKER the
 // command string is refreshed/migrated in-place to the canonical form.
 // Stale entries matching CONTEXT_METER_STALE_PATTERNS are migrated on the spot.
@@ -1720,6 +1749,9 @@ async function doInit(projectName) {
     }
   }
 
+  // M52 D1: auto-install the journey-coverage gate. Idempotent — no-op if marker present.
+  if (hasUI(projectDir)) installJourneyCoverageHook(projectDir);
+
   showInitTree(projectDir);
 }
 
@@ -3055,6 +3087,12 @@ async function doDoctor(opts) {
     heading("Installing pre-commit hooks");
     installPlaywrightGateHook(process.cwd());
   }
+  // M52 D1: opt-in install of the journey-coverage pre-commit hook.
+  if (opts && opts.installJourneyHook) {
+    log("");
+    heading("Installing journey-coverage pre-commit hook");
+    installJourneyCoverageHook(process.cwd());
+  }
   log("");
   if (issues === 0) {
     log(`${GREEN}${BOLD}  All checks passed!${RESET}`);
@@ -4325,15 +4363,22 @@ if (require.main === module) {
       doUninstall();
       break;
     case "doctor": {
-      const doctorOpts = { prune: false, installPlaywright: false, installHooks: false };
+      const doctorOpts = { prune: false, installPlaywright: false, installHooks: false, installJourneyHook: 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;
+        if (args[i] === "--install-journey-hook") doctorOpts.installJourneyHook = true;
       }
       doDoctor(doctorOpts).catch((e) => { error(e.message || String(e)); process.exit(1); });
       break;
     }
+    case "check-coverage": {
+      const cli = path.join(__dirname, "journey-coverage-cli.cjs");
+      const { spawnSync } = require("child_process");
+      const res = spawnSync(process.execPath, [cli, ...args.slice(1)], { stdio: "inherit" });
+      process.exit(res.status == null ? 1 : res.status);
+    }
     case "setup-playwright": {
       // Single-project explicit installer. Thin wrapper around installPlaywright().
       const targetDir = args[1] && !args[1].startsWith("-") ? path.resolve(args[1]) : process.cwd();

package/bin/journey-coverage-cli.cjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const jc = require('./journey-coverage.cjs');
+
+const VIEWER_FILES = [
+  'scripts/gsd-t-transcript.html',
+  'scripts/gsd-t-dashboard-server.js',
+];
+
+function discoverViewerFiles(projectDir) {
+  const out = [];
+  for (const rel of VIEWER_FILES) {
+    if (fs.existsSync(path.join(projectDir, rel))) out.push(rel);
+  }
+  const binDir = path.join(projectDir, 'bin');
+  if (fs.existsSync(binDir)) {
+    for (const f of fs.readdirSync(binDir)) {
+      if (/^gsd-t-dashboard.*\.cjs$/.test(f)) out.push(path.join('bin', f));
+    }
+  }
+  const journeyDir = path.join(projectDir, 'e2e', 'journeys');
+  if (fs.existsSync(journeyDir)) {
+    for (const f of fs.readdirSync(journeyDir)) {
+      if (/\.spec\.ts$/.test(f)) out.push(path.join('e2e', 'journeys', f));
+    }
+  }
+  return out;
+}
+
+function discoverStagedViewerFiles(projectDir) {
+  let raw;
+  try {
+    raw = execSync('git diff --cached --name-only', { cwd: projectDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  } catch {
+    return [];
+  }
+  const all = raw.split('\n').filter(Boolean);
+  return all.filter((rel) => jc.isViewerSource(rel));
+}
+
+function parseArgs(argv) {
+  const out = { stagedOnly: false, manifest: null, quiet: false, projectDir: process.cwd() };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--staged-only') out.stagedOnly = true;
+    else if (a === '--manifest') { out.manifest = argv[++i]; }
+    else if (a === '--quiet') out.quiet = true;
+    else if (a === '--project-dir') { out.projectDir = argv[++i]; }
+    else if (a === '-h' || a === '--help') {
+      process.stdout.write([
+        'Usage: gsd-t check-coverage [--staged-only] [--manifest PATH] [--quiet]',
+        '',
+        'Exit codes:',
+        '  0  All detected listeners covered. Manifest fresh.',
+        '  4  Coverage gap or stale manifest entry.',
+        '  2  Manifest missing or unreadable (fail-closed).',
+        '',
+      ].join('\n'));
+      process.exit(0);
+    }
+  }
+  return out;
+}
+
+function main(argv) {
+  const opts = parseArgs(argv);
+  const projectDir = opts.projectDir;
+
+  // --staged-only is a gate: only RUN when at least one viewer-source file is
+  // staged. The actual scan always covers the full viewer source — otherwise
+  // a commit that touches only spec files would falsely flag every manifest
+  // entry as stale (because the staged-only file list contains no listeners).
+  if (opts.stagedOnly) {
+    const staged = discoverStagedViewerFiles(projectDir);
+    if (staged.length === 0) {
+      if (!opts.quiet) process.stdout.write('OK: 0 listeners, 0 specs (no staged viewer files)\n');
+      process.exit(0);
+    }
+  }
+  const files = discoverViewerFiles(projectDir);
+
+  const listeners = jc.detectListeners(files, { projectDir });
+
+  let manifest;
+  try {
+    if (opts.manifest) {
+      const p = path.isAbsolute(opts.manifest) ? opts.manifest : path.join(projectDir, opts.manifest);
+      const raw = fs.readFileSync(p, 'utf8');
+      manifest = JSON.parse(raw);
+      if (!manifest || typeof manifest !== 'object' || !Array.isArray(manifest.specs)) {
+        const err = new Error('manifest-shape-invalid');
+        err.code = 'MANIFEST_INVALID';
+        throw err;
+      }
+    } else {
+      manifest = jc.loadManifest(projectDir);
+    }
+  } catch (e) {
+    if (e && (e.code === 'MANIFEST_MISSING' || e.code === 'MANIFEST_UNREADABLE' || e.code === 'MANIFEST_INVALID')) {
+      if (listeners.length === 0) {
+        if (!opts.quiet) process.stdout.write('OK: 0 listeners, 0 specs (no manifest, no listeners — vacuous pass)\n');
+        process.exit(0);
+      }
+      process.stderr.write('check-coverage: manifest missing or unreadable: ' + (e.path || '.gsd-t/journey-manifest.json') + '\n');
+      process.stderr.write('hint: run a D2-authored manifest or pass --manifest PATH\n');
+      process.exit(2);
+    }
+    throw e;
+  }
+
+  const gaps = jc.findGaps(listeners, manifest);
+  const specCount = (manifest.specs || []).length;
+  if (gaps.length === 0) {
+    if (!opts.quiet) process.stdout.write('OK: ' + listeners.length + ' listeners, ' + specCount + ' specs\n');
+    process.exit(0);
+  }
+  process.stderr.write(jc.formatReport(gaps) + '\n');
+  process.exit(4);
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}
+
+module.exports = { main, discoverViewerFiles, discoverStagedViewerFiles, parseArgs };

package/bin/journey-coverage.cjs

@@ -0,0 +1,347 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const VIEWER_FILE_PATTERNS = [
+  /^scripts\/gsd-t-transcript\.html$/,
+  /^scripts\/gsd-t-dashboard-server\.js$/,
+  /^bin\/gsd-t-dashboard.*\.cjs$/,
+  /^e2e\/journeys\/.*\.spec\.ts$/,
+];
+
+const IGNORE_FILE_PATTERNS = [
+  /^e2e\/viewer\/.*\.spec\.ts$/,
+];
+
+const KNOWN_KINDS = new Set([
+  'addEventListener',
+  'inline-handler',
+  'function-call',
+  'mutation-observer',
+  'hashchange',
+  'delegated',
+]);
+
+const TRACKED_FUNCTIONS = new Set(['connectMain', 'connect', 'fetchMainSession']);
+
+function isViewerSource(rel) {
+  if (IGNORE_FILE_PATTERNS.some((p) => p.test(rel))) return false;
+  return VIEWER_FILE_PATTERNS.some((p) => p.test(rel));
+}
+
+function readSource(absPath) {
+  return fs.readFileSync(absPath, 'utf8');
+}
+
+function lineOf(src, idx) {
+  let line = 1;
+  for (let i = 0; i < idx && i < src.length; i++) {
+    if (src.charCodeAt(i) === 10) line++;
+  }
+  return line;
+}
+
+function lineStartIndex(src, idx) {
+  let i = idx;
+  while (i > 0 && src[i - 1] !== '\n') i--;
+  return i;
+}
+
+function lineEndIndex(src, idx) {
+  let i = idx;
+  while (i < src.length && src[i] !== '\n') i++;
+  return i;
+}
+
+function lineText(src, idx) {
+  return src.slice(lineStartIndex(src, idx), lineEndIndex(src, idx));
+}
+
+function buildStringMask(src) {
+  const len = src.length;
+  const mask = new Uint8Array(len);
+  let i = 0;
+  while (i < len) {
+    const ch = src[i];
+    if (ch === '/' && src[i + 1] === '/') {
+      while (i < len && src[i] !== '\n') { mask[i] = 1; i++; }
+      continue;
+    }
+    if (ch === '/' && src[i + 1] === '*') {
+      mask[i] = 1; mask[i + 1] = 1; i += 2;
+      while (i < len && !(src[i] === '*' && src[i + 1] === '/')) { mask[i] = 1; i++; }
+      if (i < len) { mask[i] = 1; mask[i + 1] = 1; i += 2; }
+      continue;
+    }
+    if (ch === '<' && src[i + 1] === '!' && src[i + 2] === '-' && src[i + 3] === '-') {
+      while (i < len && !(src[i] === '-' && src[i + 1] === '-' && src[i + 2] === '>')) { mask[i] = 1; i++; }
+      if (i < len) { mask[i] = 1; mask[i + 1] = 1; mask[i + 2] = 1; i += 3; }
+      continue;
+    }
+    if (ch === "'" || ch === '"' || ch === '`') {
+      const quote = ch;
+      mask[i] = 1; i++;
+      while (i < len) {
+        if (src[i] === '\\') {
+          mask[i] = 1;
+          if (i + 1 < len) mask[i + 1] = 1;
+          i += 2;
+          continue;
+        }
+        if (src[i] === quote) { mask[i] = 1; i++; break; }
+        if (quote !== '`' && src[i] === '\n') break;
+        mask[i] = 1; i++;
+      }
+      continue;
+    }
+    i++;
+  }
+  return mask;
+}
+
+function masked(mask, idx) {
+  return mask[idx] === 1;
+}
+
+function isFeatureDetectGuard(src, matchIdx) {
+  const line = lineText(src, matchIdx);
+  return /if\s*\(\s*!\s*\w+(\.\w+)?\.addEventListener\s*\)/.test(line);
+}
+
+function isEslintExempt(src, matchIdx) {
+  const lineStart = lineStartIndex(src, matchIdx);
+  if (lineStart === 0) return false;
+  const prevLineEnd = lineStart - 1;
+  const prevLineStart = lineStartIndex(src, prevLineEnd - 1);
+  const prevLine = src.slice(prevLineStart, prevLineEnd);
+  if (!/eslint-disable/.test(prevLine)) return false;
+  return /journey-coverage/.test(prevLine);
+}
+
+function findReceiverBeforeDot(src, dotIdx) {
+  let i = dotIdx - 1;
+  while (i >= 0 && /\s/.test(src[i])) i--;
+  let depth = 0;
+  const end = i + 1;
+  while (i >= 0) {
+    const ch = src[i];
+    if (ch === ')' || ch === ']') { depth++; i--; continue; }
+    if (ch === '(' || ch === '[') {
+      if (depth === 0) break;
+      depth--; i--; continue;
+    }
+    if (depth > 0) { i--; continue; }
+    if (/[A-Za-z0-9_$.\?]/.test(ch)) { i--; continue; }
+    break;
+  }
+  return src.slice(i + 1, end).trim();
+}
+
+function looksLikeDelegatedHandler(src, matchIdx, matchLen) {
+  const tail = src.slice(matchIdx + matchLen, matchIdx + matchLen + 600);
+  if (!/=>\s*\{|function\s*\(/.test(tail)) return false;
+  return /e\.target\.matches\s*\(|event\.target\.matches\s*\(/.test(tail);
+}
+
+function extractDelegatedSelector(src, matchIdx) {
+  const tail = src.slice(matchIdx, matchIdx + 600);
+  const m = /\.target\.matches\s*\(\s*(['"])([^'"]+)\1/.exec(tail);
+  return m ? m[2] : '';
+}
+
+function detectAddEventListener(file, src, mask, listeners) {
+  const re = /\.addEventListener\s*\(\s*(['"])([A-Za-z_][\w-]*)\1/g;
+  let m;
+  while ((m = re.exec(src)) !== null) {
+    const matchIdx = m.index;
+    if (masked(mask, matchIdx)) continue;
+    if (isFeatureDetectGuard(src, matchIdx)) continue;
+    const event = m[2];
+    const receiver = findReceiverBeforeDot(src, matchIdx);
+    if (!receiver) continue;
+    if (isEslintExempt(src, matchIdx)) continue;
+    let kind = 'addEventListener';
+    let selector;
+    if (receiver === 'window') {
+      if (event === 'hashchange') {
+        kind = 'hashchange';
+        selector = 'window:hashchange';
+      } else {
+        selector = 'window:' + event;
+      }
+    } else if (looksLikeDelegatedHandler(src, matchIdx, m[0].length)) {
+      kind = 'delegated';
+      const matchesSel = extractDelegatedSelector(src, matchIdx);
+      selector = receiver + ':' + event + (matchesSel ? '|' + matchesSel : '');
+    } else {
+      selector = receiver + ':' + event;
+    }
+    const line = lineOf(src, matchIdx);
+    const raw = lineText(src, matchIdx).trim();
+    listeners.push({ file, line, selector, kind, raw });
+  }
+}
+
+function detectInlineHandler(file, src, mask, listeners) {
+  const re = /<(\w+)([^>]*?)\s+on(\w+)\s*=\s*(['"])([^'"]*)\4/g;
+  let m;
+  while ((m = re.exec(src)) !== null) {
+    const matchIdx = m.index;
+    if (masked(mask, matchIdx)) continue;
+    const tag = m[1];
+    const attrs = m[2];
+    const event = m[3].toLowerCase();
+    const idMatch = /\sid\s*=\s*(['"])([^'"]+)\1/.exec(attrs);
+    const id = idMatch ? idMatch[2] : null;
+    const selector = id ? id + ':' + event : tag + ':' + event;
+    if (isEslintExempt(src, matchIdx)) continue;
+    const line = lineOf(src, matchIdx);
+    const raw = lineText(src, matchIdx).trim();
+    listeners.push({ file, line, selector, kind: 'inline-handler', raw });
+  }
+}
+
+function detectMutationObserver(file, src, mask, listeners) {
+  const re = /new\s+MutationObserver\s*\(/g;
+  let m;
+  let counter = 0;
+  while ((m = re.exec(src)) !== null) {
+    const matchIdx = m.index;
+    if (masked(mask, matchIdx)) continue;
+    counter++;
+    const selector = 'mutation-observer:' + path.basename(file) + ':' + counter;
+    if (isEslintExempt(src, matchIdx)) continue;
+    const line = lineOf(src, matchIdx);
+    const raw = lineText(src, matchIdx).trim();
+    listeners.push({ file, line, selector, kind: 'mutation-observer', raw });
+  }
+}
+
+function detectFunctionCall(file, src, mask, listeners) {
+  const defRe = /(?:^|\n)\s*(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\(/g;
+  const defs = new Map();
+  let m;
+  while ((m = defRe.exec(src)) !== null) {
+    const matchIdx = m.index;
+    if (masked(mask, matchIdx)) continue;
+    if (!defs.has(m[1])) defs.set(m[1], matchIdx);
+  }
+  if (!defs.size) return;
+  for (const [fnName, defIdx] of defs) {
+    if (!TRACKED_FUNCTIONS.has(fnName)) continue;
+    const callRe = new RegExp('(?<![\\w.])' + fnName + '\\s*\\(', 'g');
+    let cm;
+    let foundCall = false;
+    while ((cm = callRe.exec(src)) !== null) {
+      const before = src.slice(Math.max(0, cm.index - 12), cm.index);
+      if (/\bfunction\s+$/.test(before)) continue;
+      if (masked(mask, cm.index)) continue;
+      foundCall = true; break;
+    }
+    if (!foundCall) continue;
+    if (isEslintExempt(src, defIdx)) continue;
+    const line = lineOf(src, defIdx);
+    const raw = lineText(src, defIdx).trim();
+    listeners.push({ file, line, selector: fnName, kind: 'function-call', raw });
+  }
+}
+
+function detectListeners(filepaths, opts = {}) {
+  const projectDir = opts.projectDir || process.cwd();
+  const listeners = [];
+  for (const fp of filepaths) {
+    const rel = path.isAbsolute(fp) ? path.relative(projectDir, fp) : fp;
+    if (!isViewerSource(rel)) continue;
+    const abs = path.isAbsolute(fp) ? fp : path.join(projectDir, fp);
+    let src;
+    try { src = readSource(abs); } catch { continue; }
+    const mask = buildStringMask(src);
+    detectAddEventListener(rel, src, mask, listeners);
+    detectInlineHandler(rel, src, mask, listeners);
+    detectMutationObserver(rel, src, mask, listeners);
+    detectFunctionCall(rel, src, mask, listeners);
+  }
+  return listeners;
+}
+
+function loadManifest(projectDir) {
+  const p = path.join(projectDir, '.gsd-t', 'journey-manifest.json');
+  if (!fs.existsSync(p)) {
+    const err = new Error('manifest-missing');
+    err.code = 'MANIFEST_MISSING';
+    err.path = p;
+    throw err;
+  }
+  let raw;
+  try { raw = fs.readFileSync(p, 'utf8'); }
+  catch (e) {
+    const err = new Error('manifest-unreadable: ' + e.message);
+    err.code = 'MANIFEST_UNREADABLE';
+    throw err;
+  }
+  let parsed;
+  try { parsed = JSON.parse(raw); }
+  catch (e) {
+    const err = new Error('manifest-invalid-json: ' + e.message);
+    err.code = 'MANIFEST_INVALID';
+    throw err;
+  }
+  if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.specs)) {
+    const err = new Error('manifest-shape-invalid');
+    err.code = 'MANIFEST_INVALID';
+    throw err;
+  }
+  return parsed;
+}
+
+const KEY_SEP = '||';
+
+function findGaps(listeners, manifest) {
+  const covered = new Set();
+  const declared = [];
+  for (const spec of manifest.specs || []) {
+    for (const c of spec.covers || []) {
+      covered.add(c.file + KEY_SEP + c.selector);
+      declared.push({ name: spec.name, file: c.file, selector: c.selector, kind: c.kind });
+    }
+  }
+  const detectedKey = new Set();
+  for (const l of listeners) detectedKey.add(l.file + KEY_SEP + l.selector);
+  const gaps = [];
+  for (const l of listeners) {
+    const key = l.file + KEY_SEP + l.selector;
+    if (!covered.has(key)) {
+      gaps.push({ type: 'gap', file: l.file, line: l.line, selector: l.selector, kind: l.kind });
+    }
+  }
+  for (const d of declared) {
+    const key = d.file + KEY_SEP + d.selector;
+    if (!detectedKey.has(key)) {
+      gaps.push({ type: 'stale', name: d.name, file: d.file, selector: d.selector });
+    }
+  }
+  return gaps;
+}
+
+function formatReport(gaps) {
+  if (!gaps.length) return '';
+  const lines = [];
+  for (const g of gaps) {
+    if (g.type === 'gap') {
+      lines.push('GAP: ' + g.file + ':' + g.line + '  ' + g.selector + '  (' + g.kind + ')  no spec covers this');
+    } else {
+      lines.push('STALE: spec=' + g.name + '  covers ' + g.file + ' selector=' + g.selector + '  no such listener');
+    }
+  }
+  return lines.join('\n');
+}
+
+module.exports = {
+  detectListeners,
+  loadManifest,
+  findGaps,
+  formatReport,
+  isViewerSource,
+  KNOWN_KINDS,
+};

package/docs/architecture.md

@@ -1100,3 +1100,20 @@ M50 retires the prose-only "Playwright Readiness Guard" in favor of executable e
 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.
+
+## Journey Coverage Enforcement (M52, v3.22.x+)
+
+M52 layers a journey-coverage gate on top of M50's Playwright enforcement. M50 makes sure Playwright runs; M52 makes sure every interactive viewer surface has a journey spec asserting user-visible state change. Three components:
+
+1. **Listener detector** (`bin/journey-coverage.cjs`) — regex-based source-form scanner with single-pass string-mask precomputation (handles `//`, `/*…*/`, `<!-- -->`, `'`/`"`/template literals). Recognises 6 listener kinds per `journey-coverage-contract.md` §3: `addEventListener`, `inline-handler`, `function-call`, `mutation-observer`, `hashchange`, `delegated`. Exports `detectListeners`, `loadManifest`, `findGaps`, `formatReport`. Zero parser deps (no acorn/babel). Sub-100ms on the full viewer file set.
+
+2. **CLI** (`bin/journey-coverage-cli.cjs` → `gsd-t check-coverage`) — supports `--staged-only`, `--manifest PATH`, `--quiet`. Exit codes per contract §5: 0 = clean, 4 = coverage gap or stale entry, 2 = manifest missing/unreadable. Vacuous-pass when zero listeners + zero specs.
+
+3. **Commit-time gate** (`scripts/hooks/pre-commit-journey-coverage`) — auto-installed by `gsd-t install` and `gsd-t init`, manually re-installable via `gsd-t doctor --install-journey-hook`. Fires when staged files match the viewer-source pattern set (`scripts/gsd-t-transcript.html`, `scripts/gsd-t-dashboard-server.js`, `bin/gsd-t-dashboard*.cjs`, `e2e/journeys/`, `e2e/viewer/`). Idempotent install via `# >>> GSD-T journey-coverage gate >>>` marker block (mirrors M50 idiom). Fail-open on detector internal exception.
+
+The content layer that the enforcer measures against ships in M52 D2: 12 inaugural journey specs in `e2e/journeys/` (one per interactive surface), `.gsd-t/journey-manifest.json` with 12 entries 1:1 with the spec files, and 3 real-data NDJSON fixtures in `e2e/fixtures/journeys/` (sliced from captured `.gsd-t/transcripts/in-session-*.ndjson` files with PII scrub applied). Every assertion verifies state changed / data flowed / content loaded / widget responded — zero `toBeVisible`/`toBeAttached` shallow assertions across the 12 specs.
+
+A new Red Team category — "Test Pass-Through — Journey Edition" — extends `templates/prompts/red-team-subagent.md` to mandate adversarial validation: write ≥5 broken viewer patches, run the journey specs, every patch must be caught (verdict FAIL otherwise).
+
+Contract: `.gsd-t/contracts/journey-coverage-contract.md` v1.0.0.
+

package/docs/requirements.md

@@ -727,3 +727,25 @@ Acceptance:
 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.
+
+
+## M52 Rigorous User-Journey Coverage + Anti-Drift Test Quality (planned — 2026-05-06)
+
+| REQ-ID | Requirement Summary | Domain | Task(s) | Status |
+|--------|---------------------|--------|---------|--------|
+| REQ-M52-D1-01 | `bin/journey-coverage.cjs` walks `scripts/gsd-t-transcript.html` for every interactive listener (click, keydown, change, mousedown, drag, hashchange) and emits a normalized listing keyed by selector + event. | m52-d1-journey-coverage-tooling | T1 | done |
+| REQ-M52-D1-02 | `bin/journey-coverage.cjs` cross-references the listener listing against `e2e/journeys/*.spec.ts` to verify each listener has a corresponding journey spec asserting state change; reports missing-coverage rows; exits non-zero on gaps. | m52-d1-journey-coverage-tooling | T1, T3 | done (T1 detector + findGaps; CLI exit codes pending T3) |
+| REQ-M52-D1-03 | `journey-coverage-contract.md` (manifest schema + listener-pattern catalogue + gap rules + exit codes) STABLE; `.gsd-t/journey-manifest.json` (D2-authored) is the canonical enumeration of interactive viewer surfaces — supersedes the originally-proposed standalone `JOURNEYS.md` file. | m52-d1-journey-coverage-tooling | T2 | done |
+| REQ-M52-D1-04 | `scripts/hooks/pre-commit-journey-coverage` (auto-installed by `gsd-t install` and re-installable via `gsd-t doctor --install-journey-hook`, same shape as `pre-commit-playwright-gate`) blocks commits when viewer-source files are staged AND `bin/journey-coverage-cli.cjs --staged-only` reports uncovered surfaces. Fail-open on detector internal exception. | m52-d1-journey-coverage-tooling | T4 | done |
+| REQ-M52-D1-05 | `bin/gsd-t.js` wired with `installJourneyCoverageHook`, `check-coverage` subcommand, install-flow autoinstall, and `--install-journey-hook` doctor flag. Idempotent marker. | m52-d1-journey-coverage-tooling | T5 | done |
+| REQ-M52-D2-01 | 12 inaugural journey specs land in `e2e/journeys/`: `main-session-stream`, `click-completed-conversation`, `click-spawn-entry`, `splitter-drag`, `splitter-keyboard`, `right-rail-toggle`, `completed-collapse-toggle`, `auto-follow-toggle`, `kill-button`, `sessionstorage-persistence`, `keyboard-shortcuts`, `hashchange`. Every assertion proves user-visible state change (no `toBeVisible`-only specs). | m52-d2-journey-specs-and-fixtures | T2, T3, T4 | done |
+| REQ-M52-D2-02 | All 12 journey specs pass against the v3.22.x viewer (`scripts/gsd-t-transcript.html` + `scripts/gsd-t-dashboard-server.js`); `.gsd-t/journey-manifest.json` has 12 entries 1:1 with the spec files; `gsd-t check-coverage` exit 0. | m52-d2-journey-specs-and-fixtures | T4 | done |
+| REQ-M52-D3-01 | `templates/prompts/red-team-subagent.md` adds new mandatory category "Test Pass-Through — Journey Edition": for each journey spec, the adversary writes a deliberately-broken viewer impl that breaks the journey but satisfies the literal assertions of another spec. Each pass-through is a spec failure → tighten. | m52-d2-journey-specs-and-fixtures | T5 | done |
+| REQ-M52-D3-02 | M52 D2 Red Team run: ≥5 broken impls written against the 12 D2 journey specs; all caught; findings logged to `.gsd-t/red-team-report.md` § "M52 JOURNEY-EDITION RED TEAM"; pre-commit-journey-coverage hook exercised end-to-end (block + unblock paths). | m52-d2-journey-specs-and-fixtures | T5 | done |
+| REQ-M52-D4-01 | `e2e/fixtures/journeys/` ships 3 real-data NDJSONs sliced from `.gsd-t/transcripts/in-session-*.ndjson`: `fixture-medium-session.ndjson` (~50 frames), `fixture-completed-session.ndjson` (~150 frames), `fixture-multi-spawn.ndjson` (~80 frames across 3 spawns). PII scrub applied. | m52-d2-journey-specs-and-fixtures | T1 | done |
+| REQ-M52-D4-02 | `e2e/fixtures/journeys/replay-helpers.ts` exports `replayFixture(page, fixturePath)` that drives at least 3 of the 12 journey specs end-to-end via fixture replay and asserts: page renders without errors, frame count matches expected, scrolling works, no `[object Object]`/`undefined` literals visible, all bubble types render correctly. | m52-d2-journey-specs-and-fixtures | T1, T2 | done (replay-helpers shipped + main-session-stream uses fixture-medium-session via startReplayServer) |
+| REQ-M52-D5-01 | Doc-ripple: `~/.claude/CLAUDE.md` E2E Test Quality Standard rewritten to formally define "rigorous" (every interactive surface clicked, every assertion proves visible state change, journey specs not unit tests in browser clothing, real-data fixtures, adversarial Red Team on journeys); `templates/CLAUDE-global.md` matches; `commands/gsd-t-debug.md` + `gsd-t-execute.md` + `gsd-t-quick.md` + `gsd-t-verify.md` reference `journey-coverage.cjs` zero-gap requirement; `docs/architecture.md` adds "Journey Coverage Enforcement (M52)" section. | m52-d1-journey-coverage-tooling | T5 | done (architecture.md + CHANGELOG.md ripple completed during /gsd-t-verify; CLAUDE-global E2E Test Quality Standard already defines "functional behavior over element existence" — same doctrine M52 enforces mechanically) |
+| REQ-M52-VERIFY | Full unit suite 2166 baseline preserved + 12 journey specs + 3 real-data fixture replays all green; `gsd-t check-coverage` reports zero gaps; pre-commit-journey-coverage hook blocks deliberate test-commit-without-spec; Red Team finds ≥5 breakages, all caught; CHANGELOG entry written. | both | D1 T5, D2 T5 | done (unit 2195/2195, E2E 35/35 + 1 skip, `gsd-t check-coverage` exit 0, hook end-to-end exercised, Red Team 5/5 caught, CHANGELOG entry written) |
+
+Supporting contracts (to be written during D1):
+- `.gsd-t/contracts/journey-coverage-contract.md` (proposed) — listener detector API, gap-report schema, pre-commit hook semantics, JOURNEYS.md schema.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "3.22.10",
+  "version": "3.23.10",
   "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",

package/scripts/gsd-t-transcript.html

@@ -870,14 +870,10 @@
           });
           el.appendChild(dot); el.appendChild(name); el.appendChild(kill);
           el.addEventListener('click', () => {
-            // M48 — symmetric with renderRailEntry: in-session entries
-            // belong to the TOP pane only. Without this guard the legacy
-            // renderTree path (called for the `live` bucket when ≥2
-            // in-session NDJSONs exist) would mutate location.hash to an
-            // in-session-* value, polluting the URL and the rail's active
-            // highlight even though the hashchange handler now blocks
-            // bottom-pane SSE pinning.
-            if (isInSession(node)) return;
+            // M52 — symmetric with renderRailEntry: only the LIVE main
+            // session id is blocked from the bottom pane. Historical /
+            // additional in-session entries route normally.
+            if (isInSession(node) && node.spawnId === ('in-session-' + window.__mainSessionId)) return;
             if (node.spawnId === currentId) return;
             location.hash = node.spawnId;
           });
@@ -1006,12 +1002,13 @@
         });
         el.appendChild(dot); el.appendChild(name); el.appendChild(kill);
         el.addEventListener('click', () => {
-          // M48 — in-session conversation entries belong in the TOP pane only.
-          // The top pane is wired to /api/main-session and streams the
-          // current orchestrator session. Routing them through location.hash
-          // would also load them into the bottom pane (the SELECTED-SPAWN
-          // pane), making both panes show identical content.
-          if (isInSession) return;
+          // M52 — narrow the M48 Bug 4 guard. The TOP pane streams the LIVE
+          // main session via /api/main-session; only THAT specific in-session
+          // id should be blocked from the bottom pane (otherwise both panes
+          // would show identical content). Historical in-session conversations
+          // (the entire COMPLETED rail) are tagged in-session-* but are NOT
+          // the live main session — they must load into the bottom pane.
+          if (isInSession && node.spawnId === ('in-session-' + window.__mainSessionId)) return;
           if (node.spawnId === currentId) return;
           _ssSet(SS_KEY_SELECTED, node.spawnId);
           location.hash = node.spawnId;
@@ -1251,6 +1248,10 @@
       const mainStreamEl = document.getElementById('main-stream');
       function connectMain(sessionId) {
         if (mainSrc) { try { mainSrc.close(); } catch { /* gone */ } mainSrc = null; }
+        // M52 — expose the active main session id so the bottom-pane click +
+        // hashchange handlers can distinguish the LIVE main session (must stay
+        // top-only) from HISTORICAL in-session conversations (loadable below).
+        window.__mainSessionId = sessionId || null;
         if (!mainStreamEl) return;
         mainStreamEl.innerHTML = '';
         if (!sessionId) {
@@ -1284,6 +1285,18 @@
           .then((j) => {
             if (j && j.sessionId) {
               connectMain(j.sessionId);
+              // M52 — if the bottom pane was seeded with the live main
+              // session's id (e.g., from sessionStorage on reload), clear it
+              // out to prevent the M48 Bug 4 dual-pane mirror.
+              const liveId = 'in-session-' + j.sessionId;
+              const seededId = _ssGet(SS_KEY_SELECTED) || '';
+              if (seededId === liveId) {
+                _ssSet(SS_KEY_SELECTED, '');
+                if ((location.hash || '').slice(1) === liveId) {
+                  try { history.replaceState(null, '', location.pathname + location.search); } catch { /* ok */ }
+                }
+                connect('');
+              }
               const t1 = (typeof performance !== 'undefined' && performance.now) ? performance.now() : Date.now();
               try { console.debug('[m47] top-pane connected in', Math.round(t1 - t0), 'ms'); } catch { /* ok */ }
             } else {
@@ -1295,8 +1308,10 @@
 
       window.addEventListener('hashchange', () => {
         const id = (location.hash || '').slice(1);
-        // M48 — keep in-session-* ids out of the bottom pane (top pane only).
-        if (id && id.indexOf('in-session-') === 0) { return; }
+        // M52 — narrow the M48 Bug 4 guard. Only the LIVE main session's
+        // in-session id is blocked; historical in-session-* hashes load into
+        // the bottom pane normally (connect() already handles the SSE).
+        if (id && id === ('in-session-' + window.__mainSessionId)) { return; }
         if (id) { connect(id); pollSpawns(); }
       });
 
@@ -1304,19 +1319,15 @@
       //   1. data-spawn-id non-empty → connect that (bookmark flow)
       //   2. else sessionStorage.selectedSpawnId → connect that
       //   3. else show empty state
-      // M48 — never seed the bottom pane with an in-session-* id; the top
-      // pane already owns the main session, and showing it in both panes
-      // is one of the regressions Bug 4 fixes.
+      // M52 — historical in-session-* ids may seed the bottom pane (the M48
+      // Bug 4 case is now narrowed to the LIVE main session only, handled by
+      // the click + hashchange + fetchMainSession callback).
       let initialBottomId = '';
       if (spawnId) {
         initialBottomId = spawnId;
       } else {
         initialBottomId = _ssGet(SS_KEY_SELECTED) || '';
       }
-      if (typeof initialBottomId === 'string' && initialBottomId.indexOf('in-session-') === 0) {
-        initialBottomId = '';
-        _ssSet(SS_KEY_SELECTED, '');
-      }
       if (initialBottomId && !location.hash) location.hash = initialBottomId;
       connect(initialBottomId);
 

package/scripts/hooks/pre-commit-journey-coverage

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# GSD-T journey-coverage gate (M52 D1)
+# Blocks commits that touch viewer-source files when uncovered listeners are
+# detected by `bin/journey-coverage-cli.cjs --staged-only`.
+#
+# Install (opt-in):  gsd-t doctor --install-journey-hook
+# Remove:            rm .git/hooks/pre-commit  (or remove the marker block if
+#                    merged into an existing hook)
+#
+# Exit codes:
+#   0 — clean (no viewer-source files staged, OR coverage clean, OR fail-open)
+#   1 — blocked (uncovered listener in staged viewer-source files)
+#
+# Fail-open philosophy: a broken hook is worse than a permissive one. Detector
+# internal exception → exit 0 with a stderr warning, never block.
+
+set -e
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+
+VIEWER_SOURCE_PATTERNS=(
+  "scripts/gsd-t-transcript.html"
+  "scripts/gsd-t-dashboard-server.js"
+  "bin/gsd-t-dashboard"
+  "e2e/journeys/"
+  "e2e/viewer/"
+)
+
+STAGED="$(git diff --cached --name-only --diff-filter=AM 2>/dev/null || true)"
+[ -z "$STAGED" ] && exit 0
+
+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
+
+if [ -z "$matches" ]; then
+  exit 0
+fi
+
+CLI="$ROOT/bin/journey-coverage-cli.cjs"
+if [ ! -f "$CLI" ]; then
+  echo "[journey-coverage] WARNING: $CLI not found — fail-open." >&2
+  exit 0
+fi
+
+# Run the CLI in --staged-only mode. Capture stdout+stderr; rely on exit code.
+set +e
+OUT="$(node "$CLI" --staged-only --project-dir "$ROOT" 2>&1)"
+RC=$?
+set -e
+
+case "$RC" in
+  0)
+    exit 0
+    ;;
+  4)
+    echo "[journey-coverage] BLOCKED: uncovered viewer listener in staged files." >&2
+    echo "$OUT" >&2
+    echo "" >&2
+    echo "  Add a journey spec under e2e/journeys/ and update .gsd-t/journey-manifest.json." >&2
+    exit 1
+    ;;
+  2)
+    echo "[journey-coverage] BLOCKED: manifest missing/unreadable." >&2
+    echo "$OUT" >&2
+    exit 1
+    ;;
+  *)
+    # Unknown exit — fail-open so a detector bug doesn't break workflow.
+    echo "[journey-coverage] WARNING: detector exited $RC (fail-open):" >&2
+    echo "$OUT" >&2
+    exit 0
+    ;;
+esac

package/templates/prompts/red-team-subagent.md

@@ -42,3 +42,56 @@ Summary:
 - VERDICT: `FAIL` ({N} bugs found) | `GRUDGING PASS` (exhaustive search, nothing found)
 
 Write findings to `.gsd-t/red-team-report.md`. If bugs found, also append to `.gsd-t/qa-issues.md`.
+
+## Test Pass-Through — Journey Edition (M52)
+
+**Activates when**: `.gsd-t/journey-manifest.json` exists AND `e2e/journeys/` is non-empty (M52 D2 has landed).
+
+**Goal**: Prove the journey specs catch real regressions in the journeys they
+claim to cover. A journey spec that only checks "the button exists and is
+clickable" passes through any breakage to the user — that is what this
+category attacks.
+
+**Protocol**:
+
+1. For each spec in `.gsd-t/journey-manifest.json`, identify the listener(s) it covers.
+2. Write a deliberately-broken patch to `scripts/gsd-t-transcript.html` that
+   targets that listener — examples:
+   - Remove the listener entirely (`addEventListener` line stripped).
+   - Comment out the side-effect inside the handler (e.g. `_ssSet` call).
+   - Swap a sessionStorage key name (e.g. splitterPct key → `'XXX'`).
+   - Stub the handler to early-return (`if (true) return;` at top).
+   - Reverse a state mutation (`next ? 'true' : 'false'` → `next ? 'false' : 'true'`).
+3. Run the journey spec against the broken viewer.
+4. **PASS**: spec FAILS (red) → revert patch → spec PASSES (green). Record `caught`.
+5. **FAIL**: spec PASSES with broken viewer → SHALLOW SPEC, must be tightened.
+   Record `pass-through` and rewrite the assertion to verify state change /
+   data flow / content load.
+6. Write at least 5 broken patches across different specs. Each pass-through
+   is a verdict-level FAIL until rewritten.
+
+**Hook end-to-end exercise** (also part of this category):
+- Stage a viewer-source diff that adds a NEW listener with no manifest entry.
+- Confirm `pre-commit-journey-coverage` blocks the commit (exit 1).
+- Update `.gsd-t/journey-manifest.json` with a covering entry.
+- Confirm the hook now allows the commit (exit 0).
+- Both transitions logged in `.gsd-t/red-team-report.md` § "M52 JOURNEY-EDITION RED TEAM".
+
+**Findings format** in `.gsd-t/red-team-report.md` (append-only section):
+```
+## M52 JOURNEY-EDITION RED TEAM — {date}
+
+### Patch {N}: {short-name}
+- **Spec**: {spec-name}
+- **Broken-line(s)**: file:line — {one-line description of patch}
+- **Expected**: spec FAILS, caught the regression
+- **Actual**: {fail|pass-through}
+- **Verdict**: caught | PASS-THROUGH (must rewrite spec)
+
+### Hook end-to-end
+- Block exercise: {git diff details, exit code, stderr summary}
+- Unblock exercise: {manifest update, exit code, stderr summary}
+
+### VERDICT
+{GRUDGING PASS — N patches written, all caught | FAIL — {M} pass-through(s)}
+```