task-pipeline-skill 1.88.1 → 1.89.1

package/plugins/task-pipeline/skills/task-pipeline/references/browser.md

@@ -28,6 +28,7 @@ which is how a run says *I checked the browser* and means *I ran the unit tests*
 - Sessions, and why an agent needs them
 - Reading a look vs gating on one
 - "Tested in a browser" is three different claims
+- The visual half — pixels against intent, under a contract
 - Getting past a login, and past a backend
 - When the look finds something: debugging the spec that missed it
 - Evidence a reader can open
@@ -48,7 +49,9 @@ Three consequences the doctrine rests on:
 
 - **A look costs a page of text and no vision model.** This is why the pipeline can ask
   for one at three stages without the cost being an argument. A `screenshot` exists in
-  both channels and *is* pixels — take one for a human to look at, not for you to read.
+  both channels and *is* pixels — in the functional look, take one for a human, not for
+  you to read. Reading pixels against the design's intent is a different check with its
+  own contract: *The visual half*, below.
 - **The ref is a fact about the page as rendered**, so `click e12` after a snapshot is
   deterministic in a way a coordinate never is.
 - **A ref that no longer resolves is a finding, not an error to retry past.** The element
@@ -125,7 +128,7 @@ commonest way a run reports a green it does not have.
 
 | | What it is | What it proves | Where it counts |
 |---|---|---|---|
-| **The look** | an agent driving a page: open, snapshot, console, network | that this surface renders, right now, and what the browser said while it did | the **look**, stage 6 — recommended, never a gate |
+| **The look** | an agent driving a page: open, snapshot, console, network | that this surface renders, right now, and what the browser said while it did | the **functional look**, stage 6 — recommended, never a gate. Its **visual half** is a gate on a `flagship`, `product` or `ad` surface — *The visual half*, below |
 | **The spec suite** | `playwright test` — the **test runner** | that the assertions someone wrote still hold, on the paths someone thought to write | the **suite** half of the stage-6 gate, counted with every other test |
 | **The library** | `require('playwright')` — `chromium`/`firefox`/`webkit`, `devices`, `request`, `selectors` | whatever your own script asserts; it is an automation API, not a test framework | wherever the project already runs it |
 
@@ -155,6 +158,95 @@ in the claim's own state (the initial screenshot closes nothing about opened/err
 a suite PASS closes no look claim; a toggle owes its full cycle; no browser channel
 is NOT_RUN with the reason.
 
+## The visual half — pixels against intent, under a contract
+
+Everything above reads the **accessibility tree**: it proves the surface renders and the
+browser stayed quiet. It cannot say whether the surface looks like what was designed —
+the wrong weight on a heading, a card that lost its spacing at 200 % text, a dark theme
+that drops a border, a frame that drifted from the Figma it was built from. That is a
+different question, and asking it of a snapshot is how a run reports *it looks right*
+having read no pixels at all. The **functional look** and the **visual half** are two
+checks; neither discharges the other.
+
+**When it runs, and when it gates — by the brief's `surface_class`**
+([`stages.md`](stages.md) → stage 0, *The surface class*):
+
+| Class | Visual half at stages 5–6 | Human pass at stage 10 |
+|---|---|---|
+| `flagship` | **gate** — full matrix, pairwise across every axis, judge items per the full rubric | **gate** — the approved contact sheet |
+| `product` | **gate** — every state, the mandatory pairs; pairwise holes reported | **gate** — the approved contact sheet |
+| `ad` | **gate** — the ad rubric profile and the safe zones | **gate** — the approved contact sheet |
+| `internal` | recommended — the project linter is the floor; a sheet, if made, is checked for honesty | the functional look closes it |
+
+It gates only where the stage-3 VISUAL track ran. A recorded refusal (*«без дизайна»*,
+`Mode: declined`) turns the visual half into the functional look plus the linter, said in
+the close-out — the same rule as every other refusal in the pipeline.
+
+**The checks run cheapest first, and the person last:**
+
+1. **Deterministic.** The project linter — `python3 scripts/visual_gate.py lint <dir>`,
+   which runs sheleg-design's `--lint` where it is installed and answers **NOT_RUN (exit 3)**
+   where it is not — plus axe or Lighthouse, the token check, the type checker. An S1
+   finding blocks, whatever anyone says about the picture later.
+2. **Regression** against the approved baseline, where one exists (`toHaveScreenshot`, or
+   the platform's snapshot test).
+3. **The matrix.** One frame per `SCR-NN` state the screen map lists (default, loading,
+   empty, error, offline, long-content, keyboard-up, first-run — the ones that apply),
+   across viewport × theme × text size × locale: **pairwise coverage** — every value of one
+   axis meets every value of every other in some frame — plus the **mandatory pairs**
+   (dark × large text, RTL × narrow). Never the full cross product: every state at every
+   combination of every axis value is hundreds of frames, and nobody reads them. Seed the
+   worst-case data first (`break-ui`, [`companion-skills.md`](companion-skills.md) →
+   *Visual lanes*) so the frames show long names and empty lists, not the demo account.
+4. **Each frame carries its capture record** — revision, route, state, viewport, locale,
+   theme, motion, captured-at, source — and is disqualified, not passed, when it is blank,
+   stale, of the wrong route or state, or taken before the fonts rendered. This is
+   sheleg-design's visual-review contract; the pipeline only refuses a frame without it.
+   Where a Figma frame or an approved baseline exists, the frame is **diffed against it**,
+   and a failing diff is never a PASS the run writes: either the build drifted, or the
+   person approves a new baseline.
+5. **The rubric**, read by a judge that is not the agent that built the surface: a
+   checklist per task, never a single score; pairwise only against the approved
+   reference and in both orders; three samples, and disagreement is `uncertain`, which
+   goes to the person rather than to a coin. **A judge item (J) is `NOT_ASSESSED` until a
+   labelled set exists and the judge's agreement with it is measured** — a verdict from an
+   uncalibrated judge is a guess with a format. A gate item (G) is deterministic and the
+   judge never overrides its FAIL. Every FAIL is a triple: *region → defect → fix*.
+6. **One human pass** over the contact sheet. Approval makes its frames the next baseline.
+
+**The contact sheet is the one surface the person reviews**, and its data is
+`templates/browser-claims.json` — the same file, **not a second schema**. A look row
+that carries `axes` is a frame: `axes{viewport,theme,text,locale}`, `capture{revision,
+route,motion,captured_at,source}`, `figma_frame`, `baseline`, `diff`, `rubric[]`. The file
+names its `surface`, `revision`, `review_rounds`, `approved_by` and `approved_at`. The
+viewing page is a self-contained local HTML beside the frames — a full document, `<meta
+charset="utf-8">`, no CDN. **Frames and the HTML stay out of git; the JSON goes in.**
+
+```bash
+python3 scripts/visual_gate.py sheet design/review/contact-sheet.json \
+    --class product --artifact-root design/review --states SCR-01/default,SCR-01/empty
+# stage 10 adds --require-approval
+```
+
+Exit `0` PASS · `1` FAIL · `2` unreadable · `3` NOT_RUN — a frame that did not run makes
+the whole verdict NOT_RUN, never PASS. **On a gated class NOT_RUN stops the stage and
+asks**: connect a capture channel, or the operator accepts the surface as `unverified`,
+recorded in the brief and named in the close-out. It is never reported around, which is
+the failure `DEC-0004` kept the functional look ungated to avoid; `DEC-0006` gates the
+visual half on these classes and keeps that exit open in words.
+
+**Two rules keep the loop from becoming the work** ([`loop-guard.md`](loop-guard.md) →
+*The re-render loop*): a re-render budget of **one, two at most**, after which a failing
+item goes to the person as `unresolved`; and **only external, specific feedback** starts a
+round — a linter line, a diff, an audit item, a triple — never "look again". Each return
+from the person adds one to `review_rounds` and one `review:` line to the run ledger, so the
+number of passes a surface took is measured, not remembered.
+
+**Native surfaces are not web surfaces.** A web render styled as a phone is a mockup. A
+native screen's frames come from a simulator or a device (XCUITest snapshots, Compose
+screenshot tests) and its accessibility from the platform's own audit; with neither, the
+native rows stay `NOT_RUN`, said in words.
+
 ## Getting past a login, and past a backend
 
 A surface behind auth is the usual reason a run skips the look. Both channels solve it,
@@ -277,7 +369,9 @@ On a CI box, headed is the failure you will spend an hour on.
 | The excuse | Why it fails |
 |---|---|
 | *"`playwright test` is green, the surface is checked."* | The suite asserts what someone wrote down. `DEC-0004`: it is the coverage half, never the look. |
-| *"I took a screenshot, so I looked."* | A screenshot is pixels you did not read. The look is `snapshot` + `console` + `requests`, and the verdict quotes them. |
+| *"I took a screenshot, so I looked."* | A screenshot is pixels you did not read. The functional look is `snapshot` + `console` + `requests`, and the verdict quotes them; reading the pixels is the visual half, with a capture record per frame and a matrix behind it. |
+| *"The snapshot is clean, so it looks right."* | The tree says the heading exists, not that it rendered at the right weight, in the dark theme, at 200 % text. That is the visual half's question, and on a flagship, product or ad surface it is a gate. |
+| *"The judge said it looks great."* | An uncalibrated judge's J items are `NOT_ASSESSED`, and no judge overrides a deterministic FAIL. A verdict needs a checklist, a reference, both orders and three samples. |
 | *"The click failed, I'll find a better selector."* | A ref that stopped resolving **is the finding**. Re-snapshot and report what moved. |
 | *"The docs say the CLI has no `tracing`."* | A vendor page is a claim; `--help` is the tool. This file was written against `--help` **because** a page-derived claim shipped here and was wrong. |
 | *"The tool list is in the docs."* | The page listed tools this version does not ship, and omitted that tracing, video and PDF need `--caps`. Ask the server: 24 tools default, 42 with all caps. |

package/plugins/task-pipeline/skills/task-pipeline/references/certification.md

@@ -15,6 +15,7 @@ queue is — graph or plan — is what decides, not the mood of the closer.
 
 - Why one verifier is not enough, stated as the failure it produces
 - The three tiers
+- The fourth reading — `visual`, on a flagship or product surface
 - Blind, and it is the whole design
 - A pass has to mean something, so two rules have teeth
 - The report, and where each field lands
@@ -60,7 +61,42 @@ that reads no code is not the soft one.
 
 Agents: [`../../../agents/verifier-unit.md`](../../../agents/verifier-unit.md),
 [`verifier-seam.md`](../../../agents/verifier-seam.md),
-[`verifier-product.md`](../../../agents/verifier-product.md).
+[`verifier-product.md`](../../../agents/verifier-product.md) — and, on a visual surface,
+[`verifier-visual.md`](../../../agents/verifier-visual.md), below.
+
+## The fourth reading — `visual`, on a flagship or product surface
+
+The three tiers read code, what reaches it, and what the product says about it. **None
+of them opens a picture**, and on a surface whose look is part of the requirement that
+leaves a whole level unread: a node can pass unit, seam and product while its empty
+state renders grey on grey at 200 % text, and every report is truthful about what its
+tier saw.
+
+| Tier | Subject | Characteristic finding |
+|---|---|---|
+| `visual` | the contact sheet, the director record, the project linter's output, the rubric | a frame that contradicts the record's intent; a gate item failing under a PASS; a hole in the state × axes matrix; a judge verdict from an uncalibrated judge |
+
+**When it runs.** A node that builds a user-facing surface copies the brief's
+`surface_class` ([`stages.md`](stages.md) → stage 0, *The surface class*). On
+**`flagship` and `product`** the `visual` report is **required** — `graph.py certify`
+refuses the round without it and names the tier. On `internal` and `ad` it is accepted
+when given and counted like any other tier, and not demanded: an internal tool's floor
+is the linter, and an ad's gate is its rubric profile on the contact sheet.
+
+**It is the fourth blind reading, not a reviewer with a vision model.** Same eight-key
+report, same `breaks`/`risk`, same blindness — it never sees the other three reports
+and they never see it. Its own rules, because a judge of pixels fails in its own ways:
+
+- **A checklist per task, never a score.** It answers the rubric's binary items against
+  the record and the sheet; "looks polished" is not an item.
+- **Pairwise only against the approved reference, and in both orders**; three samples.
+  A verdict that flips with the order, or between samples, is **`uncertain`** and goes to
+  the person — it is neither a pass nor a `breaks`.
+- **It never overrides a deterministic FAIL.** A gate item (G) or a linter S1 that
+  failed is a `breaks` whatever the picture looks like to it.
+- **A judge item (J) is `NOT_ASSESSED` until a labelled set exists** and the judge's
+  agreement with it has been measured. It goes in `not_examined`, which reaches the
+  closing verdict as `not_verified` — the honest name for an opinion nobody calibrated.
 
 ## Blind, and it is the whole design
 
@@ -71,8 +107,10 @@ will paraphrase it back as product truth. The disagreement between blind reading
 the instrument, so `graph.py certify` refuses a report whose prose cites another
 tier's verdict.
 
-Dispatch all three in one message so they run concurrently. Give each the node id,
-its `serves`, and the diff — nothing else, and never another tier's output.
+Dispatch all three in one message so they run concurrently — all four on a visual
+node. Give each the node id, its `serves`, and the diff — the `visual` tier also the
+paths of the contact sheet, the director record and the linter output — nothing else,
+and never another tier's output.
 
 **The second axis, and it is the one an optimisation removes first: whoever produced
 the fix never grades it.** Tier blindness is horizontal — no tier reads another's
@@ -146,6 +184,9 @@ consumer refuses.
 # three reports in, one verdict out — exits 1 if any tier failed
 graph.py certify --node N-007 \
     --tier unit.json --tier seam.json --tier product.json
+# a node with surface_class flagship or product: four, or the round is refused
+graph.py certify --node N-008 \
+    --tier unit.json --tier seam.json --tier product.json --tier visual.json
 
 # unchanged, and still the only thing that moves the graph
 graph.py close --verdict .task-pipeline/verdict-N-007.json
@@ -176,8 +217,8 @@ has failed **every** round. A run spinning on one level needs the operator to se
 
 ## What this costs, said out loud
 
-Three agents per node instead of one. That is the price of the visibility, and it is
-paid per node rather than per run. The three are dispatched in parallel, so the
+Three agents per node instead of one — four on a flagship or product surface. That is
+the price of the visibility, and it is paid per node rather than per run. The three are dispatched in parallel, so the
 wall-clock cost is roughly one reading; the token cost is three. A node whose
 `check` is mechanical and whose blast radius is genuinely nil still pays it — and a
 tier with nothing to find says so in `scope` and `not_examined` rather than being

package/plugins/task-pipeline/skills/task-pipeline/references/companion-skills.md

@@ -24,11 +24,15 @@ one must never look alike.
 > stop at the first that answers. The step stays **recommended and never a gate**: a gate
 > an environment cannot satisfy is one an agent learns to report around, and *verified by
 > reading the diff* already prices the absence honestly (`docs/DECISIONS.md`).
+> **`DEC-0006`** scopes that to the functional look: the **visual half** is a gate on a
+> `flagship`, `product` or `ad` surface, and its absent tool reads NOT_RUN and stops to
+> ask rather than passing ([`browser.md`](browser.md) → *The visual half*).
 
 ## Contents
 
 - Built in — nothing to install
 - The matrix
+- Visual lanes — tools, never entry points
 - Optional bridge — substituting an external skill set
 - Preflight (emit before stage 0)
 - Is this skill itself current?
@@ -76,6 +80,30 @@ one must never look alike.
 | ~~superpowers~~ | — | **Not a dependency.** Stages 2/4/5/6 run on the built-in doctrine above. See *Optional bridge* | — |
 | ~~grill-me / grilling~~ | — | **Not a dependency.** The stage-0 grill is built in (`references/grill.md`) | — |
 
+## Visual lanes — tools, never entry points
+
+The visual half ([`browser.md`](browser.md) → *The visual half*) asks for checks no
+companion above owns alone. These are the public tools that do each one. **Each is a
+tool a stage reaches for, never an entry point and never a second route**: the stage
+decides when, the tool does one job, and the close-out names which one it took. None is
+required; an absent one is a check recorded as NOT_RUN with its reason.
+
+| Tool | What it is for | Where in the stages |
+|---|---|---|
+| `break-ui` | seeds worst-case data — the longest name, the empty list, the 4-digit badge, the slow response — so frames show what a real account shows, not the demo | stage 6, **before** the contact-sheet screenshots |
+| `review-animations`, `improve-animations` | reviews motion against its intent: timing, easing, interruption, reduced-motion fallback | stage 6, on a surface with motion; findings as triples |
+| `mobile-native` | the mobile-web surface: viewport, safe areas, touch targets, keyboard-up states | stages 5–6, mobile-web frames of the matrix |
+| `animate-expo` | React Native and Expo motion, built and reviewed on the platform's own primitives | stage 5, an RN or Expo surface |
+| `webapp-testing`, `chrome-devtools` (`take_screenshot`, `lighthouse_audit`) | the frames of the matrix at each viewport and theme, and a Lighthouse pass as the deterministic floor | stage 6, the capture and the floor; stage 8 on a deployed target |
+| `accessibility-review`, `a11y-debugging` | accessibility review of the rendered surface and debugging what it finds | stage 6, beside axe or Lighthouse |
+| XCUITest `performAccessibilityAudit` | the iOS platform's own accessibility audit, run in UI tests | stage 6, a native iOS surface |
+| Compose `enableAccessibilityChecks` | Android's accessibility checks in Compose UI tests | stage 6, a native Android surface |
+| Playwright `toHaveScreenshot` | screenshot regression against the approved baseline, per state and theme | stage 6 (regression), and the nightly or release baseline after |
+| axe-core | the deterministic accessibility floor of a web surface | stage 6, first in the cheap-first order |
+
+A native screen is captured on a simulator or a device; a web render styled as a phone is
+a mockup, and the native rows of the sheet stay NOT_RUN without one.
+
 ## Optional bridge — substituting an external skill set
 
 An operator who already runs an equivalent skill set may map it onto stages 2/4/5/6

package/plugins/task-pipeline/skills/task-pipeline/references/conventions.md

@@ -103,9 +103,9 @@ closing a stage with an unread CI verdict.
 - Host self-update rules (module docs, runbooks, agent-self cards, etc.) — update
   in the same change. Fix dangling links.
 - **The design destination, on a project with no `docs/ux/`.** When the work uses
-  Figma but super-ux isn't in play, there is no `foundation.md` to hold the file, so
-  the brief is canonical — and a brief is per-run. Write the team and the file URL
-  into the host's own docs (`CLAUDE.md`, or the README) in this change, so the next
+  Figma but super-ux isn't in play, there is no `foundation.md` to hold the files, so
+  the brief is canonical — and a brief is per-run. Write the team and each surface's
+  file URL into the host's own docs (`CLAUDE.md`, or the README) in this change, so the next
   run reads the destination instead of creating a second file
   ([`grill.md`](grill.md) → *The design destination*).
 - **The code graph:** [graphify](https://github.com/Graphify-Labs/graphify) —

package/plugins/task-pipeline/skills/task-pipeline/references/doctrine-map.md

@@ -30,7 +30,7 @@ UX track on a user-facing task.
 | 3 Spec | `references/spec.md` |
 | 4 Plan | `references/planning.md` |
 | the queue the loop walks | `references/work-graph.md` |
-| 5–8 · how a **work-graph node** is CLOSED — three blind readings at three distances, all three required (ceiling 3); a **prose-plan task** closes through `review.md` instead — one reviewer, five-round cap | `references/certification.md` |
+| 5–8 · how a **work-graph node** is CLOSED — three blind readings at three distances, all three required, plus a fourth `visual` reading on a flagship or product surface (ceiling 3); a **prose-plan task** closes through `review.md` instead — one reviewer, five-round cap | `references/certification.md` |
 | 5 Build (worktree, subagents, fix loop) | `references/build.md` + `references/review.md` |
 | 5–6 TDD + suite gate | `references/tdd.md` |
 | 5, 6, 8 The browser — the look, the spec suite, and the difference | `references/browser.md` |

package/plugins/task-pipeline/skills/task-pipeline/references/grill.md

@@ -18,7 +18,7 @@ coming back to the operator.
 - Phase 2 — the gap check, then the loop
 - Domain awareness
 - The autonomy sweep
-- The design destination — one file, decided here, never invented later
+- The design destination — one file per surface, decided here, never invented later
 - The REQ spine — the grill's other hard output
 - Output
 
@@ -170,9 +170,9 @@ explicit "stop and ask me here":
 | 0 Docs regime | where settled things live (the decision home — **one** per project, and an existing `docs/adr/` **is** it), who may write it, whether a lease mechanism is present or the run is `ungated`, the gate command and its ratchet floors, and whether this run may raise a floor ([`documentation.md`](documentation.md)) |
 | 1 Docs | external libs/APIs/SDKs in play; any private ones context7 can't resolve → where their docs live |
 | 2 Decompose | is this a platform (several capabilities/surfaces) or one module? if platform: deploy cadence — per module or once at the end |
-| 2–3 Spec | UI verdict (arms super-ux); any scenario-tracing waiver |
+| 2–3 Spec | UI verdict (arms super-ux) **and the surface class** — `flagship`, `product`, `internal` or `ad`, which selects the visual gate profile ([`stages.md`](stages.md) → stage 0, *The surface class*); any scenario-tracing waiver |
 | 3 Design surface | UI tasks only: **Figma on or text-only** (super-ux's project-level choice, default on — check `docs/ux/foundation.md` → *Design tooling* before asking); is the Figma MCP connected; **and if it isn't — ship text-only, or stop here and connect it?** super-ux degrades to text-only on its own and never blocks, which means an unasked question here silently ships a UI feature with no mockups |
-| 3 Design file | Figma on only: **exactly which file, in which team/org** — the recorded one, or a URL the operator gives, or *create one in a named team* with that creation explicitly authorized. A destination decided at drawing time is how a project ends up with three "design" files and no way to tell which is real. See *The design destination* below |
+| 3 Design file | Figma on only: **exactly which files — one per surface (App, Web, ASO) — in which team/org** — the recorded ones, or a URL the operator gives, or *create one in a named team* with that creation explicitly authorized. A destination decided at drawing time is how a project ends up with three "design" files and no way to tell which is real. See *The design destination* below |
 | 4–5 Dev | base branch; worktree/branch policy; is `main` off-limits; commit convention; task tracker |
 | 5 Integration | how the branch lands (merge / PR + approver / "leave it unmerged"); parallel fan-out wanted (one worktree per implementer)? |
 | 6 Tests | the test command; what "green" means here; known-red baseline; coverage expectation |
@@ -188,7 +188,7 @@ preconditions ("staging once lint and the full suite are green; production alway
 asks"). Specific and recorded → it satisfies the stage-7 manual gate. Broader,
 absent or ambiguous → stage 7 stops and asks.
 
-## The design destination — one file, decided here, never invented later
+## The design destination — one file per surface, decided here, never invented later
 
 When the project designs in Figma, **the destination is a stage-0 decision, not a
 stage-3 side effect.** Left to drawing time, the question "where do I put this?"
@@ -199,16 +199,22 @@ the team actually opens.
 
 **Settle three things, in this order:**
 
-1. **Is there already a file?** Read `docs/ux/foundation.md` → *Design tooling*
-   first. A recorded, resolving file ends the question — record "use the recorded
-   file" and move on. Do not ask the operator something the project already answered.
+1. **Is there already a file for this surface?** Read `docs/ux/foundation.md` →
+   *Design tooling* first. A recorded, resolving file ends the question — record "use
+   the recorded file" and move on. Do not ask the operator something the project
+   already answered.
 2. **Which team / organization**, by name. A file URL identifies a file; it does not
    say whose workspace it lives in, and a design that lands in someone's personal
    drafts instead of the team space is invisible to everyone who needs it. When the
    operator belongs to several teams, the choice is theirs and it gets written down —
    `whoami` tells you which are available, it does not tell you which is right.
-3. **Which file** — an existing URL the operator supplies, or **creation in that
-   named team, explicitly authorized.**
+3. **Which file, per surface** — an existing URL the operator supplies, or **creation
+   in that named team, explicitly authorized.** The shape is **one file per surface** —
+   App, Web, ASO (store screenshots, icon, logo) — never one file holding every frame:
+   the surfaces have different owners, sizes and reviewers, and a single file is the
+   one nobody can hand to any of them. The record names each file with its surface,
+   and stage 3's gate checks every frame link against that set
+   (`scripts/visual_gate.py filekeys`).
 
 **Creating a file in a shared workspace is outward and irreversible enough to need a
 named target.** It follows the same floor as deploy authorization above: *"create

package/plugins/task-pipeline/skills/task-pipeline/references/loop-guard.md

@@ -23,6 +23,7 @@ searches.
 - Bookkeeping — the thing that makes detection mechanical
 - Detection — any one of these trips the guard
 - The review loop — a cap that measures rather than stops
+- The re-render loop — a budget of one, two at most
 - The break protocol
 - When to stop and hand back
 - Rationalizations
@@ -110,6 +111,28 @@ that was not.
 `touch:` lines at the review stage. A round that finds nothing ends the loop by
 definition and needs no counting.
 
+## The re-render loop — a budget of one, two at most
+
+A visual surface has a loop of its own: render, critique the render, render again. It
+is the one loop here with a **budget rather than a cap**, because its gain is measured
+to flatten fast — past the first or second refinement the change sits inside the noise
+of the judge reading it, and a third round mostly swaps one defect for another. So:
+
+- **One re-render per critique, two at the most.** After the second, the item still
+  failing is marked **`unresolved`** on the contact sheet with its triple and goes to the
+  person on their one pass — not into round three. Keep every rendered version; the last
+  is not automatically the best, and the sheet can show two side by side.
+- **Only external, specific feedback starts a round**: a linter finding, a failed audit
+  item, a diff against the frame or the approved baseline, a *region → defect → fix*
+  triple. "Look again" or "make it better" is not feedback and starts nothing — a round
+  with no named defect is churn with a screenshot.
+- **The person's rounds are counted, not remembered.** Each return of the contact sheet
+  with triples is a `review:` line in the run ledger ([`../templates/run.md`](../templates/run.md)),
+  and the sheet's `review_rounds` carries the same number
+  ([`browser.md`](browser.md) → *The visual half*). Like the review cap above it is a
+  measurement — a class of defect that keeps reaching the person is a rule missing from
+  the machine checks, and the fix is that rule, not more attention.
+
 ## The break protocol
 
 When the guard trips, **stop editing immediately**. Do not dispatch another fix, do

package/plugins/task-pipeline/skills/task-pipeline/references/portability.md

@@ -74,7 +74,7 @@ a row pointing outside the bundle is the defect this file exists to catch.
 | What a spec must lock, the UX-track order, the module dossier | `references/spec.md` |
 | The zero-context plan format, parallel groups, set equality | `references/planning.md` |
 | The work graph: its fields, the verbs and their exit codes, and the three invariants a schema cannot state | `references/work-graph.md`, `scripts/graph.py`, `graph.schema.json` |
-| How a node is CLOSED: three blind readings at escalating visibility, all three required, and the round ledger the ceiling reads | `references/certification.md`, `agents/verifier-{unit,seam,product}.md`, `scripts/graph.py certify` |
+| How a node is CLOSED: three blind readings at escalating visibility, all three required — four on a flagship or product surface — and the round ledger the ceiling reads | `references/certification.md`, `agents/verifier-{unit,seam,product,visual}.md`, `scripts/graph.py certify` |
 | Workspace isolation, the subagent loop, who may write the register | `references/build.md` |
 | The review rubric, diff packages, the three verdicts | `references/review.md` |
 | **False success** — the class, its known shapes and its two rules | `references/gates.md` |

package/plugins/task-pipeline/skills/task-pipeline/references/spec.md

@@ -33,9 +33,9 @@ Runs on **super-ux** — the one companion this pipeline recommends by name
 give the install line and stop; don't improvise a half-chain.
 
 0. **The design destination is already decided — read it, don't re-open it.** When
-   Figma is on, the stage-0 brief names the team/org and the file
-   ([`grill.md`](grill.md) → *The design destination*), and
-   `docs/ux/foundation.md` → *Design tooling* is the canonical record. Confirm the
+   Figma is on, the stage-0 brief names the team/org and the files — one per surface
+   (App, Web, ASO) — ([`grill.md`](grill.md) → *The design destination*), and
+   `docs/ux/foundation.md` → *Design tooling* is the canonical record. Confirm each
    recorded file **resolves** before any drawing. **Never create a file when a
    recorded one resolves; if it doesn't resolve, stop and ask — never create a
    replacement.** A creation happens at most once per project, in the team the
@@ -90,6 +90,30 @@ green over both.
   boundary with Figma (tokens as variables, never raw values carried across). Not
   through it: a purely structural change — what sits where is the UX track's — text,
   a backend, an internal script.
+- **The VISUAL track leaves a trace, and the gate reads the trace.** "The track ran" is
+  not checkable; a record is. The track writes a **director record** in the product's
+  repository, beside `docs/ux/`: `docs/design/<surface>/director-record.md`, a header
+  line `surface_class: <class>` and one `## <Field>` heading per field. Which fields are
+  owed is the brief's `surface_class` ([`stages.md`](stages.md) → stage 0, *The surface
+  class*):
+
+  | Class | Fields the record owes |
+  |---|---|
+  | `flagship` | Brief, Mode, Taste, References, Cast, Fork, Rubric, Critique, Markers, Alignment, Quality, Signature, Surfaces, Haptics, ADA, Open |
+  | `product` | Brief, Mode, References, Markers, Open |
+  | `ad` | Brief, Mode, References, Markers, ADA (the ad rubric profile and safe zones), Open |
+  | `internal` | none — the project linter is the floor |
+
+  What each field must say is sheleg-design's contract, and its validator checks it:
+  `npx sheleg-design-skill --check-record <file>`. The pipeline's gate is `python3
+  scripts/visual_gate.py record <file> --class <surface_class>`: it checks the headings
+  itself — present, and not a placeholder — and runs that validator where sheleg-design
+  is installed and new enough. Where it is not, the validator reads **NOT_RUN**, never
+  PASS, and the gate stands on the heading floor with that said. **The refusal is the
+  same file**: `## Mode` saying `declined` and why — *«без дизайна»*, *as is* — passes,
+  and a bare `declined` with no reason does not. The Rubric is written **before** any
+  direction is rendered; a rubric written after the render grades the render it already
+  liked.
 - **Each track's refusal is a sentence, never a silence.** *"Без дизайна" / "as is"*
   ends the visual track; *"без бренда" / "draft"* ends the copy track. Either one is
   the operator's to make and costs nothing — but it is **recorded in the brief and

package/plugins/task-pipeline/skills/task-pipeline/references/stages.md

@@ -187,10 +187,28 @@ never that the work was skipped quietly.
 - **UI early-detect:** one branch of the grill is always "does this touch a
   user-facing surface (web/mobile/CLI/TUI)?". If yes → surface **super-ux**
   now (use it if installed; otherwise give the install line — see SKILL.md
-  *Prerequisites*); this arms the stage-3 UX track.
+  *Prerequisites*); this arms the stage-3 UX track. **And the same branch records
+  the surface's class** — the next bullet.
+- **The surface class.** Every user-facing task's brief carries
+  `surface_class: flagship | product | internal | ad`, and the class selects the gate
+  profile the visual layer is held to for the rest of the run:
+
+  | Class | What it is | Director record (stage 3) | Visual half (stages 5–6) | Stage 10 |
+  |---|---|---|---|---|
+  | `flagship` | the surface a product is judged by — landing, onboarding, paywall, a hero screen | the full record | **gate**: full matrix, pairwise across every axis, the full rubric | approved contact sheet |
+  | `product` | an ordinary screen of the product | the short record — Brief, Mode, References, Markers, Open | **gate**: every state and the mandatory pairs; the gate items of the rubric | approved contact sheet |
+  | `internal` | an admin panel, an internal tool, a CLI | none owed | recommended; the project linter is the floor | the functional look |
+  | `ad` | a creative that runs as an advertisement or a store asset | Brief, Mode, References, Markers, ADA (its rubric profile and safe zones), Open | **gate**: the ad profile and the safe zones | approved contact sheet |
+
+  Ask it as one question with a recommended answer read off the request — a landing or a
+  paywall is `flagship` unless the operator says otherwise — and never leave it to stage
+  5: a class decided at build time is decided by whoever wants the build to pass. A
+  work-graph node that builds the surface copies the class as `surface_class`, and
+  `graph.py certify` then owes the fourth, `visual` reading on `flagship` and `product`
+  ([`certification.md`](certification.md) → *The fourth reading*).
 - **Artifact:** lock the resolved decisions into a **task brief** committed at
-  `<artifacts>/specs/YYYY-MM-DD-<topic>-brief.md` (scope, users/UI verdict,
-  constraints, assumptions, explicitly-deferred items, done-criteria) **plus the
+  `<artifacts>/specs/YYYY-MM-DD-<topic>-brief.md` (scope, users/UI verdict and,
+  for a user-facing task, `surface_class`, constraints, assumptions, explicitly-deferred items, done-criteria) **plus the
   autonomy sweep's per-stage answers and the model decision**. Seed it from
   the skill's `templates/brief.md` skeleton — but only when absent, never
   overwrite an existing brief. Stages 2–4 build on this brief; stages 5–10 read
@@ -214,7 +232,8 @@ never that the work was skipped quietly.
   a recorded answer or an explicit deferral, **every answer that contradicted a
   harvested source has a recorded resolution** (which governs, and whether the doc
   is now stale), no open contradictions, **every
-  autonomy-sweep row is answered or explicitly marked "stop and ask here"**, the
+  autonomy-sweep row is answered or explicitly marked "stop and ask here"**, **a
+  user-facing task's brief names its `surface_class`**, the
   **REQ table is written and every row names its check**, the carry-over ledger is
   seeded, **`.task-pipeline/run.md` exists and the header block has been printed**
   ([`progress.md`](progress.md)), the model decision is recorded, and the operator
@@ -314,8 +333,9 @@ never that the work was skipped quietly.
   ssheleg/super-ux`). super-ux builds a traced chain — walk it top-down (see its
   `system-map.md`):
   0. **Destination first, when Figma is on.** The brief already names the team/org
-     and the file; `docs/ux/foundation.md` → *Design tooling* is the canonical
-     record. Confirm it **resolves** before drawing. **Never create a file while a
+     and the files — **one per surface** (App, Web, ASO: store screenshots, icon and
+     logo), never one file for every frame; `docs/ux/foundation.md` → *Design tooling*
+     is the canonical record. Confirm each **resolves** before drawing. **Never create a file while a
      recorded one resolves; if it doesn't resolve, stop and ask — never create a
      replacement** (that is the duplicate, and it hides a permissions problem).
      A creation happens at most once, in the named team, and its URL is written to
@@ -350,7 +370,10 @@ never that the work was skipped quietly.
   disagree together on one screen. The full doctrine — each track's scope and
   out-of-scope, the refusal sentences, the four contradictions the check
   catches — is [`spec.md`](spec.md) → *The COPY and VISUAL tracks, and their
-  convergence*, its one home.
+  convergence*, its one home. **The VISUAL track leaves a trace, not a fact**: a
+  director record at `docs/design/<surface>/director-record.md`, whose fields the gate
+  reads by the brief's `surface_class` (`python3 scripts/visual_gate.py record <file>
+  --class <c>`), and a refusal is that same file saying `Mode: declined` and why.
 - **Spec:** write the approved design to
   `<artifacts>/specs/YYYY-MM-DD-<topic>-design.md` and commit it. Lock all
   shared contracts (types, schemas, signatures, file layout). For UI tasks the
@@ -367,12 +390,23 @@ never that the work was skipped quietly.
   designed, validated and approved; scenarios validated in `docs/ux/scenarios.md`;
   the linter passes; every user-facing spec requirement traces to a scenario ID
   (or an explicit v1-mode/tiny-project waiver by the operator). **With Figma on:
-  the canonical record names one file, and every `screens.md` frame link carries
-  that same `:fileKey`** — a string match, not a judgement; a differing key means
-  the run drew in a second file nobody will open. **Every user-facing string went
+  the canonical record names one file per surface (App, Web, ASO), and every
+  `screens.md` frame link's `:fileKey` is one of them** — a string match, not a
+  judgement (`python3 scripts/visual_gate.py filekeys --record docs/ux/foundation.md
+  --screens docs/ux/screens.md`); a key outside the set means the run drew in a file
+  nobody recorded and nobody will open. **Every user-facing string went
   through the COPY track or the refusal is recorded**, and **the visual layer went
   through the VISUAL track or the refusal is recorded** — a recorded refusal passes
   this gate and an unmentioned one does not, which is the only difference that matters.
+  **And the VISUAL track is checked by its trace, not by the fact that it ran:** on a
+  `flagship`, `product` or `ad` surface the director record exists and carries the
+  fields its class owes — `python3 scripts/visual_gate.py record
+  docs/design/<surface>/director-record.md --class <surface_class>` exits 0. That
+  command checks the headings itself and runs the record's own validator from `sheleg-design`
+  (`--check-record`) where it is installed and new enough; where it is not, the
+  validator reads **NOT_RUN** beside the verdict — never PASS — and the gate stands on
+  the floor, said so. A record saying `Mode: declined` with its reason is the refusal,
+  and it passes.
   **Where both tracks ran, their convergence check is recorded** — findings with the
   ruling, or `Tracks converge: clean`; a screen where each track is right alone and they
   disagree together is the defect neither track's own review can see.
@@ -435,7 +469,12 @@ never that the work was skipped quietly.
   requires — never parked silently** — a browser finding filed without a ruling is the
   diff-review verdict wearing a screenshot; the look was worth taking only if it can
   still change the code or is on record as deliberately not doing so. Absent, say the surface was verified by reading
-  the diff and treat it as the weaker claim it is. Stage 6 repeats this over the whole tree; this one catches it while the
+  the diff and treat it as the weaker claim it is. **On a surface whose brief names a
+  `surface_class`, the project linter runs here too**, after each task that changes a
+  rendered surface — `python3 scripts/visual_gate.py lint <dir>`; an S1 finding is
+  fixed in the task, and NOT_RUN (exit 3) is recorded as such
+  ([`browser.md`](browser.md) → *The visual half*). A slop marker caught while the
+  implementer is dispatched costs a line; caught on the contact sheet it costs a round. Stage 6 repeats this over the whole tree; this one catches it while the
   implementer that wrote it is still dispatched. The matrix pointed this companion at
   stages 5–6 from the day it was added and **this stage had never named it** — found by
   the guard comparing the two, not by a reader.
@@ -472,7 +511,10 @@ never that the work was skipped quietly.
   printed beside their floors; the **full** suite is green (not just the new tests); new/changed code
   is covered; **every check this run added or widened has been probed both ways —
   seen rejecting a planted defect and passing the clean tree, asserted on its exit
-  code** ([`probing.md`](probing.md)); no `skip`/`xfail` smuggling a red suite past the gate. Never advance
+  code** ([`probing.md`](probing.md)); no `skip`/`xfail` smuggling a red suite past the gate; **on a
+  `flagship`, `product` or `ad` surface where the VISUAL track ran, the visual half's
+  `visual_gate.py sheet` exits 0** — NOT_RUN stops and asks, it is not green
+  ([`browser.md`](browser.md) → *The visual half*). Never advance
   to deploy on a red or partial run. **The carry-over count is printed beside this
   verdict** — a ratchet nobody prints is a TODO with a better name
   ([`audit.md`](audit.md)) — **and so are the disclosures**, `abstained` and
@@ -502,6 +544,19 @@ never that the work was skipped quietly.
   run that answers *the surface was checked* by pointing at its spec suite has answered
   a different question. Where the suite is the thing that changed, the look is what
   proves it runs against a page that renders.
+- **The visual half is a separate check, and on most user-facing classes a gate.** The
+  look above reads the accessibility tree; it cannot say whether the surface looks like
+  what was designed. Where the stage-3 VISUAL track ran on a `flagship`, `product` or
+  `ad` surface, stage 6 also owes **the contact sheet** — frames over the `SCR-NN` states
+  × viewport × theme × text × locale (pairwise, plus the mandatory pairs), each with its
+  capture record, diffed against its Figma frame or approved baseline, the project
+  linter run, and the rubric read by a judge that is not the builder — and its command
+  exits 0: `python3 scripts/visual_gate.py sheet <contact-sheet.json> --class
+  <surface_class> --artifact-root <frames>` (NOT_RUN, exit 3, is not green). On
+  `internal` it is recommended and the linter is the floor. The re-render budget is
+  **one, two at most**, then `unresolved` to the person — never round three — and only
+  external, specific feedback starts a round. The procedure and the order of the checks:
+  [`browser.md`](browser.md) → *The visual half*.
 - **What the look finds is fixed here.** A rendering defect found at stage 6 is a
   stage-6 finding: fix it, look again, then call the stage green. Filing it to the
   board and advancing is how a run reports *checked in a browser* for a page it has
@@ -672,7 +727,14 @@ never that the work was skipped quietly.
   surface**: read it against the spec section that covers its `SCR-` id and against
   what shipped. The super-ux linter proves a frame link exists, is named right and
   is not stale — it cannot read the picture, so a frame promising a limit, a meter
-  or a tier nobody built passes every lint there is. An absence
+  or a tier nobody built passes every lint there is. **Where the VISUAL track ran, the
+  walk carries one more row: visual intent ↔ final render** — the director record (the
+  brief's falsifier, the signature moment, the rubric written before any render) read
+  against the **approved contact sheet**. On a `flagship`, `product` or `ad` surface the
+  sheet is approved (`visual_gate.py sheet … --require-approval` exits 0), and the last
+  `review:` line per surface — how many human rounds it took — is copied into the
+  acceptance file, because `.task-pipeline/run.md` does not outlive the run
+  ([`audit.md`](audit.md) → the `V→R` seam). An absence
   becomes a **new REQ row with its check** and *then* the table is written;
   appending after the table is how acceptance goes green over a gap. Findings that
   belong to a lower layer go back to that layer (spec → stage 3, plan → stage 4).

package/plugins/task-pipeline/skills/task-pipeline/references/work-graph.md

@@ -59,7 +59,7 @@ conditional on the code, never merely sequenced after it.**
 | `goal` | the release goal | `0` · `3` unstated |
 | `add` | the id it allocated | `0` · `1` refused |
 | `park` | the id and the reason | `0` · `1` refused |
-| `certify` | the round, and on a failure every `breaks` finding with its fix and its check | `0` all three tiers passed · `1` a tier failed, or a report is malformed |
+| `certify` | the round, and on a failure every `breaks` finding with its fix and its check | `0` every owed tier passed — three, or four with `visual` on a flagship or product node · `1` a tier failed, a required one is missing, or a report is malformed |
 | `close` | the goal, the new frontier count, and what was not verified | `0` · `1` refused **or the verdict stops the run** |
 | `producer` | what produced this proof — actor, model, runtime, skill, config, commit, trace | `0` |
 | `doctrine` | how many of the bundle's reference files this run opened | `0` |
@@ -84,7 +84,7 @@ A **`parked`** node is the single exemption: it is the one node nobody will clos
 *n/a — parked* in that field is confidence without correctness. `park` never removes what
 the node said it would run.
 
-**A node is closed by three readings, not one.** `certify` takes one tier report from each of `unit`, `seam` and `product` — dispatched blind and in parallel — requires all three to pass, and assembles the seven-key verdict `close` consumes. `close`'s contract is unchanged; what changed is that the verdict is now built from three readings at different distances instead of written from one, because a change can be correct where it was made and wrong one level out. A failing round records itself and leaves the node open. Doctrine: [`certification.md`](certification.md).
+**A node is closed by three readings, not one.** `certify` takes one tier report from each of `unit`, `seam` and `product` — dispatched blind and in parallel — requires all three to pass, and assembles the seven-key verdict `close` consumes. `close`'s contract is unchanged; what changed is that the verdict is now built from three readings at different distances instead of written from one, because a change can be correct where it was made and wrong one level out. A failing round records itself and leaves the node open. **A node whose `surface_class` is `flagship` or `product` owes a fourth, `visual` report** — the contact sheet read against the director record — and `certify` refuses the round without it; on any other node a `visual` report is accepted when given. Doctrine: [`certification.md`](certification.md).
 
 **`close` stamps the commit; the verifier never supplies it.** A verdict written after the
 tree moved is evidence about a different tree, and an agent cannot name the wrong commit if