baldart 4.89.1 → 4.92.0

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

@@ -1,7 +1,7 @@
 ---
 name: e2e-review
 effort: medium
-version: 1.0.0
+version: 1.2.0
 description: >
   Deterministic, BLOCKING end-to-end review run after a feature is implemented.
   Combines functional E2E (Playwright spec written by `coder`, executed via
@@ -181,10 +181,18 @@ system constraints into a machine-readable verification plan.
        }
      ],
      "non_functional_checks": ["loads in < 2s on slow 3G"],
-     "mockup_refs": [{"route": "/dashboard", "level": "local", "path": "mockups/dashboard.png"}]
+     "mockup_refs": [{"route": "/dashboard", "level": "local", "path": "mockups/dashboard.png"}],
+     "tablet_in_scope": false
    }
    ```
 
+5. **Tablet-in-scope detection (deterministic).** Set `tablet_in_scope: true` when
+   the card's title, `acceptance_criteria[]`, `scope`, or `requirements[]` mention
+   `tablet` (case-insensitive) or an explicit breakpoint in the 768–1024px band.
+   This drives the optional third viewport capture (Phase 3) and the tablet
+   responsive pass (Phase 4 step 2c). Default `false` — the tablet lane is
+   scope-driven, not unconditional (cost discipline).
+
 ---
 
 ## Phase 2 — Mockup Source Cascade (4 levels)
@@ -227,8 +235,17 @@ directory alongside its YAML:
 
 **Structural source (route-free ground truth).** Independently of the image, record a
 `structural_source` for the route when the mockup is **code**:
-- `links.design` is an `.html` file → `structural_source = { level: "html", mockup_path:
-  "<abs html path>" }`.
+- `links.design` is an `.html` file → FIRST probe it for an encoded Claude Design
+  offline bundle: run `node .framework/framework/scripts/extract-mockup-design.mjs
+  --input <abs html path> --out .baldart/e2e-review/<CARD-ID>/mockups/_src/` (always
+  exits 0, one JSON line on stdout). On `status: "ok"` the decoded JSX/CSS is the
+  richer ground truth → `structural_source = { level: "design_src", design_src_dir:
+  ".baldart/e2e-review/<CARD-ID>/mockups/_src/" }`. On `status: "no-code"` /
+  `"skipped"` the raw markup is still diffable → `structural_source = { level:
+  "html", mockup_path: "<abs html path>" }`. **Never leave an `.html` mockup with no
+  `structural_source`** — a decode failure downgrades the source, it does not drop
+  the structural lane (that was the handoff gap that let an HTML mockup skip Phase
+  2.7 entirely).
 - `links.design_src` is set / `mockups/_src/` exists (finished Claude Design CODE, v4.75)
   → `structural_source = { level: "design_src", design_src_dir: "<abs dir>" }`.
 This feeds Phase 2.7 (`markup-fidelity-verifier`) and is what makes per-card fidelity
@@ -258,6 +275,35 @@ If none of (a)–(c) apply (no mockup, no design system):
 
 The cascade output is appended to the plan under `mockup_refs[]`.
 
+### Phase 2 closing step — Lane Matrix (verification-coverage ledger)
+
+SSOT: `design-system-protocol.md` § "Route-Independent Fidelity & Coverage
+Obligation" → 6. Verification-Lane Ledger. After the cascade, derive the
+**planned lanes** per route and persist them into `plan.json` under `lanes`:
+
+```json
+"lanes": {
+  "/dashboard": {
+    "structural":     "planned",   // iff a structural_source was recorded
+    "visual_desktop": "planned",   // iff mockup_source.level ∈ {figma, local, compliance-only}
+    "visual_mobile":  "planned",   // iff the route is renderable-in-plan and not marked desktop-only
+    "visual_tablet":  "planned",   // iff plan.tablet_in_scope == true (same renderability condition)
+    "quality":        "planned",   // iff a quality oracle exists (has_design_system OR ui_guidelines)
+    "functional":     "planned"    // iff ≥1 scenario touches the route
+  }
+}
+```
+
+A lane that does not meet its condition is recorded `"not_planned"` (it will never
+be asserted). As each later phase runs, update the route's lane in the state
+directory to `"ran"` or `"skipped:<authorized reason>"` — this ledger is what
+Phase 5 step 0 reconciles. The authorized skip reasons are ONLY:
+`pixel_diff_below_threshold` (visual pre-filter passed — the comparison DID run),
+`render_unavailable_structural_covered` (Phase 3.8 outcome on a code-form mockup),
+`no_quality_oracle`, `harness_render_fidelity_guard`, `desktop_only_route`
+(responsive passes), `quality_prefilter_skip` (Phase 4b gate). Anything else left
+un-run is an under-run and blocks (Phase 5 step 0).
+
 ---
 
 ## Phase 2.7 — Structural Fidelity (route-free, runs BEFORE the browser)
@@ -278,6 +324,20 @@ For each such route:
 1. **Resolve the implementation files** for the route from the diff / the card's File
    Ownership Map (the `*.tsx` / `*.css` / `*.module.css` / `*.scss` / `*.svelte` / `*.vue`
    the card touched under `${paths.app_dir}` / `${paths.components_root}`).
+1b. **Deterministic pre-gate (structural-compare.mjs — signals, not verdicts).** Run:
+
+   ```bash
+   node .framework/framework/scripts/structural-compare.mjs \
+     --mockup <structural_source dir|file> --impl <implementation files> \
+     > .baldart/e2e-review/<CARD-ID>/structural-signals-<route-slug>.json
+   ```
+
+   One JSON line (`match | divergence | skipped` + graded-confidence findings). The
+   signals do NOT replace the verifier (a regex signature cannot see grids/landmarks
+   owned by composed primitives — necessary, not sufficient) and a `match` never
+   authorizes skipping step 2. They are **focus hints**: pass them to the verifier
+   below so it confirms or dismisses each deterministic signal explicitly instead of
+   rediscovering the obvious. Script errors fail open (`skipped`).
 2. **Invoke `markup-fidelity-verifier`** (input contract in
    [`markup-fidelity-verifier.md`](../../agents/markup-fidelity-verifier.md)):
 
@@ -295,7 +355,8 @@ For each such route:
        "mockup_source": { ...the route's structural_source (html | design_src)... },
        "implementation_files": [ ...abs paths the card touched for this route... ],
        "tolerance": "<from config>",
-       "resolved_orphans": [ ...from the card's UI Element Inventory, as in Phase 4... ]
+       "resolved_orphans": [ ...from the card's UI Element Inventory, as in Phase 4... ],
+       "deterministic_signals": { ...the structural-compare.mjs output from step 1b... }
      }
    ```
 3. **Parse the JSON strictly** (same discipline as Phase 4). On malformed output log
@@ -360,9 +421,19 @@ capture the result + screenshots per route.
          path: ".baldart/e2e-review/<CARD-ID>/screenshots/<route-slug>@mobile.png",
          fullPage: true
        });
+       // Tablet — ONLY when plan.tablet_in_scope == true (Phase 1 step 5).
+       await page.setViewportSize({ width: 768, height: 1024 });
+       await page.goto(route);
+       await page.waitForLoadState("networkidle");
+       await page.screenshot({
+         path: ".baldart/e2e-review/<CARD-ID>/screenshots/<route-slug>@tablet.png",
+         fullPage: true
+       });
      Both screenshot paths are consumed by the visual-fidelity-verifier in
      Phase 4 — do not change them. 375px is the canonical small-screen audit
-     width (design-system-protocol Reference Tables); it is fixed, not a config key.
+     width and 768px the canonical tablet audit width (design-system-protocol
+     Reference Tables); they are fixed, not config keys. Omit the tablet block
+     entirely when `tablet_in_scope` is false.
    - For OTP-driven personas (test_plan.test_credentials.auth_method == "otp"),
      use `await page.pause()` between phone-entry and code-entry. Document
      the manual step in a test.step block.
@@ -470,10 +541,18 @@ still wrong).
 For each `route` in `plan.routes[]`:
 
 1. **Pre-filter with pixel-diff** (optimization to control Vision cost):
-   - When `mockup_source.level in {figma, local}`, run a pixel-level diff
-     (any cheap library: `pixelmatch`, `looks-same`, or even ImageMagick's
-     `compare -metric AE`) between the implementation screenshot and the
-     mockup. Pass `pixel_diff_threshold` from config (default `0.02` = 2%).
+   - **1a-pre. Viewport-dimension validation (BEFORE any diff).** Compare the
+     implementation screenshot's pixel WIDTH with the mockup image's (±5px for
+     rounding). On mismatch, the pixel-diff is meaningless — a diff computed
+     across different widths can land under the threshold while hiding a real
+     misalignment (the false-negative channel), or blow to 100% noise. Do NOT
+     run the pre-filter: log `viewport_dimension_mismatch (<impl>w vs <mock>w)`
+     in `gaps[]` and go DIRECTLY to step 2 (the Vision comparison judges
+     content, not pixel alignment). Never resize either image to force the diff.
+   - When `mockup_source.level in {figma, local}` (and dimensions validated), run
+     a pixel-level diff (any cheap library: `pixelmatch`, `looks-same`, or even
+     ImageMagick's `compare -metric AE`) between the implementation screenshot
+     and the mockup. Pass `pixel_diff_threshold` from config (default `0.02` = 2%).
    - If the diff is **below** the threshold, skip the Vision call for this
      route and record an empty findings array with
      `pre_filter: "pixel_diff_below_threshold"`. This is the primary
@@ -561,6 +640,14 @@ For each `route` in `plan.routes[]`:
    desktop-only in the plan. Cost is ~one extra verifier call per route — measured
    marginal (~0.3% of a card run) because the 375px screenshot is lighter than the
    1440px one and only renderable routes incur it.
+2c. **Tablet responsive-integrity pass** *(only when `plan.tablet_in_scope ==
+   true`)*. Same contract as step 2b with the `<route-slug>@tablet.png`
+   screenshot, `"viewport": { "width": 768, "height": 1024 }` and
+   `viewport_role: "tablet"`. This closes the "responsive middle" gap: a card
+   whose ACs promise tablet behaviour (the 768–1024px band) was previously
+   verified only at 1440px + 375px, so a grid that collapses at the wrong
+   breakpoint hid between the two audited widths. Findings are tagged
+   `viewport_role: "tablet"` and deduplicate alongside the other passes.
 3. **Parse the agent's JSON response** strictly. If the response is malformed
    or contains prose outside the JSON, log
    `verifier_protocol_violation` in `gaps[]` and treat the route's findings
@@ -596,7 +683,24 @@ mockup) **and `mockup_source.level == "harness-render"` per-primitive PNGs from
 arrive here, NEVER at Phase 4 fidelity). Skip a route only when no screenshot was
 captured, or when BOTH `features.has_design_system: false` AND
 `${paths.ui_guidelines}` is unset (no quality oracle at all — log
-`no_quality_oracle` in `gaps[]`). **i18n note:** a harness PNG flagged
+`no_quality_oracle` in `gaps[]`), or on the **quality pre-filter** below.
+
+**Quality pre-filter skip (authorized lane skip).** When ALL of these hold for a
+route, skip the critic and mark the route's quality lane
+`skipped:quality_prefilter_skip` in the Lane Matrix:
+- `features.has_design_system: true` (the surface is built from a governed
+  registry), AND
+- the route's structural lane (Phase 2.7) ran with ZERO gating findings, AND
+- the route's desktop visual pass was pre-filtered clean
+  (`pixel_diff_below_threshold` — the render is pixel-faithful to an
+  APPROVED mockup).
+Rationale: quality scoring is advisory-leaning by calibration
+(`design-system-protocol.md` § Gating philosophy), and a render that is both
+structure- and pixel-faithful to a user-approved mockup composed of governed
+primitives has no room for a *gating* quality finding — the critic spawn is pure
+cost there. **Never apply this skip to `harness-render` PNGs** (isolated quality
+IS their purpose) or when the route has no mockup (`level: skip` — the critic is
+then the only design oracle). **i18n note:** a harness PNG flagged
 `i18n-incomplete` (raw `t()` keys rendered — no provider) is passed with that
 disclaimer so the critic does not raise false `typography`/`hierarchy` findings on
 placeholder text.
@@ -645,6 +749,23 @@ For each such `route`:
 **Goal**: combine functional + visual findings into a single verdict using
 the canonical severity taxonomy from `visual-fidelity-verifier.md`.
 
+0. **Lane-coverage assertion (runs FIRST — before any verdict math).** SSOT:
+   `design-system-protocol.md` § "...→ 6. Verification-Lane Ledger". Reconcile
+   the Lane Matrix from Phase 2 against what actually executed: every
+   route×lane marked `"planned"` must now be `"ran"` or
+   `"skipped:<authorized reason>"` (the closed reason set from the Phase 2
+   closing step). For every planned lane still `not_run`, synthesize a
+   **`verification-coverage-gap`** finding (Critical, `source: "coverage"`,
+   `route`, `lane`, `description: "planned lane never executed"`). Like
+   `coverage-gap`, it is NOT fixable by an agent — it bypasses the Phase 5b
+   self-heal loop and maps to `blocked`. This is the global guard against the
+   FEAT-0064 under-run (a "fidelity review" in which the visual + quality
+   verifiers were never spawned and the verdict recorded nothing): a lane
+   under-run can never again surface as a pass. There is NO self-served
+   "accepted (harness limit)" verdict — accepting an un-run lane requires the
+   explicit override path (manual mode, human reason) or the caller's
+   escalation (programmatic mode returns `blocked`).
+
 1. **Compose** the `findings[]` array:
    - **Structural findings** from Phase 2.7 (`source: "structural"`) — route-free
      code-structure divergence (`markup-fidelity-verifier`).
@@ -654,12 +775,15 @@ the canonical severity taxonomy from `visual-fidelity-verifier.md`.
      orchestrator-synthesized `coverage-gap` (Phase 4 step 1c — a required check that
      could not run at all).
    - Design-quality findings from Phase 4b (`source: "design-quality"`).
+   - Coverage findings from step 0 (`source: "coverage"` —
+     `verification-coverage-gap`).
    - Each finding carries: `severity`, `category` (or `dimension` for
      design-quality), `source`, `route`, `description`, `expected`, `actual`,
      `fix_hint`, `evidence`, `ds_drift_code`, `confidence`. All sources
      share the **same canonical severity taxonomy**, so the tolerance filter in
-     step 2 applies to them uniformly — no per-source special-casing. (`coverage-gap`
-     and `data-state-mismatch` are Critical and gate in every tolerance.)
+     step 2 applies to them uniformly — no per-source special-casing. (`coverage-gap`,
+     `verification-coverage-gap` and `data-state-mismatch` are Critical and gate in
+     every tolerance.)
 2. **Apply tolerance filter** based on
    `features.e2e_review.fidelity_tolerance`:
    - `strict` (DEFAULT): Critical + Major + Minor all gate. Additionally,
@@ -680,12 +804,13 @@ applies only when `verdict == "blocked"` AND `iteration < max`.
 
 For each iteration:
 
-0. **`coverage-gap` findings bypass the loop.** A `coverage-gap` is not fixable by any
-   agent (the route still will not render — it is a harness/data limitation, not a code
-   defect). Do NOT spawn a fixer for it. It keeps the verdict `blocked` and flows straight
-   to the override path below (programmatic mode returns `blocked`; `/new` escalates it to
-   a follow-up card). If `coverage-gap` is the ONLY gating finding, skip the rest of this
-   loop entirely.
+0. **`coverage-gap` and `verification-coverage-gap` findings bypass the loop.** Neither is
+   fixable by any agent (`coverage-gap`: the route still will not render — a harness/data
+   limitation; `verification-coverage-gap`: a planned lane never executed — an
+   orchestration failure, not a code defect). Do NOT spawn a fixer for either. They keep
+   the verdict `blocked` and flow straight to the override path below (programmatic mode
+   returns `blocked`; `/new` escalates to a follow-up card). If coverage findings are the
+   ONLY gating findings, skip the rest of this loop entirely.
 
 1. **Route the remaining gating findings to the right fixer by `source`**, then spawn the
    fixer(s). **Fidelity is UI-scoped**: `source == "structural"` (layout/grid/order —
@@ -713,7 +838,8 @@ For each iteration:
 
      ## Rules
      - File ownership: stay within the card's allowed file set (see
-       /tmp/batch-tracker-<FIRST-CARD-ID>.md ## File Ownership Map).
+       "$(git rev-parse --git-common-dir)/baldart/run/batch-tracker-<FIRST-CARD-ID>.md"
+       ## File Ownership Map — the durable tracker location, new/SKILL.md § Context Tracking).
      - One fix per finding. Reuse existing tokens / primitives before inventing
        new ones (cite ${paths.design_system}/INDEX.md + tokens-reference.md).
      - For a `structural` `layout-break`, match the mockup's layout exactly (e.g.
@@ -740,7 +866,8 @@ For each iteration:
 
      ## Rules
      - File ownership: stay within the card's allowed file set (see
-       /tmp/batch-tracker-<FIRST-CARD-ID>.md ## File Ownership Map).
+       "$(git rev-parse --git-common-dir)/baldart/run/batch-tracker-<FIRST-CARD-ID>.md"
+       ## File Ownership Map — the durable tracker location, new/SKILL.md § Context Tracking).
      - One fix per finding when possible. Reuse existing tokens / primitives
        before inventing new ones (cite ${paths.design_system}/INDEX.md +
        tokens-reference.md).
@@ -753,12 +880,27 @@ For each iteration:
 
    Both fixers run in `bypassPermissions` mode when called by `/new`.
 
+   **Spawn ONLY the non-empty bucket(s)** — when every gating finding is UI-scoped,
+   no `coder` is spawned (and vice versa); a fixer with an empty findings list is a
+   wasted spawn.
+
 2. **Re-run the affected verifiers**: Phase 2.7 (structural, route-free — re-run when a
    `structural` fix was applied), Phase 3 (functional), Phase 3.8 (re-render / state),
    Phase 4 (visual), and Phase 4b (quality) with fresh screenshots. Increment `iteration`.
-   (A `coverage-gap`-only block does not enter this loop — see step 0.)
-3. **Re-aggregate and re-decide** (back to Phase 5 step 1).
-4. **STOP** when `verdict == "passed"` OR `iteration == max`.
+   (A `coverage-gap`-only block does not enter this loop — see step 0.) Deliberately NOT
+   narrowed to "only the lane that failed": a fix can regress a lane that previously
+   passed, and a selectively-skipped lane would be exactly the under-run the Phase 5
+   step 0 Lane-Ledger assertion exists to block. The Phase 4 pixel-diff pre-filter and
+   the Phase 4b quality pre-filter already make a clean re-run cheap.
+3. **Re-aggregate and re-decide** (back to Phase 5 step 1), with **convergence
+   detection (v4.92.0)**: compare the new gating-finding set with the pre-fix one by
+   `(route, source, category, region)`. If the fix produced **NEW gating findings that
+   were not present before** (the fixer is regressing while fixing — the documented
+   non-convergent failure mode), do NOT burn another iteration: STOP the loop now and
+   transition to the override path with both sets in the report (`convergence:
+   "diverging"`). Shrinking-or-equal sets keep iterating normally.
+4. **STOP** when `verdict == "passed"` OR `iteration == max` OR convergence detection
+   fired (step 3).
 
 When the loop exhausts iterations and findings remain, transition to the
 **override path** below.
@@ -796,6 +938,17 @@ Write the final report to `.baldart/e2e-review/<CARD-ID>/report.json`:
     "compliance-only": 1,
     "skip": 0
   },
+  "lane_coverage": "complete" | "incomplete",
+  "lanes": {
+    "/dashboard": {
+      "structural": "ran",
+      "visual_desktop": "skipped:pixel_diff_below_threshold",
+      "visual_mobile": "ran",
+      "visual_tablet": "not_planned",
+      "quality": "ran",
+      "functional": "ran"
+    }
+  },
   "functional": {
     "scenarios_total": 5,
     "passed": 5,
@@ -908,6 +1061,7 @@ and starts from Phase 3 (skipping plan extraction and mockup cascade).
 | `quality_critic_protocol_violation` in gaps | `ui-quality-critic` returned prose mixed with JSON | Re-spawn the critic once; if persistent, surface to user (likely a model regression). Treat that route's quality findings as empty meanwhile |
 | `verifier_protocol_violation` in gaps | `visual-fidelity-verifier` returned prose mixed with JSON | Re-spawn the verifier once; if persistent, surface to user (likely a model regression) |
 | `coverage-gap` (Critical) on a route | An image-only mockup route could not be rendered in any lane and its state could not be reached | Correct by design — the gate BLOCKS instead of silently passing. Add a reach-state recipe to `.baldart/overlays/e2e-review.md` (seed / select populated context), or provide an HTML/`design_src` mockup so the route-free structural pass covers it. Never override without fixing the lane |
+| `verification-coverage-gap` (Critical) on a route×lane | A lane the Phase 2 Lane Matrix planned was never executed (verifier not spawned / phase silently skipped) — the FEAT-0064 under-run | Correct by design — an under-run blocks, never passes. Re-run the skill; if the lane keeps under-running, that is an orchestration bug to report, not a finding to override |
 | `data-state-mismatch` (Critical) on a route | Render opened an empty / wrong-tenant / error state; mockup depicts a populated state | The reach-state loop (Phase 3.8) should seed/select a populated context. If it has no recipe and cannot auto-seek, add `select_populated_context` / `seed_data` to the e2e-review overlay |
 | `markup_verifier_protocol_violation` in gaps | `markup-fidelity-verifier` returned prose mixed with JSON | Re-spawn once; if persistent, surface to user. Treat that route's structural findings as empty meanwhile |
 

package/framework/.claude/skills/new/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.3.0 — 2026-07-02
+
+- **Hot-file economy (T2.A)**: il briefing "Codebase Context" passa il baseline
+  per PATH (`/tmp/arch-baseline-<CARD-ID>.md`, guardia `[BASELINE-READ-FAIL]`) e
+  la disciplina range-read sui file > 800 righe è SSOT in
+  `code-search-protocol.md` § "Large-file read discipline" (Hot-File Map emesso
+  dal contratto terse di `codebase-architect`).
+- **Empty-scope guard (T2.B)**: Phase 2.5x + team-mode D.1.6 non invocano più
+  `new-card-review` a scope vuoto (cluster no-op misurati agents=0).
+- **verify-item.sh (T2.C)**: la Grep-verification discipline del completeness è
+  ora CODE (`scripts/verify-item.sh` — exit 2 = UNVERIFIED mai Missing);
+  composizioni shell hand-rolled per quei check = protocol violation.
+
+## 1.2.0 — 2026-07-02
+
+- **AUTONOMOUS OFF-CONTEXT DELEGATION GATE** (kickoff, pre-Phase-0): un batch
+  `-auto` viene delegato di default al motore workflow `new2` (pipeline per-card
+  off-context) quando Workflow tool + `new2.js` + skill `new2` sono presenti, il
+  batch è migration-free e non è `-auto-ship`. Driver misurato su 3 run reali:
+  turn-tax orchestrator = 53–59% dei token fatturati (contesto accumulato
+  ri-servito a ogni turno). Delega MANDATORY a condizioni verdi (no discretion,
+  come i gate Phase 2.5x/F.1.5); escape hatch `-inline`; il path classico resta
+  SSOT per interattivo / Codex / `-auto-ship` / migrazioni dichiarate.
+- Nuovo token `-inline` / `--inline` nel parser (`FORCE_INLINE`).
+- Phase 2.6: consumo additivo `lane_coverage`/`lanes` dal report `/e2e-review`
+  (`[E2E-LANE-UNDERRUN]`, niente chiusura fidelity-AC su under-run — T1.A).
+- Coarse fallback UI: binding-compliance verificata con `check-bindings.mjs`
+  (T1.A) + obbligo build-with-eyes nel briefing [UI-ONLY] (T1.B).
+
 ## 1.1.2 — 2026-07-01
 
 - Context economy: trimmed the top-level **RUNTIME PORTABILITY** citation to a one-liner (cite, don't restate — the detail lives in `runtime-portability-protocol.md`). ~470 chars off the SKILL.md core, which sits in context every turn. No behavior change.

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

@@ -1,7 +1,7 @@
 ---
 name: new
 effort: medium
-version: 1.1.2
+version: 1.3.0
 description: >
   Orchestrate a team of specialized agents to implement one or more backlog cards
   end-to-end inside a dedicated worktree, with code review, doc review, QA, and
@@ -45,7 +45,49 @@ If no card IDs are provided, ask the user which cards to implement.
 
 **Opt-in session telemetry (`-stats` / `--stats`)**: strip `-stats` / `--stats` from the args list exactly like `-full` (it is NOT a card ID), and set an internal flag `STATS=true` for this run. When present, Phase 8 additionally measures REAL token + wall-clock cost per agent role (coder, code-reviewer, …) by post-processing the session transcripts — zero model-token overhead, runs in Bash after the work is done. When absent, Phase 8 behaves exactly as before. The flag is batch-scoped and composes with `-full` (`/new FEAT-005 -full -stats`).
 
-**Autonomous run (`-auto` / `--auto`, `-auto-ship` / `--auto-ship`)**: strip these tokens from the args list exactly like `-full`/`-stats` (they are NOT card IDs). `-auto` / `--auto` sets `AUTONOMOUS=true`; `-auto-ship` / `--auto-ship` sets `AUTO_SHIP=true` AND implies `AUTONOMOUS=true`. When `AUTONOMOUS` is set the orchestrator runs the WHOLE batch without ever calling `AskUserQuestion` — every decision gate is resolved deterministically per § "AUTONOMOUS RESOLUTION RULE" below. The flags are **batch-scoped** and compose with `-full`/`-stats` (`/new FEAT-005 -full -auto`). `AUTONOMOUS` is ALSO set when the environment already signals an unattended run — env `BALDART_AUTONOMOUS`, `CI`, or `GITHUB_ACTIONS` (unify with that existing codepath: treat the env signal and the flag as the same `AUTONOMOUS` state; `AUTO_SHIP` is flag-only). **Record `AUTONOMOUS` / `AUTO_SHIP` in the Phase-0 tracker** (the recovery SSOT — write them once into `## Issues & Flags` or a dedicated tracker field; never re-derive them per turn, since a compaction would otherwise lose the run mode).
+**Autonomous run (`-auto` / `--auto`, `-auto-ship` / `--auto-ship`)**: strip these tokens from the args list exactly like `-full`/`-stats` (they are NOT card IDs). `-auto` / `--auto` sets `AUTONOMOUS=true`; `-auto-ship` / `--auto-ship` sets `AUTO_SHIP=true` AND implies `AUTONOMOUS=true`. When `AUTONOMOUS` is set the orchestrator runs the WHOLE batch without ever calling `AskUserQuestion` — every decision gate is resolved deterministically per § "AUTONOMOUS RESOLUTION RULE" below. The flags are **batch-scoped** and compose with `-full`/`-stats` (`/new FEAT-005 -full -auto`). `AUTONOMOUS` is ALSO set when the environment already signals an unattended run — env `BALDART_AUTONOMOUS`, `CI`, or `GITHUB_ACTIONS` (unify with that existing codepath: treat the env signal and the flag as the same `AUTONOMOUS` state; `AUTO_SHIP` is flag-only). **Record `AUTONOMOUS` / `AUTO_SHIP` in the Phase-0 tracker** (the recovery SSOT — write them once into `## Issues & Flags` or a dedicated tracker field; never re-derive them per turn, since a compaction would otherwise lose the run mode). Also strip `-inline` / `--inline` (sets `FORCE_INLINE=true` — the escape hatch of the delegation gate below; NOT a card ID).
+
+## AUTONOMOUS OFF-CONTEXT DELEGATION GATE (v4.90.0 — fires at kickoff, BEFORE Phase 0)
+
+Forensics on three real `-auto` batches showed the **orchestrator's own turn-tax is
+53–59% of the whole run's billed tokens** (an ever-growing accumulated context,
+replayed via `cache_read` on every one of 400–700 turns) — while the genuinely new
+tokens are a rounding error. An `-auto` run has, by definition, **no human gates**:
+exactly the case the workflow-hosted `new2` engine was built for (the entire per-card
+pipeline runs in an isolated background runtime whose output never enters this
+context). So an `-auto` batch is delegated off-context **by default**:
+
+**Delegate — invoke the `new2` skill — when ALL of these hold** (checked once, at
+kickoff, right after arg parsing):
+
+1. `AUTONOMOUS == true` AND `AUTO_SHIP == false` (the `AUTO_SHIP` deploy boundary —
+   § "AUTONOMOUS SAFETY BOUNDARY" — is implemented by THIS skill's
+   production/merge phases only; an `-auto-ship` run stays inline).
+2. `FORCE_INLINE == false` (the user did not pass `-inline`).
+3. The `Workflow` tool is available in this session AND `.claude/workflows/new2.js`
+   is linked AND the `new2` skill is available.
+4. No epic card in the batch declares `migration_plan.required: true` (cheap YAML
+   probe on the batch's `group.parent` epics). A declared migration keeps the
+   classic path — its Phase 0 step 1b owns the owner-gated apply under
+   § "AUTONOMOUS RESOLUTION RULE"; `new2`'s own migration gate is interactive.
+
+**Action**: log ONE tracker line `[DELEGATED] -auto batch → new2 engine
+(off-context): <residual args>` and invoke the `new2` skill with the SAME residual
+invocation — card IDs + `-full` + `-stats` + `effort=<level>` (its grammar is
+identical; do NOT forward `-auto`/`-auto-ship`/`-inline`, which new2 does not
+parse — new2 IS autonomous by contract). `new2` owns the run end-to-end
+(pre-flight → per-card pipeline → final review → merge → follow-up
+materialization → truthful telemetry) and this orchestrator does NOT re-run any
+phase: relay new2's final report verbatim and stop. **This delegation is
+MANDATORY when the conditions hold — no discretion** (the same no-discretion
+contract as the Phase 2.5x / F.1.5 workflow gates; running inline with the
+conditions green is a protocol violation that costs the measured 53–59%).
+
+**Else** — any condition fails (interactive run, Codex / no Workflow tool,
+`-auto-ship`, declared migration, `-inline`, missing new2) → run the classic
+inline path below exactly as written. The classic prose remains the SSOT for all
+semantics; the delegation only changes WHERE the batch executes, never what it
+does.
 
 ## Effort
 

package/framework/.claude/skills/new/references/completeness.md

@@ -10,6 +10,7 @@ Before triggering any review, you MUST verify that the coder agent implemented *
 > 1. **Quote-broken pattern.** Code-shaped tokens contain shell/regex metacharacters — a TS union literal `mode:'catalog'|'picker'`, an object key, anything with `'` `"` `|` `[]` `?` `(`. Embedding such a pattern in an `echo "=== … ===" && grep …` block or an unquoted `-E` arg breaks the shell/regex parse → the grep matches **nothing even though the code is there**. **Search literals with `rg -F '<exact string>'` (fixed-string, no regex), single-quote the WHOLE pattern, and run ONE pattern per `rg` call** — never fold the search token into a quoted header/echo composition.
 > 2. **`0 matches` ≠ absent.** A zero-match result is ambiguous (true miss vs. broken pattern / wrong file / wrong escaping). Do NOT classify an item `Missing`/`Partial` on a 0-match alone. **If the 0-match CONTRADICTS the coder completion report's claim that the item is implemented, treat it as a likely broken grep — re-confirm by reading the report's cited `file:line` (or a corrected `rg -F`) BEFORE flagging or spawning a gap-fix agent.** Never re-spawn a coder on a 0-match alone. When unsure, a targeted `Read` at the report's `file:line` is more reliable than a hand-rolled grep.
 > 3. **Binary-heuristic false-empty.** Plain `grep` decides a file is *binary* when it sees a byte it reads as non-text (a non-UTF-8 byte, an accented char under some locales) or very long lines, and then prints `Binary file … matches` / **nothing** instead of the line — so a perfectly valid source file (e.g. an 8000-line `data.ts` with accented strings) silently returns 0 matches for tokens that ARE present. The mandated `rg` does NOT have this failure mode (it searches UTF-8 and long lines fine). **Always reach for `rg -F` first; if you must use `grep`, force text mode with `grep -a`.** A 0-match from plain `grep` on a file you KNOW was just modified is almost always this artifact — switch to `rg`/`grep -a` and re-check before concluding the code is missing.
+> 4. **Canonical runner (v4.91.0 — use the SCRIPT, not hand-rolled shell).** All three guards above are CODE in `scripts/verify-item.sh` — run every per-item check through it: `bash .claude/skills/new/scripts/verify-item.sh '<exact literal>' <changed files...>` (one pattern per call; the pattern is a single argv, so metacharacters cannot break the parse). Exit `0` = FOUND (with `file:line`); exit `2` = **UNVERIFIED — not Missing**: confirm via a targeted `Read` at the completion report's cited `file:line` before classifying or spawning a gap-fixer; exit `3` = the FILES were wrong (fix the paths first). Hand-rolled `echo "===" && grep …` compositions for these checks are now a protocol violation.
 
 **Step-by-step**:
 

package/framework/.claude/skills/new/references/implement.md

@@ -135,7 +135,15 @@
    [if field is empty/missing, read PRD Section 1b from card's links.prd path]
 
    ### Codebase Context
-   [paste codebase-architect key findings: file paths, exact line numbers, type signatures, existing patterns to follow]
+   Architecture baseline: Read /tmp/arch-baseline-<CARD-ID>.md BEFORE writing any
+   code — it holds the file paths, exact line numbers, type signatures, existing
+   patterns to follow, high-risk paths, and the ## Hot-File Map (per-symbol line
+   ranges for files > 800 lines: Read those RANGES, never the whole file —
+   `code-search-protocol.md` § "Large-file read discipline"). If the baseline file
+   is missing/unreadable, report `[BASELINE-READ-FAIL] <path>` in your completion
+   report and derive the context yourself per Phase 1 — do NOT code blind.
+   [do NOT paste the baseline content here — pass the path only (§ "Context
+   economy" rule 4); inline ONLY the plan-auditor corrections/anti-patterns below]
    [include any corrections or anti-patterns flagged by plan-auditor grounding check]
 
    ### Design Reference (UI cards only — include if card has links.design)
@@ -184,7 +192,12 @@
    Only `action: new` entries (confirmed at `/prd` time) may introduce a component.
    UI scope + `features.has_design_system: true` but NO `component_bindings` → run
    the cascade below as your own reconciliation before writing code (do not assume
-   a mockup affordance is a new component).
+   a mockup affordance is a new component). **After the build, compliance is
+   VERIFIED deterministically** — run
+   `node .claude/skills/ui-implement/scripts/check-bindings.mjs --bindings-json
+   '<bindings as JSON>' --files <touched files>` (exit 3 = `binding-not-honored`,
+   Critical → one fix retry, then blocked; `/ui-implement` Step 5b is the SSOT of
+   this gate — the coarse fallback runs the same script).
 
    ### i18n constraint (include when `features.has_i18n: true`)
    No user-facing string may be hardcoded. Externalize every label through the
@@ -196,7 +209,10 @@
    curates the registry afterwards; the anti-hardcoded linter is the gate.
 
    ### [UI-ONLY] Registry-first BLOCKING pre-work (include ONLY when briefing = "ui-expert")
-   You are spawned as `ui-expert`. Before writing any UI code, you MUST complete
+   You are spawned as `ui-expert`. When the card has a mockup, your own
+   `ui-expert.md` § "Build-with-eyes" self-check contract applies (bounded
+   structural + visual self-check BEFORE returning — report its one-line
+   outcome). Before writing any UI code, you MUST complete
    the registry-first cascade defined in
    `framework/.claude/agents/ui-expert.md` § "Authoritative Style Reference —
    Registry-First Protocol" (the SSOT lives in

package/framework/.claude/skills/new/references/review-cycle.md

@@ -58,6 +58,16 @@ so it surfaces in telemetry.
   ```
   `codexScriptPath` — resolve the Codex companion path ONCE per `/new` run (glob in `references/team-mode.md` § Step D delegation) and reuse it here + at the Final, so the workflow skips its internal Haiku resolver; omit when stdout is empty (the workflow self-resolves as fallback).
 
+  **Empty-scope pre-invocation guard (v4.91.0).** If `scopeFiles` resolves EMPTY (the card's
+  committed diff has no files — e.g. its work was absorbed by a prior in-batch commit), do
+  NOT invoke the workflow: it would only schedule an empty cluster that immediately no-ops
+  (measured: two `new-card-review` runs with `agents=0, dur=0` in one real batch — a wasted
+  invocation + wake each). Log `review-cluster: SKIP (empty diff — nothing to review)` and
+  proceed to Phase 2.6. This mirrors the workflow's own internal no-op guard; the guard
+  belongs HERE too so the invocation itself is saved. (An empty diff on a card that was
+  supposed to change code is suspicious — cross-check `alreadyCommitted` / the tracker
+  before treating it as fine.)
+
   The workflow runs Simplify + Codex (agent-launched, code-reviewer fallback) + qa-sentinel + security,
   FP-checks each specialist's own findings, then the **domain writer applies its VERIFIED findings**
   (canonical writer map v4.26.1: `security` → `security-reviewer`; `code`/`perf`/`migration`/`test`/
@@ -228,10 +238,22 @@ When the gate above passes, the orchestrator invokes `/e2e-review` in
      "findings": [ ... ],
      "ds_drift_codes": [ "DS_TOKENS_DRIFT" | "DS_COMPONENT_STALE" | "DS_INDEX_DRIFT" ],
      "gaps": [ ... ],
+     "lane_coverage": "complete" | "incomplete",
+     "lanes": { "<route>": { "<lane>": "ran|skipped:<reason>|not_planned" } },
      "transcript_paths": [ ... ]
    }
    ```
 
+   `lane_coverage` / `lanes` (additive, e2e-review ≥1.1.0): the skill's own
+   Lane Matrix reconciliation (`design-system-protocol.md` § Verification-Lane
+   Ledger). An unauthorized lane under-run already surfaces as a
+   `verification-coverage-gap` finding → `status: "blocked"`, so no NEW gating
+   logic is needed here — but log the field in the tracker line, and treat a
+   `"passed"` accompanied by `lane_coverage: "incomplete"` (possible only from
+   an older skill version or a protocol violation) like the suspicious-skip
+   case: record `[E2E-LANE-UNDERRUN]` in `## Issues & Flags` and do NOT close
+   fidelity ACs on it.
+
 #### Gating logic (BLOCKING)
 
 | `status` from `/e2e-review` | Orchestrator action |
@@ -257,7 +279,7 @@ of the skill (skipping plan extraction and mockup cascade).
 Append to `## Current Card` and (on completion) carry into `## Completed Cards`:
 
 ```
-e2e-review: <status> | iterations: <N> | findings: <X critical, Y major, Z minor> | drift: [<codes>] | tolerance: <strict|balanced|lenient>
+e2e-review: <status> | iterations: <N> | findings: <X critical, Y major, Z minor> | drift: [<codes>] | lanes: <complete|incomplete> | tolerance: <strict|balanced|lenient>
 ```
 
 #### Out of scope for this phase

package/framework/.claude/skills/new/references/team-mode.md

@@ -209,6 +209,10 @@ After ALL agents in the group complete successfully:
      Map slice), `qaTier` (`full` iff the GROUP max is `deep`/risk-escalated per D.1.5 — mirrors D.4's
      group predicate; else `light`), `hasSecurityFiles` (scope ∩ `paths.high_risk_modules`),
      `runSimplify:true`, `archBaselinePath` (`/tmp/arch-baseline-group-<FIRST-CARD-ID>.md`).
+     **Empty-scope pre-invocation guard (v4.91.0, mirrors Phase 2.5x):** drop from `cards[]` any card
+     whose `scopeFiles` resolves EMPTY (absorbed by a prior in-batch commit — cross-check the tracker),
+     and if the WHOLE wave's `cards[]` ends up empty, do NOT invoke the workflow at all — log
+     `D.1.6: SKIP (empty wave scope — nothing to review)` instead of scheduling a no-op cluster.
      ```
      Workflow({ name: 'new-card-review', args: {
        cards: [ …one entry per non-trivial card in the wave… ],

package/framework/.claude/skills/new/scripts/verify-item.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# verify-item.sh — deterministic single-item grep verification for /new Phase 2.5
+# (T2.C, framework v4.91.0). Encodes the "Grep-verification discipline" of
+# completeness.md as CODE, so the three prose-documented failure modes cannot
+# recur by hand-rolled shell composition:
+#   1. quote-broken pattern  → the pattern is ONE argv, searched fixed-string (-F),
+#      never interpolated into an echo/regex composition.
+#   2. `0 matches` ≠ absent  → exit 2 prints UNVERIFIED, never "Missing" — the
+#      caller MUST confirm via a targeted Read before classifying/spawning a fixer.
+#   3. binary false-empty    → rg searches NUL/UTF-8 files as text; the grep
+#      fallback forces text mode with -a.
+#
+# Usage:   verify-item.sh '<exact literal pattern>' <file> [<file> ...]
+# Output:  one line — "FOUND <n> match(es); first: <file>:<line>"  or
+#          "UNVERIFIED: 0 matches — NOT proof of Missing; Read the completion
+#           report's cited file:line before classifying"
+# Exit:    0 = found · 2 = unverified (0 matches) · 3 = usage/no readable files
+#          (never 1, so a caller cannot confuse it with grep's no-match code)
+
+set -u
+
+if [ "$#" -lt 2 ]; then
+  echo "usage: verify-item.sh '<exact literal pattern>' <file> [<file> ...]" >&2
+  exit 3
+fi
+
+pattern="$1"; shift
+
+files=()
+for f in "$@"; do
+  [ -f "$f" ] && [ -r "$f" ] && files+=("$f")
+done
+if [ "${#files[@]}" -eq 0 ]; then
+  echo "UNVERIFIED: no readable files among the $# provided — verify the paths before classifying anything"
+  exit 3
+fi
+
+if command -v rg >/dev/null 2>&1; then
+  # rg: fixed-string, line numbers, filename always (-H), NUL-safe text search.
+  out="$(rg -F -n -H --no-messages -- "$pattern" "${files[@]}" 2>/dev/null)"
+else
+  # grep fallback: -a forces text mode (binary-heuristic guard), -F fixed-string.
+  out="$(grep -a -F -n -H -- "$pattern" "${files[@]}" 2>/dev/null)"
+fi
+
+if [ -n "$out" ]; then
+  n="$(printf '%s\n' "$out" | wc -l | tr -d ' ')"
+  first="$(printf '%s\n' "$out" | head -1 | cut -d: -f1,2)"
+  echo "FOUND ${n} match(es); first: ${first}"
+  exit 0
+fi
+
+echo "UNVERIFIED: 0 matches for the pattern in ${#files[@]} file(s) — NOT proof of Missing (completeness.md discipline #2): Read the completion report's cited file:line (or re-check the pattern) BEFORE classifying or spawning a gap-fixer"
+exit 2