baldart 4.80.1 → 4.81.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.81.0] - 2026-06-29
+
+**Playwright capture is CLI-only — no Playwright MCP anywhere in the framework.** BALDART already used the **Playwright Test CLI** for its main capture pipeline (`/e2e-review` Phase 3→4, `playwright-skill`, `webapp-testing`'s headless Python scripts), but three surfaces still drove the **Playwright MCP** interactively: the `bug` skill (Phase 1 UI reproduction via `browser_navigate`/`browser_take_screenshot`/`browser_console_messages`/`browser_network_requests`/`browser_evaluate`), the `/design-review` command (`allowed-tools` declared the four `mcp__playwright__*` tools + relied on `localhost:9221`), and the `/qa` DEEP tier ("Use MCP Playwright if available"). For **deterministic capture** the MCP is pure token overhead — every action round-trips a result (often a full a11y-tree snapshot) into context, accumulating per-step; a headless CLI script enters context once and writes screenshots/console/network to disk, read back only when needed. This release converts those three surfaces to the CLI so **no Playwright MCP is ever loaded into the agent context**.
+
+The `bug` skill's interactive `browser_evaluate` instrumentation (fetch interceptor, SWR mutation tracker) is preserved with **zero loss of capability** by moving it into `page.addInitScript(() => { … })` inside the headless capture script — same injection, headless and reproducible, with the forwarded `console.*` collected via `page.on('console', …)` and read from disk.
+
+**MINOR** — behaviour change across `bug`, `/design-review`, `/qa` (the Playwright MCP dependency is removed; capture is now CLI). No new config key, no install-layout change. The Codex broker's leaked Playwright-MCP orphans (spawned from the user's `~/.codex/config.toml`, independent of BALDART) remain handled by the `baldart doctor` orphan reaper — untouched.
+
+### Changed
+
+- **`framework/.claude/skills/bug/SKILL.md`** — frontmatter, "MCP dependencies" (Playwright MCP required → "None required for browser capture"; CLI via webapp-testing), Phase 0 triage tool, Phase 1 UI reproduction (browser_* steps → headless capture script writing screenshot/console/network to disk), Phase 2 client-side logging (`browser_evaluate` → `page.addInitScript`), Phase 3 evidence collection, Phase 5 verify, Tools Quick Reference.
+- **`framework/.claude/skills/bug/references/logging-patterns.md`** — "Playwright MCP Debug Patterns" → "Playwright CLI Debug Patterns"; `// browser_evaluate:` → `page.addInitScript()` in the capture script.
+- **`framework/.claude/commands/design-review.md`** — removed the four `mcp__playwright__*` tools from `allowed-tools`; the route capture is now a headless Playwright CLI screenshot (Bash) read back as a PNG, instead of opening the MCP browser on `localhost:9221`.
+- **`framework/.claude/commands/qa.md`** — DEEP-tier UI quality checks use a headless Playwright CLI screenshot script (when `@playwright/test` is installed) instead of MCP Playwright.
+- **`framework/.claude/skills/playwright-skill/SKILL.md`** — the cross-reference to `bug` no longer says it "requires `mcp__playwright__browser_*`"; both use the CLI.
+- **`framework/docs/MCP-INTEGRATION.md`** — "Browser automation" catalog entry: Playwright MCP → **Playwright CLI**, with the token-economy rationale and the note that the Codex-broker orphan reaper is independent; the section-authoring example tool prefix swapped off `mcp__playwright__browser_navigate` (now a Firebase example) so the doc no longer implies BALDART uses the Playwright MCP.
+
 ## [4.80.1] - 2026-06-29
 
 **Self-heal payload drift on an already-current install + a Codex-correct "agent not found" message.** Shipping v4.80.0 surfaced two gaps in the field, both from the same incident: a consumer's Codex session emitted the AGENTS.md STOP message for `codebase-architect`, yet the framework was already at v4.80.0. Two root causes:

package/VERSION

@@ -1 +1 @@
-4.80.1
+4.81.0

package/framework/.claude/commands/design-review.md

@@ -1,9 +1,9 @@
 ---
-description: Trigger the design-review subagent with MCP Playwright for the specified route.
-allowed-tools: Bash, Grep, LS, Read, WebFetch, TodoWrite, WebSearch, BashOutput, KillBash, ListMcpResourcesTool, ReadMcpResourceTool, mcp__playwright__browser_navigate, mcp__playwright__browser_click, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_console_messages
+description: Trigger the design-review subagent with the Playwright CLI for the specified route.
+allowed-tools: Bash, Grep, LS, Read, WebFetch, TodoWrite, WebSearch, BashOutput, KillBash
 ---
 
-You are the design-review subagent. Ensure `npm run design-review` is running before continuing so Playwright MCP can expose `localhost:9221` to Claude.
+You are the design-review subagent. Ensure the dev server is running, then capture each route with a **headless Playwright CLI screenshot** (a short script run via Bash, e.g. `npx playwright screenshot` or an inline `.mjs` using `@playwright/test`'s `chromium`) — no Playwright MCP. Read the saved PNG back to reason over it.
 
 ## Invocation Modes (since v3.18.1)
 
@@ -110,7 +110,7 @@ When the user invokes `/design-review`, do the following (in both modes — only
    - Read `${paths.design_system}/tokens-reference.md`.
    - Read `${paths.design_system}/components/<Name>.md` for every primitive expected on the route.
    When the flag is `false`, skip the registry reads. In Mode A flag the gap in the final report and recommend `/design-system-init`. In Mode B add the gap to the `gaps[]` array of the JSON output.
-1. Start with the route or component specified (e.g., `/dashboard`) and open it in the MCP browser. In Mode B, use the `dev_server_port` from the input envelope to construct `http://localhost:<port><route>`.
+1. Start with the route or component specified (e.g., `/dashboard`) and capture it with a headless Playwright CLI screenshot script (run via Bash), then Read the PNG back. In Mode B, use the `dev_server_port` from the input envelope to construct `http://localhost:<port><route>`.
 2. Follow the Quick Visual Check in `agents/design-review.md` and run Phases 0‑7 (interaction, responsiveness, polish, accessibility, robustness, code health, content/console).
 3. Capture at least one full-page screenshot at the viewport from the input (default 1440px) and note console errors. In Mode B save the screenshot at `/tmp/design-review/<route-slug>.png` and cite it in `evidence.screenshot_path`.
 4. **Mode A**: report findings using the Markdown template in `agents/design-review.md` (Blockers/High/Medium/Nitpicks). **Mode B**: assemble the JSON output described above, normalizing severity per the table.

package/framework/.claude/commands/qa.md

@@ -169,7 +169,7 @@ Run everything in BALANCED, plus:
 - If NO: log in findings file: "E2E framework not configured — recommend setting up e2e smoke suite. No e2e tests run."
 
 **UI quality checks:**
-- Use MCP Playwright (if available) to open key flows related to the diff and take screenshots, checking for console errors and visual regressions.
+- Use a headless Playwright CLI screenshot script (when `@playwright/test` is installed) to open key flows related to the diff and take screenshots, checking for console errors and visual regressions — no Playwright MCP.
 - Validate: login/auth flow, critical navigation, any flow directly touched by the diff.
 
 Run the e2e pass in parallel with the `qa-sentinel` FULL-tier gate run (launch both as sub-agents simultaneously). This inline two-agent launch is the DEEP default; escalate to the team-based strategy (Step 4) ONLY when 3+ clearly independent risk tracks exist [DESIGN-CHOICE: below this threshold, TeamCreate overhead exceeds benefit; two inline Task spawns are sufficient]. A DEEP run with fewer than 3 tracks stays on this inline path and does NOT create a team.

package/framework/.claude/skills/bug/SKILL.md

@@ -7,7 +7,7 @@ description: >
   'investigate', or reports unexpected behavior. Accepts optional bug description as argument.
   Enforces a disciplined 5-phase debugging protocol that prevents blind guessing:
   (1) Reproduce & observe, (2) Enhanced logging if stuck, (3) Data-driven analysis,
-  (4) Hypothesis & minimal fix, (5) Verify. Leverages Playwright MCP for browser capture,
+  (4) Hypothesis & minimal fix, (5) Verify. Leverages the Playwright CLI (headless capture scripts via webapp-testing) for browser capture,
   codebase-architect for code path tracing, `rg` over docs for known patterns, git bisect for regressions.
 ---
 
@@ -35,8 +35,7 @@ precedence caveats: `framework/agents/effort-protocol.md`.
 
 See [framework/docs/MCP-INTEGRATION.md](../../../docs/MCP-INTEGRATION.md) for the BALDART MCP integration contract and the rationale behind this section.
 
-**Required** (skill cannot complete its task without these MCPs for the relevant bug class):
-- `mcp__playwright__browser_*` (`browser_navigate`, `browser_take_screenshot`, `browser_console_messages`, `browser_network_requests`, `browser_evaluate`) — Phase 1 reproduction for **UI/Client** bugs. Without it the skill cannot capture deterministic state and Phase 1 degrades to "ask the user to reproduce manually and paste console logs". Phase 2's client-side `window.fetch` interception is impossible without `browser_evaluate`.
+**None required for browser capture.** UI/Client reproduction uses the **Playwright CLI**, NOT an MCP: write a short headless capture script (via the [webapp-testing](../webapp-testing/SKILL.md) toolkit) that navigates, screenshots, and dumps console + network to disk, then read the artifacts back. Nothing is driven interactively, so **no Playwright MCP is ever loaded into the agent context** (deliberate token-economy choice — see `framework/docs/MCP-INTEGRATION.md`). The `addInitScript` instrumentation in Phase 2 replaces the old live `browser_evaluate` injection with zero loss of capability.
 
 **Optional** (the skill benefits if present, has a documented fallback):
 - `mcp__plugin_firebase_firebase__firestore_*` (or the project's DB MCP, when `stack.database.primary` is set) — Phase 1 inspection of runtime data state for **Data** bugs. Fallback: ask the user for a document export, or read the relevant code path and infer.
@@ -54,7 +53,7 @@ See [framework/docs/MCP-INTEGRATION.md](../../../docs/MCP-INTEGRATION.md) for th
 
 1. Parse the bug description from args (or ask user if missing)
 2. Classify the bug domain:
-   - **UI/Client** → Playwright MCP is primary tool
+   - **UI/Client** → Playwright CLI capture script (via webapp-testing) is primary tool
    - **API/Server** → dev server logs + route handler analysis
    - **Data/Datastore** → the project's datastore inspection tooling per `stack.database` (e.g. the Firebase MCP for `firestore`, a SQL client for `postgres`/`supabase`, the Mongo shell for `mongodb`) + transaction tracing
    - **Auth** → the project's auth middleware/guard + auth error codes (per `stack.auth_provider`)
@@ -82,13 +81,16 @@ See [framework/docs/MCP-INTEGRATION.md](../../../docs/MCP-INTEGRATION.md) for th
 
 Goal: get a reliable reproduction that you can re-run after fixing.
 
-**For UI bugs:**
-1. Navigate with Playwright MCP: `browser_navigate` to the affected page
-2. Capture baseline: `browser_take_screenshot`
-3. Capture console state: `browser_console_messages`
-4. Capture network: `browser_network_requests`
-5. Reproduce the bug step-by-step, capturing after each action
-6. Record the exact sequence that triggers the bug
+**For UI bugs (Playwright CLI capture — no MCP):**
+Write a short **headless capture script** to scratch (e.g. `scratch/bug-repro.mjs`, or a Python helper via the [webapp-testing](../webapp-testing/SKILL.md) toolkit) and run it with Bash — never drive the browser interactively. The script:
+1. Navigates to the affected page (build the URL from the project baseURL / dev-server port)
+2. Captures a baseline screenshot to disk: `await page.screenshot({ path: 'scratch/repro.png', fullPage: true })`
+3. Dumps console to a file: `page.on('console', m => fs.appendFileSync('scratch/console.log', m.text()+'\n'))`
+4. Dumps network to a file: `page.on('response', r => fs.appendFileSync('scratch/network.log', `${r.status()} ${r.url()}\n`))` (or record a HAR via `browser.newContext({ recordHar: { path: 'scratch/repro.har' } })`)
+5. Performs the repro steps (`click`/`fill`), screenshotting after each action
+6. Then **Read the artifact files back** and record the exact sequence that triggers the bug
+
+Delete the scratch script + artifacts in Phase 5.
 
 **For API bugs:**
 1. Identify the route handler file from the URL pattern
@@ -141,10 +143,12 @@ await firestore.runTransaction(async (tx) => {
 console.log(`[DEBUG:tx] done in ${attempt} attempts`); // DEBUG:
 ```
 
-### Client-side logging (via Playwright MCP — zero code changes)
+### Client-side logging (via the Playwright CLI capture script — zero app code changes)
 
-Use `browser_evaluate` to inject runtime instrumentation:
+Inject runtime instrumentation with `page.addInitScript(() => { ... })` (runs before the page's own scripts) inside the capture script — same effect as a live `evaluate`, but headless and reproducible. The forwarded `console.*` is collected by the script's `page.on('console', …)` handler and written to disk; read the file back after the run:
 ```javascript
+// inside the capture script, before page.goto():
+await page.addInitScript(() => {
 // Intercept all fetch calls
 const origFetch = window.fetch;
 window.fetch = async (...args) => {
@@ -163,8 +167,9 @@ window.fetch = async (...args) => {
     throw e;
   }
 };
+}); // end addInitScript
 ```
-Then capture everything: `browser_console_messages` after reproducing.
+Then run the script and read the console artifact file back after reproducing.
 
 ### Cache/data-fetch debug mode
 
@@ -179,8 +184,8 @@ If the project exposes an env-summary helper (listed in `.baldart/overlays/bug.m
 1. Reproduce the bug AGAIN with enhanced logging active
 2. Collect ALL output:
    - Server terminal (grep for `[DEBUG:`)
-   - `browser_console_messages` from Playwright
-   - `browser_network_requests` from Playwright
+   - the console artifact file written by the capture script
+   - the network artifact file (or HAR) written by the capture script
    - Screenshots before/after
 3. Analyze:
    - **Timeline**: what happened in what order?
@@ -216,7 +221,7 @@ If the project exposes an env-summary helper (listed in `.baldart/overlays/bug.m
    ```
    Remove every line found. Run grep again to confirm zero results.
 5. Revert any temporary cache/data-fetch debug switches enabled in Phase 2
-6. Final Playwright screenshot to confirm visually
+6. Re-run the Playwright CLI capture script for a final screenshot to confirm visually, then delete the scratch script + artifacts
 
 ## TOOLS QUICK REFERENCE
 
@@ -224,7 +229,7 @@ If the project exposes an env-summary helper (listed in `.baldart/overlays/bug.m
 |------|------|---------|
 | `codebase-architect` agent | Phase 0 | Map affected code paths |
 | `rg` over docs / error-code module | Phase 0 | Search known patterns/errors |
-| `mcp__playwright__browser_*` | Phase 1-5 | Navigate, screenshot, console, network |
+| Playwright CLI capture script (webapp-testing) | Phase 1-5 | Navigate, screenshot, console, network — headless, artifacts to disk (no MCP) |
 | Project DB MCP (if available) | Phase 1 | Inspect storage state (e.g. firestore/postgres tools) |
 | `git log/blame/bisect` | Phase 0, 3 | Find regression commits |
 | Project-specific entry points | various | Listed in `.baldart/overlays/bug.md` — error-code module, env-summary helper, cache debug switch |

package/framework/.claude/skills/bug/references/logging-patterns.md

@@ -115,11 +115,16 @@ const analysis = await query.explain({ analyze: true });
 `debug()` in Firestore rules works ONLY in the emulator, no-op in production.
 Use `@firebase/rules-unit-testing` (already in devDeps) for rule testing.
 
-## Playwright MCP Debug Patterns
+## Playwright CLI Debug Patterns
 
-### Inject fetch interceptor (zero code changes)
+> Headless capture scripts only — no Playwright MCP. Inject the instrumentation
+> with `page.addInitScript(() => { ... })` (runs before the page's own scripts),
+> collect the forwarded `console.*` with `page.on('console', …)`, and write it to
+> disk; read the artifact back after the run.
+
+### Inject fetch interceptor (zero app code changes)
 ```javascript
-// browser_evaluate:
+// inside the capture script: await page.addInitScript(() => {
 const origFetch = window.fetch;
 window.fetch = async (...args) => {
   const url = typeof args[0] === 'string' ? args[0] : args[0]?.url;
@@ -143,7 +148,7 @@ window.fetch = async (...args) => {
 
 ### Inject SWR mutation tracker
 ```javascript
-// browser_evaluate:
+// inside the capture script: await page.addInitScript(() => {
 const origMutate = window.__SWR_MUTATE__;
 if (origMutate) {
   window.__SWR_MUTATE__ = (...args) => {
@@ -161,7 +166,7 @@ const context = await browser.newContext({ recordHar: { path: 'debug.har', mode:
 
 ## CDP (Chrome DevTools Protocol) via Playwright
 
-For deep debugging beyond MCP tools:
+For deep debugging beyond the basic capture script:
 ```typescript
 const session = await context.newCDPSession(page);
 await session.send('Runtime.enable');

package/framework/.claude/skills/playwright-skill/SKILL.md

@@ -31,7 +31,7 @@ precedence caveats: `framework/agents/effort-protocol.md`.
 
 See [framework/docs/MCP-INTEGRATION.md](../../../docs/MCP-INTEGRATION.md) for the BALDART MCP integration contract and the rationale behind this section.
 
-**None.** This skill uses the **Playwright Test CLI** (`@playwright/test`) directly via `npm run test:e2e` — `.spec.ts` files under `${paths.e2e_tests_dir}`. It does NOT use Playwright MCP. Consumers don't need any MCP configured to use this skill. For ad-hoc interactive browser debugging during bug investigation (not E2E test authoring) see [bug/SKILL.md](../bug/SKILL.md), which DOES require `mcp__playwright__browser_*`.
+**None.** This skill uses the **Playwright Test CLI** (`@playwright/test`) directly via `npm run test:e2e` — `.spec.ts` files under `${paths.e2e_tests_dir}`. It does NOT use Playwright MCP. Consumers don't need any MCP configured to use this skill. For ad-hoc browser capture during bug investigation (not E2E test authoring) see [bug/SKILL.md](../bug/SKILL.md), which **also uses the Playwright CLI** (headless capture scripts via [webapp-testing](../webapp-testing/SKILL.md)) — no Playwright MCP anywhere in BALDART.
 
 ## E2E Review Integration (since v3.18.0)
 

package/framework/docs/MCP-INTEGRATION.md

@@ -25,7 +25,7 @@ Tre opzioni per integrare un sistema esterno in un agent BALDART. Scegli il più
 Non è un'imposizione: BALDART non installa MCP, non li valida, non li richiede. È una lista curata di MCP che hanno senso nei deployment dove BALDART è già in uso.
 
 ### Browser automation
-- **Playwright MCP** (`@modelcontextprotocol/server-playwright`) — usato da [bug](../.claude/skills/bug/SKILL.md) e [webapp-testing](../.claude/skills/webapp-testing/SKILL.md) per cattura visiva, network, console.
+- **Playwright CLI** (`@playwright/test` / `playwright`) — BALDART usa la **CLI**, non un MCP, per ogni cattura browser (screenshot, console, network). Le skill [playwright-skill](../.claude/skills/playwright-skill/SKILL.md), [webapp-testing](../.claude/skills/webapp-testing/SKILL.md) e [bug](../.claude/skills/bug/SKILL.md) scrivono script headless che salvano gli artefatti su disco e li rileggono, così **nessun MCP Playwright resta fisso nel contesto dell'agente**. Scelta deliberata per l'economia di token: la cattura deterministica non ha bisogno del modello-nel-loop, quindi la CLI evita gli accumuli di snapshot/a11y-tree per-azione tipici dell'MCP. (Il Playwright MCP che il broker Codex può spawnare dal `~/.codex/config.toml` dell'utente resta gestito dal reaper orfani in `baldart doctor` — è indipendente da BALDART.)
 
 ### Code knowledge graph (Graphify)
 - **Graphify** (`pipx install graphifyy` → CLI `graphify` + MCP server `graphify-mcp`) — code knowledge graph (tree-sitter, locale/offline, Leiden nativo). Gatato da `features.has_code_graph`. Usato da [codebase-architect](../.claude/agents/codebase-architect.md) e dalle skill di esplorazione per query **strutturali/relazionali** (`graphify query`/`path`/`explain`/`affected`), e dal layer wiki (`wiki-curator`, `/capture`, routine `doc-graph-align`) che si alimenta del `GRAPH_REPORT.md` nativo. **CLI-first** (sempre disponibile post-install); l'MCP `graphify-mcp` è opt-in (`graph.register_mcp`, best-effort `claude mcp add`). Fallback: degrada a LSP→Grep→Git. Vedi [code-graph-protocol.md](../agents/code-graph-protocol.md) e [CODE-GRAPH-LAYER.md](CODE-GRAPH-LAYER.md).
@@ -77,7 +77,7 @@ Subito dopo la sezione `## Project Context` (o, in mancanza, subito dopo il fron
 
 ### Regole
 
-1. **Sii specifico**: cita il prefisso del tool (`mcp__playwright__browser_navigate`), non il "concetto" (`Playwright MCP`). Aiuta il consumer a fare grep.
+1. **Sii specifico**: cita il prefisso del tool (es. `mcp__plugin_firebase_firebase__firestore_get_document`), non il "concetto" (`Firebase MCP`). Aiuta il consumer a fare grep.
 2. **Required vs Optional**: required = la skill non può completare il proprio task senza il MCP (o degrada gravemente). Optional = la skill ha un fallback funzionante.
 3. **Fallback espliciti**: per ogni `Optional`, descrivi il fallback in una frase ("se MCP unavailable, usa `rg` su `docs/` per trovare pattern noti").
 4. **Niente nuovo schema in `baldart.config.yml`**: non aggiungere `mcp.required` o `mcp.optional` nel config — è solo convenzione testuale finché non c'è una skill che ha bisogno di gatearne il comportamento a runtime.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.80.1",
+  "version": "4.81.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"