baldart 4.76.1 → 4.78.0

package/framework/templates/overlays/e2e-review.fidelity-example.md

@@ -0,0 +1,74 @@
+---
+base_skill: e2e-review
+base_skill_version: 4.78.0
+mode: extend
+---
+
+# e2e-review — fidelity-app overlay (example)
+
+> Project-specific **reach-state recipes** for `/e2e-review` Phase 3.8. The framework
+> owns the contract and the bounded loop; this overlay tells the orchestrator HOW to put
+> the app into the data state a mockup depicts, so the visual reviewer never compares a
+> degenerate (empty / wrong-tenant / error) render. Drop into
+> `.baldart/overlays/e2e-review.md` and adapt to your stack.
+>
+> Without these recipes `/e2e-review` falls back to generic remediation (real auth from
+> the persona creds, MSW/API-mock, deterministic factory/snapshot, heuristic context
+> auto-seek) and, failing that, **blocks** with `coverage-gap` — it never silently passes
+> an empty render.
+
+## [APPEND] Reach-state recipes
+
+The orchestrator runs the applicable recipes in order until `render_health.degenerate`
+is false. Each recipe is a named, deterministic sequence of steps the orchestrator can
+execute via Playwright / `webapp-testing` / a project script. Cap: 2 attempts.
+
+### `seed_data` — populate the database for the route
+
+Run before navigating, when the route shows an empty-state because the demo/CI database
+is empty:
+
+```bash
+# Example: seed a deterministic dataset the mockup depicts (idempotent).
+npm run db:seed:e2e            # creates store "demo" + ≥3 products + 1 supplier
+```
+
+State guarantee: after this, `/products` renders a populated table matching the mockup's
+DATI PRODOTTO / FORNITORI sections. The seed MUST be deterministic (fixed ids, no
+faker-without-seed) so screenshots are reproducible.
+
+### `select_populated_context` — the multi-store / multi-tenant case
+
+When the default-selected store/tenant is empty but another has data (the exact failure
+the user flagged): switch context to a populated one before screenshotting.
+
+```
+1. Authenticate as the owner persona (test_plan.test_credentials).
+2. Open the store switcher: getByRole("button", { name: /store|negozio/i }).
+3. Pick the first store whose product count > 0 (the seeded "demo" store), NOT the
+   default empty one.
+4. Wait for networkidle, then proceed to the route.
+```
+
+Heuristic fallback (no explicit list): enumerate the switcher options, navigate the route
+under each, and pick the first that yields non-empty content (the verifier confirms
+non-emptiness). This is the generic `webapp-testing` auto-seek.
+
+### `goto_populated_entity` — detail routes that need a specific id
+
+When the mockup depicts a specific entity (e.g. a product detail), navigate to a seeded
+entity id rather than a random/empty one:
+
+```
+Navigate to `/products?selected=<seeded-product-id>&edit=1` (the id created by
+`seed_data`), not the bare `/products`.
+```
+
+## [APPEND] Notes
+
+- Recipes are tried in the order above (`seed_data` → `select_populated_context` →
+  `goto_populated_entity`); a recipe that does not apply to a route is a no-op.
+- Keep recipes **deterministic and idempotent** — they run inside the bounded reach-state
+  loop and may be re-invoked across self-heal iterations.
+- A recipe MUST NOT mutate production data: scope to the e2e/demo database the dev server
+  uses. The framework's contract assumes an isolated test database.

package/package.json

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