task-pipeline-skill 1.88.1 → 1.90.0

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,105 @@ 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. **With Figma on, the
+   token check includes the drift probe**: `python3 scripts/visual_gate.py tokens
+   --figma <variables.json> --css <tokens.css>` compares the variable names exported
+   from the file (the JSON `get_variable_defs` returns, or the REST export) with the
+   custom properties the pack's token file declares. It names each variable with no
+   property, each property with no variable, and each variable whose WEB code syntax
+   is not the property the file actually declares. A name maps by kebab-case
+   (`Color/Text Muted` → `--color-text-muted`) unless code syntax says otherwise.
+   Exit `0` PASS · `1` FAIL · `2` unreadable · `3` NOT_RUN. No export is NOT_RUN,
+   never PASS: save the export beside the frames and run again, or record the probe
+   as not run.
+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 +379,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/build.md

@@ -532,10 +532,13 @@ it invents what was already decided.
    approximately, and approximate is indistinguishable from exact in a report.
 3. **A component with a Code Connect mapping is not rewritten.** If
    `get_code_connect_map` names a code component for that node, the screen uses it.
-   Reimplementing it is a silent fork of the design system.
+   Reimplementing it is a silent fork of the design system. *Code Connect, kept*, below,
+   is what keeps that mapping true.
 4. **A token names its variable.** A raw hex or px where the file has a variable is a
    token that has quietly split in two. `get_variable_defs` is the canon; a screenshot
-   is a way to *look*, never a way to *know*.
+   is a way to *look*, never a way to *know*. Whether the names still agree is
+   measured, not assumed: `visual_gate.py tokens` ([`browser.md`](browser.md) →
+   *The visual half*).
 5. **The frame is a contract at its own width.** It is one width and said nothing about
    the others, so behaviour at other breakpoints — and states the frame does not draw,
    like error, empty and loading — is a **decision that gets recorded**, not guessed.
@@ -559,6 +562,42 @@ same false confidence as an unproven green.
 platform constraint, an accessibility floor, a breakpoint — write what and why.
 Otherwise *"built from the frame"* and *"built to look like it"* read identically.
 
+### Code Connect, kept
+
+Rule 3 trusts the mapping. It is only worth trusting while it stays true. A mapping
+that still names a component's old props hands the next agent a snippet that does
+not compile, so it is followed by reimplementing the component. That is the fork
+rule 3 exists to prevent, reached by obeying it.
+
+- **A component whose API changes updates its Code Connect mapping in the same
+  change.** That covers a renamed or removed prop, a new variant, or a moved import
+  path. The mapping file is part of the component's diff and reviewed with it. A
+  mapping left for later is wrong from the next merge onwards. Figma's own guidance
+  says the same: *"When component APIs change in your codebase, update the
+  corresponding Code Connect mappings"* ([Code Connect integration][fcc], accessed
+  2026-10-08).
+- **A core component with no mapping gets an offer, not a silent skip.** Where a
+  task builds on a design-system component that the file draws and Code Connect does
+  not map, the run offers to map it with `/figma-code-connect`, Figma's public
+  plugin skill ([`companion-skills.md`](companion-skills.md)). The offer names which
+  components and which file. Mapping publishes to the Figma file, so it runs only on
+  an explicit go, like drawing a missing frame. Absent the skill, the run names the
+  unmapped components in the close-out and goes on.
+- **Never rewrite a mapped component instead of using it** — rule 3, unchanged. An
+  API that no longer fits the frame is a change to the component and its mapping
+  together, never a local copy.
+
+Why it pays, in Figma's words and on Figma's measurement: their own evals report *"a
+19.6% reduction in median task duration, a full point of improvement in code quality
+on a 1–4 scale, and a 29.5% reduction in token usage"* with Code Connect
+([Figma MCP use cases][fuc], accessed 2026-10-08). **That is Figma's unaudited
+number** — a vendor's eval of its own feature, with no published protocol here and
+not reproduced by this pipeline. Quote it as theirs, never as a measured property
+of a run.
+
+[fcc]: https://developers.figma.com/docs/figma-mcp-server/code-connect-integration/
+[fuc]: https://www.figma.com/resource-library/figma-mcp-use-cases/
+
 ## 5. Final whole-branch review
 
 After the last task: build a package over `MERGE_BASE`..`HEAD`

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,31 @@ 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 |
+| `figma-code-connect` (Figma's public plugin skill) | maps a design-system component in the file to its code component, so `get_design_context` hands the agent the real import instead of approximated markup | stage 5, **offered** for a core component the file draws and nothing maps — publishes to the file, so it needs a go ([`build.md`](build.md) → *Code Connect, kept*) |
+
+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