@petukhovart/agent-view 0.8.0 → 0.8.2

package/skills/verify-recipe/SKILL.md

@@ -1,258 +1,286 @@
----
-name: verify-recipe
-description: "Generates a concrete, command-by-command agent-view recipe for verifying a feature or bugfix. Use when the developer wants to write a verify-recipe.md, create a verification plan, build an agent-view recipe, or produce a verify checklist for a change they shipped. Triggers on: write a verify-recipe, write verification steps, generate verify steps for the feature/bug I just shipped/fixed, make a verify-recipe.md, what should I run to verify X, create a verification plan, agent-view recipe for this fix, verify checklist for this feature. Does NOT execute the checks — it authors the plan. For running checks against a live app, use the verify skill instead."
-allowed-tools: Read, Write, Bash(agent-view *)
----
-
-# Verification Recipe Generator
-
-You help the developer author a disciplined, cheapest-first verification recipe for a feature they shipped or a bug they fixed. You do not run the checks — you produce a `.claude/verify-recipes/<slug>.md` file that any AI coding agent can execute later.
-
-## What this produces
-
-A file at `.claude/verify-recipes/<kebab-slug>.md` with three precondition phases plus the verification body:
-
-- **MANUAL PRECONDITIONS** — only what `agent-view` physically cannot do (rare; usually empty)
-- **BRINGUP** — idempotent setup steps the verify-runner executes itself: `if <state-check> is falsy → run actions → wait for state to settle`. Drives the app from auth screen / fresh shell / mid-state into the exact state the recipe needs. Re-runs cost almost nothing because each step skips when its condition is already met.
-- **MACHINE PRECONDITIONS** — pure state queries that confirm Bringup actually settled. No actions here. Any false → runner aborts.
-- **EVIDENCE COMMANDS** — ordered `agent-view` calls, cheapest first, each annotated with what it proves.
-- **POSITIVE-CASE ASSERTIONS** + **REGRESSION CHECKS** + optional **DESIGN CONFORMANCE**.
-
-Create the directory if missing: `mkdir -p .claude/verify-recipes`
-
-## Why three precondition phases
-
-| Phase | Who runs it | What it does | Idempotent? |
-|---|---|---|---|
-| `## Manual Preconditions` | Human (or main agent) | Only what `agent-view` physically can't (USB token, hardware setup, multi-machine state) | n/a |
-| `## Bringup` | verify-runner | `if state-check is falsy → action → wait`. Logins, mounting widgets, navigation — anything `agent-view` can do deterministically | YES (per step) |
-| `## Machine Preconditions` | verify-runner | Pure `eval` / `dom --filter` state queries. NO actions. | trivially |
-
-**Why split Bringup from Machine Preconditions?** A failure tells you a different thing in each:
-- A failed Bringup post-condition → bringup spec is wrong (e.g., `selectLocationAndFly` doesn't exist; "Войти" button text changed). Author error.
-- A failed Machine Precondition after Bringup succeeded → bringup THINKS it set up the state but the state isn't there (e.g., login appeared to succeed but the user role is wrong, the app is in a degraded mode). Real environment issue.
-- A failed Evidence Command after both passed → real bug in the verified feature.
-
-Without the split, all three look like "step N failed" and the developer can't tell which.
-
-**Why keep Manual at all?** Some things really can't be automated cheaply: physical USB-key auth, multi-machine setups, long-running data migrations. List them — but be honest, this section should usually be empty.
-
-## Methodology
-
-Frame the recipe with **hard-debug** discipline. Apply this chain in authoring mode:
-
-1. Start from the broadest possible starting state — recipe should run from auth screen, from logged-in shell, or from "already in the feature" without modification.
-2. Convert vague expectations ("looks right") into measurable signals ("`store.user.role === 'admin'`").
-3. Prefer the cheapest tool that can answer the question — a value check costs ~50 tokens, a screenshot costs ~6 000.
-4. Include at least one negative-case check (the old symptom must no longer appear).
-5. Include at least one regression check (an adjacent flow must still work).
-6. **Bringup steps must be conditional + idempotent.** Every action wrapped in `if <state-check> is falsy`. Every action followed by `wait for <post-condition> to be truthy`. Re-running the recipe must be a no-op when the app is already ready.
-
-## Tool-cost decision tree
-
-Pick the first row that can answer the question. Only go lower when the row above can't:
-
-| Question | Command | Why it's cheapest |
-|---|---|---|
-| Element exists / has specific text / role | `agent-view dom --filter "<text>" --depth 2` | Structured text, zero vision tokens |
-| App state, store value, computed flag | `agent-view eval "<expr>"` | Returns the value directly; DOM inference is wasteful and fragile |
-| What changed between action and final state | `agent-view watch "<expr>" --until "<condition>"` or `--max-changes 1` | `eval` shows the snapshot; `watch` shows the trajectory |
-| SharedWorker / ServiceWorker internal state | `agent-view eval --target <name> "<expr>"` | Workers have no DOM; this is the only path |
-| Did this action throw or warn silently? | `agent-view console --clear` before, `agent-view console --level error,warn` after | Catches uncaught exceptions and network failures invisible to DOM |
-| Layout, spacing, visual regression | `agent-view screenshot --scale 0.5` | Last resort — the only tool that sees pixels, but costs ~6 000 tokens |
-| Canvas / WebGL scene state | `agent-view scene --diff` | DOM is empty for canvas apps |
-
-**Anti-patterns to reject:**
-- Putting UI clicks (`click`, `fill`) in `## Machine Preconditions`. Actions go in `## Bringup`. Machine Preconditions are state queries only.
-- Bringup steps without an IF condition (unconditional actions). They break idempotency — re-running a "click Login" step when already logged in fails. Always wrap.
-- Bringup steps without a post-condition wait. Without it, the runner advances before the action settled, and the next step's IF check sees stale state.
-- Manual Preconditions for anything `agent-view` can do. Drag widget into cell? Often there's a programmatic API — interview the developer for it before defaulting to Manual.
-- Hardcoded credentials in Bringup commands. Use env-var references (`"$AGENTVIEW_PASSWORD"`) — never inline a password, even for dev/masterkey accounts. Recipes get committed to git.
-- Opening Evidence Commands with a screenshot to "see the state" — use `dom --filter` or `eval` first.
-- "Check that it looks right" — every Evidence assertion must be a concrete pass/fail criterion. The single legitimate exception is the `## Design Conformance` section.
-- Inventing design reference paths (`.figma-refs/...`) when the developer did not provide them. No refs → no Design Conformance section.
-
-## Workflow
-
-### Step 1 — gather context (interview the developer)
-
-When invoked, ask in plain text. Wait for response before continuing.
-
-**Block A — what's being verified:**
-
-1. What was shipped or fixed? (feature name or bug description)
-2. What was the original symptom or expected behavior?
-3. Any known failure mode or edge case to cover?
-
-**Block B — bringup: how the runner gets the app into a state where verification makes sense:**
-
-4. **Authentication** — does the app require login before the feature is reachable? If yes:
-   - What identifies "logged out" vs "logged in" in JS state? (e.g., `typeof window.__dev`, `!!store.user`)
-   - Login flow: which fields/buttons (`fill --filter "..."`, `click --filter "..."`) and what credentials? **Use an env-var, never inline.** Suggest a name like `AGENTVIEW_PASSWORD` and tell the user to `export` it in their shell or `.env.local`.
-5. **UI mode / view requirements** — does the feature live behind a specific app mode/view that must be active before it appears (e.g., "map view, not settings panel"; "edit mode, not view mode"; "modal X must be open")? For each:
-   - State check that proves this mode is active (e.g., `document.querySelector('.cesium-widget') !== null` for map mode).
-   - Action(s) to enter this mode if not active. Prefer programmatic API (e.g., `eval "store.setMode('map')"`) over UI clicks. If only UI works, list the click sequence.
-6. **Setup actions** — beyond modes, what other setup must happen (drag widget into cell, navigate camera to a location, open a dialog)? For each:
-   - Programmatic API if it exists (e.g., `gis-widget-root.selectLocationAndFly(uuid)`, `workspace.addWidget(...)`). Prefer this — much more reliable than UI automation.
-   - State check that proves the setup happened.
-   - Wait timing: how long does this take to settle? (camera animation, async data load).
-
-If the developer doesn't know whether a programmatic API exists, ask them to point you at the relevant store/composable/component file — you can read it and find one (or confirm none).
-
-**Block C — verification body and visual:**
-
-7. State assertions for the verified feature itself — JS expressions that prove it works (separate from bringup setup checks).
-8. **(Optional) Design references** — local image paths to compare screenshots against (Figma exports, hand-off PNGs). **Only local files are supported.** If none — skip the Design Conformance section.
-
-### Step 2 — draft the recipe
-
-Use the answers to produce a recipe in this format:
-
-````markdown
-# Verify: <feature or fix name>
-
-Generated: <date>
-Scope: <one sentence describing what this covers>
-
-## Manual Preconditions
-<!-- ONLY for things agent-view physically cannot do. Usually empty. -->
-<!-- The verify-runner does NOT execute these. -->
-(none — bringup handles everything)
-
-## Bringup
-<!-- The verify-runner executes these. Each step is conditional + idempotent: skipped if already in target state. -->
-<!-- Format per step: -->
-<!--   ### B<N>. <one-line title> -->
-<!--   - if `<eval>` is `<falsy criterion>`: -->
-<!--       <action command 1> -->
-<!--       <action command 2> -->
-<!--     wait for `<post-condition eval>` to be `<truthy criterion>`, timeout <Ns> -->
-
-### B1. Login if on auth screen
-- if `agent-view eval "typeof window.__dev"` is not `"object"`:
-    agent-view fill --window $W --filter "Логин" "root"
-    agent-view fill --window $W --filter "Пароль" "$AGENTVIEW_PASSWORD"
-    agent-view click --window $W --filter "Войти"
-  wait for `agent-view eval "typeof window.__dev"` to be `"object"`, timeout 15s
-
-### B2. Mount the GIS widget if not mounted
-- if `agent-view eval "!!window.__dev.pinia._s.get('gis-widget-root')?.cesiumReadyFlag"` is `false`:
-    agent-view eval "window.__dev.pinia._s.get('workspace').addWidget({type:'gis', cell:0})"
-  wait for `agent-view eval "!!window.__dev.pinia._s.get('gis-widget-root')?.cesiumReadyFlag"` to be `true`, timeout 10s
-
-### B3. Exit settings mode if active
-- if `agent-view eval "document.querySelector('.cesium-widget') !== null"` is `false`:
-    agent-view click --window $W --filter "Готово"
-  wait for `agent-view eval "document.querySelector('.cesium-widget') !== null"` to be `true`, timeout 5s
-
-### B4. Fly to first sublocation
-- if `agent-view eval "!!window.__dev.pinia._s.get('gis-widget-root')?.selectedLocation"` is `false`:
-    agent-view eval --await "window.__dev.pinia._s.get('gis-widget-root').selectLocationAndFly(window.__dev.mwStore.nvgn.sublocations.value[0].id)"
-  wait for `agent-view eval "(()=>{const w=document.querySelector('.cesium-widget'); const cw=Object.values(w).find(v=>v?.scene); return Math.round(window.Cesium.Cartographic.fromCartesian(cw.scene.camera.position).height);})()"` to be `< 5000`, timeout 30s
-
-### B5. Snapshot for the report (always runs)
-agent-view screenshot --window $W --scale 0.25
-
-## Machine Preconditions
-<!-- Pure state checks. NO actions. The verify-runner aborts with `precondition_failed` if any return false. -->
-- `agent-view eval "typeof window.__dev"` → must be `"object"`
-- `agent-view eval "!!window.__dev.pinia._s.get('gis-widget-root')?.cesiumReadyFlag"` → must be `true`
-- `agent-view eval "document.querySelector('.cesium-widget') !== null"` → must be `true`
-- `agent-view eval "!!window.__dev.pinia._s.get('gis-widget-root')?.selectedLocation"` → must be `true`
-- `agent-view eval "({locations:window.__dev.mwStore.nvgn.locations.value.length, sublocations:window.__dev.mwStore.nvgn.sublocations.value.length, zones:window.__dev.mwStore.nvgn.zones.value.length, objects:window.__dev.mwStore.nvgn.objects.value.length})"` → all four counts must be `> 0`
-
-## Narrowed Signal
-<!-- The one measurable thing that proves the verified feature works -->
-`<agent-view command>` must return `<expected value>`.
-
-## Evidence Commands
-
-### 1. <What this proves>
-```bash
-agent-view <command>
-```
-Expected: <concrete criterion — value, text, absence of error>
-Cost: ~<N> tokens
-
-### 2. ...
-
-## Positive-Case Assertions
-- [ ] <criterion>
-- [ ] <criterion>
-
-## Regression Checks
-- [ ] <adjacent flow> — `agent-view <command>` → `<expected>`
-
-## Design Conformance
-<!-- Include ONLY if the developer provided design refs in question 8. -->
-
-| Step Label | Screenshot Command | Expected Reference |
-|---|---|---|
-| <area name e.g. "filter panel collapsed"> | `agent-view screenshot --crop "<area>" --scale 0.5` | `<absolute path to expected PNG/JPEG>` |
-
-Tolerance: `normal` (default).
-
-## Anti-patterns avoided
-- <note any recipe-specific traps, e.g. "B4 relies on `selectLocationAndFly` from gis-widget-root — verified to exist as of <date>; if it's removed, B4 falls back to Manual Precondition">
-````
-
-### Step 3 — save the file
-
-Determine a kebab-slug from the feature/fix name. Save to `.claude/verify-recipes/<slug>.md`. Create the directory first if it doesn't exist. Confirm the path to the developer.
-
-### Step 4 — credentials warning (if Bringup contains login)
-
-If Bringup includes a login step:
-
-> Recipe uses `$AGENTVIEW_PASSWORD` for login. Make sure that env var is set in your shell or `.env.local` before running verify (`export AGENTVIEW_PASSWORD=<value>`). The recipe never contains the literal password.
-
-If the developer insisted on inlining a literal password earlier, warn:
-
-> ⚠️ Recipe contains a literal password on line N. This will be committed to git. Consider replacing with `$AGENTVIEW_PASSWORD` (env-var). Want me to convert it now? (yes/no)
-
-### Step 5 — offer dry-run validation
-
-After saving, ask:
-
-> The recipe is saved at `<path>`. Is the app running? If yes, I can spawn `verify-runner` in `dry_run` mode — it'll execute Bringup + Machine Preconditions + the first Evidence Command (~10-20 commands total). That validates the recipe isn't broken before you commit a full run. Want me to run the dry-run? (yes/no)
-
-If yes:
-1. Get the window id with `agent-view discover`.
-2. Spawn `verify-runner` via the Agent tool with `mode: dry_run`, the recipe path, and the window id.
-3. Read the JSON report.
-4. **`status: bringup_failed`** → relay `failed_bringup_step` and the post-condition's actual value. Suggest revising the bringup step (most often: action commands wrong, programmatic API doesn't exist, or post-condition criterion mistuned).
-5. **`status: precondition_failed`** → bringup ran but state isn't there. Either bringup is incomplete, or a state check is overly strict. Show both bringup outcome and the failing precondition.
-6. **`status: completed` and dry-run passed** → recipe is healthy. Confirm and stop.
-
-If no — confirm path and stop.
-
-## Worked example: GIS feature with full bringup automation
-
-**Developer input:**
-> Verifying selective filter changes (commits 0c5f1b1ee, 4d0c89467, 4c99c1591) in the GIS widget. App requires login (root/masterkey via middleware). GIS widget mounts via `workspace.addWidget({type:'gis', cell:0})`. Camera flies via `gis-widget-root.selectLocationAndFly(id)`. Map view is the default after widget mount.
-
-**Recipe produced:**
-
-(see the template above — it's already the worked example for this scenario)
-
-**Saved to:** `.claude/verify-recipes/nvgn-gis-improvements.md`
-
-**Dry-run output (first run after auth screen):**
-```
-status: completed
-mode: dry_run
-bringup: 5 steps, 12 commands, 18s — B1 (login) + B2 (mount) + B4 (fly) all triggered; B3 skipped (already map mode); B5 screenshot saved
-machine_preconditions: 5/5 passed
-steps: 1/1 passed
-```
-
-**Dry-run output (second run, app already in target state):**
-```
-status: completed
-mode: dry_run
-bringup: 5 steps, 5 commands (4 IF-checks + 1 screenshot), 3s — all 4 conditional steps skipped_already_ready
-machine_preconditions: 5/5 passed
-steps: 1/1 passed
-```
-
-This is what idempotent bringup buys you: 5x speedup on re-runs, zero manual intervention either way.
+---
+name: verify-recipe
+description: "Generates a concrete, command-by-command agent-view recipe for verifying a feature or bugfix. Use when the developer wants to write a verify-recipe.md, create a verification plan, build an agent-view recipe, or produce a verify checklist for a change they shipped. Triggers on: write a verify-recipe, write verification steps, generate verify steps for the feature/bug I just shipped/fixed, make a verify-recipe.md, what should I run to verify X, create a verification plan, agent-view recipe for this fix, verify checklist for this feature. Does NOT execute the checks — it authors the plan. For running checks against a live app, use the verify skill instead."
+allowed-tools: Read, Write, Bash(agent-view *)
+---
+
+# Verification Recipe Generator (rigor edition)
+
+You help the developer author a disciplined, cheapest-first verification recipe for a feature they shipped or a bug they fixed. You do not run the checks — you produce a `.claude/verify-recipes/<slug>.md` file that any AI coding agent can execute later.
+
+This edition is hardened against the failure mode of "construction-validated only" recipes that pass while real bugs sit in plain sight in the same data. See `## Bug-class invariants` and `## Discipline rules`.
+
+## What this produces
+
+A file at `.claude/verify-recipes/<kebab-slug>.md` containing:
+
+- **REPRO STEPS** — exact state the app must be in before checks run.
+- **NARROWED SIGNAL** — the measurable indicator that proves success or failure.
+- **EVIDENCE COMMANDS** — ordered `agent-view` calls, cheapest first.
+- **POSITIVE-CASE ASSERTIONS** — what "pass" looks like for each command.
+- **BUG-CLASS INVARIANTS** *(required)* — properties that must hold across all states the recipe touches, not just the action-result state.
+- **ROUND-TRIP CHECKPOINT** *(required when the feature touches persistence or mutable structure)* — a save-and-reload (or equivalent) comparison.
+- **REGRESSION CHECKS** — adjacent paths that must not have broken.
+- **DESIGN CONFORMANCE** *(optional)* — reference image comparisons.
+
+Create the directory if missing: `mkdir -p .claude/verify-recipes`
+
+## Methodology
+
+Frame the recipe with **hard-debug** discipline: REPRO → narrowed signal → minimize scope → root-cause check → fix verification.
+
+1. Start from a reproducible starting state, not "open the app and poke around".
+2. Convert vague expectations ("looks right") into measurable signals (`store.user.role === 'admin'`).
+3. Prefer the cheapest tool that can answer the question — a value check costs ~50 tokens, a screenshot costs ~6 000.
+4. Include at least one negative-case check (the old symptom must no longer appear).
+5. Include at least one regression check (an adjacent flow must still work).
+6. **Construction-only verification is not enough.** For any non-trivial feature, add invariant checks (see next section) and a round-trip checkpoint.
+
+## Bug-class invariants (required section in every recipe)
+
+The recipe must include an `## Invariants` section listing properties that hold *regardless of how state was reached*. These catch bugs that construction-only tests cannot see, because the bug lives in the gap between what the model says and what the user sees / what persistence preserves.
+
+Pick at least one invariant from each applicable class. Skip a class only if it provably cannot apply to the feature.
+
+### Class A — UI ≡ Model
+For every visible representation of state (tree, list, panel, breadcrumb, overlay, badge, count):
+- **Count parity:** `count(DOM rows of kind X) === count(model nodes of kind X)`.
+- **Hierarchy parity:** for any parent/child relationship the model expresses, the DOM must mirror it. A flat-rendered DOM of a nested model is a UI bug, not a model bug.
+- **Text parity:** the label shown in the UI for a node must equal `model.get(nodeId).name` (or whichever field the UI claims to display).
+
+Encode this as a single `eval` that returns a JSON struct so a single failed comparison is unambiguous:
+
+```bash
+agent-view eval "var model=<source-of-truth>;var dom=<measurement>;JSON.stringify({modelCount:model.size, domCount:dom.length, match:model.size===dom.length})"
+```
+
+If `match: false` — that is a FAIL. Do not rationalize a DOM/model count mismatch as "label reuse" or "the breadcrumb counts too" without confirming the matched elements' bounding boxes and DOM ancestry first.
+
+### Class B — Round-trip
+For any feature that creates / mutates persisted structure:
+- `state ≡ deserialize(serialize(state))` (model survives save→load with bit-identical structure for the projected fields).
+- `world(child) === origWorld(child)` immediately after a wrap/unwrap action (the wrapping must not silently shift the wrapped element).
+- Reloading the page (`agent-view eval "location.reload()"`) and re-reading the same state must produce an identical signature.
+
+A round-trip discrepancy that the save serializer silently "fixes" is a model bug, not a save-format bug. Live-vs-persisted divergence between actions and reloads is a class-B failure even if save/load round-trips cleanly with itself.
+
+### Class C — Reversibility & identity
+- Every user-facing command produces exactly one `commandHistory` entry (`canUndo→true`; one `undo()` fully reverses).
+- `undo` then `redo` produces an identical state to "do once".
+- The set of nodes after `do → undo → redo` equals the set after one `do`. Compare full IDs, not counts — a swap of one node for another with the same name is a real bug.
+
+### Class D — No phantom state
+- For each visible entity the user can interact with, there exists exactly one corresponding model node.
+- For each model node, there exists at most one corresponding UI entity in each view.
+- An entity that appears in two views (e.g. tree and canvas) must have the same identity in both (the same `nodeId` resolves both).
+
+This class is the one most often missed. Verify it explicitly when the feature changes structure.
+
+### Class E — Config conformance (rendering vs. configured constraint)
+
+Class A compares model to DOM. Class E compares the **rendered output** (DOM bounds, canvas geometry, computed styles, layout sizes) to an **explicit configuration value** the system declares it must respect. This is the home for invariants that have no DOM counterpart to diff against — they assert against a config the user (or product) chose.
+
+Typical examples — adapt names to the project:
+
+- **Snap/grid:** every shape's bounding box must satisfy `x % gridSize === 0` (and same for `y / width / height`). Read `gridSize` from the live config (`store.gridSettings.gridSize`, `theme.grid.size`, `viewport.snap`, …); do not hardcode.
+- **Viewport bounds:** elements declared "viewport-contained" must have `getBoundingClientRect()` within the viewport rect.
+- **Z-order / layering:** elements declared "above modals" must have computed `z-index` above the modal's. Compare against the configured layer table, not a literal number.
+- **Spacing / density tokens:** if the design system declares a spacing scale, computed `margin` / `padding` must be a multiple of the base token.
+- **Theme tokens:** computed colors / fonts must match the active theme's declared values, not literal hex codes.
+
+Generic helper shape:
+
+```bash
+agent-view eval "var cfg=<read live config value>; var items=<measure rendered items>; var off=items.filter(function(it){return !<conforms(it, cfg)>}); JSON.stringify({cfg:cfg, total:items.length, offCount:off.length, sample:off.slice(0,3)})"
+```
+
+Expected: `offCount: 0`. A non-zero count means the renderer ignored a config the system promised to honor — that is a real bug class, even if the model is internally consistent and round-trips cleanly. Bugs of the form "element is half a pixel off the grid", "modal renders behind the toast", "freshly-created group is not snapped" all live here and fall between the other classes.
+
+When generating recipes, ask: *what config values does this feature claim to respect?* Each one is one Class-E invariant. If the answer is "none" — say so explicitly in the recipe, so a future reader doesn't wonder why the class is absent.
+
+## Discipline rules
+
+These rules govern how the recipe is *executed* — they must appear verbatim in the recipe's `## Discipline` section so the executor cannot forget them.
+
+1. **A failed `Expected:` line is FAIL, not "actually fine".** Rationalizations belong in the bug report after the run, not inline in the run log. If the actual output disagrees with the expected line, mark `FAIL` and continue to the next step; do not edit the expected line, do not invent a "label reuse" or "convention" explanation that makes the discrepancy disappear from the count.
+
+2. **Prefer model-vs-DOM mismatches as the bug, not as noise.** When a Class-A invariant fails, the default hypothesis is "the UI renderer is wrong", not "the DOM filter matched something extra". To rule out the latter, query bounding boxes and ancestor chains for every match; if the matches turn out to be sibling rows in the same list, the renderer is the bug.
+
+3. **Defensive eval reads.** Every read of `node.transform.x` (or any model field) must include a sentinel: `isFinite(value)` or `value !== undefined`. A silent `NaN`/`null` from a renamed field looks like a real `0` in arithmetic and will fail-pass the assertion.
+
+4. **No hardcoded literal IDs.** All node IDs in evals must be resolved by role at runtime (e.g. "the first group at root", "the line at root not inside any group"). Hardcoded prefixes silently degrade the recipe to no-op when the scene differs.
+
+5. **The reload checkpoint is not optional.** For any recipe that touches mutable structure, include at least one `location.reload()` between an action and a re-measurement. Compare the projected signature before and after; differences are real bugs, not "fixed-up on save".
+
+6. **Compose, do not narrate.** Final report is `pass / fail / requires_visual_review` counts plus one-line failure reasons. Do not paste raw stdout. Do not include prose justifications in the per-step output.
+
+7. **`requires_visual_review` is an executor verdict, not an authoring shortcut.** When generating the recipe, draft every step so it executes through `agent-view`. Do not write `requires_visual_review` as the planned status of a step just because the path looks tricky (event delegation, canvas hit-test, file dialog, etc.) — first encode the cheapest sub-check that *can* run programmatically (e.g. "no console error during the action", "model state changed", "command history advanced by one"). The `requires_visual_review` label is set by the *executor* at run time, only after at least one genuine attempt to drive the action via agent-view failed for a reason they record. Authoring the recipe with `requires_visual_review` prebaked is what lets real regressions sit unobserved.
+
+## Tool-cost decision tree
+
+Pick the first row that can answer the question. Only go lower when the row above can't:
+
+| Question | Command | Why it's cheapest |
+|---|---|---|
+| Element exists / has specific text / role | `agent-view dom --filter "<text>" --depth 2` | Structured text, zero vision tokens |
+| Count of matching elements | `agent-view dom --filter X --count` | Single integer, zero tree tokens |
+| App state, store value, computed flag | `agent-view eval "<expr>"` | Returns the value directly; DOM inference is wasteful and fragile |
+| What changed between action and final state | `agent-view watch "<expr>" --until "<condition>"` or `--max-changes 1` | `eval` shows the snapshot; `watch` shows the trajectory |
+| SharedWorker / ServiceWorker internal state | `agent-view eval --target <name> "<expr>"` | Workers have no DOM |
+| Did this action throw or warn silently? | `agent-view console --clear` before, `agent-view console --level error,warn` after | Catches uncaught exceptions invisible to DOM |
+| Layout, spacing, visual regression | `agent-view screenshot --scale 0.5` | Last resort — only tool that sees pixels (~6 000 tokens) |
+| Canvas / WebGL scene state | `agent-view scene --diff` | DOM is empty for canvas apps |
+
+**Anti-patterns to reject:**
+- Opening with a screenshot to "see the state" — use `dom --filter` or `eval` first.
+- Using `eval` when `dom --filter` answers the question.
+- Assertions that depend on transient state without `watch --until` to stabilize first.
+- "Check that it looks right" — every assertion must be a concrete pass/fail criterion. Single legitimate exception: `## Design Conformance`.
+- Inventing design reference paths (`.figma-refs/...`) when the developer did not provide them.
+- **Treating SG (or any model layer) as the sole source of truth.** Model is one of several representations; the bug may live in the gap between model and UI. The recipe must check the gap explicitly.
+
+## Workflow
+
+### Step 1 — gather context
+
+Ask in plain text (no tool calls yet):
+
+1. What was shipped or fixed?
+2. What was the original symptom or expected behavior?
+3. Any known failure mode or edge case to cover?
+4. Does this feature touch persisted structure (YAML, IndexedDB, server)? If yes → mandatory round-trip section.
+5. Which views render this state (tree, panel, list, canvas, breadcrumb)? Each named view → one UI-≡-Model invariant in Class A.
+6. Which **configured constraints** does this feature claim to respect (grid/snap, viewport, z-order/layer table, spacing tokens, theme tokens, density)? Each named constraint → one Class-E invariant. If none — say so explicitly.
+7. *(Optional)* Local design reference images? Local files only.
+
+Wait for the response before continuing.
+
+### Step 2 — derive invariants before drafting commands
+
+Before writing any `agent-view` call, list the invariants the feature must satisfy. For each, write one sentence in the form:
+> "After any sequence of allowed actions, `<measurable property>` must hold."
+
+This list seeds the `## Invariants` section. If you cannot articulate three invariants for a non-trivial feature, the feature is under-specified — ask the developer for clarification.
+
+### Step 3 — draft the recipe
+
+```markdown
+# Verify: <feature or fix name>
+
+Generated: <date>
+Scope: <one sentence>
+
+## Repro Steps
+1. <Exact starting state>
+2. <Action(s) that trigger the behavior under test>
+
+## Narrowed Signal
+`<agent-view command>` must return `<expected value>`.
+
+## Invariants
+<!-- Required. List each invariant the feature must maintain. -->
+
+- **A1 (UI≡Model — <view name>):** `<eval expression that returns {model: N, dom: M, match: bool}>` must return `match: true`.
+- **A2 (Hierarchy):** For each model node with `parentId === X`, its UI row must be a DOM-descendant of the UI row of `X`.
+- **B1 (Round-trip):** After `location.reload()`, the projected signature `<projection>` is identical to the pre-reload signature.
+- **B2 (No silent wrap-shift):** After `<wrap-creating action>`, `getWorldTransform(child).x === origWorldX(child)` for every wrapped child.
+- **C1 (Single undo):** After `<action>`, `commandHistory.canUndo === true` and one `undo()` produces a signature identical to the pre-action signature.
+- **D1 (No phantoms):** For each visible UI row of kind `<X>`, there exists exactly one model node it resolves to via its `nodeId` data-attribute (or the equivalent identifier).
+- **E1 (Config conformance — <constraint name>):** Every rendered `<entity>` must satisfy `<conforms(rendered, configValue)>`, where `<configValue>` is read live from `<config source>` (do not hardcode). `offCount: 0` is required.
+
+## Discipline
+
+1. A failed `Expected:` line is FAIL, not "actually fine".
+2. UI-vs-model mismatches are the bug; confirm by ancestry/bbox before dismissing.
+3. Every `node.field` read in eval must be sentinel-checked (`isFinite` / `!== undefined`).
+4. No hardcoded literal IDs; resolve by role at runtime.
+5. Reload checkpoint is mandatory when the feature touches mutable structure.
+6. Report `pass / fail / requires_visual_review` per step; failure prose belongs in the bug report only.
+7. Do not pre-bake `requires_visual_review` as the planned status of a step. Every step ships with an executable `agent-view` path (at minimum a console-error gate around the action). The executor sets `requires_visual_review` only after a real attempt fails for a recorded reason.
+
+## Evidence Commands
+
+### 0. Setup — capture baseline signature
+```bash
+agent-view eval "<signature expression — projection of all structural fields>"
+```
+Stash the output as `BASELINE_SIG`.
+
+### 1. <What this proves>
+```bash
+agent-view <command>
+```
+Expected: <concrete criterion>
+Cost: ~<N> tokens
+
+### 2. ... (one per action / invariant pair)
+
+### N. Round-trip checkpoint (if applicable)
+```bash
+agent-view eval "location.reload()"
+# wait for app to come back
+agent-view eval "<same signature expression as step 0>"
+```
+Expected: identical to `BASELINE_SIG` after the action's expected effect is accounted for. Diff any drift.
+
+## Positive-Case Assertions
+- [ ] <criterion>
+
+## Regression Checks
+- [ ] <adjacent flow> — `agent-view <command>` → `<expected>`
+
+## Design Conformance
+<!-- Optional. Include ONLY if developer provided design refs. -->
+
+| Step Label | Screenshot Command | Expected Reference |
+|---|---|---|
+| <area name> | `agent-view screenshot --crop "<area>" --scale 0.5` | `<absolute path>` |
+
+Tolerance: `normal`.
+
+## Anti-patterns avoided
+- <recipe-specific traps>
+```
+
+### Step 4 — save the file
+
+Determine a kebab-slug. Save to `.claude/verify-recipes/<slug>.md`. Create the directory first.
+
+Confirm the path to the developer.
+
+## Worked example: "added group component to scene editor"
+
+**Developer input:**
+> Added a group component that wraps multiple scene elements. Ctrl+G groups selected elements; Ctrl+Shift+G ungroups. Groups appear in the left tree panel as collapsible nodes. Groups are persisted in YAML.
+
+**Recipe excerpt (Invariants + Round-trip — the parts that catch the bugs construction-only recipes miss):**
+
+```markdown
+## Invariants
+
+- **A1 (UI≡Model, tree count):**
+  ```
+  agent-view eval "var sg=window.__editorCore.sceneGraph;var modelCount=0;sg.nodes.forEach(function(n){if(n.componentType==='group')modelCount++});var domCount=[...document.querySelectorAll('[role=treeitem]')].filter(function(e){return e.textContent.includes('Группа')}).length;JSON.stringify({modelCount:modelCount, domCount:domCount, match:modelCount===domCount})"
+  ```
+  must return `match: true`.
+
+- **A2 (Tree hierarchy):**
+  ```
+  agent-view eval "var sg=window.__editorCore.sceneGraph;var violations=[];sg.nodes.forEach(function(n,id){if(n.componentType==='group'){n.childrenIds.forEach(function(cid){var domChild=document.querySelector('[data-node-id=\"'+cid+'\"]');var domParent=document.querySelector('[data-node-id=\"'+id+'\"]');if(domChild&&domParent&&!domParent.contains(domChild))violations.push({c:cid,p:id})})}});JSON.stringify({violations:violations.length})"
+  ```
+  must return `violations: 0`.
+
+- **B1 (Round-trip after Ctrl+G + reload):**
+  Capture signature, dispatch Ctrl+G, capture signature, reload, capture signature. The post-reload signature must equal the post-Ctrl+G signature *projected to the persisted fields*. Drift in `transform.x` of any wrapped child means the wrap path did not normalize coords.
+
+- **B2 (No silent wrap-shift):**
+  Before Ctrl+G: capture `getWorldTransform(child).x` for each leaf. After Ctrl+G: re-capture. Difference must be 0 (within float epsilon). Non-zero means the wrap action shifted the child in world space — a regression.
+
+- **C1 (Single undo):**
+  After Ctrl+G, `commandHistory.canUndo === true`. After one `undo()`, signature equals pre-Ctrl+G signature exactly.
+
+- **D1 (No phantom group rows):**
+  Same eval as A1; if the result is `modelCount: 1, domCount: 2`, that is a phantom-row bug. Confirm by `agent-view eval "[...document.querySelectorAll('span')].filter(e=>e.textContent==='Группа'&&e.children.length===0).map(e=>{var r=e.getBoundingClientRect();return{x:r.x,y:r.y}})"` — two adjacent rows in the same column = phantom.
+```
+
+This single example pair (A1 + D1 + B1 + B2) catches the three bugs from the 4.7 grouping session that the construction-only recipes missed.