baldart 4.89.2 → 4.92.1

package/CHANGELOG.md

@@ -5,6 +5,93 @@ 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.92.1] - 2026-07-02
+
+**Review avversariale post-release del motore new2 (coerenza interna).** Tre reviewer indipendenti a contesto fresco (dataflow / edge-case / contratti) sull'onda v4.90–4.92; ogni finding ri-verificato contro il codice prima di agire: **11 confermati e fixati, 9 refutati con evidenza empirica** (tra i refutati: la "race" del worker-pool adattivo — simulata: 0 buchi; `verify-item.sh` su bash 3.2 reale — funziona; `parseInt` con CRLF; un CAP attribuito a `new2.js` che non esiste).
+
+**PATCH** — hardening senza cambi di superficie. **Nessuna nuova chiave config**. **Codex parity: portable/N/A** (prosa + workflow JS Claude-only).
+
+### Fixed
+
+- **`new2.js`**: verifier strutturale che si auto-dichiara `status:"skipped"` = UNDERRUN (mai PASS — era l'ultimo canale di under-run mascherato); **re-verify deterministica** una-tantum dopo un fix strutturale risolto (il self-report del fixer non è la conferma del verifier); **`bindingCheck` consumato** (violazioni sopravvissute al pass dell'agent → resolve ui; report assente → ledger fail-open, mai silente); `${MAIN}` quotato dentro `$(git -C …)` (path con spazi).
+- **`/e2e-review` 1.2.1**: stringa lane canonica `skipped:render_unavailable_structural_covered` scritta esplicitamente da Phase 3.8 (l'assertion di Phase 5 valida l'enum chiuso); chiave di convergenza del self-heal estesa con `viewport_role`.
+- **`new2` 1.2.1**: Step 3.5 ramo AUTONOMOUS (CI/`BALDART_AUTONOMOUS`/origine delegata → mai una domanda, mai un apply command autonomo); **origine delegata = autonoma ovunque** (escape hatch 3b SKIPPED anche con TTY — chiuso il rischio di ciclo `/new`→`new2`→`/new` a costo pieno); contatore resume **durabile nel batch tracker** (una compaction non resetta il bound) + teardown broker Codex su ogni uscita per stallo.
+- **`structural-compare.mjs`**: arbitrary value Tailwind con funzioni (`grid-cols-[repeat(2,_minmax(0,1fr))]`) contati con la `countTracks` parens-aware (era `split('_')` → 3 invece di 2, falso segnale di divergenza).
+- **`ui-implement` 1.1.1**: Return Contract documenta i campi `bindings`/`lane_coverage`/`lanes` (schema SSOT in integration.md).
+
+## [4.92.0] - 2026-07-02
+
+**Tier 3 del programma "deep analysis /new+/ui-implement": parity tripwire, bound dei loop, verifica payload new2.** Chiude il programma a 3 tier (4.90.0 → 4.92.0).
+
+**MINOR** — nuovo guard CI + bound espliciti. **Nessuna nuova chiave `baldart.config.yml`**.
+
+**Codex parity: N/A / portable** (script maintainer + prose skill; nessuna superficie runtime nuova).
+
+### Added — T3.A Parity tripwire /new ↔ new2
+
+- **`scripts/check-new-parity.mjs`** (maintainer, CI-hard in `check-reference-integrity.yml`): 9 policy a location parallela codificate come obbligazioni (file, token) che devono valere su TUTTI i lati — mockup-first, router clamp, binding gate, lane strutturale, Verification-Lane Ledger, path tracker durabile (con FORBIDDEN sul path /tmp), verify-item runner, cap adattivo, delegation gate. La classe di difetto "fix propagato a metà" (v4.89.0, B4, singleCard…) ora fallisce la build invece di emergere in un post-mortem.
+
+### Added — T3.C Loop bounds
+
+- **`new2` 1.2.0**: resume loop HARD-bounded (`resumeMaxAttempts = 3` + stall detection sullo stesso set di card incomplete).
+- **`/e2e-review` 1.2.0**: convergence detection nel self-heal (fix che genera finding gating NUOVI → stop immediato + override path, `convergence: "diverging"`); spawn del solo fixer-bucket non vuoto. Deliberatamente NIENTE re-verify selettiva delle lane (sarebbe un under-run auto-inflitto contro la Lane-Ledger assertion).
+
+### Verified — T3.B new2 prompt payload (measure-first, esito documentato)
+
+- La claim "i prompt di new2 embeddano 40–80KB di moduli per agente" è **REFUTATA alla verifica**: i prompt passano i moduli **per path** (`per ${REF}/implement.md Phase 2` — l'agent li legge da disco) e l'audit dei run reali mostra i moduli letti 1× ciascuno. Nessun cambio necessario; il "briefing-extract" resta non implementato di proposito (sarebbe un secondo SSOT distillato).
+
+## [4.91.0] - 2026-07-02
+
+**Tier 2 del programma "deep analysis /new+/ui-implement": hot-file economy, right-sizing del review fan-out, robustezza (B4/NUL/verify-item).** Interventi mirati dai numeri delle stesse 3 run reali del Tier 1.
+
+**MINOR** — nuove capacità (script, sezioni protocollo), zero breaking. **Nessuna nuova chiave `baldart.config.yml`**.
+
+**Codex parity: portable** (prosa protocollo/agent transpilata + script bash/zero-dep; i due workflow JS toccati sono Claude-only by design, path inline invariato).
+
+### Added — T2.A Hot-file economy
+
+- **`code-search-protocol.md` § "Large-file read discipline"** (SSOT): file > 800 righe = hot file; misurato un client da 2110 righe (~29k tok) riletto INTERO **28×** in un run (i moduli framework si leggono 1× — il repeated-read vero è questo). Regole: Hot-File Map → range-read; brief per path, mai body.
+- **`codebase-architect`**: il contratto terse emette `## Hot-File Map` MANDATORY (`path (N lines): symbol — Lstart–Lend`) per ogni file in scope > 800 righe; `coder`/`ui-expert` citano la disciplina; `implement.md` Step 7 passa il baseline per PATH (guardia `[BASELINE-READ-FAIL]`).
+
+### Added — T2.B Review fan-out right-sizing
+
+- **Empty-scope pre-invocation guard** (Phase 2.5x + team-mode D.1.6): card/wave a diff vuoto non schedulano un cluster `new-card-review` no-op (misurati 2 cluster `agents=0, dur=0` in un batch reale).
+- **Cap adattivo** in `new-card-review.js` + `new-final-review.js`: fisso 3 → parte 5, **scende a 2 al primo transient rate-limit** per il resto del run (rispetta il guardrail v4.53.6/v4.66.0 eliminando la queue-wait tax sui run senza pressione). Deliberatamente NON toccata la policy di profondità review (refutazioni slimCodex / review-gate additions).
+
+### Fixed — T2.C Robustezza
+
+- **B4 tracker LOST — propagazione completata**: il fix del path durabile (`$(git rev-parse --git-common-dir)/baldart/run/…`) era atterrato solo in `new/SKILL.md`+`metrics.md`; **`new2.js` creava ancora il tracker in `/tmp`** (la causa dei FAIL B4 nei run di audit) e i prompt fixer di `/e2e-review` citavano il path volatile. Entrambe le location parallele allineate.
+- **Sweep anti-NUL**: sezione "Search discipline (MUST)" (prefer `rg`; 0-match ≠ assente) aggiunta ai 5 reviewer che ne erano privi — `qa-sentinel`, `code-reviewer`, `security-reviewer`, `markup-fidelity-verifier`, `api-perf-cost-auditor` (84–149 sintomi binary-grep per run nonostante il fix B3 su coder/architect).
+- **`scripts/verify-item.sh` (skill /new)**: la Grep-verification discipline del completeness è ora CODE — pattern come singolo argv `-F` (metacaratteri innocui), exit 2 = `UNVERIFIED` mai `Missing`, rg NUL-safe con fallback `grep -a`. Testato incluso il file-con-NUL (la trappola FEAT-0041 B3). Hand-rolled shell per quei check = protocol violation.
+- Versioni skill: `new` 1.3.0 · `new2` 1.1.1 · `e2e-review` 1.1.1.
+
+## [4.90.0] - 2026-07-02
+
+**Tier 1 del programma "deep analysis /new+/ui-implement" (lug-2026): fidelity chain a prova di under-run, build-with-eyes, e la delega off-context del batch `-auto`.** Fondato sui dati di 3 run reali (mayo `a73a52d0`/`a946415b`/`6882a2b7`): (a) il 53–59% dei token fatturati è la turn-tax dell'orchestrator inline; (b) nel run FEAT-0064 la catena di fedeltà è stata SOTTO-eseguita in silenzio (zero `visual-fidelity-verifier`/`ui-quality-critic` spawnati) e l'escape è diventata BUG-0017 lavorata a mano; (c) i moduli reference vengono letti 1× (economy OK) — il costo ricorrente è altrove.
+
+**MINOR** — nuove capacità (gate, script, delega), zero breaking. **Nessuna nuova chiave `baldart.config.yml`** → la schema-change propagation rule NON si applica.
+
+**Codex parity: portable / inline-fallback** — script zero-dep + prosa skill/agent (trasp. TOML) portabili; il delegation gate e la lane new2 sono Claude-only by design con il path classico inline come fallback documentato (ogni run Codex è invariata).
+
+### Added — T1.A Fidelity chain (verification-lane ledger)
+
+- **`design-system-protocol.md` § 6 "Verification-Lane Ledger"** (nuovo check SSOT): riconciliazione planned-vs-executed delle lane di verifica; una lane pianificata mai eseguita = **`verification-coverage-gap`** (Critical, unfixable, bypassa il self-heal, → `blocked`). Nessun verdetto self-served "accepted (harness limit)".
+- **`/e2e-review` 1.1.0**: Lane Matrix (chiusura Phase 2) + assertion Phase 5 step 0; bundle HTML Claude Design SEMPRE sondato con `extract-mockup-design.mjs` e threaded come `structural_source` (decode fallito ≠ lane persa); viewport **tablet @768px** scope-driven (`plan.tablet_in_scope` → cattura + pass 2c `viewport_role: tablet`); report JSON additivo `lanes`/`lane_coverage`.
+- **`/ui-implement` 1.1.0 — binding gate**: nuovo script deterministico `skills/ui-implement/scripts/check-bindings.mjs` (Step 5b) — binding `reuse`/`reuse-variant` non usato nel codice = `binding-not-honored` (Critical, 1 retry, poi blocked). Fail-open.
+- **`new2.js` (location parallela)**: lane strutturale route-free (`markup-fidelity-verifier`) per card con mockup + obbligo Lane-Ledger (verifier assente → residual `verification-coverage-gap`, card mai auto-DONE); binding gate nel brief; cardGraph `designSrcDir`/`designHtml`/`hasBindings`.
+- `visual-fidelity-verifier`: `viewport_role: "tablet"` (responsive-integrity + wrong-band collapse con cite dell'AC).
+
+### Added — T1.B Build-with-eyes (costruisci-bene a monte)
+
+- **`framework/scripts/structural-compare.mjs`**: pre-gate strutturale deterministico (grid cols per breakpoint / responsive machinery / landmark, confidence graduata). Semantica onesta: SEGNALI, mai verdetti (le primitive composte sono invisibili al regex) — hint `deterministic_signals` che il `markup-fidelity-verifier` conferma o dismette esplicitamente; un `match` non autorizza mai lo skip del verifier.
+- **`ui-expert.md` § "Build-with-eyes"**: self-check in-build bounded (max 2 iter) — strutturale via script + visivo con `npx playwright screenshot` e Read multimodale del mockup; degrado onesto e SEMPRE riportato. Il trio verifier resta il giudice indipendente.
+- **`/e2e-review`**: validazione dimensioni viewport prima del pixel-diff (chiude il falso-negativo cross-width); **quality pre-filter skip** (design system + structural pulita + pixel-diff sotto threshold → `ui-quality-critic` saltato come skip autorizzato `quality_prefilter_skip`; mai su `harness-render`/no-mockup).
+
+### Added — T1.C Turn-tax (delega off-context)
+
+- **`/new` 1.2.0 — AUTONOMOUS OFF-CONTEXT DELEGATION GATE** (kickoff, pre-Phase-0): un batch `-auto` è delegato di default al motore `new2` (Workflow tool + `new2.js` + skill presenti, batch migration-free, non `-auto-ship`). Delega MANDATORY a condizioni verdi; escape hatch **`-inline`**; il classico resta SSOT (interattivo / Codex / `-auto-ship` / migrazioni).
+- **`new2` 1.1.0**: promossa a motore di default di `/new -auto` (Step 1.5 = contratto della delega + handback su migrazione dichiarata); `docs/WORKFLOWS.md` riframato ("new2 is the engine, /new is the SSOT").
+
 ## [4.89.2] - 2026-07-01
 
 **`baldart update` auto-commit now covers the FULL payload — Codex artifacts included.** A consumer reported that `baldart update` "never commits anything" even when authorized, and that other clones keep seeing the same files untracked. Root cause: `postUpdateAutoCommit` (`src/commands/update.js`) auto-commits only paths matching `BALDART_MANAGED_PATTERNS`; everything else is classified `userOwned` and left in the tree forever. The allowlist had drifted behind the payloads BALDART actually writes — it was missing every Codex-native artifact (`.codex/agents/*.toml` transpiled agents v4.80.0, `.codex/hooks.json` v4.88.0, `.agents/skills/*` skill symlinks v3.7.0), `.claude/output-styles/` (v4.50.0), and the i18n gate files (`eslint.i18n.config.mjs` / `.eslintrc.i18n.json` / the `paths.i18n_registry` directory, v4.52.0). On a Codex-enabled consumer the 32 `.toml` files are regenerated as real files on every update, classified `userOwned`, never committed → churn in every other clone.

package/VERSION

@@ -1 +1 @@
-4.89.2
+4.92.1

package/framework/.claude/agents/api-perf-cost-auditor.md

@@ -38,6 +38,15 @@ To prevent context bloat:
 - Max **25 Bash/grep calls**.
 - Never read files outside `git diff --name-only` (or scope passed by orchestrator) unless tracing a callgraph that proves a regression.
 
+## Search discipline (MUST)
+
+Prefer `rg` over GNU `grep` on source files: GNU `grep` silently flips to binary
+mode on the first NUL/non-UTF-8 byte (common in large generated/bundled files) and
+prints nothing + exit 1 — indistinguishable from "no match". An empty result on a
+file you EXPECT to match is a binary-mode trap, not evidence: re-run with `rg` (or
+`grep -a`) before concluding anything. SSOT:
+`framework/agents/code-search-protocol.md` § Budget.
+
 ## Project Context (read from `baldart.config.yml`)
 
 Read `stack.framework`, `stack.database`, `stack.deployment` at the start of

package/framework/.claude/agents/code-reviewer.md

@@ -40,6 +40,15 @@ Before applying the review checklist, consult MEMORY for similar prior reviews:
 4. In the verdict line context, declare: `Memory matches: <N> known pitfalls applied`.
 5. If you find a NEW recurring pattern during review, append it to MEMORY.md at end.
 
+## Search discipline (MUST)
+
+Prefer `rg` over GNU `grep` on source files: GNU `grep` silently flips to binary
+mode on the first NUL/non-UTF-8 byte (common in large generated/bundled files) and
+prints nothing + exit 1 — indistinguishable from "no match". An empty result on a
+file you EXPECT to match is a binary-mode trap, not evidence: re-run with `rg` (or
+`grep -a`) before concluding anything. SSOT:
+`framework/agents/code-search-protocol.md` § Budget.
+
 ## Design System Compliance (MANDATORY for UI work)
 
 When reviewing files that touch UI components, styling, or visual output,

package/framework/.claude/agents/codebase-architect.md

@@ -326,6 +326,12 @@ prose costs them context budget on every subsequent turn.
   the `## Canonical Evidence` block.
 - **Affected code as rows, not paragraphs:** `path:line — symbol — pattern/role`.
 - **High-risk paths / integration points, one line each:** `path:line — risk`.
+- **Hot-File Map (MANDATORY for every in-scope file > 800 lines):** a
+  `## Hot-File Map` block, one row per exported/major symbol —
+  `path (N lines): symbol — L<start>–L<end>` — so every downstream agent Reads the
+  target RANGE instead of the whole file (`code-search-protocol.md` § "Large-file
+  read discipline"; a 2110-line hot file was measured re-read whole 28× in one
+  run). Cheap to produce: `rg -n "^export|^function|^class|^const"` on the file.
 - **Close with** a `totals:` line (files, reuse candidates, high-risk paths).
 - **Drop:** the high-level-overview paragraph, the "why" essays, restating the
   request, any prose a row already carries.

package/framework/.claude/agents/coder.md

@@ -71,7 +71,7 @@ Any requirement of the form "verify X; if found → do A; if missing → do B/le
 is a **binary-outcome item**. BOTH branches have a mandatory artifact — silence is never valid.
 
 Rules:
-1. **Verify actively**: read the relevant code (don't assume). Use Grep/Read. **Prefer `rg` over GNU `grep` on source** — GNU `grep` silently flips to binary mode on the first NUL byte (common in large generated/bundled `data.ts`-style files) and then prints nothing + exits 1, *indistinguishable from "no match"*. An empty result + exit 1 on a file you expect to match is a binary-mode trap, NOT proof the symbol is gone: re-run with `rg` (or `grep -a`) before acting. See `framework/agents/code-search-protocol.md` § Budget.
+1. **Verify actively**: read the relevant code (don't assume). Use Grep/Read. **Prefer `rg` over GNU `grep` on source** — GNU `grep` silently flips to binary mode on the first NUL byte (common in large generated/bundled `data.ts`-style files) and then prints nothing + exits 1, *indistinguishable from "no match"*. An empty result + exit 1 on a file you expect to match is a binary-mode trap, NOT proof the symbol is gone: re-run with `rg` (or `grep -a`) before acting. See `framework/agents/code-search-protocol.md` § Budget. **Hot files (> 800 lines): Read the target RANGE, never the whole file** — use the baseline's `## Hot-File Map` line ranges when present, else `rg -n` the symbol first (`code-search-protocol.md` § "Large-file read discipline"). A whole-file Read of a hot file is justified only for a genuinely dispersed edit — say so in one line.
 2. **Branch A (condition satisfied)**: implement A as specified.
 3. **Branch B (condition not met)**: produce B — either:
    - A code change (add the missing piece), OR

package/framework/.claude/agents/markup-fidelity-verifier.md

@@ -45,6 +45,15 @@ which needs a render) and you do NOT judge whether the design is *good*
 gracefully (skip the check you lack inputs for). Do not assume defaults. See
 `framework/agents/project-context.md` § 3.
 
+## Search discipline (MUST)
+
+Prefer `rg` over GNU `grep` on source files: GNU `grep` silently flips to binary
+mode on the first NUL/non-UTF-8 byte (common in large generated/bundled files) and
+prints nothing + exit 1 — indistinguishable from "no match". An empty result on a
+file you EXPECT to match is a binary-mode trap, not evidence: re-run with `rg` (or
+`grep -a`) before concluding anything. SSOT:
+`framework/agents/code-search-protocol.md` § Budget.
+
 ## Hard Prohibitions (non-negotiable)
 
 - **NEVER edit any file.** You produce a JSON report only. The orchestrator delegates
@@ -83,7 +92,11 @@ The orchestrator (`/e2e-review`) invokes you with this JSON payload:
   "tolerance": "strict" | "balanced" | "lenient",
   "resolved_orphans": [                                  // optional — Functional Traceability Gate
     "Export CSV button", "bell icon"                     // mockup affordances deliberately dropped
-  ]
+  ],
+  "deterministic_signals": {                             // optional — structural-compare.mjs output
+    "status": "match" | "divergence" | "skipped",
+    "findings": [ { "category": "...", "severity": "...", "confidence": "..." } ]
+  }
 }
 ```
 
@@ -106,6 +119,16 @@ that is absent in the implementation is **EXPECTED — never a `component-missin
 finding**. See `framework/agents/design-system-protocol.md` § "Functional Traceability
 Gate".
 
+**`deterministic_signals` (focus hints, when present).** The regex-level pre-gate
+(`framework/scripts/structural-compare.mjs`) already scanned the same inputs. Its
+signals are hints, not verdicts — it cannot see a grid or landmark owned by a
+COMPOSED primitive (it only reads the card-touched files; you CAN read the composed
+primitives). For each signal: **confirm it** (emit the corresponding finding, your
+severity call) or **dismiss it explicitly** (state which composed primitive explains
+it — e.g. "the reused `SplitView` owns the 2-column grid"). Do not silently ignore a
+signal, and do not let a `match` lower your own scrutiny — the signature is necessary,
+not sufficient.
+
 ## Severity Taxonomy (cite — do NOT redefine)
 
 The canonical severity taxonomy is SSOT in

package/framework/.claude/agents/qa-sentinel.md

@@ -70,6 +70,15 @@ Default pre-commit gates (MUST pass before any commit verdict) — used when no
 
 ---
 
+## Search discipline (MUST)
+
+Prefer `rg` over GNU `grep` on source files: GNU `grep` silently flips to binary
+mode on the first NUL/non-UTF-8 byte (common in large generated/bundled files) and
+prints nothing + exit 1 — indistinguishable from "no match". An empty result on a
+file you EXPECT to match is a binary-mode trap, not evidence: re-run with `rg` (or
+`grep -a`) before concluding anything. SSOT:
+`framework/agents/code-search-protocol.md` § Budget.
+
 ## Step 0: Always Start Here
 
 Before running any checks:

package/framework/.claude/agents/security-reviewer.md

@@ -35,6 +35,15 @@ Before reviewing:
 1. Locate security-related ADRs and NFRs via `${paths.references_dir}/ssot-registry.md` and `rg` over security-related ADRs, reference docs, and agent instructions. Verify runtime/security truth against repo docs/code before making recommendations.
 2. Check the traceability matrix (`${paths.traceability_matrix}`, typically `docs/references/traceability-matrix.md`) for which docs govern the code under review; if absent, skip this step.
 
+## Search discipline (MUST)
+
+Prefer `rg` over GNU `grep` on source files: GNU `grep` silently flips to binary
+mode on the first NUL/non-UTF-8 byte (common in large generated/bundled files) and
+prints nothing + exit 1 — indistinguishable from "no match". An empty result on a
+file you EXPECT to match is a binary-mode trap, not evidence: re-run with `rg` (or
+`grep -a`) before concluding anything. SSOT:
+`framework/agents/code-search-protocol.md` § Budget.
+
 ## Core Responsibilities
 
 1. **Detect vulnerabilities** in source code, configurations, and architecture.

package/framework/.claude/agents/ui-expert.md

@@ -32,6 +32,12 @@ When `false`, that section is a no-op).
 **On missing/empty keys:** ask the user; do not assume defaults. See
 `framework/agents/project-context.md` § 3.
 
+**Read discipline (hot files):** for any source file > 800 lines, Read the target
+RANGE (the baseline's `## Hot-File Map` line ranges when present, else `rg -n` the
+symbol first) — never the whole file unless the edit is genuinely dispersed (say
+so in one line). SSOT: `framework/agents/code-search-protocol.md` § "Large-file
+read discipline".
+
 ## Authoritative Style Reference — Registry-First Protocol
 
 This agent follows the registry-first discipline defined in
@@ -104,6 +110,49 @@ screenshot throws away exact values you already have and reintroduces drift.
 Reuse-first keeps your design system the authority while inheriting the design's
 exact composition — faithful AND token-clean.
 
+## Build-with-eyes — bounded in-build self-check (MANDATORY when building from a mockup)
+
+Catch-and-repair downstream is more expensive than build-right upstream: every
+fidelity miss you ship costs a full verify→heal→re-verify cycle. So when you
+build from a mockup, you check your own first pass BEFORE returning. This is
+NOT self-grading — the independent verifier trio (`markup-fidelity-verifier`,
+`visual-fidelity-verifier`, `ui-quality-critic`) remains the judge; your
+self-check exists to raise first-pass fidelity so their loop converges in 0–1
+iterations. **Bounded: max 2 self-check iterations**, then return with an honest
+report.
+
+1. **Structural self-check (code-form mockup — deterministic).** After your
+   first complete build (the code compiles), run:
+
+   ```bash
+   node "$(ls .framework/framework/scripts/structural-compare.mjs scripts/structural-compare.mjs 2>/dev/null | head -1)" \
+     --mockup <design_src dir | mockup .html> --impl <the files you wrote>
+   ```
+
+   Judge each signal with your knowledge of what you composed: a `layout-break`
+   signal explained by a reused primitive that owns the grid (e.g. a `SplitView`)
+   is dismissible with that reason; one you cannot explain is a real miss — fix
+   it NOW, not in the heal loop.
+2. **Visual self-check (any mockup — when a render is cheaply capturable AND you
+   are multimodal).** If the worktree's dev server is already running (check the
+   port registry) or boots within ~60s — or the surface is an isolated registry
+   primitive renderable via the `/ds-render` harness — capture it headless:
+
+   ```bash
+   npx playwright screenshot --viewport-size=1440,900 --full-page <url> /tmp/bwe-<CARD-ID>.png
+   ```
+
+   `Read` the capture AND the mockup image, compare them yourself, and fix the
+   clear divergences you see (region placement, column structure, spacing
+   rhythm, obvious color blocks). Re-capture once after fixing. Never install
+   browsers or debug a server that fails to boot twice mid-build — that is a
+   skip, not a setup task.
+3. **Degrade honestly, report always.** No server / no Playwright /
+   non-multimodal runtime → skip the visual pass (the structural one still runs
+   when a code-form mockup exists) and say so. Your completion report ALWAYS
+   carries one line:
+   `build-with-eyes: structural=<match|divergence-fixed|divergence-dismissed(<why>)|skipped> visual=<checked|checked-fixed|skipped(<reason>)>`.
+
 ## i18n — No Hardcoded Strings (BLOCKING when `features.has_i18n: true`)
 
 When you WRITE UI code (the implementer role above) and `features.has_i18n: true`,

package/framework/.claude/agents/visual-fidelity-verifier.md

@@ -63,7 +63,7 @@ The orchestrator (`/e2e-review`) invokes you with this JSON payload:
   "card_id": "FEAT-XXXX",
   "route": "/dashboard",
   "viewport": { "width": 1440, "height": 900 },
-  "viewport_role": "desktop" | "mobile",          // optional, default "desktop"
+  "viewport_role": "desktop" | "mobile" | "tablet",   // optional, default "desktop"
   "implementation_screenshot_path": "/abs/path/to/impl.png",
   "mockup_source": {
     "level": "figma" | "local" | "compliance-only" | "skip",
@@ -83,21 +83,25 @@ The orchestrator (`/e2e-review`) invokes you with this JSON payload:
 
 If `mockup_source.level == "skip"`, return immediately with
 `{ "status": "skipped", "reason": "no_mockup_available", "findings": [] }` —
-**unless** `viewport_role == "mobile"`, in which case run the responsive-integrity
-pass below (it needs no mockup).
-
-**`viewport_role: "mobile"` — responsive-integrity pass.** When set, you are
-looking at the **mobile render** (a narrow viewport, typically 375px). Mobile
-mockups are rarely provided, and the mobile layout *correctly* reflows away from
-any desktop mockup — so in this mode you **do NOT diff against a mockup** and you
-do **NOT** emit fidelity findings (`element-order`, `spacing-off-scale`,
-`typography-*`, `color-*` relative to a desktop design). Evaluate the mobile
+**unless** `viewport_role` is `"mobile"` or `"tablet"`, in which case run the
+responsive-integrity pass below (it needs no mockup).
+
+**`viewport_role: "mobile" | "tablet"` — responsive-integrity pass.** When set,
+you are looking at a **responsive render** (mobile ≈ 375px; tablet ≈ 768px).
+Per-viewport mockups are rarely provided, and the layout *correctly* reflows away
+from any desktop mockup — so in this mode you **do NOT diff against a mockup** and
+you do **NOT** emit fidelity findings (`element-order`, `spacing-off-scale`,
+`typography-*`, `color-*` relative to a desktop design). Evaluate the
 screenshot on its own and flag **only genuine viewport breakage**:
 `responsiveness-break` (horizontal scroll past the viewport, content cut off,
 elements overlapping/unreadable), `unreachable-action` (primary CTA off-screen or
 behind a fixed overlay), and `layout-break` (a container that genuinely collapsed,
-not an intended stack). Be conservative: a dense-but-legible layout is **not** a
-break — flag only hard failures a user would hit. Return the same output schema.
+not an intended stack). At tablet width also flag a **wrong-band collapse** — a
+layout the card's ACs promise as multi-column at ≥768px that has already collapsed
+to the mobile stack — as `responsiveness-break` (cite the AC in `expected`). Be
+conservative: a dense-but-legible layout is **not** a break — flag only hard
+failures a user would hit. Return the same output schema, tagging findings with
+the `viewport_role` you were given.
 
 **`resolved_orphans` carve-out (Functional Traceability Gate).** The mockup is a
 fidelity target, not a requirements oracle: it may contain interactive chrome that

package/framework/.claude/skills/e2e-review/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.2.1 — 2026-07-02
+
+- Phase 3.8: la lane visual del route non renderizzabile con mockup code-form viene
+  marcata esplicitamente `skipped:render_unavailable_structural_covered` nel Lane
+  Matrix (l'enum canonico che l'assertion di Phase 5 step 0 valida); `gaps[]` tiene
+  il diagnostico `render_unavailable` — due stringhe deliberatamente distinte.
+- Phase 5b step 3: chiave di convergenza estesa con `viewport_role`
+  (`route, source, category, viewport_role, region`) — una regressione
+  viewport-scoped non può più matchare falsamente il finding pre-fix.
+
+## 1.2.0 — 2026-07-02
+
+- **Self-heal convergence detection (Phase 5b step 3)**: se il fix produce finding
+  gating NUOVI assenti prima (fixer che regredisce mentre ripara), stop immediato →
+  override path con entrambi i set (`convergence: "diverging"`) — non si brucia
+  l'iterazione 2. Set che si restringono/uguali iterano normalmente.
+- Phase 5b step 1: spawn del SOLO bucket non vuoto (niente coder su finding
+  tutti-UI e viceversa). Deliberatamente NON introdotta la re-verify selettiva
+  delle lane (sarebbe l'under-run che la Lane-Ledger assertion blocca; i due
+  pre-filter rendono già economico il re-run pulito).
+
+## 1.1.1 — 2026-07-02
+
+- Fix B4 (location parallela): i prompt fixer di Phase 5b citavano il tracker in
+  `/tmp/batch-tracker-…` (path volatile pre-fix) — ora la location DURABILE
+  `$(git rev-parse --git-common-dir)/baldart/run/…` (new/SKILL.md § Context
+  Tracking).
+
+## 1.1.0 — 2026-07-02
+
+- **Lane Matrix + lane-coverage assertion**: Phase 2 chiude con un ledger delle lane
+  pianificate per route (structural / visual desktop·mobile·tablet / quality /
+  functional); Phase 5 step 0 riconcilia planned-vs-ran e sintetizza
+  `verification-coverage-gap` (Critical, `source: "coverage"`, bypassa il self-heal)
+  per ogni lane pianificata mai eseguita. Chiude l'under-run FEAT-0064 (run con solo
+  verifier strutturale, zero visual/quality, verdetto muto). SSOT:
+  `design-system-protocol.md` § Verification-Lane Ledger (nuovo check #6).
+- **Threading del bundle HTML decodificato**: un mockup `.html` viene SEMPRE sondato
+  con `extract-mockup-design.mjs`; `status: ok` → `structural_source` di livello
+  `design_src` (JSX/CSS decodificati), altrimenti resta `html`. Un mockup HTML non può
+  più perdere la lane strutturale per un decode mancato.
+- **Viewport tablet @768px scope-driven**: `plan.tablet_in_scope` (deterministico da
+  title/AC/scope) → terza cattura Playwright + pass responsive-integrity 2c con
+  `viewport_role: "tablet"`. Chiude il buco della "fascia di mezzo" 768–1024px.
+- Report JSON: nuovi campi `lane_coverage` + `lanes` (additivi, consumer /new e
+  /ui-implement invariati sul contratto esistente).
+- **Pre-gate deterministico Phase 2.7** (`framework/scripts/structural-compare.mjs`):
+  signature strutturale mockup↔implementazione (griglia/breakpoint/landmark, con
+  confidence graduata) passata al `markup-fidelity-verifier` come
+  `deterministic_signals` (hint da confermare/dismettere esplicitamente — mai un
+  verdetto autonomo: le primitive composte sono fuori dalla vista del regex).
+- **Validazione dimensioni viewport (Phase 4 step 1a-pre)**: pixel-diff mai eseguito
+  su larghezze diverse (falso-negativo sotto threshold); mismatch → log +
+  comparazione Vision diretta, mai resize forzato.
+- **Quality pre-filter skip (Phase 4b)**: con design system + lane strutturale pulita
+  + pixel-diff sotto threshold, lo spawn di `ui-quality-critic` è saltato come
+  `skipped:quality_prefilter_skip` (skip autorizzato nel Lane Matrix); mai su
+  `harness-render` o route senza mockup.
+
 ## 1.0.0 — 2026-07-01
 
 - Baseline: versioning per-skill introdotto al framework v4.82.0.