task-pipeline-skill 1.88.1 → 1.89.1

package/CHANGELOG.md

@@ -1,3 +1,67 @@
+## v1.89.1 — v1.89.0's payload, released with its no-stamp declaration
+
+`v1.89.0` was refused by its own release check: the release carried no run stamp and was not
+named in `## Releases that carry no stamp`. Nothing was published under it. This release is the
+same payload with the declaration in `docs/evidence/retro.md`, the tenth such instance. What
+v1.89.0 ships is described in its section below.
+
+Guards: 430 → **430** — a declaration and a version bump; no check changes.
+
+## v1.89.0 — the visual layer is checked by its trace, and a fourth reading opens the picture
+
+Until now the stage-3 VISUAL track passed on the fact that it ran, the look at stages 5–6
+read the accessibility tree and never the pixels, and none of the three verifiers opened a
+picture. A landing could pass every gate while nobody compared what shipped with what was
+designed. This release adds the visual half, gated by a class the brief now records
+(`DEC-0006`).
+
+Guards: 430 → **430** — the new checks are suites of their own and the validator is unchanged.
+
+- **Stage 0 records `surface_class: flagship | product | internal | ad`** for every
+  user-facing task (`references/stages.md` → *The surface class*, the grill's UI branch,
+  `templates/brief.md`). The class selects the gate profile for stages 3, 6 and 10.
+- **Stage 3 reads the director record's fields, not the fact the track ran.**
+  `scripts/visual_gate.py record <file> --class <c>` checks the headings each class owes
+  (the full set on `flagship`; Brief, Mode, References, Markers, Open on `product`) and runs
+  sheleg-design's `--check-record` where it is installed and new enough. Where it is not,
+  the validator reads NOT_RUN beside the verdict, never PASS. `Mode: declined` with a reason
+  is the refusal, and it passes (`references/spec.md`).
+- **Figma: one file per surface (App, Web, ASO), not one for every frame.**
+  `visual_gate.py filekeys` checks every `screens.md` frame link's key against the recorded
+  set (`grill.md`, `stages.md`, `audit.md`'s `→F` seam).
+- **The visual half of the look** (`references/browser.md` → *The visual half*). Checks
+  run cheapest first: the project linter (`visual_gate.py lint`, NOT_RUN exit 3 where
+  absent), regression against the baseline, then the state × axes matrix (pairwise plus
+  the mandatory pairs dark × large text and RTL × narrow). Each frame carries its capture
+  record and a diff against its Figma frame or baseline. A judge reads the rubric. J items
+  stay NOT_ASSESSED until a labelled set calibrates the judge, and no judge overrides a G
+  FAIL. It is a gate on `flagship`, `product` and `ad`, and recommended on `internal`.
+  Re-render budget: one, two at most, then `unresolved` to the person. Only external,
+  specific feedback starts a round (`loop-guard.md` → *The re-render loop*).
+- **The contact sheet is `templates/browser-claims.json`, extended rather than replaced**
+  — row fields `axes`, `capture`, `figma_frame`, `baseline`, `diff`, `rubric[]`; file
+  fields `surface`, `revision`, `review_rounds`, `approved_by`, `approved_at`.
+  `visual_gate.py sheet` validates it and exits 0 · 1 · 2 · 3. The browser-claims rules now
+  live in that shipped script, so a host can run them. `test/browser_claims_test.py`
+  imports them under the old names.
+- **`agents/verifier-visual.md` — the fourth blind reading.** `graph.py certify` requires
+  a `visual` report on a node whose new `surface_class` is `flagship` or `product`, and
+  accepts one on any other node. `graph.schema.json` gains the field and the tier
+  (`references/certification.md` → *The fourth reading*).
+- **Acceptance walks visual intent ↔ the approved contact sheet** (`audit.md`'s `V→R`
+  seam). The run ledger gains a `review:` line. `stage_checkpoint.py` carries it into the
+  checkpoint of the stage it names, so the passes a surface took are measured.
+- **Visual lanes in `companion-skills.md`.** These are tools, never entry points:
+  `break-ui`, `review-animations` / `improve-animations`, `mobile-native`, `animate-expo`,
+  `webapp-testing` / `chrome-devtools`, `accessibility-review` / `a11y-debugging`, and the
+  platform audits.
+- **Tests:** `test/visual_gate_test.py` (24 cases); `test/browser_claims_test.py` (35
+  cases, 27 of them new contact-sheet plants); six `graph_test.py` cases for the visual tier and
+  the class; one `stage_checkpoint_test.py` case; and a `certify_mutations.py` mutation for
+  the visual requirement. A hand mutation pass over `visual_gate.py` disabled each of 34
+  rules in turn, and a fixture failed for every one. CI now also runs the three suites
+  `npm test` already ran.
+
 ## v1.88.1 — v1.88.0's payload, released with its no-stamp declaration
 
 The same payload as `v1.88.0`: the stage-boundary checkpoint writer, `scripts/stage_checkpoint.py`

package/README.md

@@ -182,7 +182,7 @@ until it is installed.
 | 3 Spec | [`spec.md`](plugins/task-pipeline/skills/task-pipeline/references/spec.md) — UX-track order, locked contracts, global constraints, self-review |
 | 4 Plan | [`planning.md`](plugins/task-pipeline/skills/task-pipeline/references/planning.md) — zero-context tasks, parallel groups, no placeholders |
 | the queue | [`work-graph.md`](plugins/task-pipeline/skills/task-pipeline/references/work-graph.md) — a script walks the graph so the model never reads it: 400 nodes and 4 print the same 27-byte frontier |
-| closing a node | [`certification.md`](plugins/task-pipeline/skills/task-pipeline/references/certification.md) — three blind readings at escalating visibility (the changed code, what reaches it, the product around it), all three required to pass; a failing round records itself and the node stays open |
+| closing a node | [`certification.md`](plugins/task-pipeline/skills/task-pipeline/references/certification.md) — three blind readings at escalating visibility (the changed code, what reaches it, the product around it), all three required to pass — and a fourth, `verifier-visual`, on a flagship or product surface, which reads the contact sheet against the director record; a failing round records itself and the node stays open |
 | 5 Build | [`build.md`](plugins/task-pipeline/skills/task-pipeline/references/build.md) + [`review.md`](plugins/task-pipeline/skills/task-pipeline/references/review.md) — isolation, ledger, subagent loop, review rubric, fix loop |
 | 5–6 TDD | [`tdd.md`](plugins/task-pipeline/skills/task-pipeline/references/tdd.md) — the iron law, red/green/refactor, the suite gate |
 | 5, 6, 8 The browser | [`browser.md`](plugins/task-pipeline/skills/task-pipeline/references/browser.md) — the ref model both channels share, the four commands the look is made of, sessions, and the three different things *"tested in a browser"* means |

package/SKILL-CARD.md

@@ -12,7 +12,7 @@ harmless.
 |---|---|
 | **Purpose** | Runs a substantial task through ten gated delivery stages — intake grill, docs study, brainstorm, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs+registers, acceptance — refusing to advance until each gate passes |
 | **Owner** | ssheleg ([github.com/ssheleg/task-pipeline](https://github.com/ssheleg/task-pipeline)) |
-| **Version** | 1.88.1 |
+| **Version** | 1.89.1 |
 | **Surface** | Claude Code (filesystem skill + plugin) and the vercel `skills` CLI. **Not** uploaded to the Skills API; custom Skills do not sync across surfaces |
 | **Dependencies** | None required. Optional: `context7` (MCP), `figma` (MCP), super-ux, agent-sync, graphify, obsidian-wiki, and **one of two browser channels** — `playwright` (CLI or MCP) or `chrome-devtools` (MCP); either satisfies the browser step and neither is required. Every stage's doctrine ships in-repo; the one conditional requirement is super-ux for the stage-3 UX track on a user-facing task |
 | **Evaluation status** | Suite authored, 5 categories. One recorded run, **self-observed by the author**; **zero blind runs on zero of three models** — the split, and the numbers, live in [`evals/RESULTS.md`](evals/RESULTS.md) and are computed by `evals/run.py` |

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.88.1",
+  "version": "1.89.1",
   "description": "Full-cycle delivery pipeline for coding agents: a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine ships inside the skill — no companion plugin required. This package is the installer CLI.",
   "bin": {
     "task-pipeline": "bin/task-pipeline.js"
   },
   "scripts": {
-    "test": "python3 test/validate.py && python3 test/graph_test.py && python3 test/project_audit_test.py && python3 test/packet_schema_test.py && python3 test/browser_claims_test.py && python3 test/stage_checkpoint_test.py && npm run test:audit-regressions",
-    "test:all": "python3 test/validate.py && python3 test/graph_test.py && python3 test/project_audit_test.py && python3 test/packet_schema_test.py && python3 test/browser_claims_test.py && python3 test/stage_checkpoint_test.py && python3 test/negatives.py && npm run test:certify && npm run test:exposure && npm run test:probe && npm run test:anchors && npm run test:runner && npm run test:hooks && npm run test:artifacts && npm run test:docs && npm run test:audit-regressions",
+    "test": "python3 test/validate.py && python3 test/graph_test.py && python3 test/project_audit_test.py && python3 test/packet_schema_test.py && python3 test/browser_claims_test.py && python3 test/visual_gate_test.py && python3 test/stage_checkpoint_test.py && npm run test:audit-regressions",
+    "test:all": "python3 test/validate.py && python3 test/graph_test.py && python3 test/project_audit_test.py && python3 test/packet_schema_test.py && python3 test/browser_claims_test.py && python3 test/visual_gate_test.py && python3 test/stage_checkpoint_test.py && python3 test/negatives.py && npm run test:certify && npm run test:exposure && npm run test:probe && npm run test:anchors && npm run test:runner && npm run test:hooks && npm run test:artifacts && npm run test:docs && npm run test:audit-regressions",
     "test:negatives": "python3 test/negatives.py",
     "test:exposure": "python3 test/exposure_test.py",
     "test:probe": "python3 test/probe.py --self-test",

package/plugins/task-pipeline/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "task-pipeline",
   "displayName": "Task Pipeline",
   "description": "Runs a substantial task through a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine is built into the skill — no companion plugin required — with typed auto/judgment/manual gates, a frozen requirement spine that closes with evidence, a work board and a verification ledger that outlive a run, an exposure line naming what shipped unconfirmed, a progress rail computed from the project's own config, a loop guard whose review ceiling measures rather than stops, and stage-3 tracks for what a product does, how it sounds and how it looks. Two modes need no task: `checkup` (what is unverified) and `setup` (audit existing docs). Retro insights can publish upstream as issues, opt-in and redacted.",
-  "version": "1.88.1",
+  "version": "1.89.1",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/task-pipeline/agents/verifier-product.md

@@ -16,7 +16,9 @@ Your subject is **behaviour and what claims it.** Documentation, scenarios, the
 changelog, ADRs, the runbook, the strings a user reads, and the other features that
 share this path. You may open code to confirm a behaviour — but code is your
 evidence, never your scope. If your report describes functions, you have written a
-third unit-tier report and the level the user built this gate for went unread.
+third unit-tier report and the level the user built this gate for went unread. The
+rendered pixels are not yours either: on a flagship or product surface a fourth,
+visual reading takes the contact sheet.
 
 ## Read the claims before you judge the change
 

package/plugins/task-pipeline/agents/verifier-visual.md

@@ -0,0 +1,115 @@
+---
+name: verifier-visual
+description: Tier 4 of a task-pipeline certification, owed on a flagship or product surface. Reads the contact sheet, the director record, the project linter's output and the rubric, and reports whether what a user SEES carries the intent the record set — every state in the matrix, no gate item failing under a pass, no judge verdict an uncalibrated judge invented. Returns an eight-key tier report. Use as the fourth blind reading when a node whose surface_class is flagship or product claims to be finished. Not for code, call graphs or documentation — those are the unit, seam and product tiers.
+model: inherit
+tools: Read, Grep, Glob, Bash
+---
+
+# Visual tier — what a user sees, read against what was intended
+
+You are the **fourth** reading, and the only one that opens a picture. Three agents are
+reading the same node — the diff, what reaches it, what the product says about it — and
+you will never see their reports, nor they yours. Blind is the point: an agent that has
+just read *the implementation is sound* will look at a frame and see a sound
+implementation.
+
+Your subject is **the rendered surface against its stated intent.** Four inputs, and
+nothing else is yours:
+
+- the **contact sheet** — a filled `browser-claims/1` file whose look rows carry
+  `axes`, `capture`, `figma_frame`, `baseline`, `diff` and `rubric`, and the frames it
+  names;
+- the **director record** — `docs/design/<surface>/director-record.md`: the brief and
+  its falsifier, the rubric written before any render, the signature moment, the
+  markers run;
+- the **project linter's output** — `scripts/visual_gate.py lint`, or its NOT_RUN;
+- the **rubric** — the items the record and the sheet name, each typed G (deterministic
+  gate), J (judge) or H (the person on the sheet).
+
+If you find yourself reading a component's source to decide something, stop — that
+finding belongs to the unit tier. If you are checking whether the README describes the
+screen, that is the product tier's.
+
+## What you actually do
+
+1. **Run the deterministic checks first, and quote them.**
+   `python3 scripts/visual_gate.py sheet <sheet> --class <surface_class> --artifact-root
+   <frames>` and, where the record exists, `python3 scripts/visual_gate.py record <record>
+   --class <surface_class>`. Their output is your first `evidence` rows. A FAIL there is
+   a `breaks` finding, whatever the frames look like to you; a NOT_RUN is said as
+   NOT_RUN, never smoothed into a pass.
+2. **Read the record before any frame.** The falsifier, the signature moment, the rubric.
+   The standard is what the record committed to before the render, not what the render
+   turned out to be.
+3. **Walk the matrix, state by state.** For each `SCR` state: does a frame exist at the
+   mandatory pairs (dark × large text, RTL × narrow where the product has RTL), is its
+   capture record for this revision, does it diff clean against its Figma frame or
+   approved baseline? A hole or a stale frame is a finding about the sheet, not a
+   judgement about taste.
+4. **Answer the rubric as a checklist — never as a score.** Each item is binary against
+   the record and the frame. Where you compare, compare **only against the approved
+   reference, in both orders**, and take **three samples**. A verdict that flips with the
+   order or between samples is **`uncertain`**: it goes in `not_examined` as
+   `uncertain — <item> — to the person on the sheet`, not into `confirms` and not into
+   `findings`.
+5. **Mark every judge item NOT_ASSESSED until a labelled set calibrates it.** A J item
+   whose sheet row carries no `calibration` is not yours to pass or fail: list it in
+   `not_examined` as `NOT_ASSESSED — <item> — no labelled set`. A verdict from an
+   uncalibrated judge is a guess with a format.
+6. **Never override a deterministic FAIL.** A G item or a linter S1 that failed is
+   `breaks`. You may add a finding beside it; you may not argue it away.
+7. **Say what you read.** `scope` lists the sheet, the record, the frames you opened and
+   the linter output, each with its path. A pass on an empty `scope` is refused by
+   `graph.py certify` by name.
+
+## `breaks` or `risk`, and the line is not taste
+
+- **`breaks`** — the surface contradicts the record (the falsifier fails, the signature
+  moment is absent, a rubric item the record wrote first is violated on a frame), a G
+  item or an S1 failed, a required state has no frame, or a frame is stale or of the
+  wrong state. Every `breaks` carries a `check` — the command, or the judgement named as
+  one ("judgement — SCR-02/empty at 375 × dark × 200 %, against R-item and the record's
+  falsifier") — and its `fix` is a **triple: region → defect → fix**. A finding nobody
+  can locate on the frame is an impression.
+- **`risk`** — found and survivable: a pairwise hole on a product surface, a frame whose
+  diff was NOT_RUN with a reason, an item the person should look at first. It ships,
+  named, as a blocker the run can continue around.
+
+**A clean render is a valid result.** There is no quota of findings; inventing a defect
+to look thorough starts a re-render round nobody needed, and the budget is one, two at
+most.
+
+## The report — all eight keys, and `[]` is an answer
+
+```json
+{
+  "node": "N-012",
+  "tier": "visual",
+  "verdict": "fail",
+  "scope":        ["design/review/contact-sheet.json — 9 frames, SCR-01 and SCR-02",
+                   "docs/design/landing/director-record.md — Brief, Rubric, Signature",
+                   "design/review/lint.json — the project linter at 4dbb96c"],
+  "confirms":     ["the falsifier holds on every 375-wide frame: the price is above the fold"],
+  "findings":     [{ "what": "the empty state's helper text is grey on grey in dark at 200 % text",
+                     "where": "contact-sheet.json BC-06 — SCR-02/empty, 375x667 · dark · 200% · ar",
+                     "severity": "breaks",
+                     "fix": "region: empty-state helper → defect: contrast 2.9:1 → fix: --sem-fg-muted to --sem-fg-default",
+                     "check": "python3 scripts/visual_gate.py sheet design/review/contact-sheet.json --class product" }],
+  "evidence":     ["visual_gate.py sheet … --class product → FAIL, 1 problem (BC-06 G item FAIL under PASS)",
+                   "visual_gate.py record … --class product → PASS · validator NOT_RUN (sheleg-design without --check-record)"],
+  "not_examined": ["NOT_ASSESSED — R7 (J) — no labelled set calibrates the judge",
+                   "uncertain — R12 on BC-08: the order-swapped comparison disagreed — to the person on the sheet"]
+}
+```
+
+## Three ways this goes wrong
+
+| Temptation | Why it is wrong |
+|---|---|
+| «It looks great» | That is a score with no checklist under it. Name the items, the frames and the reference, or name nothing |
+| «The linter flagged it, but visually it's fine» | You sit below the deterministic floor. A G item or S1 that failed is `breaks`, and the fix is the code or the rule, not your opinion |
+| «One more re-render will get it» | The budget is one, two at most. Past it, the item is `unresolved` on the sheet and goes to the person on their one pass |
+
+Doctrine: `references/certification.md` → *The fourth reading*. The checks and the
+contact sheet: `references/browser.md` → *The visual half*. The record's fields:
+`references/spec.md` → *The COPY and VISUAL tracks*.

package/plugins/task-pipeline/agents/verifier.md

@@ -9,7 +9,8 @@ tools: Read, Grep, Glob, Bash
 
 > **A node is normally closed by three readings, not by this one.**
 > `verifier-unit`, `verifier-seam` and `verifier-product` each report at a
-> different distance, `graph.py certify` requires all three to pass and assembles
+> different distance — plus `verifier-visual` on a node whose `surface_class` is
+> flagship or product — `graph.py certify` requires every owed tier to pass and assembles
 > the verdict below from them — because a change can be correct where it was made
 > and wrong one level out, and a single context cannot see both. Doctrine:
 > `references/certification.md`. This agent remains for the case `certify` does not

package/plugins/task-pipeline/skills/task-pipeline/SKILL.md

@@ -135,7 +135,7 @@ Three things the grill does beyond clarifying the request, each in full in
 [`references/grill.md`](references/grill.md):
 - **Domain awareness** — it reads the project's `CONTEXT.md` / `docs/adr/` and holds the operator to them, writing resolved terms back as they land.
 - **The autonomy sweep** — it pre-resolves what would otherwise stop stages 1→10 mid-flight. Autonomy is bought here or not at all; an unasked question is a scheduled interruption.
-- **The design destination** with Figma on — *which* file, in which team, decided at stage 0. Left to drawing time it is answered by whoever holds the brush, and the answer is usually *create a new file*.
+- **The design destination** with Figma on — *which* file per surface, in which team, decided at stage 0. Left to drawing time it is answered by whoever holds the brush, and the answer is usually *create a new file*.
 
 ## How to run
 
@@ -207,13 +207,13 @@ capable available — see `references/model-tiering.md`).
 
 | # | Stage | Gate | Type |
 |---|---|---|---|
-| 0 | Intake grill — **mandatory** | source ledger written with its `Contradictions:` line; `docs/DOCMAP.md` answered and intent reconciled against as-built; the retro read in full; autonomy sweep covered; brief locked and confirmed | manual |
+| 0 | Intake grill — **mandatory** | source ledger written with its `Contradictions:` line; `docs/DOCMAP.md` answered and intent reconciled against as-built; the retro read in full; autonomy sweep covered; UI: `surface_class` recorded; brief locked and confirmed | manual |
 | 1 | Docs study | contracts grounded on fetched docs | auto |
 | 2 | Brainstorm + decompose | design approved; UI verdict recorded; every REQ answered; **the queue is an artifact** — a work graph validates and its coverage names no unserved REQ; platform: module map approved | manual |
-| 3 | Spec | committed + reviewed; UI: chain validated, linter green, scenarios and `SCR-` traced; COPY and VISUAL are a parallel layer after UX, and where both ran their convergence check is recorded | manual |
+| 3 | Spec | committed + reviewed; UI: chain validated, linter green, scenarios and `SCR-` traced; COPY and VISUAL are a parallel layer after UX, and where both ran their convergence check is recorded; VISUAL is checked by its director record | manual |
 | 4 | Plan | parallel-ready, DoD per task; **every edge names what it carries** — the fake-edge test run and its `Edges:` count computed; **`scripts/plan_audit.py` clean** — every live node's packet survives a cold reader, and no two unordered nodes edit one file | auto |
 | 5 | Dev | tasks DONE, TDD green per task, branch integrated per the brief; a fanned-out group gets **one convergence check over all its diffs together** before the first worktree lands | auto |
-| 6 | Tests | full suite green, new and changed code covered, every new check probed both ways and asserted on its exit code; **a web surface is checked in a browser, not in the diff** — where a browser channel is connected; absent, the weaker claim is recorded | auto |
+| 6 | Tests | full suite green, new and changed code covered, every new check probed both ways and asserted on its exit code; **a web surface is checked in a browser, not in the diff** — where a browser channel is connected; absent, the weaker claim is recorded; a gated surface's contact sheet passes | auto |
 | 7 | Lint + deploy | lint clean and suite green before deploy; deploy needs a go, or the brief's specific standing authorization | manual |
 | 8 | Post-deploy | clean boot or an honest degradation report; **a deployed web target is opened, not curled** — a `200` proves the server answered and nothing else; where no browser channel is connected, the weaker claim is recorded | auto |
 | 9 | Docs + wiki | every stale row of the stage-0 source ledger updated; the propagation matrix walked for every change type this run produced; the documentation gate green with its ratchets printed; docs, wiki and the code graph synced and checked against each other | auto |

package/plugins/task-pipeline/skills/task-pipeline/graph.schema.json

@@ -196,9 +196,18 @@
           },
           "description": "What this node MUTATES — paths, register names, remote resource ids. `references/planning.md` states the rule the frontier needs: *distinct is not the same as independent, and the check is what they touch, never what they are called.* That rule lived in the markdown plan, and the graph replaced the plan as the thing deciding what runs next — so `next` could hand two agents two runnable nodes that write the same file, with nothing able to report it.\\n\\nOptional, and its absence is DISCLOSED rather than treated as «touches nothing»: `next` prints how many frontier nodes declared no targets, because a quiet run and a checked one must not look alike."
         },
+        "surface_class": {
+          "enum": [
+            "flagship",
+            "product",
+            "internal",
+            "ad"
+          ],
+          "description": "The class of the user-facing surface this node builds, copied from the brief's `surface_class` (stage 0). It selects the gate profile, and `graph.py certify` reads it: on `flagship` or `product` the fourth, `visual` tier report is REQUIRED, because none of unit, seam or product opens the contact sheet; on any other class a `visual` report is accepted when given. Absent on a node that builds no user-facing surface. `references/certification.md` → *The fourth reading*."
+        },
         "certification": {
           "type": "object",
-          "description": "What the three-tier certification recorded for this node. Written by `graph.py certify` on every round, pass or fail: a failing round that wrote nothing would erase the only evidence that a node is churning, which is the number the loop-guard ceiling reads.",
+          "description": "What the tiered certification recorded for this node. Written by `graph.py certify` on every round, pass or fail: a failing round that wrote nothing would erase the only evidence that a node is churning, which is the number the loop-guard ceiling reads.",
           "additionalProperties": false,
           "required": [
             "round",
@@ -237,6 +246,12 @@
                     "pass",
                     "fail"
                   ]
+                },
+                "visual": {
+                  "enum": [
+                    "pass",
+                    "fail"
+                  ]
                 }
               }
             },
@@ -273,6 +288,12 @@
                       "pass",
                       "fail"
                     ]
+                  },
+                  "visual": {
+                    "enum": [
+                      "pass",
+                      "fail"
+                    ]
                   }
                 }
               }

package/plugins/task-pipeline/skills/task-pipeline/pipeline.example.json

@@ -18,7 +18,7 @@
       ],
       "gate": {
         "type": "manual",
-        "check": "MANDATORY stage — never skipped (only sanctioned bypass: the entry-from-super-ux short-circuit). PHASE 1, before the first question: harvest the knowledge sources (references/knowledge-sources.md) — code, THE CODE GRAPH when one is built (references/knowledge-graph.md: graphify query/affected/god-nodes answer reach, which grep cannot; detect graphify-out/graph.json — recommended, never required), CLAUDE.md/AGENTS.md, CONTEXT.md + docs/adr, docs/ + docs/ux, past pipeline briefs and carry-over ledgers, THE RETRO'S STANDING INSTRUCTIONS (docs/evidence/retro.md — read IN FULL, not queried: they are capped at ten and they BIND this run; stamp each one the moment it fires, since that date is the only evidence behind stage 10's cold-retirement rule — references/retrospective.md), the knowledge wiki when installed (obsidian-wiki — recommended, never required; detect ~/.obsidian-wiki/config), and any other repo or hosted doc system the project names as its docs — queried by this task's own terms, with the SOURCE LEDGER written into the brief (a row per source consulted, or an explicit 'none found'; THE GRAPH'S ROW CARRIES ITS MEASURED LAG — commits and days behind HEAD, the signal it was measured with (built_at_commit exact / mtime approximate / unresolvable), and the marker '⚠ not trusted for reach until refreshed' — that exact string, so one marker is greppable across every ledger — on anything but current. A bare build date does NOT satisfy this: it is the graph's own reply about itself, true and self-reported and silent about whether the graph describes the tree this run is about to change — references/knowledge-graph.md -> Measure the lag, and references/gates.md -> False success for the class). PHASE 2, the grill, built into the skill (references/grill.md) — no companion to install. Per its contract: one question at a time, a recommended answer with each, explore the codebase/docs before asking, depth-first, contradictions reconciled; EVERY answer that touches a harvested source is validated against that source — the operator outranks any document, but only out loud, and the losing side is logged for the stage-9 doc update; domain awareness applied (terms challenged against CONTEXT.md, ADRs recorded for hard-to-reverse calls). The autonomy sweep is covered — every stage 1-10 has its blockers pre-resolved (docs sources, branch/tracker policy, test + lint commands, deploy target and authorization, log/health locations, docs+wiki targets, and for UI tasks the design surface: Figma on or text-only, is the Figma MCP connected, and if it is not — ship text-only or stop and connect it, since the UX chain degrades on its own and never blocks; plus, with Figma on, the DESIGN DESTINATION — which team/org by name and which file (the recorded one, a URL the operator gives, or creation in that named team with the creation explicitly authorized), written into the project's canonical record before the first frame, and never created while a recorded file resolves — an unreachable recorded file means stop and ask, never make a replacement) or is explicitly marked 'stop and ask here'. UI verdict recorded (arms super-ux); model decision recorded. All of it locked into a committed task brief the operator confirms before stage 1. The REQ table is written — one row per independently verifiable deliverable, each naming how it is verified — and frozen: adding later is free, removing or narrowing needs the operator's explicit agreement. The carry-over ledger is seeded. PHASE 1b, THE DOCUMENTATION INVENTORY (references/documentation.md): four questions answered into docs/DOCMAP.md before the interview — where settled things live (the DECISION HOME, and there is exactly one per project: an existing docs/adr/ IS the register and is recorded as such, never duplicated), what each fact's single home is, what a change of type X obliges (THE PROPAGATION MATRIX, non-empty, every row naming the check that enforces it or the word 'review' with a one-line reason), and what proves it (the gate command). A project with no answers gets them seeded — registers, matrix and scripts/check-docs.sh from the skill's templates — and the seeding is recorded as the register's first entry; the seeded gate must exit 0 on its own seeds, because a project that starts red teaches everyone on day one that the gate is noise. The regime is recorded. PHASE 1c, RECONCILE: git says how it should be, the run record says how it turned out — read both for the area about to be touched and resolve every divergence (the document is stale, the record is wrong, or they genuinely disagree and that is a decision), because starting on an unresolved divergence means building against a system that does not exist. The retro's in-force sections are read IN FULL and its archive is QUERIED by the task's nouns."
+        "check": "MANDATORY stage — never skipped (only sanctioned bypass: the entry-from-super-ux short-circuit). PHASE 1, before the first question: harvest the knowledge sources (references/knowledge-sources.md) — code, THE CODE GRAPH when one is built (references/knowledge-graph.md: graphify query/affected/god-nodes answer reach, which grep cannot; detect graphify-out/graph.json — recommended, never required), CLAUDE.md/AGENTS.md, CONTEXT.md + docs/adr, docs/ + docs/ux, past pipeline briefs and carry-over ledgers, THE RETRO'S STANDING INSTRUCTIONS (docs/evidence/retro.md — read IN FULL, not queried: they are capped at ten and they BIND this run; stamp each one the moment it fires, since that date is the only evidence behind stage 10's cold-retirement rule — references/retrospective.md), the knowledge wiki when installed (obsidian-wiki — recommended, never required; detect ~/.obsidian-wiki/config), and any other repo or hosted doc system the project names as its docs — queried by this task's own terms, with the SOURCE LEDGER written into the brief (a row per source consulted, or an explicit 'none found'; THE GRAPH'S ROW CARRIES ITS MEASURED LAG — commits and days behind HEAD, the signal it was measured with (built_at_commit exact / mtime approximate / unresolvable), and the marker '⚠ not trusted for reach until refreshed' — that exact string, so one marker is greppable across every ledger — on anything but current. A bare build date does NOT satisfy this: it is the graph's own reply about itself, true and self-reported and silent about whether the graph describes the tree this run is about to change — references/knowledge-graph.md -> Measure the lag, and references/gates.md -> False success for the class). PHASE 2, the grill, built into the skill (references/grill.md) — no companion to install. Per its contract: one question at a time, a recommended answer with each, explore the codebase/docs before asking, depth-first, contradictions reconciled; EVERY answer that touches a harvested source is validated against that source — the operator outranks any document, but only out loud, and the losing side is logged for the stage-9 doc update; domain awareness applied (terms challenged against CONTEXT.md, ADRs recorded for hard-to-reverse calls). The autonomy sweep is covered — every stage 1-10 has its blockers pre-resolved (docs sources, branch/tracker policy, test + lint commands, deploy target and authorization, log/health locations, docs+wiki targets, and for UI tasks the design surface: Figma on or text-only, is the Figma MCP connected, and if it is not — ship text-only or stop and connect it, since the UX chain degrades on its own and never blocks; plus, with Figma on, the DESIGN DESTINATION — which team/org by name and which file per surface, App / Web / ASO (the recorded one, a URL the operator gives, or creation in that named team with the creation explicitly authorized), written into the project's canonical record before the first frame, and never created while a recorded file resolves — an unreachable recorded file means stop and ask, never make a replacement) or is explicitly marked 'stop and ask here'. UI verdict recorded (arms super-ux), and for a user-facing task its SURFACE CLASS — surface_class: flagship | product | internal | ad — which selects the visual gate profile for stages 3, 6 and 10 (references/stages.md -> The surface class); model decision recorded. All of it locked into a committed task brief the operator confirms before stage 1. The REQ table is written — one row per independently verifiable deliverable, each naming how it is verified — and frozen: adding later is free, removing or narrowing needs the operator's explicit agreement. The carry-over ledger is seeded. PHASE 1b, THE DOCUMENTATION INVENTORY (references/documentation.md): four questions answered into docs/DOCMAP.md before the interview — where settled things live (the DECISION HOME, and there is exactly one per project: an existing docs/adr/ IS the register and is recorded as such, never duplicated), what each fact's single home is, what a change of type X obliges (THE PROPAGATION MATRIX, non-empty, every row naming the check that enforces it or the word 'review' with a one-line reason), and what proves it (the gate command). A project with no answers gets them seeded — registers, matrix and scripts/check-docs.sh from the skill's templates — and the seeding is recorded as the register's first entry; the seeded gate must exit 0 on its own seeds, because a project that starts red teaches everyone on day one that the gate is noise. The regime is recorded. PHASE 1c, RECONCILE: git says how it should be, the run record says how it turned out — read both for the area about to be touched and resolve every divergence (the document is stale, the record is wrong, or they genuinely disagree and that is a decision), because starting on an unresolved divergence means building against a system that does not exist. The retro's in-force sections are read IN FULL and its archive is QUERIED by the task's nouns."
       }
     },
     {
@@ -65,7 +65,7 @@
       ],
       "gate": {
         "type": "manual",
-        "check": "UX track ran FIRST for user-facing tasks (/ux -> ux-foundation CJM -> ux-flows screens -> ux-scenarios -> /ux-lint green); spec committed and user-reviewed; every user-facing requirement traces to a scenario ID. Every spec section carries covers: REQ-... and every REQ appears in at least one section. With Figma on: the destination the brief named was used — the canonical record (docs/ux/foundation.md -> Design tooling) holds exactly one file, no file was created while a recorded one resolved, 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). COPY and VISUAL are a parallel layer after UX: every user-facing string went through the COPY track or the refusal is recorded, the visual layer went through the VISUAL track or the refusal is recorded, and where both tracks ran their convergence check is recorded - findings with the ruling, or 'Tracks converge: clean'."
+        "check": "UX track ran FIRST for user-facing tasks (/ux -> ux-foundation CJM -> ux-flows screens -> ux-scenarios -> /ux-lint green); spec committed and user-reviewed; every user-facing requirement traces to a scenario ID. Every spec section carries covers: REQ-... and every REQ appears in at least one section. With Figma on: the destination the brief named was used — the canonical record (docs/ux/foundation.md -> Design tooling) names one file per surface (App, Web, ASO), no file was created while a recorded one resolved, and every screens.md frame link's :fileKey is one of the recorded set (a string match, not a judgement — scripts/visual_gate.py filekeys; a key outside the set means the run drew in a file nobody recorded and nobody will open). COPY and VISUAL are a parallel layer after UX: every user-facing string went through the COPY track or the refusal is recorded, the visual layer went through the VISUAL track or the refusal is recorded — and on a flagship, product or ad surface the VISUAL track is checked by its TRACE, not by the fact it ran: the director record at docs/design/<surface>/director-record.md carries the fields its surface_class owes ('scripts/visual_gate.py record <file> --class <surface_class>' exits 0; sheleg-design's own --check-record validator runs where installed and reads NOT_RUN, never PASS, where it is not; 'Mode: declined' with its reason is the refusal and passes), and where both tracks ran their convergence check is recorded - findings with the ruling, or 'Tracks converge: clean'."
       }
     },
     {
@@ -106,7 +106,7 @@
       ],
       "gate": {
         "type": "auto",
-        "check": "full suite green (not just new tests); new/changed code covered including failure paths; no skip/xfail smuggling a red suite past the gate; tests assert real behavior, not mock behavior",
+        "check": "full suite green (not just new tests); new/changed code covered including failure paths; no skip/xfail smuggling a red suite past the gate; tests assert real behavior, not mock behavior. Where the stage-3 VISUAL track ran on a flagship, product or ad surface, THE VISUAL HALF of the look passes too (references/browser.md -> The visual half): the contact sheet — frames over the SCR states x viewport x theme x text x locale, pairwise plus the mandatory pairs, each with its capture record, diffed against its Figma frame or approved baseline, the project linter run, judge items NOT_ASSESSED until calibrated — and 'scripts/visual_gate.py sheet <file> --class <surface_class>' exits 0 (NOT_RUN, exit 3, is not green); re-render budget one, two at most, then unresolved to the person. On internal it is recommended and the linter is the floor",
         "command": "npm test"
       }
     },
@@ -167,7 +167,7 @@
       ],
       "gate": {
         "type": "manual",
-        "check": "Close the circle. FIRST the LADDER WALK (references/audit.md), because the REQ table can only find what was named and lost — a comparison needs two sides and an absence has one: walk each REQ bottom-up through its rungs (decision -> spec section -> contract AND its failure behavior -> plan task -> change -> executed test -> surface/docs), check the seam at each step, order findings BY SEAM not by file, and turn every absence into a new REQ row with its check BEFORE the table is written; findings belonging to a lower layer go back to that layer (spec -> stage 3, plan -> stage 4); record the pass's two counts (new findings vs findings caused by this run's own fixes) so the next pass can tell whether the axis is exhausted. THEN the coverage table: every REQ has a status (verified / partial / deferred / dropped) — none unknown; every verified carries evidence (a passing test name, file:line, a command and its output, or a scenario ID) — 'done' without evidence is downgraded to partial, not upgraded, and a green from a check nobody has watched fail against a planted defect is not evidence at all; every partial names what is missing and where it is tracked; every deferred/dropped has the operator's agreement and, for deferred, a tracker entry; no carry-over row is left unresolved and the ledger's counts are printed beside this verdict, so 'green' never reads as 'verified'; EVERY REPOSITORY IS CLOSED, THE PARENT INCLUDED — a submodule is finished only when its parent points at it, so 'git submodule status' shows no line starting with '+' and every repo is clean and pushed ('git -C <repo> status --porcelain' and 'git -C <repo> log @{u}..HEAD' both empty), because a parent records a submodule as a pointer to one commit and moving the submodule does not move the pointer: neither repo looks wrong alone and the disagreement survives every check that runs inside one; and the operator answers the closing question — here is what you asked for, here is what shipped, here is what is deferred, what is missing? — and signs off. LAST ACT, THE RETROSPECTIVE (references/retrospective.md, written to docs/evidence/retro.md — one file per project, not per run, because every gate in this flow is good at THIS run and blind across runs): STAMP THE RUN FIRST (date, topic, verdict, counts) — the order is load-bearing, not style: the cold-retirement trigger reads the stamp this stage writes, so a prune placed ahead of the stamp can never run on real data; THEN PRUNE — every standing instruction checked against its retirement triggers (it became a check; every path/command/stage it names is gone; it has not fired in the last five run stamps, or in the last sixty days), the list held to its hard cap of ten (at eleven the oldest never-fired row goes — 'they all matter' is the state in which the list stopped being read), and EVERY DELETION LOGGED as one line, never silent; THEN, only if the run diverged, write the entry — symptom with evidence, the stage it surfaced at, the stage that OWNED it, the root cause ('the agent was careless' is not one), the fix by grade (mechanical check > standing instruction with its retire-when written at birth > a note that expires in two runs), and the check that catches it the first time from now on. A retro left empty after a messy run is the failure this file exists to stop, and the retro counts are printed beside this gate's verdict like the carry-over ledger's, so a list that quietly grew back is visible where it happened. EVERY LESSON CARRIES ITS COMMIT: each standing instruction has the SHA that introduced it and the SHA of the run in which it last fired, each log entry and each retirement carries one, the run stamp carries the run's own — a file:line rots at the next edit while 'git show <sha>' reconstructs the whole incident two months later — and every SHA must resolve, which the documentation gate checks with 'git rev-parse --verify'. ROTATION: entries older than the last five run stamps MOVE into docs/evidence/retro/YYYY-QN.md, which is append-only and QUERIED rather than read, so the in-force file stays short enough to be read in full and pruning costs no knowledge. AND THE GATE ITSELF IS PROVEN: every check this close-out leans on — the documentation gate included — has been seen failing once against a planted defect, with the probe recorded, and its ratchet counts are printed beside this verdict (references/gates.md). THE HAND-BACK IS WRITTEN — the request quoted as GIVEN, progress against it, what was solved with evidence, what surfaced unasked, every waiting decision ASKED here with options, and the ambiguity count computed from the four registers; zero prints as zero."
+        "check": "Close the circle. FIRST the LADDER WALK (references/audit.md), because the REQ table can only find what was named and lost — a comparison needs two sides and an absence has one: walk each REQ bottom-up through its rungs (decision -> spec section -> contract AND its failure behavior -> plan task -> change -> executed test -> surface/docs), check the seam at each step — and where the VISUAL track ran, the row visual intent (the director record) <-> final render (the APPROVED contact sheet: 'visual_gate.py sheet ... --require-approval' exits 0 on flagship, product or ad), with the review rounds it took copied from the run ledger's review: lines into the acceptance file — order findings BY SEAM not by file, and turn every absence into a new REQ row with its check BEFORE the table is written; findings belonging to a lower layer go back to that layer (spec -> stage 3, plan -> stage 4); record the pass's two counts (new findings vs findings caused by this run's own fixes) so the next pass can tell whether the axis is exhausted. THEN the coverage table: every REQ has a status (verified / partial / deferred / dropped) — none unknown; every verified carries evidence (a passing test name, file:line, a command and its output, or a scenario ID) — 'done' without evidence is downgraded to partial, not upgraded, and a green from a check nobody has watched fail against a planted defect is not evidence at all; every partial names what is missing and where it is tracked; every deferred/dropped has the operator's agreement and, for deferred, a tracker entry; no carry-over row is left unresolved and the ledger's counts are printed beside this verdict, so 'green' never reads as 'verified'; EVERY REPOSITORY IS CLOSED, THE PARENT INCLUDED — a submodule is finished only when its parent points at it, so 'git submodule status' shows no line starting with '+' and every repo is clean and pushed ('git -C <repo> status --porcelain' and 'git -C <repo> log @{u}..HEAD' both empty), because a parent records a submodule as a pointer to one commit and moving the submodule does not move the pointer: neither repo looks wrong alone and the disagreement survives every check that runs inside one; and the operator answers the closing question — here is what you asked for, here is what shipped, here is what is deferred, what is missing? — and signs off. LAST ACT, THE RETROSPECTIVE (references/retrospective.md, written to docs/evidence/retro.md — one file per project, not per run, because every gate in this flow is good at THIS run and blind across runs): STAMP THE RUN FIRST (date, topic, verdict, counts) — the order is load-bearing, not style: the cold-retirement trigger reads the stamp this stage writes, so a prune placed ahead of the stamp can never run on real data; THEN PRUNE — every standing instruction checked against its retirement triggers (it became a check; every path/command/stage it names is gone; it has not fired in the last five run stamps, or in the last sixty days), the list held to its hard cap of ten (at eleven the oldest never-fired row goes — 'they all matter' is the state in which the list stopped being read), and EVERY DELETION LOGGED as one line, never silent; THEN, only if the run diverged, write the entry — symptom with evidence, the stage it surfaced at, the stage that OWNED it, the root cause ('the agent was careless' is not one), the fix by grade (mechanical check > standing instruction with its retire-when written at birth > a note that expires in two runs), and the check that catches it the first time from now on. A retro left empty after a messy run is the failure this file exists to stop, and the retro counts are printed beside this gate's verdict like the carry-over ledger's, so a list that quietly grew back is visible where it happened. EVERY LESSON CARRIES ITS COMMIT: each standing instruction has the SHA that introduced it and the SHA of the run in which it last fired, each log entry and each retirement carries one, the run stamp carries the run's own — a file:line rots at the next edit while 'git show <sha>' reconstructs the whole incident two months later — and every SHA must resolve, which the documentation gate checks with 'git rev-parse --verify'. ROTATION: entries older than the last five run stamps MOVE into docs/evidence/retro/YYYY-QN.md, which is append-only and QUERIED rather than read, so the in-force file stays short enough to be read in full and pruning costs no knowledge. AND THE GATE ITSELF IS PROVEN: every check this close-out leans on — the documentation gate included — has been seen failing once against a planted defect, with the probe recorded, and its ratchet counts are printed beside this verdict (references/gates.md). THE HAND-BACK IS WRITTEN — the request quoted as GIVEN, progress against it, what was solved with evidence, what surfaced unasked, every waiting decision ASKED here with options, and the ambiguity count computed from the four registers; zero prints as zero."
       }
     }
   ],

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

@@ -48,6 +48,16 @@ surface and docs), checking the seam at each step. It is one pass, scoped to thi
 run's deliverables, and it is the only part of the pipeline that can find a gap
 that was never a row.
 
+**Where the stage-3 VISUAL track ran, the walk carries a row the REQ table cannot:
+visual intent (the director record) ↔ final render (the approved contact sheet)** —
+`audit.md`'s `V→R` seam. Read the record's falsifier, signature moment and rubric
+against the sheet the person approved, frame by frame where they disagree. On a
+`flagship`, `product` or `ad` surface the sheet must be approved — `python3
+scripts/visual_gate.py sheet <file> --class <surface_class> --require-approval` exits
+0 — and the rounds it took (the last `review:` line per surface in the run ledger) are
+written into the acceptance file, because the ledger does not outlive the run and the
+count of human passes is the number this whole layer exists to bring down.
+
 - **An absence found here becomes a new REQ row with its check**, then the table is
   written. The list is frozen against *narrowing*, never against additions
   ([`grill.md`](grill.md) → *The REQ spine*). Writing the table first and appending
@@ -69,6 +79,8 @@ Read all of them before writing anything:
 - git log for the run's branch; the test suite's final output
 - stage 8's post-deploy notes; stage 9's doc/wiki changes
 - for UI tasks: `docs/ux/scenarios.md` statuses and the `/ux-lint` result
+- where the VISUAL track ran: the director record, the approved contact sheet, and the
+  run ledger's `review:` lines
 
 ## Every declared stage is accounted for
 

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

@@ -110,7 +110,8 @@ absence findable.
 | **L5** | Change | the commits — the thing actually in the tree |
 | **L6** | Test | an **executed** assertion, by name — never "the tests pass" |
 | **L7** | Surface | what a user reaches: scenario, screen state, CLI output, runbook |
-| **F** | Frame — *conditional* | UI work with Figma on: one frame per `SCR-NN/<Screen>/<state>`, **in the one file the project recorded**. Not a step in the sequence — a **second, parallel statement of the same surface**, made in pictures |
+| **F** | Frame — *conditional* | UI work with Figma on: one frame per `SCR-NN/<Screen>/<state>`, **in one of the files the project recorded — one per surface (App, Web, ASO)**. Not a step in the sequence — a **second, parallel statement of the same surface**, made in pictures |
+| **V** | Visual intent — *conditional* | UI work where the stage-3 VISUAL track ran: the director record (`docs/design/<surface>/director-record.md`) — the falsifier, the signature moment, the rubric written before any render. Its counterpart **R** is the final render as the person approved it: the contact sheet (`browser.md` → *The visual half*) |
 
 **Audit the seams, not the artifacts.** Each rung is internally consistent most of
 the time — that is exactly what the horizontal pass is good at, and it has already
@@ -128,7 +129,8 @@ done it. What survives lives between rungs:
 | L7→L0 | does the shipped surface satisfy the requirement's **statement**? | it does what the task said and not what the requirement meant |
 | L2→F | *(UI)* does the frame render what the spec **says**? | a frame that promises a capability, limit or number the product does not have |
 | F→L7 | *(UI)* did what shipped match the frame, or did the frame become fiction? | the frame is still the design of record and no longer describes anything that exists |
-| →F | *(UI)* is every frame **in the recorded file**? | a second design file nobody opens, holding real work — the check is a `:fileKey` string match, so it is a gate, not an opinion |
+| →F | *(UI)* is every frame **in a recorded file**? | a design file outside the recorded set — one per surface — that nobody opens, holding real work; the check is a `:fileKey` set membership (`visual_gate.py filekeys`), so it is a gate, not an opinion |
+| V→R | *(UI, VISUAL track ran)* does the **approved contact sheet** carry the intent the **director record** set? | a render that passed every frame check and lost the falsifier, the signature moment or a rubric item the record wrote first; or a sheet nobody approved, standing in for the person's pass. The rounds it took (`review:` lines) go into the acceptance file |
 
 The L7→L0 seam is stage 10's question, expressed as a seam. When it fails, the run
 did every instruction correctly and delivered the wrong thing.
@@ -161,12 +163,16 @@ a deploy, or docs in another repository. **Creating** one is stronger still: it
 needs a named team and an explicit authorization recorded at intake
 ([`grill.md`](grill.md) → *The design destination*).
 
-**And check the file, not just the frames.** Every deep link is
-`figma.com/design/:fileKey/…`, so comparing each `screens.md` link's key against
-the canonical record (`docs/ux/foundation.md` → *Design tooling*) is a string
-match. A key that differs is a **second file with real work in it** — the failure
-that starts with one agent unable to open the recorded file and quietly making a
-new one. Nothing else in the chain notices: the new file is internally consistent,
+**And check the files, not just the frames.** Every deep link is
+`figma.com/design/:fileKey/…`, so checking each `screens.md` link's key against
+the set the canonical record names (`docs/ux/foundation.md` → *Design tooling*: one
+file per surface — App, Web, ASO) is a string match —
+`python3 scripts/visual_gate.py filekeys --record docs/ux/foundation.md --screens
+docs/ux/screens.md`. A key outside the set is a **file nobody recorded, with real work
+in it** — the failure that starts with one agent unable to open the recorded file and
+quietly making a new one. One file per surface is the shape, not one file for every
+frame: a store asset and an app screen have different owners, sizes and reviewers, and a
+single file holding both is the file nobody can hand to either. Nothing else in the chain notices: the new file is internally consistent,
 its frames are named correctly, and the linter is green.
 
 ## How one audit pass runs