chore(agentic): enforce authenticated-Brave QA across agent guidance (#565)

## What

Make the **authenticated Brave QA profile** the single source of truth
for local browser verification across all agent guidance, and add
enforcement so the policy cannot silently drift back to isolated-browser
proof.

## Changes

- **`scripts/check-browser-verification-policy.mjs`** (new): asserts the
5 guidance files (`AGENTS.md`, `CLAUDE.md`,
`packages/{admin,client,shared}/AGENTS.md`) carry the required
authenticated-Brave phrases, bans stale isolated-browser guidance
repo-wide, and verifies the `package.json` wiring.
- **`scripts/require-authenticated-browser-qa.mjs`** (new): fails local
`agentic:browser-proof` unless `CI=true`, so isolated / clean-room proof
can't be reported as authenticated local QA.
- **`package.json`**: runs `check:browser-verification-policy` inside
`agentic:check`, and guards `agentic:browser-proof` with the new script.
- **`AGENTS.md`, `CLAUDE.md`,
`packages/{admin,client,shared}/AGENTS.md`**: replace the prior isolated
/ non-default Brave browser-proof guidance with the authenticated Brave
QA path (Claude Code `/chrome` + Brave profile, Codex browser-extension
path, computer-use fallback; report QA blocked rather than substitute
isolated proof).

## Verification

- `bun run check:browser-verification-policy` -> pass (5 guidance files)
- `bun run agentic:check` -> pass (guidance, policy,
design-md/generated/tokens, stories 176/176, story-quality)

## Notes

- Touches security-sensitive agent-operating surfaces (`AGENTS.md`,
`CLAUDE.md`, `package.json`); flagged for review.
- Not spawned from a Linear issue; link one if this should be tracked.
- Follow-up: the two new scripts are not yet listed in
`scripts/README.md` (repo convention); can add on request.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: Oba-One

.agents/skills/audit-then-ship/SKILL.md

@@ -88,7 +88,7 @@ Hard rules:
 Apply only the approved fixes, in order. For each:
 
 1. Make the edit.
-2. **Verify the change in the same turn**: re-read the file, run the targeted test, or read the rendered DOM (Brave-backed browser MCP) for UI changes. No "should work" claims. (See AGENTS.md → *Verify Before Claiming Success*.)
+2. **Verify the change in the same turn**: re-read the file, run the targeted test, or read the rendered DOM through the authenticated Brave QA profile for UI changes. No "should work" claims. (See AGENTS.md → *Verify Before Claiming Success*.)
 3. Move to the next.
 
 **If you discover a new issue mid-fix**:

.agents/skills/debug/SKILL.md

@@ -107,7 +107,7 @@ Fires for `user_bug_triage` mode. Use this as the gating frame whenever any exte
 regardless of phrasing or role. Apply this BEFORE choosing UI Regression or Data/API/Contract
 protocols; this decides which one fits.
 
-1. **Reproduce, with the user's exact inputs.** Drive the real surface (Brave-backed browser MCP against
+1. **Reproduce, with the user's exact inputs.** Drive the real surface (authenticated Brave QA profile against
    `localhost` or prod in Brave, real auth mode, real garden, real entry path). Target: trigger the failure
    yourself within 5 minutes. Do not open PostHog or Sentry yet. If reproducing is impossible, document why
    and proceed with explicit caveat.

.agents/skills/design/defect-grammar.md

@@ -8,12 +8,12 @@ How Claude (and subagents) resolve casual admin-UI defect reports to an exact DO
 
 When the user reports anything off on an admin surface, the agent MUST resolve to a canonical `Admin*` wrapper or canvas region before proposing an edit. Never guess. Escalate in this order:
 
-### Tier 1 — Live DOM via Brave-Backed Browser MCP (preferred)
+### Tier 1 — Live DOM via Authenticated Brave QA (preferred)
 
-If an admin tab is open in Brave through a Brave-backed browser MCP, read the rendered DOM to locate the target:
+If an admin tab is open in the authenticated Brave QA profile and the Codex or Claude browser-extension path can control it, read the rendered DOM to locate the target:
 
 ```js
-// Via the available Brave-backed browser MCP JavaScript tool
+// Via the authenticated Brave browser-extension JavaScript tool
 Array.from(document.querySelectorAll('[data-component], [data-region]')).map(el => ({
   component: el.dataset.component,
   variant: el.dataset.variant,
@@ -45,7 +45,7 @@ Narrow candidates by:
 | "the tooltip" | `data-component="AdminTooltip"` |
 | "the badge" / "notification dot" | `data-component="AdminBadge"` |
 
-### Tier 2 — Static grep (Brave-backed browser MCP unavailable, or page not open)
+### Tier 2 — Static grep (authenticated Brave access unavailable, or page not open)
 
 ```bash
 grep -rn 'data-component="Admin<X>"' packages/admin/src/views/<workspace>/
@@ -104,7 +104,7 @@ The left column is what the user says. The right column is the internal statemen
 
 Design-system updates do not automatically propagate to casual issue reports. Before `data-component` / `data-region` / `data-workspace`, a description like "the thing looks off" forced the agent to guess between 5+ candidate components; guesses miss, which is how "updates to the design system don't seem to address identified issues" happens.
 
-The data attributes make the DOM self-identifying. This file tells the agent to **read them** (via Brave-backed browser MCP or grep) **before editing**, so casual user input maps to exact canonical targets. The grammar is a tool the agent uses on itself, not a vocabulary imposed on the user.
+The data attributes make the DOM self-identifying. This file tells the agent to **read them** (via authenticated Brave QA or grep) **before editing**, so casual user input maps to exact canonical targets. The grammar is a tool the agent uses on itself, not a vocabulary imposed on the user.
 
 ## Related
 
@@ -113,4 +113,4 @@ The data attributes make the DOM self-identifying. This file tells the agent to
 - [language.md](./language.md) — full Warm Earth token + motion spec
 - Project rules: `.claude/rules/frontend-design.md`
 - Tooling: `bun run check:design-tokens`, `bun run lint:vocab`
-- Brave-backed browser MCP tools: use the project `.mcp.json` `brave-devtools` server or a Brave-attached Claude browser extension. Never use Google Chrome, Chrome for Testing, Chromium, or Edge for Green Goods browser proof.
+- Authenticated Brave QA: use the Codex browser-extension path or the Claude Code Chrome/Chromium extension path against the already-open authenticated Brave profile/tab. If that access is blocked, report QA as blocked rather than switching to an isolated Browser, Playwright, or DevTools MCP profile.

.claude/skills/audit-then-ship/SKILL.md

@@ -88,7 +88,7 @@ Hard rules:
 Apply only the approved fixes, in order. For each:
 
 1. Make the edit.
-2. **Verify the change in the same turn**: re-read the file, run the targeted test, or read the rendered DOM (Brave-backed browser MCP) for UI changes. No "should work" claims. (See CLAUDE.md → *Verify Before Claiming Success*.)
+2. **Verify the change in the same turn**: re-read the file, run the targeted test, or read the rendered DOM through the authenticated Brave QA profile for UI changes. No "should work" claims. (See CLAUDE.md → *Verify Before Claiming Success*.)
 3. Move to the next.
 
 **If you discover a new issue mid-fix**:

.claude/skills/debug/SKILL.md

@@ -107,7 +107,7 @@ Fires for `user_bug_triage` mode. Use this as the gating frame whenever any exte
 regardless of phrasing or role. Apply this BEFORE choosing UI Regression or Data/API/Contract
 protocols; this decides which one fits.
 
-1. **Reproduce, with the user's exact inputs.** Drive the real surface (Brave-backed browser MCP against
+1. **Reproduce, with the user's exact inputs.** Drive the real surface (authenticated Brave QA profile against
    `localhost` or prod in Brave, real auth mode, real garden, real entry path). Target: trigger the failure
    yourself within 5 minutes. Do not open PostHog or Sentry yet. If reproducing is impossible, document why
    and proceed with explicit caveat.

.claude/skills/design/defect-grammar.md

@@ -8,12 +8,12 @@ How Claude (and subagents) resolve casual admin-UI defect reports to an exact DO
 
 When the user reports anything off on an admin surface, the agent MUST resolve to a canonical `Admin*` wrapper or canvas region before proposing an edit. Never guess. Escalate in this order:
 
-### Tier 1 — Live DOM via Brave-Backed Browser MCP (preferred)
+### Tier 1 — Live DOM via Authenticated Brave QA (preferred)
 
-If an admin tab is open in Brave through a Brave-backed browser MCP, read the rendered DOM to locate the target:
+If an admin tab is open in the authenticated Brave QA profile and the Codex or Claude browser-extension path can control it, read the rendered DOM to locate the target:
 
 ```js
-// Via the available Brave-backed browser MCP JavaScript tool
+// Via the authenticated Brave browser-extension JavaScript tool
 Array.from(document.querySelectorAll('[data-component], [data-region]')).map(el => ({
   component: el.dataset.component,
   variant: el.dataset.variant,
@@ -45,7 +45,7 @@ Narrow candidates by:
 | "the tooltip" | `data-component="AdminTooltip"` |
 | "the badge" / "notification dot" | `data-component="AdminBadge"` |
 
-### Tier 2 — Static grep (Brave-backed browser MCP unavailable, or page not open)
+### Tier 2 — Static grep (authenticated Brave access unavailable, or page not open)
 
 ```bash
 grep -rn 'data-component="Admin<X>"' packages/admin/src/views/<workspace>/
@@ -104,7 +104,7 @@ The left column is what the user says. The right column is the internal statemen
 
 Design-system updates do not automatically propagate to casual issue reports. Before `data-component` / `data-region` / `data-workspace`, a description like "the thing looks off" forced the agent to guess between 5+ candidate components; guesses miss, which is how "updates to the design system don't seem to address identified issues" happens.
 
-The data attributes make the DOM self-identifying. This file tells the agent to **read them** (via Brave-backed browser MCP or grep) **before editing**, so casual user input maps to exact canonical targets. The grammar is a tool the agent uses on itself, not a vocabulary imposed on the user.
+The data attributes make the DOM self-identifying. This file tells the agent to **read them** (via authenticated Brave QA or grep) **before editing**, so casual user input maps to exact canonical targets. The grammar is a tool the agent uses on itself, not a vocabulary imposed on the user.
 
 ## Related
 
@@ -113,4 +113,4 @@ The data attributes make the DOM self-identifying. This file tells the agent to
 - [language.md](./language.md) — full Warm Earth token + motion spec
 - Project rules: `.claude/rules/frontend-design.md`
 - Tooling: `bun run check:design-tokens`, `bun run lint:vocab`
-- Brave-backed browser MCP tools: use the project `.mcp.json` `brave-devtools` server or a Brave-attached Claude browser extension. Never use Google Chrome, Chrome for Testing, Chromium, or Edge for Green Goods browser proof.
+- Authenticated Brave QA: use the Codex browser-extension path or the Claude Code Chrome/Chromium extension path against the already-open authenticated Brave profile/tab. If that access is blocked, report QA as blocked rather than switching to an isolated Browser, Playwright, or DevTools MCP profile.

AGENTS.md

@@ -148,11 +148,12 @@ Single design language across frontend packages, with distinct admin, installed
 
 ## Agentic Modern Web Standard
 
-- Baseline target: Baseline Widely Available. Before frontend, UI, CSS, accessibility, browser proof, or web-design changes, use repo-installed Modern Web Guidance through `bun run agentic:guidance` to search and retrieve current Chrome guidance as documentation/source material only; Green Goods browser proof still runs in Brave. Then apply the repo's Warm Earth and package-level design rules.
+- Baseline target: Baseline Widely Available. Before frontend, UI, CSS, accessibility, browser proof, or web-design changes, use repo-installed Modern Web Guidance through `bun run agentic:guidance` to search and retrieve current Chrome guidance as documentation/source material only; Green Goods local QA uses the authenticated Brave QA profile, while CI clean-room browser proof uses Brave only as non-authenticated evidence. Then apply the repo's Warm Earth and package-level design rules.
 - Prefer semantic HTML, native controls, platform CSS, and browser primitives before custom JavaScript. Keep headings, landmarks, form labels, accessible names, focus order, visible focus, touch targets, loading/error/empty states, and reduced-motion behavior legible to humans, assistive tech, and browser agents.
-- Run `bun run agentic:check` as the hard guidance-readiness front door for repo-installed Modern Web Guidance, design docs, token drift, Codex/skill guidance, and shared Storybook story quality. Use `bun run agentic:verify` for Storybook-backed component proof, and `bun run agentic:browser-proof` for built-route proof across client, admin, and docs when layout, interaction, motion, or public routes change. The route proof writes screenshots, accessibility summaries, `/llms.txt` status, reduced-motion state, console/page errors, overflow checks, and WebMCP discovery to `.codex-artifacts/agentic-browser-proof/`; run `bun run lighthouse` when the heavier Lighthouse lane is needed. `dev-surfaces` remains the cross-repo/global doctor for shared Modern Web Guidance cache refresh, Brave, and MCP readiness.
-- For local human/agent browser walkthroughs, WebMCP validation, extension review, visual debugging, and DevTools MCP proof, use Brave with an isolated/non-default profile. Do not silently fall back to any non-Brave browser for Green Goods browser proof.
-- Brave DevTools MCP is project-configured in `.mcp.json` through `scripts/mcp/brave-devtools.mjs`; use it as the Brave-backed DevTools MCP path for live browser debugging, rendered DOM proof, console/network/performance inspection, screenshots, traces, and WebMCP discovery when troubleshooting Green Goods. The wrapper calls the upstream `chrome-devtools-mcp` package because that is the protocol package name, but the browser executable must be Brave. It rejects Google Chrome, Chrome for Testing, Chromium, and Edge paths. The wrapper uses the repo Node 22 toolchain, Brave browser discovery, isolated browser profiles, localhost HTTPS support, WebMCP debug category, and WebMCP testing flags. Native WebMCP discovery requires a Brave build that exposes `navigator.modelContext`. WebMCP v1 is implemented only for public-safe client/browser routes via `packages/client/src/modules/webmcp/public-tools.ts`; do not expose secrets, private data, hidden admin actions, onchain writes, destructive operations, or background-only actions as WebMCP tools.
+- Run `bun run agentic:check` as the hard guidance-readiness front door for repo-installed Modern Web Guidance, design docs, token drift, Codex/skill guidance, and shared Storybook story quality. For local built-route QA across client, admin, and docs, use the authenticated Brave QA profile through the live authenticated-browser path below. Treat `bun run agentic:verify`, `bun run agentic:browser-proof`, and `bun run lighthouse` as CI/clean-room or code-level proof only unless they attach to authenticated Brave; do not report them as local authenticated verification. `dev-surfaces` remains the cross-repo/global doctor for shared Modern Web Guidance cache refresh, Brave, and MCP readiness.
+- Local agentic browser QA must use the authenticated Brave QA profile. Codex: use the Codex browser-extension path and claim the already-open Brave tab/window. Claude Code: use the Claude Code Chrome/Chromium extension path (`claude --chrome` or `/chrome`) and select the authenticated Brave profile/tab when it is installed, connected, and able to control the already-open Brave window. Do not fall back merely because the extension is branded Chrome. If the Brave extension path is unavailable or not connected, use Claude computer-use/visible desktop control of the already-open Brave window; if neither can reach authenticated Brave, report QA as blocked. Use this for admin, PWA, extension, wallet/passkey, staging-session, installed-app, and profile-dependent verification.
+- Do not use isolated Browser, Playwright, or DevTools MCP profiles for local QA. Existing isolated browser-proof commands are CI/clean-room checks only and must not be reported as authenticated verification. If authenticated Brave access is blocked, stop and report QA as blocked.
+- Brave DevTools MCP is project-configured in `.mcp.json` through `scripts/mcp/brave-devtools.mjs`, but do not use it for local QA, live admin/PWA verification, rendered DOM proof, screenshots, traces, or success claims because it can launch a separate non-authenticated profile. The wrapper calls the upstream `chrome-devtools-mcp` package because that is the protocol package name, but the browser executable must be Brave. It rejects Google Chrome, Chrome for Testing, Chromium, and Edge paths. Use this wrapper only for CI/clean-room public-route checks or explicit non-authenticated protocol debugging, and label any result as non-authenticated evidence. Native WebMCP discovery requires a Brave build that exposes `navigator.modelContext`. WebMCP v1 is implemented only for public-safe client/browser routes via `packages/client/src/modules/webmcp/public-tools.ts`; do not expose secrets, private data, hidden admin actions, onchain writes, destructive operations, or background-only actions as WebMCP tools.
 
 ## Known Gotchas