baldart 4.80.0 → 4.81.0

package/CHANGELOG.md

@@ -5,6 +5,37 @@ 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:
+
+1. **CLI↔framework skew left the consumer stuck even after the framework reached 4.80.0.** The consumer's subtree was pulled to v4.80.0, but the `update` that pulled it ran with an **older global CLI** (4.76.x) whose `codex.agentsDir()` was still `null` — so the new Codex-agent payload was silently skipped, and `.codex/agents/` was never created. Worse, *re-running* `update` after aligning the CLI hit the **`Already up to date!` early-exit** (line ~893), which returned BEFORE the symlink/merge reconciliation block — so the version-aligned install never self-healed the missing payload (recoverable only via `baldart doctor`). Fix: the `isAligned` branch now runs the idempotent, additive per-item merges (skills/agents/commands/workflows/output-styles) **before** declaring "up to date". They stay silent when nothing is missing and emit a one-line "Reconciled N newly-shipped item(s)" when they heal real drift — so a CLI-skew victim self-heals on the next `update`, not only via `doctor`. This generalises: ANY future payload-kind addition (a new `MERGE_KINDS` entry) is now reconciled on version-aligned installs too.
+2. **The "agent not found" STOP message told a Codex user to "riavvia Claude Code".** The v4.80.0 AGENTS.md edit gave the Codex branch the Claude verbatim message. Fix: a **Codex-specific** message — *"Agent `<name>` non trovato tra i custom agent di Codex (`.codex/agents/<name>.toml`) — allinea la CLI (`npm i -g baldart@latest`), esegui `npx baldart update` (o `npx baldart doctor`), assicurati che il progetto sia trusted in Codex, poi riavvia la sessione Codex"* — encoding the exact remediation (CLI align → update → trust → restart; Codex loads `.codex/agents/` only in **trusted** projects, and discovers agents at session start).
+
+**PATCH** — script bugfix (update self-heals payload drift) + AGENTS.md message correction; no behaviour change on the happy path, no new config key. Existing v4.80.0 consumers should `npm i -g baldart@latest` (kill the skew at the source) then `npx baldart update`; the Codex session must be restarted to discover the newly-installed agents.
+
+### Changed
+
+- **`src/commands/update.js`** — the `Already up to date!` (`status.isAligned`) branch now runs the per-item merges before the early exit (self-heal of payload drift from a prior CLI-skew update), reports the healed count, and adds `reconciled_items` to the `already-current` JSON event.
+- **`framework/AGENTS.md`** — the no-silent-substitution rule's Codex branch now carries its own verbatim "agent not found" remediation message (was reusing the Claude "riavvia Claude Code" text).
+
 ## [4.80.0] - 2026-06-29
 
 **Codex-native subagents — the 32 BALDART agents are now installed for Codex, not just Claude.** A portability bug surfaced in the field: a skill running on Codex delegated to `codebase-architect` (*"invoke the codebase-architect agent"*), but the agent did not exist in the Codex tree and there was no obvious mechanism to spawn it, so the model **improvised** a generic explorer sub-agent. Root cause (confirmed against the OpenAI Codex docs, June 2026): the framework treated subagents as Claude-only — the Codex tool adapter declared `supportsSubagents() === false` / `agentsDir() === null`, so the agent definitions under `framework/.claude/agents/` were **never installed into a Codex tree**. But **Codex now has custom agents** (subagents) — they were simply in a different shape than Claude's, and BALDART had not yet mapped them. This release closes that gap.

package/VERSION

@@ -1 +1 @@
-4.80.0
+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/AGENTS.md

@@ -104,7 +104,7 @@ Conflict steps (must follow in order):
 
 - MUST treat `AGENTS.md` as authoritative for agent rules.
 - MUST invoke the `codebase-architect` agent whenever you need to understand codebase structure, existing patterns, or code architecture before planning or implementing changes; do not proceed with planning or implementation without first understanding the existing system through codebase-architect. **The agent exists on both tools** — Claude Code spawns it via the Task/Agent tool with `subagent_type: "codebase-architect"`; Codex spawns the `codebase-architect` custom agent **by name** (BALDART installs it at `.codex/agents/codebase-architect.toml`, transpiled from the same `.md` source). Only if your environment genuinely exposes NEITHER subagent mechanism (a stripped tool host) do you degrade — explicitly — to inline structural retrieval (code-graph → LSP → Grep → direct file reads per `agents/code-search-protocol.md`), and SAY SO; never silently skip the understanding step.
-- MUST NOT silently substitute a *different* agent when an agent invocation returns empty (`0 tool uses · Done`), times out, or fails with `permissionDecision: deny`. On **Claude Code** this pattern indicates a sub-agent failure (see anthropics/claude-code#56869) or a discovery miss / blocked agent (see #20931 and BALDART's own `agent-discovery-gate` PreToolUse hook): STOP, report to the user verbatim: "Agent `<name>` non discoverato o fallito in questa sessione — riavvia Claude Code e verifica con `npx baldart doctor`", and wait for direction. Never auto-route to `feature-dev:*`, `general-purpose`, or any other marketplace/built-in agent as a replacement. **This rule is the ONLY defense against bug #56869 (which BALDART cannot patch from outside Claude Code); deviating from it reintroduces the exact failure mode the rule exists to prevent.** On **Codex** the named-agent spawn is the equivalent; the same no-silent-substitution rule holds (the #56869 specifics are Claude-only, the principle is universal).
+- MUST NOT silently substitute a *different* agent when an agent invocation returns empty (`0 tool uses · Done`), times out, or fails with `permissionDecision: deny`. On **Claude Code** this pattern indicates a sub-agent failure (see anthropics/claude-code#56869) or a discovery miss / blocked agent (see #20931 and BALDART's own `agent-discovery-gate` PreToolUse hook): STOP, report to the user verbatim: "Agent `<name>` non discoverato o fallito in questa sessione — riavvia Claude Code e verifica con `npx baldart doctor`", and wait for direction. Never auto-route to `feature-dev:*`, `general-purpose`, or any other marketplace/built-in agent as a replacement. **This rule is the ONLY defense against bug #56869 (which BALDART cannot patch from outside Claude Code); deviating from it reintroduces the exact failure mode the rule exists to prevent.** On **Codex** the equivalent is spawning the custom agent by name; the same no-silent-substitution rule holds — but the remediation differs, so STOP and report the **Codex-specific** message verbatim: "Agent `<name>` non trovato tra i custom agent di Codex (`.codex/agents/<name>.toml`) — allinea la CLI (`npm i -g baldart@latest`), esegui `npx baldart update` (o `npx baldart doctor`), assicurati che il progetto sia *trusted* in Codex, poi riavvia la sessione Codex", and wait for direction. (The #56869 specifics are Claude-only; the no-silent-substitution principle is universal.)
 - MUST NOT work on files/components already claimed by another agent; multiple agents allowed if working on independent areas.
 - MUST perform a mandatory clarity analysis before fixing any issue labeled `bug`; confirm that the issue description, proposed correct behavior, and edge cases are unambiguous, document any resolved doubts, and only start fix work once every zone of uncertainty is covered.
 - MUST mark missing info as UNKNOWN and ask the user; if blocked, set `BLOCKED` with a blocker.

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.0",
+  "version": "4.81.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/update.js

@@ -891,11 +891,33 @@ async function update(options = {}, unknownArgs = []) {
     // VERSION-compare authority. Subtree-merge commit count is noise; never
     // use behind > 0 as the up-to-date signal (root cause of v3.24.x bug).
     if (status.isAligned) {
+      // Even when the VERSION is aligned, the per-item PAYLOAD may be stale.
+      // The failure class: a consumer updates with an OLDER CLI (CLI↔framework
+      // skew) → gets the new framework content but the old reconciliation logic,
+      // so a newly-added payload kind (e.g. Codex agents in v4.80.0, where
+      // `codex.agentsDir()` flipped from null to `.codex/agents`) is silently
+      // skipped. Later aligning the CLI and re-running `update` hit this early
+      // "already current" exit and NEVER reconciled — leaving the consumer
+      // stuck (recoverable only via `doctor`). The per-item merges are
+      // idempotent + additive and stay SILENT when nothing is missing, so run
+      // them here: an up-to-date install now self-heals payload drift too.
+      const alignedTools = readEnabledTools();
+      const reconciled = [
+        symlinks.mergeSkills({ tools: alignedTools }),
+        symlinks.mergeAgents({ tools: alignedTools }),
+        symlinks.mergeCommands({ tools: alignedTools }),
+        symlinks.mergeWorkflows({ tools: alignedTools }),
+        symlinks.mergeOutputStyles({ tools: alignedTools })
+      ].reduce((n, r) => n + ((r.linked && r.linked.length) || 0) + ((r.generated && r.generated.length) || 0), 0);
+      if (reconciled > 0) {
+        UI.info(`Reconciled ${reconciled} newly-shipped item(s) into per-tool dir(s) — payload drift from a prior CLI-skew update, now healed.`);
+      }
       UI.success(`Already up to date! (v${status.installedVersion})`);
       emitUpdateJson({ ok: true, action: 'already-current',
         installed_before: status.installedVersion,
         installed_after: status.installedVersion,
-        remote_version: status.remoteVersion }, 0);
+        remote_version: status.remoteVersion,
+        reconciled_items: reconciled }, 0);
     }
 
     UI.warning(`Update available: v${status.installedVersion} → v${status.remoteVersion}`);