From 643a0428a26c4bee6d754b3338eceacf214334a4 Mon Sep 17 00:00:00 2001
From: Brad Cunningham <cunningham.be@gmail.com>
Date: Tue, 5 May 2026 08:58:21 -0400
Subject: [PATCH] spec: V56.4 browser-driven harness
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Sibling to V56.3's static-fixture harness pattern. Wraps existing
camofox-mcp infrastructure into per-detector contracts. Closes ~25
of 43 remaining wired detectors that need browser runtime
(console_error, react_error, hydration_mismatch, perf metrics,
nav-state, axe-driven a11y, interaction state).

Same DetectorContract type, same calibration scorecard, same serial
1-PR-per-detector cadence. New runner class only.

Buckets:
  A — direct console / error capture (5)
  B — production classifier reuse (4)
  C — perf metrics (7)
  D — nav state (5)
  E — interaction state (4)

Defers: race conditions (V56.5), IDOR variants (V56.5), multi-context
(V56.6), service/web worker (V56.7), WebRTC (residual), agent/LLM
(V56.8), visual layout (V56.9).

After V56.4 closes: 76/94 wired detectors with working harness.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/specs/V56.4_BROWSER_HARNESS.md | 383 ++++++++++++++++++++++++++++
 1 file changed, 383 insertions(+)
 create mode 100644 docs/specs/V56.4_BROWSER_HARNESS.md

diff --git a/docs/specs/V56.4_BROWSER_HARNESS.md b/docs/specs/V56.4_BROWSER_HARNESS.md
new file mode 100644
index 00000000..8ece1ad6
--- /dev/null
+++ b/docs/specs/V56.4_BROWSER_HARNESS.md
@@ -0,0 +1,383 @@
+# V56.4 — Browser-Driven Harness
+
+**Status:** Draft 1 — implementation contract (serial calibration, single-coder)
+**Author:** @architect
+**Date:** 2026-05-05
+**Depends on:** V56.3 (static-fixture harness), V49 (camofox MCP transport), V36 (browser-platform probe), V44 (calibration corpus)
+**Deferred to follow-ups:** V56.5 (concurrent-action / race), V56.6 (multi-context), V56.7 (agent), V56.8 (visual)
+
+---
+
+## 1. Problem statement
+
+V56.3 closed the static-fixture harness pattern: 51 of 94 wired BugKinds now have a per-detector contract, mini-fixture, and calibration scorecard. The remaining 43 wired kinds cannot fit that pattern because their detection signals are not in the response body — they only exist inside a real browser at runtime: console events, React error boundaries, DOM mutations under fault injection, Performance Observer entries, navigation history state, axe-core violations on a live DOM, focus chain traversal, service-worker / web-worker errors.
+
+These kinds DO already work in production through the batch pipeline (`bughunter run`) which runs camofox-mcp + per-phase classifiers. What's missing is a calibration-friendly harness that uses the same browser primitives but in the V56.3 shape: single fixture, single detector, sub-second run, scorecard pass/fail per assertion. Without that, regressions in browser-observed kinds attribute to the run, not the detector — exactly the gap V56 was meant to close.
+
+V56.4 lands a sibling harness pattern (`BrowserHarnessRunner`) that wraps the existing camofox infrastructure into a per-detector contract, parallel to V56.3's static `runHarness` path. Same DetectorContract type, same expected-clusters.jsonl format, same `bughunter test-detector <kind>` CLI, same per-PR-per-detector merge cadence. New runner class, new fixture template (HTML page that triggers the planted bug), new browser-observation harvest step.
+
+---
+
+## 2. Boundaries
+
+### 2.1 In scope
+
+- `BrowserHarnessRunner` class in `packages/cli/src/harness/browser-executor.ts`
+- New harness phase: probe phase (camofox navigate + observation harvest) before the existing classify phase
+- Fixture template: HTML pages that trigger the planted bug at load time
+- Per-detector contracts for the ~25 browser-observed kinds (see §6 for the list)
+- Mini-fixture pattern same as V56.3: bin/up.sh boots a static HTTP server on a fixed port, serves a small set of routes
+- Browser observation envelope (see §4): console events, errors, network requests, DOM snapshot, performance entries, axe results
+- `tools: ['browser-mcp']` flag in DetectorContract triggers BrowserHarnessRunner instead of static runHarness
+- Camofox tab lifecycle management: one `withTab()` per probe with explicit teardown
+- The serial calibration cadence (one detector per PR, scorecard ALL-PASS gate)
+
+### 2.2 Out of scope
+
+- Multi-tab / multi-context harness — deferred to V56.6
+- Concurrent-action / race-condition harness — deferred to V56.5
+- LLM-agent harness (prompt_injection_executed) — deferred to V56.7
+- Visual / screenshot-diff harness (i18n_rtl_layout_break, visual_anomaly) — deferred to V56.8
+- WebRTC / webrtc_ice_failure — genuinely needs WebRTC peer infrastructure; documented as honestly-residual deferred
+- Replacing or modifying the production batch pipeline (`bughunter run`)
+- New BugKinds — V56.4 strictly wraps existing detectors that already fire in the batch path
+
+### 2.3 External dependencies
+
+- `camofox-mcp` (already deployed at port 9377) — used via existing `BrowserMcpAdapter`
+- Existing `CamofoxBrowserMcpAdapter` from `packages/cli/src/adapters/browser-mcp.ts` — REUSED, not rewritten
+- Existing classify-phase functions (`classify/console.ts`, `classify/react.ts`, etc.) — invoked by the harness; not modified
+- Existing axe-core injection helpers (used by accessibility detectors) — REUSED
+- `bootFixture()` helper from V56.2.1 — REUSED for HTTP-server-backed fixtures
+
+---
+
+## 3. Existing code map (READ FIRST)
+
+### 3.1 Files you MUST read before writing any V56.4 code
+
+| File | Purpose for V56.4 |
+|---|---|
+| `/root/BugHunter/packages/cli/src/harness/executor.ts` | V56.3 harness — `runHarness()` is the static-fixture path. V56.4 ADDS a parallel `runBrowserHarness()`; does NOT modify the static path. |
+| `/root/BugHunter/packages/cli/src/adapters/browser-mcp.ts` (lines 118–250) | `BrowserMcpAdapter` interface + `CamofoxBrowserMcpAdapter` implementation. V56.4 uses `withTab()` + `evaluate()` + `snapshot()` + `cookies()`. |
+| `/root/BugHunter/packages/cli/src/cli/test-detector.ts` | V56.3 CLI runner. V56.4 adds a switch in `runOneContract()` based on `contract.requires.tools` — calls `runBrowserHarness()` when `'browser-mcp'` is in tools. |
+| `/root/BugHunter/packages/cli/src/detectors/contracts.ts` | `DetectorContract` type. V56.4 reuses unchanged; existing `tools: ['browser-mcp']` field already drives the dispatch. |
+| `/root/BugHunter/packages/cli/src/classify/console.ts` (line 24) | Production console_error classifier. V56.4 invokes it on harvested console events. |
+| `/root/BugHunter/packages/cli/src/classify/react.ts` (lines 38, 45) | Production hydration_mismatch + react_error classifiers. Same pattern. |
+| `/root/BugHunter/packages/cli/src/classify/network.ts` | Production network_5xx + network_4xx_unexpected (already harnessed in V56.3 via static runner — V56.4 ALSO covers them via browser-observed HAR for completeness, but the static path stays primary). |
+| `/root/BugHunter/packages/cli/src/discovery/browser-platform-probe.ts` | Bootstrap-script pattern for browser observation. V56.4's harvest script borrows the same install-then-poll shape. |
+| `/root/BugHunter/packages/cli/src/perf/web-vitals-vendored/web-vitals.umd.js` | Vendored web-vitals library. V56.4 perf detectors install this on each fixture page and harvest after settle. |
+| `/root/BugHunter/fixtures/detector-calibration/seo-mini/app/server.js` | Reference fixture — minimal HTTP server returning HTML. V56.4 fixtures follow this template; the HTML payload changes per detector. |
+| `/root/BugHunter/.claude/projects/-root/memory/feedback_test_detector_contracts_fully.md` | The 4-shape testing minimum — V56.4 fixtures MUST encode positive + negative + ≥2 edges + input-degradation. |
+
+### 3.2 Patterns to follow
+
+- **Fixture HTML structure:** one `<script>` per route that triggers the planted bug (or stays clean for negatives). Inline scripts only — no bundler. Page boots fast (<200ms typical).
+- **Browser harvest envelope:** install one `bootstrapScript` that subscribes to all observation channels (console.error, window.onerror, PerformanceObserver, MutationObserver as needed) and writes results to `window.__bughunterHarvest`. Single `evaluate(getHarvestScript)` call after settle reads it back.
+- **Settle window:** 1500ms default per probe (same as production browser-platform probe). Detectors that need longer (perf metrics waiting for LCP) override per-contract via `defaultBudgetMs`.
+- **Tab lifecycle:** `await browser.withTab(url, undefined, async scope => { ... harvest ... })` — the helper guarantees teardown on success and failure paths. NEVER `openTab` + `closeTab` manually in a runner; the V56.2 camofox tab leak fix is enforced via `withTab` only.
+- **Classifier invocation:** import the production classifier function unchanged, pass it the harvested envelope. Cluster shape comes back in the production format; V56.4 maps to `BugCluster[]` the same way V56.3 does.
+
+### 3.3 DO NOT
+
+- DO NOT modify `runHarness()` in `executor.ts`. V56.4 is a sibling, not a replacement.
+- DO NOT spawn camofox tabs without `withTab()`. The orphan-reaper fix from V56.2 only catches what `withTab` releases — manual `openTab` calls leak.
+- DO NOT inline-rewrite production classifiers. Import and call.
+- DO NOT make the harness path conditional on `process.env.BUGHUNTER_BROWSER_HARNESS` or any feature flag. The dispatch is data — `contract.requires.tools.includes('browser-mcp')` flips the runner path.
+- DO NOT mock `BrowserMcpAdapter` in the harness runner. The runner takes the adapter as a constructor arg; tests inject a mock. Production passes the real `CamofoxBrowserMcpAdapter`.
+- DO NOT couple browser fixtures to the static-fixture executor. Each browser fixture has its own `bin/up.sh` that boots an HTTP server on its own port; the harness composes camofox + that server.
+- DO NOT extend phase counts. Same phases as V56.3 — `validate`, `execute`, `classify`, `cluster`. The `execute` phase merely uses a different runner.
+
+---
+
+## 4. Architecture
+
+### 4.1 Runner shape
+
+```typescript
+// packages/cli/src/harness/browser-executor.ts
+
+export type BrowserHarnessOptions = {
+  contract: DetectorContract;
+  target: HarnessTarget;          // appBaseUrl + fixturePath
+  browser: BrowserMcpAdapter;     // inject so tests can mock
+  budgetMs: number;
+  signal?: AbortSignal;
+};
+
+export async function runBrowserHarness(opts: BrowserHarnessOptions): Promise<HarnessResult> {
+  // Phase: validate — wait for HTTP fixture port + camofox health check
+  // Phase: execute — for each route in expected-clusters.jsonl:
+  //   await browser.withTab(`${appBaseUrl}${route}`, undefined, async scope => {
+  //     await scope.evaluate(BOOTSTRAP_INSTALL_SCRIPT);
+  //     await sleep(settleMs);
+  //     const envelope = (await scope.evaluate(HARVEST_SCRIPT)).value as HarvestEnvelope;
+  //     observationsByRoute.set(route, envelope);
+  //   });
+  // Phase: classify — call per-kind production classifier on each envelope, filter to contract.kind
+  // Phase: cluster — assemble BugCluster[] same shape as V56.3
+}
+```
+
+### 4.2 HarvestEnvelope
+
+```typescript
+export type HarvestEnvelope = {
+  pageRoute: string;
+  consoleEvents: Array<{ level: 'log'|'warn'|'error'; message: string; stack?: string }>;
+  uncaughtErrors: Array<{ message: string; filename?: string; lineno?: number; stack?: string }>;
+  networkRequests: Array<{ method: string; url: string; status: number; durationMs?: number; responseHeaders?: Record<string,string> }>;
+  performanceEntries: Array<{ entryType: string; name: string; startTime: number; duration?: number; value?: number }>;
+  domState: { activeElementTag: string|null; bodyTextHash: string };
+  axeResults?: AxeResultsEnvelope;          // only present when contract requests axe injection
+  navHistory?: Array<{ url: string; ts: number }>;  // only present for nav-state detectors
+  browserPlatform?: BrowserPlatformEnvelope; // for SRI / COOP-COEP / Trusted Types runtime variants
+};
+```
+
+### 4.3 Bootstrap script
+
+A single `BOOTSTRAP_INSTALL_SCRIPT` constant installed via `evaluate()` on first navigate. It registers:
+- `console.error` / `console.warn` capture (push into `window.__bh.consoleEvents`)
+- `window.addEventListener('error', ...)` for uncaught exceptions
+- `window.addEventListener('unhandledrejection', ...)`
+- `PerformanceObserver` for `largest-contentful-paint`, `first-input`, `layout-shift`, `longtask`
+- `MutationObserver` if the contract sets `requires.observeMutations: true` (extension to DetectorRequires — see §5)
+- Network request log via `PerformanceObserver({ type: 'resource' })` (replaces HAR proxy for this purpose)
+
+A single `HARVEST_SCRIPT` reads `window.__bh` and returns the envelope.
+
+### 4.4 Dispatch point
+
+In `cli/test-detector.ts`'s `runOneContract()`:
+
+```typescript
+const usesBrowser = contract.requires.tools.includes('browser-mcp');
+const result = usesBrowser
+  ? await runBrowserHarness({ contract, target, browser, budgetMs })
+  : await runHarness({ contract, target, budgetMs });
+```
+
+`browser` is constructed lazily on first browser-harness need. If camofox-mcp is unreachable, the test-detector run for that kind returns `expect: 'skipped', reason: 'browser_mcp_unavailable'` — same skip pattern as V56.3 fixture-not-built.
+
+---
+
+## 5. Contract changes
+
+### 5.1 No new fields required for the v1 set
+
+The existing `DetectorContract.requires.tools` already supports `'browser-mcp'`. The dispatch is purely on that flag. V56.4 fixtures populate the field; runners react.
+
+### 5.2 Optional field: `observationWindow` (introduced in V56.4)
+
+```typescript
+export type DetectorRequires = {
+  // ... existing fields ...
+  /**
+   * V56.4: settle time after install-bootstrap before harvest.
+   * Default 1500ms. Perf detectors awaiting LCP may set 3000–5000ms.
+   * Capped at defaultBudgetMs / 4 to leave room for navigate + classify.
+   */
+  observationWindowMs?: number;
+};
+```
+
+### 5.3 ClusterAssertion stays the same
+
+Existing `expected-clusters.jsonl` format works unchanged. Match keys (`page`, `role`, `signaturePrefix`) all apply. New skipped reasons added to the discriminated union: `'browser_mcp_unavailable'`, `'camofox_tab_failure'`, `'observation_window_exceeded'`.
+
+---
+
+## 6. Detector roster — the 25 kinds V56.4 closes
+
+Bucket A — direct console / error capture (5):
+- `console_error` — fixture page calls `console.error('boom')` at load. Negative: clean page.
+- `react_error` — fixture imports a small React app with a deliberately-throwing component.
+- `hydration_mismatch` — SSR-rendered HTML doesn't match client-rendered DOM.
+- `unhandled_exception` — fixture page throws from a microtask.
+- `dom_error_text` — fixture page renders text matching error patterns ("Something went wrong", stack-trace shapes) into the DOM.
+
+Bucket B — production classifier reuse (4):
+- `missing_state_change` — submit form, observe DOM diff before/after.
+- `surface_call_failed` — fixture exposes a `/api/broken` that 500s; page makes a client fetch and catches; harness observes failed-fetch state.
+- `accessibility_critical` — inject axe-core, run, harvest violations.
+- `axe_color_contrast_strong` — same as above, filter to color-contrast rule id.
+
+Bucket C — perf metrics (7):
+- `slow_lcp` — fixture page has a deliberately-large LCP element.
+- `slow_inp` — fixture page has a deliberately-blocking input handler.
+- `high_cls` — fixture page injects content above-fold after load.
+- `n_plus_one_api_calls` — fixture page makes 5 sequential fetches to /api/items/:i.
+- `request_dedup_missing` — fixture page makes 3 identical concurrent fetches to /api/users.
+- `request_cancellation_missing` — fixture page navigates while a fetch is in flight; harness observes the request still completes.
+- `main_thread_blocked` — fixture page runs a sync 200ms loop on click.
+
+Bucket D — nav state (5):
+- `nav_state_corruption` — submit form, navigate back, observe form fields not restored.
+- `nav_resubmit_on_back` — observe that going back triggers a resubmit confirmation OR silently re-POSTs.
+- `nav_refresh_double_mutation` — refresh during a mutation; observe mutation fires twice.
+- `nav_form_state_lost` — navigate forward then back; form values lost.
+- `nav_form_state_stale` — fill form, navigate away, navigate back; observe stale value persists despite server-side change.
+
+Bucket E — interaction state (4):
+- `keyboard_trap` — fixture has a modal that traps Tab; harness presses Tab N times and observes focus stuck.
+- `focus_lost_after_action` — click a button that opens a dialog; observe activeElement after the click.
+- `shadow_dom_a11y_violation` — fixture renders shadow DOM with missing aria; axe flags it.
+- `visibility_change_state_loss` — dispatch visibilitychange = hidden; observe state loss.
+
+Bucket A through E = 25 detectors. Same serial-calibration cadence as V56.3: one PR per detector (or tight thematic batch), ALL-PASS scorecard before merge.
+
+---
+
+## 7. Phasing
+
+### 7.1 V56.4.1 — runner infrastructure (1 PR)
+
+- Implement `runBrowserHarness()` + `BOOTSTRAP_INSTALL_SCRIPT` + `HARVEST_SCRIPT`
+- Wire dispatch in `test-detector.ts` (data-driven on `tools.includes('browser-mcp')`)
+- Add unit tests for the harness runner with a mock `BrowserMcpAdapter`
+- Add `'browser_mcp_unavailable'` and `'camofox_tab_failure'` to ClusterAssertion skip-reason union
+- No new contracts yet — runner ships dormant, dispatched-to only when V56.4.2+ adds the first contract
+- Build clean + lockstep tests pass + 26/26 contract tests still pass
+
+### 7.2 V56.4.2 through V56.4.6 — detector batches (per spec §6 buckets)
+
+Each batch = one PR per detector, calibration scorecard ALL-PASS before merge. Order:
+- V56.4.2 — Bucket A (5 PRs): console_error, react_error, hydration_mismatch, unhandled_exception, dom_error_text
+- V56.4.3 — Bucket B (4 PRs): missing_state_change, surface_call_failed, accessibility_critical, axe_color_contrast_strong
+- V56.4.4 — Bucket C (7 PRs): perf metrics
+- V56.4.5 — Bucket D (5 PRs): nav state
+- V56.4.6 — Bucket E (4 PRs): interaction state
+
+Total: 25 detector PRs + 1 infrastructure PR = 26 PRs across V56.4.
+
+### 7.3 Stop conditions
+
+- After Bucket A closes, run a coverage audit: are the harvest envelope shapes correct? Any signal we forgot to capture?
+- After Bucket C closes, audit the perf-metric reliability — flake rate on `slow_lcp` may be high; if flake >5% across 10 runs, gate the bucket as "advisory" with a soft pass criterion.
+- After all 5 buckets close, run the full V56.4 scorecard via `bughunter test-detector all` and capture timing. If total runtime exceeds 5 minutes, profile and parallelize at the test-detector level (V56.4.7).
+
+---
+
+## 8. Testing
+
+### 8.1 Per-detector calibration scorecard (the 4-shape minimum from feedback_test_detector_contracts_fully)
+
+Every browser-harness fixture MUST encode:
+1. Positive — bug planted, detector fires
+2. Negative — clean route, detector silent
+3. Edge ≥2 — boundary cases (e.g., perf metric just-below vs just-above threshold)
+4. Input degradation — malformed page (broken HTML, JS syntax error in unrelated script) — detector still fires correctly OR skips cleanly with a warning, never crashes
+
+Same `expect: 'fires' | 'silent' | 'skipped'` ladder as V56.3.
+
+### 8.2 Runner unit tests
+
+- `runBrowserHarness` happy path: mocked BrowserMcpAdapter returns a synthetic envelope, classifier produces clusters, scorecard passes.
+- `runBrowserHarness` with adapter returning a tab-creation error: returns skipped result with reason `camofox_tab_failure`.
+- `runBrowserHarness` with adapter returning malformed envelope: returns skipped result with reason `observation_window_exceeded` if settle timed out, otherwise propagates the error with a structured error payload.
+- Lockstep: every `harness: true` row added in V56.4 has exactly one DETECTOR_CONTRACTS entry.
+
+### 8.3 Tab-leak audit
+
+After each V56.4.x merge, run the smoke trio:
+```
+bughunter test-detector <kind>; sleep 5; pgrep -af camofox | grep -v grep | wc -l
+```
+Expected: zero camofox tab processes after the run completes. The V56.2 orphan-reaper fix is the safety net; `withTab()` is the primary mechanism.
+
+### 8.4 Anti-vacuous-test guard
+
+Same vacuous-test trap that bit V56.2 applies here. After Bucket A closes, MANUALLY inspect ONE detector's calibration output: does the harness actually invoke camofox? Does the envelope contain real console events from the fixture page, not an empty array? If the envelope is uniformly `{ consoleEvents: [], ... }`, the harness is vacuous and the scorecard is lying.
+
+---
+
+## 9. Architecture decisions
+
+### 9.1 Why a sibling runner instead of extending `runHarness`?
+
+Different I/O. Static `runHarness` does HTTP requests + body parsing — synchronous-style, fast, no external service dependency. Browser harness does camofox MCP roundtrips — each `evaluate()` is a JSON-RPC call over an MCP transport, several seconds round-trip, requires the camofox process to be alive. Mixing them in one function means every static detector pays the camofox import cost. Sibling-runner with a one-line dispatch keeps each path fast for its own kinds.
+
+### 9.2 Why per-detector classifier reuse instead of new harness-only classifiers?
+
+V56.2.1 lesson: when the harness implements its own detection logic separate from production, the harness drift is invisible. By calling the production classifier on the harvested envelope, harness pass = production pass. If the production classifier changes, the harness scorecard catches it without separate test maintenance.
+
+(Counterpoint observed in V56.3: for static detectors where the production path uses axe-core / browser-mcp / DB invariants, we DID write static-heuristic harness paths. That was right for V56.3 because static probes can't invoke axe-core; for V56.4 the harness runs in a real browser, so reusing the production classifier is the right call.)
+
+### 9.3 Why HTTP-server-backed fixtures instead of inline `data:text/html` URLs?
+
+`data:` URLs work for trivial pages but break on:
+- Cross-origin fetches (the planted bug often involves the page calling `/api/something`)
+- `<script src="/foo.js">` references
+- Cookies / session state
+- HTML page hash routing (data: URLs have no resolvable origin)
+
+A fixture HTTP server (port + static file routing) costs 60 lines of Node and gives every detector the same primitives. Same pattern as V56.3 fixtures; only the page contents differ.
+
+### 9.4 Why one PR per detector instead of one PR per bucket?
+
+V56.2.1 lesson again: when a parallel-dispatched batch hits a structural issue (e.g., the V56.2 vacuous-test trap), one bug becomes 5+ rolled-back commits. Per-detector serial PRs let the integration error surface immediately and stay scoped.
+
+### 9.5 Why budget the runner at 30s default?
+
+Camofox roundtrip + settle + harvest = ~3–5s typical. 4-shape testing means 4–6 routes per detector. Worst case ~30s. Same hard cap as V56.3 — not a coincidence; it's the right default for detector-level testing.
+
+### 9.6 Tab-leak risk
+
+Every V56.4 detector spawns and tears down camofox tabs via `withTab()`. The fix from V56.2 (force-close + orphan reaper) keeps leak count low under normal operation, but stress runs (e.g., `test-detector all`) can still leak if camofox itself crashes mid-run. Mitigation: post-run `pgrep` audit in CI; alert if camofox process count grows monotonically across consecutive runs.
+
+---
+
+## 10. Risks
+
+| Risk | Severity | Mitigation |
+|---|---|---|
+| Camofox flakiness (transport timeouts, tab init failures) | High — directly impacts scorecard reliability | Per-detector skip with structured reason; audit flake rate after each bucket |
+| Perf-metric variance (LCP / INP measured in milliseconds) | Medium | Use threshold + ε buffer in expected-clusters.jsonl; allow ≥2 retries before declaring fail |
+| Vacuous-test trap (harness runs but envelope is empty) | High | Anti-vacuous audit (§8.4) after each bucket; never trust scorecard ALL-PASS without one manual envelope inspection |
+| Bootstrap script not installing before bug fires | Medium | Use `addInitScript` (camofox feature, V0.23+) when available; fall back to early-evaluate with a warning |
+| Cross-detector observation interference (one detector's bootstrap leaks into another's tab) | Low (each `withTab` is isolated) | Audit: every fixture run uses a fresh tab; never reuse a tab across `withTab()` boundaries |
+| Camofox process death during a long bucket run | Medium | Wrap `withTab` in retry-with-restart; cap total restarts at 3 per `test-detector all` invocation |
+| Production classifier API drift (a phase function adds a required field) | Low — caught by typescript build | TS will fail the build; no silent regression risk |
+
+---
+
+## 11. Acceptance criteria
+
+V56.4 is "done" when:
+
+1. `runBrowserHarness()` exists in `packages/cli/src/harness/browser-executor.ts` with full unit-test coverage
+2. `bughunter test-detector <kind>` correctly dispatches to browser-harness for `tools.includes('browser-mcp')` kinds
+3. All 25 kinds in §6 have:
+   - DetectorContract entry in `DETECTOR_CONTRACTS`
+   - `harness: true` flag in DETECTOR_REGISTRY
+   - Mini-fixture under `fixtures/detector-calibration/<kind>-mini/` with the 4-shape minimum
+   - Calibration scorecard ALL-PASS recorded in the merge PR description
+4. Lockstep test passes: every `harness: true` row has exactly one DETECTOR_CONTRACTS entry, contract count = 76 (51 V56.3 + 25 V56.4)
+5. README updated with new coverage tally (51 → 76 of 94 wired)
+6. The remaining 18 kinds are documented in README as honestly-deferred with a link to V56.5 / V56.6 / V56.7 / V56.8
+
+---
+
+## 12. Out-of-scope clarification
+
+Detectors NOT in V56.4's roster and their intended home:
+
+- IDOR variants (`idor_horizontal`, `idor_horizontal_mutate`, `idor_vertical_role_escalate`, `idor_vertical_suspicious`) — V56.5 IDOR-extension harness (extends the existing `idor-mini` fixture; pure HTTP, no browser needed)
+- Race conditions (5) — V56.6 concurrent-action harness (builds on V56.4's BrowserHarnessRunner)
+- Multi-context (`multi_context_state_divergence`) — V56.7 multi-context harness
+- Service worker / web worker / WebRTC — V56.8 worker harness
+- `prompt_injection_executed` — V56.9 agent harness
+- `i18n_rtl_layout_break`, `visual_anomaly` — V56.10 visual harness (screenshot diffing)
+- Network-fault kinds — could fit V56.4 if the harness uses `applyNetworkFault` mid-probe; deferred to V56.4.7 if scope grows
+
+WebRTC / `webrtc_ice_failure` — genuinely-residual deferred. Documented honestly in registry.
+
+---
+
+## 13. Approval gate
+
+Before V56.4.1 implementation begins, Brad reviews:
+- §6 detector roster — does the bucket grouping match priorities?
+- §7.2 ordering — is Bucket A first the right call, or should Bucket C (perf) lead?
+- §10 risk table — is the camofox-flakiness mitigation enough, or do we want an explicit "if flake > X%, gate the bucket" line?