task-pipeline-skill 1.89.1 → 1.90.2

package/CHANGELOG.md

@@ -1,3 +1,63 @@
+## v1.90.2 — release evidence survives squash integration
+
+The host-portability payload from v1.90.1 is unchanged. Its release stopped at the
+documentation gate because source-branch test receipts were written as local
+ancestor citations, while squash integration preserves their files but not their
+ancestry. Those historical receipts now link to their immutable GitHub commits.
+The published v1.90.1 tag stays unchanged; this patch carries the corrected evidence.
+
+## v1.90.1 — independent skill payloads on every host
+
+Project audit now carries its own offline method instead of requiring a sibling
+skill's files. Certification includes the four portable verifier procedures with
+body parity against plugin agents. Hook guidance names the shipped adapter and
+requires observed adapter operation; other hosts retain explicit manual gate execution.
+
+## v1.90.0 — Code Connect is kept, and token names are measured against the file
+
+The build stage already said a component with a Code Connect mapping is used, never
+rewritten. Nothing said the mapping had to stay true. A mapping that still names a
+component's old props hands the next agent a snippet that does not compile, and the agent
+reimplements the component, which is the fork the rule exists to prevent. Token names had
+the same gap: rule 4 made `get_variable_defs` the canon, and no check compared it with the
+code. A variable that is `color/primary` in the file and `--brand-primary` in CSS split in
+two without anything noticing. The scope comes from a 2026-10-08 reading of Figma's own
+guidance ([Code Connect integration][fcc-cl], [Figma MCP use cases][fuc-cl], both accessed
+2026-10-08).
+
+Guards: 430 → **430**. The new check is a verb of a shipped script with a suite of its
+own, and the validator is unchanged.
+
+- **`references/build.md` → *Code Connect, kept*.** A component whose API changes updates
+  its Code Connect mapping in the same change, quoting Figma's own line. A core component
+  the file draws and nothing maps gets an **offer** to map it with `/figma-code-connect`,
+  Figma's public plugin skill. Mapping publishes to the file, so it runs only on a go. The
+  rule against rewriting a mapped component stands unchanged. Figma's measured benefit is
+  quoted as **Figma's unaudited number**: a vendor's eval of its own feature, not
+  reproduced here.
+- **`visual_gate.py tokens --figma <variables.json> --css <tokens.css>`, the token drift
+  probe.** It reads the `get_variable_defs` map, the REST export (`meta.variables`) or a
+  `variables` list, and the custom properties the pack's token file declares (comments
+  stripped, `var()` uses not counted). It names each variable with no property, each
+  property with no variable, each variable whose WEB code syntax is not the property the
+  file declares, and two variables that land on one property. Exit `0` PASS · `1` FAIL ·
+  `2` unreadable · `3` NOT_RUN. No export, or an export holding no variables, is NOT_RUN
+  and never PASS. A nested token tree is refused as unreadable, so the check never
+  compares the code with group names.
+- **Wired in** to `references/browser.md` → *The visual half* (the deterministic floor),
+  `references/stages.md` stage 5 (after a task that touches tokens, beside the project
+  linter) and stage 6 (over the whole token file, inside the contact-sheet check). It is
+  also a row in `companion-skills.md` → *Visual lanes* for `figma-code-connect`.
+- **Routing words.** The description now carries `bug` as its own word next to `fix`, so
+  "fix this bug" is claimed by name and not through `bug hunt`. 903 → 908 of 1024 chars,
+  inside the 970 working limit. The body is unchanged at 4748/4750 tokens.
+- **Tests:** `test/visual_gate_test.py` 24 → **40** cases. The 16 new ones are planted
+  defects, and all 16 were watched failing before `tokens` existed. A sweep of 15
+  mutations of the new code was run, and every mutation was killed.
+
+[fcc-cl]: https://developers.figma.com/docs/figma-mcp-server/code-connect-integration/
+[fuc-cl]: https://www.figma.com/resource-library/figma-mcp-use-cases/
+
 ## 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

package/README.md

@@ -587,7 +587,7 @@ must say so.
 ### Held to Anthropic's own Skill authoring guidance
 
 Audited against the four Agent Skills pages. Most of it already held — `name`
-13/64 chars, `description` 903/1024 chars, `SKILL.md` 279/500 lines, all 39 references
+13/64 chars, `description` 908/1024 chars, `SKILL.md` 278/500 lines, all 39 references
 linked **directly** from `SKILL.md`, and the bundle far under the 30 MB ceiling. What
 did not, now does:
 
@@ -991,3 +991,8 @@ updates is not the session that gets the new ones.
 
 MIT © 2026 ssheleg. Third-party portions (the ported stage doctrine) are credited
 and licensed in [LICENSE](LICENSE) → *Third-party*.
+
+Portable certification procedures ship in `assets/verifier-unit.md`,
+`assets/verifier-seam.md`, `assets/verifier-product.md` and `assets/verifier-visual.md`.
+A standalone `project-audit` install includes `references/portable-method.md`;
+it does not require a sibling pipeline installation or a network fetch.

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.89.1 |
+| **Version** | 1.90.2 |
 | **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,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.89.1",
+  "version": "1.90.2",
   "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"

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.89.1",
+  "version": "1.90.2",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

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

@@ -30,6 +30,13 @@ If you find yourself reading a component's source to decide something, stop —
 finding belongs to the unit tier. If you are checking whether the README describes the
 screen, that is the product tier's.
 
+## Contents
+
+- What you actually do
+- `breaks` or `risk`, and the line is not taste
+- The report — all eight keys, and `[]` is an answer
+- Three ways this goes wrong
+
 ## What you actually do
 
 1. **Run the deterministic checks first, and quote them.**

package/plugins/task-pipeline/skills/evidence-docs/references/hooks.md

@@ -23,15 +23,14 @@ that acts *while the agent is working* rather than after the commit.
 
 ## The limit, before the capability
 
-**Hooks exist only in Claude Code.** On Cursor, Codex and the other agents a skill
-can be installed and read, but there is no `PreToolUse`, so nothing blocks anything.
-On those agents the same rules run as a self-check written into the skill body, and
-the run is recorded **`ungated`**.
+**This package ships a Claude Code hook adapter.** Other hosts may expose hooks,
+but capability does not register this package's adapter. Check the active host's
+version, adapter registration, event payload and a planted refusal before claiming
+enforcement. Without a verified adapter, run the same gates explicitly and record
+**`ungated`**. Native hook support alone is not protection for this project.
 
-**Never describe a project as protected when its agents run outside Claude Code.**
-The gap between "the rule exists" and "the rule is enforced" is invisible from
-inside a transcript, and a false guarantee is worse than a stated absence: everyone
-downstream stops checking.
+Never describe a project as protected merely because a rule or a hook file exists.
+A false guarantee makes downstream readers stop checking.
 
 > **Provenance.** Every contract below is quoted from the Claude Code hooks
 > reference (`code.claude.com/docs/en/hooks`), fetched **2026-08-03**. Re-fetch
@@ -271,7 +270,7 @@ entries carrying one id — which is the exact failure the lease existed to prev
 
 | Excuse | Reality |
 |---|---|
-| "The hook is installed, so the repo is protected" | Only in Claude Code, and only while the guard exits 2. Any other exit code fails open silently. |
+| "The hook is installed, so the repo is protected" | Only after this adapter was verified on the active host. For the documented Claude command hook, exit 2 refuses; other errors fail open. |
 | "It's fine, the guard can't crash" | Then it costs one line to make crashing block instead of pass. Write the line. |
 | "I'll match `*` and filter inside the script" | Now every tool call pays your script's startup. Match narrowly; the matcher is free and the script is not. |
 | "The hook is slow, I'll disable it for now" | "For now" survives the session and the memory of why. Fix the throttle. |

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

@@ -31,15 +31,16 @@ next audit reads.
 
 | | Owns | Reach for it when |
 |---|---|---|
-| [`references/audit.md`](../task-pipeline/references/audit.md) | the **method** — the L0→L7 ladder, seams, axis rotation | one deliverable is being walked inside a run |
+| [`references/portable-method.md`](references/portable-method.md) | the **method** — the L0→L7 ladder, seams, axis rotation | one deliverable is being walked inside a run |
 | this skill | the **procedure** — cold start, probes, production, the report | a whole project is the subject |
 | `/skill-audit` (make-skill) | a skill's construction against the standard | the thing audited is a skill or plugin |
 | `/ux-audit` (super-ux) | code against documented scenarios | the question is user-facing behaviour |
 | `/seo-aeo-audit` (seo-aeo-audit) | a public surface's search and answer-engine visibility | the question is whether a machine will find it |
 
-**The method is not restated here.** Phase 4 below hands off to `audit.md` and
-comes back; a second copy of the ladder would be a second rule, and the two
-would disagree within a release.
+**Read `references/portable-method.md` before phase 4.** It carries the standalone
+audit floor and needs neither a sibling skill nor network access. The companion
+task-pipeline audit, backlog and prioritisation references are optional deeper
+reading when installed; their absence never blocks this procedure.
 
 ## The six phases
 
@@ -102,7 +103,7 @@ worse than no figure, because it is quoted with the authority of a measurement:
 
 ### 4. Seams — hand off to the ladder
 
-Now, and only now, walk `audit.md`'s ladder over the capabilities the discovery
+Now, and only now, walk the local portable method's ladder over the capabilities the discovery
 found. Bottom-up, seam-ordered. Absences found here are findings like any other.
 
 ### 5. Report — two files, one command
@@ -116,10 +117,10 @@ what ran are the same object.
 
 **This skill commits nothing.** Findings leave as board rows in the project's
 own vocabulary, priced with **the board header's declared formula** — the shipped
-default is `Sev × Blast + age_bonus` ([`references/backlog.md`](../task-pipeline/references/backlog.md), the pipeline's
-board doctrine) — and the operator accepts them. Effort never ranks inside an
+default is `Sev × Blast + age_bonus` ([`references/portable-method.md`](references/portable-method.md),
+the local priority contract) — and the operator accepts them. Effort never ranks inside an
 audit: what a fix costs is the fixer's decision, not the finder's
-([`references/prioritisation.md`](../task-pipeline/references/prioritisation.md)). An audit
+([`references/portable-method.md`](references/portable-method.md)). An audit
 that edits while it reads cannot be re-run to check itself.
 
 ## A finding keeps its axes apart, or it is a guess wearing a verdict
@@ -198,7 +199,7 @@ refused at construction.
 
 **`blind` is the whole design.** Without it, a probe that could not look and a
 probe that found nothing produce the same empty section, and a reader takes the
-second meaning every time. This is `audit.md`'s *silence is not a reading*
+second meaning every time. This is the local method's *silence is not a reading*
 raised from a command to a probe: a zero exit with no output has not answered.
 
 The page renders the blind list as a section of its own, never an appendix.

package/plugins/task-pipeline/skills/project-audit/references/portable-method.md

@@ -0,0 +1,93 @@
+# Portable project-audit method
+
+Read before phase 4 or pricing proposed findings. This is the standalone floor;
+no sibling skill, plugin agent or network fetch is required. The full pipeline's
+references explain the same ladder in delivery contexts, but are optional here.
+
+## Walk the ladder and its seams
+
+For one discovered capability at a time, record an artifact or an explicit gap
+at each rung. Never invent a missing brief or claim an unexecuted test passed.
+
+| Rung | Required evidence |
+|---|---|
+| L0 | Requirement and named check |
+| L1 | Recorded decision, ADR or accepted context term |
+| L2 | Design/specification covering the requirement |
+| L3 | Exact contract/schema and caller-visible failure behavior |
+| L4 | Task and its written acceptance criterion |
+| L5 | Actual committed implementation |
+| L6 | Executed assertion and its output, with source/artifact identity |
+| L7 | Reachable user surface: screen, CLI, scenario or runbook |
+
+Walk L0→L1→L2→L3→L4→L5→L6→L7, then L7→L0. Ask whether each
+preceding statement actually reached its dependent artifact; findings are ordered
+by the broken seam, not by the file. The last seam checks the original outcome,
+not merely whether the implementation followed its task.
+For Figma-enabled UI, compare spec→recorded frame→actual surface and ensure every
+frame belongs to the project's recorded file set. If visual intent was specified,
+compare the director record with the approved render/contact sheet. No browser,
+design tool or approval receipt means that comparison remains unverified.
+
+## Evidence and missing capabilities
+
+Every finding states the mechanism, reproduction or counterexample, exposure,
+observed incidence and impact uncertainty separately. Missing, blind, UNKNOWN and
+NOT_RUN are not zero and are not PASS. Quote the command and observed output or
+source location; an empty output must be distinguished from a broken invocation.
+Check output shape before believing a silent detector. Every check relied on must
+fire against a planted defect: plant it in an isolated fixture, observe rejection,
+remove it, then observe the clean result. Record that proof; disclosure alone is
+not detector acceptance. A check without this proof remains unverified and the
+dependent audit conclusion incomplete or UNKNOWN, never clean. Scope a runtime conclusion to the artifact/version actually
+observed; source presence is not installation, deployment or provider acceptance.
+When two copies disagree, establish which one is actually selected and consumed
+before choosing the direction of a fix. Do not discard either side as stale by taste.
+
+The collector's JSON and HTML are evidence about probes it executed. Add the
+manual seam findings and limitations to the human report; do not claim the
+collector performed judgment it cannot make. No network or credentials: use the
+available committed evidence and label the missing production probes blind.
+
+## Rotate the reading
+
+After the seam pass, choose a different axis rather than repeating effort:
+
+1. Invariants across deliverables: names, enums, owners and contracts agree.
+2. One defect class swept end to end: all error paths, counts or state transitions.
+3. Code graph against the documented modules, when graph evidence exists.
+4. False success: what could still appear green if the protected behavior were absent?
+5. Re-derivation: recompute an important result by a genuinely different method.
+
+Record new product findings versus corrections to the audit itself. If the latter
+dominate, rotate the axis. A repeated defect class deserves a proposed executable
+guard, with a planted defect proving detection; do not edit the project during an
+audit. Uncheckable claims remain disclosed, never removed to improve a score.
+
+## Proposed rows and priority
+
+Use the project's board header and column names, never positional assumptions.
+Each proposed row names the finding, evidence, affected surface, owner, acceptance
+check and dependencies. Preserve the project formula exactly. If no board formula
+exists, disclose this default for findings: `Sev × Blast + age_bonus`, with Sev and
+Blast each 1–3 and explicitly judged; age_bonus is 1 after 14 days and 2 after 30.
+Compute using the recorded finding date and audit date. Do not invent an age,
+severity or blast where unknown. Effort does not rank an audit finding.
+When product work and findings compete, defer to the project's prioritisation
+contract and operator's named task; this audit does not silently choose another job.
+Accepted waivers remain decisions with a measured revisit condition, not open debt
+that accumulates priority. Findings are proposals until accepted through the owning
+project process. The audit changes no application, deployment or shared board.
+
+At opening, measure the work-list from its owning register. At closing, remeasure
+it from current state and print both counts and the actual changes beside them;
+never reuse the opening list as the closing truth. A missing register or inaccessible
+measurement is UNKNOWN and leaves that conclusion incomplete, not an invented zero.
+
+Close when discovered capabilities and required rungs are accounted for and every
+relied-on check has demonstrated detection of a planted defect. Unavailable proof
+is explicitly incomplete, with the dependent conclusions unverified. Always write
+the JSON sidecar. Produce and inspect HTML only when `--report` was requested;
+record `--no-open` when used. Without `--report`, JSON-only delivery is complete
+when the other conditions hold. The sidecar and requested human report name exactly
+what was and was not verified, including the opening/closing work-list comparison.

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

@@ -1,6 +1,6 @@
 ---
 name: task-pipeline
-description: "Use when work changes the repository — feature, fix, refactor, migration, integration, rewrite, adoption or hardening; фича, фикс, рефактор, миграция, интеграция, доработать, починить, внедрить, перевести — or when the output is a finding that lands in it: audit/аудит, bug hunt/проверь ошибки, production check/проверь прод, PR review/ревью PR — or on 'run this through the pipeline' / 'прогони по конвейеру', 'full cycle, the full cycle' / 'полный цикл', /task-pipeline. Runs a substantial task through an intake grill, docs study, brainstorm, spec, plan, build, tests, deploy, post-deploy, docs/wiki sync and acceptance with explicit gates. 'checkup' / 'чекап' reports unconfirmed releases; 'setup' audits existing docs. Not for: answering a question, explaining code, a typo or a one-line edit, a mechanical rename, reconnaissance that lands nothing — say 'no pipeline' / 'без пайплайна' to opt out."
+description: "Use when work changes the repository — feature, fix, bug, refactor, migration, integration, rewrite, adoption or hardening; фича, фикс, рефактор, миграция, интеграция, доработать, починить, внедрить, перевести — or when the output is a finding that lands in it: audit/аудит, bug hunt/проверь ошибки, production check/проверь прод, PR review/ревью PR — or on 'run this through the pipeline' / 'прогони по конвейеру', 'full cycle, the full cycle' / 'полный цикл', /task-pipeline. Runs a substantial task through an intake grill, docs study, brainstorm, spec, plan, build, tests, deploy, post-deploy, docs/wiki sync and acceptance with explicit gates. 'checkup' / 'чекап' reports unconfirmed releases; 'setup' audits existing docs. Not for: answering a question, explaining code, a typo or a one-line edit, a mechanical rename, reconnaissance that lands nothing — say 'no pipeline' / 'без пайплайна' to opt out."
 license: MIT
 compatibility: "Doctrine runs on any agent. The bundled scripts need python3; the run needs git. Missing either degrades, never blocks — the graph verbs and seeded gates go unused, and the run says so."
 ---
@@ -139,8 +139,7 @@ Three things the grill does beyond clarifying the request, each in full in
 
 ## How to run
 
-1. Restate the task in one line. Create a **TaskList: one task per stage, starting
-   with stage 0** (survives context loss; lets you resume). Then run the
+1. Restate the task in one line. Track each stage from 0 using the host task tool or a prose checklist (for resume). Then run the
    **companion preflight** (`references/companion-skills.md`): the stage doctrine
    is built in, so this only checks the *optional* companions (super-ux for UI
    tasks, context7, wiki-update, graphify) and emits ONE block covering them

package/plugins/task-pipeline/skills/task-pipeline/assets/verifier-product.md

@@ -0,0 +1,91 @@
+# Product tier — what the product now says, and whether it is still true
+
+You are the **furthest** of three readings. One agent has the diff and one has the
+call graph; you will see neither report and neither will see yours. Blind is the
+point, and at this distance it matters most: an agent that has just read a
+convincing account of the implementation will paraphrase it back as product truth.
+
+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. 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
+
+1. **The requirement, in the words the product uses.** The node's `serves` is the
+   standard; the product's own wording of it is the thing that must still hold.
+2. **The documents that describe this behaviour.** `docs/`, `README`, the
+   changelog, `CONTEXT.md`, ADRs, the runbook. Where `docs/ux/scenarios.md` exists
+   it is the source of truth for user-facing behaviour — `super-ux` owns it, and a
+   change to user-facing behaviour is supposed to update it in the same change.
+3. **The strings a person sees.** An error message, an empty state, a label, an
+   email. A behaviour change that leaves the old wording in place is a lie shipped
+   in the product's own voice.
+4. **The neighbouring features that share this path.** Not the callers — the
+   *features*. Two flows that both end at this behaviour, a report that counts
+   these events, an export, a webhook, an admin screen, a metric on a dashboard.
+5. **The interaction the change creates.** What is now possible that was not, and
+   what does the rest of the product do when it happens? A new state usually has to
+   be handled in three places nobody listed: a list view, a filter, and a total.
+
+## The six things that are true at this level and invisible below it
+
+- **A documented behaviour is now false.** The commonest, and the cheapest to fix
+  in the same change.
+- **A scenario no longer holds** — the steps still describe the old path.
+- **A user-visible change nobody wrote down.** It shipped, and support will find it.
+- **A second feature reaches the same behaviour** and was not considered.
+- **A number the product reports moves** — a count, a total, a metric — because the
+  set it counts changed.
+- **A migration or a mixed state.** Data written before the change, in-flight
+  requests, a cached response, a client on the old version.
+
+## `breaks` or `risk`
+
+- **`breaks`** — the product now claims something untrue, or a documented behaviour
+  or scenario is contradicted, or another feature is broken by the interaction.
+  Carries a `check` that will prove the fix. *"Documentation ships in the same
+  change as the code; in the next ticket it never ships at all."*
+- **`risk`** — a claim you cannot resolve without the operator, a metric that
+  probably moves, a mixed-state window that probably closes on its own. It ships,
+  named, and reaches the closing verdict as a blocker the run can continue around.
+
+## The report — all eight keys, and `[]` is an answer
+
+```json
+{
+  "node": "N-007",
+  "tier": "product",
+  "verdict": "fail",
+  "scope":        ["docs/ux/scenarios.md:S-04 — the checkout decline flow",
+                   "README.md:120-140 — 'a declined card raises PaymentError'",
+                   "the two features that reach this behaviour: checkout, and the retry job",
+                   "the admin Payments list, which filters on state"],
+  "confirms":     ["scenario S-04's steps still describe what the product does"],
+  "findings":     [{ "what": "the README documents an exception the product no longer raises",
+                     "where": "README.md:131", "severity": "breaks",
+                     "fix": "state the return value, and note the version it changed in",
+                     "check": "judgement — the README's payment section read against the new return path" }],
+  "evidence":     ["read docs/ux/scenarios.md:S-04 — steps unchanged by this behaviour",
+                   "grep -rn 'PaymentError' docs README.md → 2 hits, both in the payment section"],
+  "not_examined": ["whether the finance export counts declines, which needs the operator"]
+}
+```
+
+**A `check` may be a judgement here, and it is written as one** — named, not dressed
+as an exit code. `references/gates.md` says which is which; recording a judgement as
+a command is how a document acquires proof it never had.
+
+## Three ways this goes wrong
+
+| Temptation | Why it is wrong |
+|---|---|
+| «The implementation is sound» | Not your level, and you are the agent least equipped to say it. Two readings already covered the code with context you do not have |
+| «No docs mention this» | Then your `scope` names the searches that found none, and *nothing documents a user-facing behaviour* is itself a finding |
+| «Docs can follow in the next ticket» | In the next ticket they never ship. A behaviour change with no document is `breaks` at this tier, and the fix is one paragraph |
+
+Doctrine: `references/certification.md`. What proof a document owes:
+`references/documentation.md`. Scenarios: `super-ux`, `docs/ux/scenarios.md`.

package/plugins/task-pipeline/skills/task-pipeline/assets/verifier-seam.md

@@ -0,0 +1,91 @@
+# Seam tier — what depends on the change, and did not change with it
+
+You are the **middle** of three readings. One agent is reading the diff itself and
+another is reading the product around it; you will never see either report, and
+they will never see yours. Blind is the point — three readings that inform each
+other are one opinion with three signatures.
+
+Your subject is **the seam**: everything that can reach the changed code, and
+everything the changed code can reach. Not the hunks. If your `scope` is mostly
+the same lines the diff shows, you have re-run the unit tier and the middle level
+went unread — which is the level the user's whole reason for this gate lives at.
+
+## Find the neighbours before you judge anything
+
+You cannot report on dependents you never enumerated, so enumerate first and put
+the enumeration in `scope`:
+
+1. **Callers.** Grep the changed symbols across the repository, including tests,
+   scripts and configuration. A call site in a fixture is a call site.
+2. **Callees.** What the change now calls that it did not before, and what it
+   stopped calling. A dropped call is invisible in a diff read forwards.
+3. **Implementors and subclasses.** If the change touched an interface, a base
+   class, a protocol or a duck-typed contract, every implementation is a dependent.
+4. **Shared state.** A module-level constant, a cache, a global, a database column,
+   a file on disk, an environment variable, a lock. Two readers of one mutable
+   thing are a seam even with no call between them.
+5. **The neighbours' tests.** A test that exercises a caller is your evidence that
+   the caller still works — or your finding that nothing covers it.
+6. **A second implementation of the same rule.** The duplicate that did *not* get
+   the fix is the single most common thing this tier exists to catch.
+
+Where a code graph exists (`graphify-out/graph.json`), it answers *reach* directly
+and grep cannot — `references/knowledge-graph.md`.
+
+## The seven contracts that move without anybody noticing
+
+- **Signature** — an argument added, reordered, renamed, or made required
+- **Return shape** — a field added or dropped, a list becoming a generator, `None`
+  becoming an empty list, a dict becoming an object
+- **Errors** — a new exception a caller does not catch, or an exception replaced by
+  a return value the caller reads as success
+- **Nullability** — something that could not be absent now can
+- **Ordering and timing** — a sort dropped, a call moved before or after another,
+  an operation that used to be atomic
+- **Units and encoding** — seconds to milliseconds, cents to units, bytes to a
+  string, a naive datetime to an aware one
+- **Idempotence and side effects** — a function that could be called twice and now
+  cannot, or a write that used to happen once
+
+For each one you find, name the **dependent** in `where`, not the change. The
+change is the unit tier's subject; the thing that will break is yours.
+
+## `breaks` or `risk`
+
+- **`breaks`** — a dependent is now wrong, or a contract moved under one and
+  nothing updated it. Carries a `check` that will prove the fix, because the
+  finding becomes a node the next round has to close.
+- **`risk`** — a dependent that is *probably* fine and nothing proves it: a caller
+  with no test, a duplicate implementation that happens to agree today. It ships,
+  and it reaches the closing verdict as a blocker the run can continue around.
+
+## The report — all eight keys, and `[]` is an answer
+
+```json
+{
+  "node": "N-007",
+  "tier": "seam",
+  "verdict": "fail",
+  "scope":        ["3 callers of charge(): api/checkout.py:44, jobs/retry.py:19, tests/test_api.py:120",
+                   "1 other implementation of the decline rule: legacy/billing.py:301",
+                   "shared: PAYMENT_STATES in src/pay/states.py, read by both"],
+  "confirms":     ["both live callers already treat Declined as a value, so the new return path is handled"],
+  "findings":     [{ "what": "legacy/billing.py still raises on a decline, so the two paths disagree",
+                     "where": "legacy/billing.py:301", "severity": "breaks",
+                     "fix": "route legacy through charge() or apply the same rule",
+                     "check": "pytest tests/test_legacy_decline.py -q" }],
+  "evidence":     ["grep -rn 'charge(' → 3 call sites, listed in scope",
+                   "pytest tests/test_api.py -q → 12 passed"],
+  "not_examined": ["the retry job's integration test, which needs a broker this box has no access to"]
+}
+```
+
+## Three ways this goes wrong
+
+| Temptation | Why it is wrong |
+|---|---|
+| «The diff looks correct» | You were not asked about the diff. Another agent has it, with more context than you, and your saying so leaves the seam unread |
+| «Nothing calls it» | Then say so in `scope` with the search you ran, including tests and config. *Nothing calls it* is a finding when something should |
+| «The callers' tests pass» | Which callers, and did any test exercise the path that moved? A suite that never reached the seam proves the suite ran |
+
+Doctrine: `references/certification.md`. Reach: `references/knowledge-graph.md`.

package/plugins/task-pipeline/skills/task-pipeline/assets/verifier-unit.md

@@ -0,0 +1,79 @@
+# Unit tier — the code that changed, and nothing else
+
+You are the **closest** of three readings. Two other agents are reading the same
+node one and two levels out, and you will never see their reports. That is
+deliberate: three readings that inform each other are one opinion with three
+signatures, and the disagreement between blind readings is the instrument.
+
+Your subject is **the diff and the unit it lands in.** The functions, methods,
+classes and branches that changed, plus whatever in the same file or module the
+change reads and writes. If you find yourself opening a caller in another module
+to decide something, stop — that finding belongs to the seam tier and reporting it
+as yours costs the certification a level.
+
+## What you actually do
+
+1. **Read the node's `serves`.** The REQ or goal clause is the standard. Not what
+   the diff does — what was asked.
+2. **Run the node's `check`.** One command, or the named judgement where no
+   command decides it. Its output is your first `evidence` row. Not `npm test`
+   when the node named something narrower.
+3. **Read every changed hunk against the requirement**, and then read the parts of
+   the unit the hunk touches but the diff does not show — the other branches of the
+   same function, the sibling method that shares the field, the error path.
+4. **Look for the five things that break a unit from inside:**
+   - a branch the change added that nothing exercises
+   - an error or empty path the change routes into differently than before
+   - a boundary the change moved (off-by-one, inclusive/exclusive, first/last)
+   - state the change mutates that another method in the same class assumes
+   - a value the change computes twice, so the two can disagree
+5. **Say what you read.** `scope` is a list of what you actually opened, with
+   `file:line` ranges. A pass on an empty `scope` is refused by
+   `graph.py certify` by name, as a rubber stamp — and it is right to.
+
+## `breaks` or `risk`, and the line is not taste
+
+- **`breaks`** — the node is not done. The requirement is unmet, or the change is
+  wrong on a path a caller can reach. Every `breaks` finding carries a `check`:
+  the command or judgement that will prove the fix, because the finding becomes a
+  node the next round has to close.
+- **`risk`** — found, judged survivable, and named. It ships, and it appears in the
+  closing verdict as a blocker the run can continue around. Use it for the thing
+  you would say in review and would not block on.
+
+There is no third value, because a certification that admits a maybe admits
+everything.
+
+## The report — all eight keys, and `[]` is an answer
+
+```json
+{
+  "node": "N-007",
+  "tier": "unit",
+  "verdict": "pass",
+  "scope":        ["src/pay/charge.py:88-140 — charge() and its three branches",
+                   "src/pay/charge.py:210-232 — _retry, which charge() now calls"],
+  "confirms":     ["a declined card returns Declined instead of raising, which REQ-004 asked for"],
+  "findings":     [{ "what": "…", "where": "src/pay/charge.py:131",
+                     "severity": "breaks", "fix": "…", "check": "…" }],
+  "evidence":     ["pytest tests/test_charge.py::test_declined -q → 1 passed",
+                   "read charge() at src/pay/charge.py:88-140"],
+  "not_examined": ["the retry backoff constants, which no test in this unit covers"]
+}
+```
+
+`not_examined` is the field that keeps a pass honest: it is what you saw and could
+not check. It flows into the closing verdict as `not_verified`, which is what
+*present and unchecked* means one level up. An empty list is a valid answer and
+silence is not.
+
+## Three ways this goes wrong
+
+| Temptation | Why it is wrong |
+|---|---|
+| «The suite is green, so it is done» | The node serves a requirement, not a suite. A green run that never exercised the requirement proves the run happened |
+| «This caller looks wrong too» | Not your level. Say it in `not_examined` if you must, and let the seam tier find it with the context to judge it |
+| «Nothing to report, pass» | Then `scope` says what you read and `confirms` says what is now true. A pass that names neither is the one thing this tier cannot return |
+
+Doctrine: `references/certification.md`. The node's own contract:
+`references/work-graph.md`.

package/plugins/task-pipeline/skills/task-pipeline/assets/verifier-visual.md

@@ -0,0 +1,115 @@
+# 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.
+
+## Contents
+
+- What you actually do
+- `breaks` or `risk`, and the line is not taste
+- The report — all eight keys, and `[]` is an answer
+- Three ways this goes wrong
+
+## 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/skills/task-pipeline/references/browser.md

@@ -187,7 +187,17 @@ the close-out — the same rule as every other refusal in the pipeline.
 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.
+   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,

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

@@ -59,10 +59,16 @@ that reads no code is not the soft one.
 | `seam` | everything that can reach the change — callers, callees, implementors, shared state, the neighbours' tests | a contract that moved under a dependent; the duplicate that did not get the fix |
 | `product` | documentation, scenarios, user-visible strings, and the neighbouring features that share this path | a documented behaviour that is now false; an interaction nobody listed |
 
-Agents: [`../../../agents/verifier-unit.md`](../../../agents/verifier-unit.md),
-[`verifier-seam.md`](../../../agents/verifier-seam.md),
-[`verifier-product.md`](../../../agents/verifier-product.md) — and, on a visual surface,
-[`verifier-visual.md`](../../../agents/verifier-visual.md), below.
+Agents: [`verifier-unit.md`](../assets/verifier-unit.md),
+[`verifier-seam.md`](../assets/verifier-seam.md),
+[`verifier-product.md`](../assets/verifier-product.md) — and, on a visual surface,
+[`verifier-visual.md`](../assets/verifier-visual.md), below. These portable procedures live inside the skill.
+Use host-native delegation when available; without it, execute the same tier
+procedures inline and disclose that self-review lacks independent contexts.
+Do not count inline passes as independent certification or close the graph on
+that basis: independence-dependent gates remain incomplete/unverified until
+independent review is available.
+The Claude plugin agent definitions carry the same bodies with host frontmatter.
 
 ## The fourth reading — `visual`, on a flagship or product surface
 

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

@@ -100,6 +100,7 @@ required; an absent one is a check recorded as NOT_RUN with its reason.
 | 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.

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

@@ -23,15 +23,14 @@ that acts *while the agent is working* rather than after the commit.
 
 ## The limit, before the capability
 
-**Hooks exist only in Claude Code.** On Cursor, Codex and the other agents a skill
-can be installed and read, but there is no `PreToolUse`, so nothing blocks anything.
-On those agents the same rules run as a self-check written into the skill body, and
-the run is recorded **`ungated`**.
+**This package ships a Claude Code hook adapter.** Other hosts may expose hooks,
+but capability does not register this package's adapter. Check the active host's
+version, adapter registration, event payload and a planted refusal before claiming
+enforcement. Without a verified adapter, run the same gates explicitly and record
+**`ungated`**. Native hook support alone is not protection for this project.
 
-**Never describe a project as protected when its agents run outside Claude Code.**
-The gap between "the rule exists" and "the rule is enforced" is invisible from
-inside a transcript, and a false guarantee is worse than a stated absence: everyone
-downstream stops checking.
+Never describe a project as protected merely because a rule or a hook file exists.
+A false guarantee makes downstream readers stop checking.
 
 > **Provenance.** Every contract below is quoted from the Claude Code hooks
 > reference (`code.claude.com/docs/en/hooks`), fetched **2026-08-03**. Re-fetch
@@ -271,7 +270,7 @@ entries carrying one id — which is the exact failure the lease existed to prev
 
 | Excuse | Reality |
 |---|---|
-| "The hook is installed, so the repo is protected" | Only in Claude Code, and only while the guard exits 2. Any other exit code fails open silently. |
+| "The hook is installed, so the repo is protected" | Only after this adapter was verified on the active host. For the documented Claude command hook, exit 2 refuses; other errors fail open. |
 | "It's fine, the guard can't crash" | Then it costs one line to make crashing block instead of pass. Write the line. |
 | "I'll match `*` and filter inside the script" | Now every tool call pays your script's startup. Match narrowly; the matcher is free and the script is not. |
 | "The hook is slow, I'll disable it for now" | "For now" survives the session and the memory of why. Fix the throttle. |

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

@@ -473,7 +473,13 @@ never that the work was skipped quietly.
   `surface_class`, the project linter runs here too**, after each task that changes a
   rendered surface — `python3 scripts/visual_gate.py lint <dir>`; an S1 finding is
   fixed in the task, and NOT_RUN (exit 3) is recorded as such
-  ([`browser.md`](browser.md) → *The visual half*). A slop marker caught while the
+  ([`browser.md`](browser.md) → *The visual half*). **With Figma on, the token drift
+  probe runs beside it** after a task that touches the token file or a tokenised
+  component: `python3 scripts/visual_gate.py tokens --figma <variables.json> --css
+  <tokens.css>`. A FAIL is fixed in the task, renaming one side to match the other.
+  No export is NOT_RUN, recorded as such. A component whose API the task changed
+  updates its Code Connect mapping in the same change
+  ([`build.md`](build.md) → *Code Connect, kept*). A slop marker caught while the
   implementer is dispatched costs a line; caught on the contact sheet it costs a round. Stage 6 repeats this over the whole tree; this one catches it while the
   implementer that wrote it is still dispatched. The matrix pointed this companion at
   stages 5–6 from the day it was added and **this stage had never named it** — found by
@@ -550,7 +556,9 @@ never that the work was skipped quietly.
   `ad` surface, stage 6 also owes **the contact sheet** — frames over the `SCR-NN` states
   × viewport × theme × text × locale (pairwise, plus the mandatory pairs), each with its
   capture record, diffed against its Figma frame or approved baseline, the project
-  linter run, and the rubric read by a judge that is not the builder — and its command
+  linter run, the token drift probe run over the whole token file where Figma is on
+  (`visual_gate.py tokens`; NOT_RUN without an export, never PASS), and the rubric
+  read by a judge that is not the builder — and its command
   exits 0: `python3 scripts/visual_gate.py sheet <contact-sheet.json> --class
   <surface_class> --artifact-root <frames>` (NOT_RUN, exit 3, is not green). On
   `internal` it is recommended and the linter is the floor. The re-render budget is

package/plugins/task-pipeline/skills/task-pipeline/scripts/visual_gate.py

@@ -15,6 +15,11 @@
     visual_gate.py filekeys --record <foundation.md or brief> --screens <screens.md> [--json]
         stage 3 with Figma on: every frame link's file key is one of the files the project
         recorded — one per surface (App, Web, ASO), never a file nobody recorded
+    visual_gate.py tokens   --figma <variables.json> --css <tokens.css> [--json]
+        stages 5–6 with Figma on, the token drift probe: every variable name exported from
+        the file (`get_variable_defs`, or the REST export) has its CSS custom property in
+        the pack's token file and the reverse, and WEB code syntax, where set, names the
+        property the file actually declares. No export is NOT_RUN (exit 3), never PASS
 
 `<surface_class>` is the brief's stage-0 answer: flagship | product | internal | ad. It
 selects what each check owes (`references/stages.md` → stage 0, *The surface class*).
@@ -536,6 +541,134 @@ def cmd_filekeys(a):
     return _emit(a, "filekeys", "FAIL" if problems else "PASS", problems, notes)
 
 
+# --- token-name drift: Figma variables against the pack's CSS custom properties ---
+# A token that has one name in the file and another in code has quietly split in two, and
+# nothing downstream notices: `get_design_context` hands the agent the Figma name, the agent
+# writes a raw value because no property answers to it, and the screen still looks right.
+
+CSS_DECL = re.compile(r"(?<![\w-])(--[A-Za-z0-9_-]+)\s*:")
+CS_PROP = re.compile(r"\s*(?:var\(\s*)?(--[A-Za-z0-9_-]+)\s*(?:,[^)]*)?\)?\s*")
+# Keys a variable's own record can carry. A dict value with none of them is a token GROUP
+# (a nested design-token tree), not a variable, and reading its key as a name would compare
+# the code against the group names.
+VAR_KEYS = ("codeSyntax", "value", "$value", "resolvedType", "type", "valuesByMode")
+
+
+def css_property(name):
+    """The CSS custom property a Figma variable name maps to when it carries no code syntax:
+    `Color/Text Muted` → `--color-text-muted`, `fontSize/bodyLarge` → `--font-size-body-large`.
+    A convention, not a law — WEB code syntax, where the file sets it, overrides it."""
+    s = re.sub(r"([a-z0-9])([A-Z])", r"\1-\2", name)
+    return "--" + re.sub(r"[^A-Za-z0-9]+", "-", s).strip("-").lower()
+
+
+def figma_variables(doc):
+    """[(name, web_code_syntax or None)] from a variable export. Accepts the map
+    `get_variable_defs` returns (name → value), the REST export (`meta.variables`, id →
+    variable) and a `variables` list. Raises ValueError on any other shape."""
+    if isinstance(doc, dict) and isinstance(doc.get("meta"), dict) and "variables" in doc["meta"]:
+        doc = doc["meta"]["variables"]
+    elif isinstance(doc, dict) and isinstance(doc.get("variables"), (list, dict)):
+        doc = doc["variables"]
+
+    def one(v):
+        cs = v.get("codeSyntax")
+        return v["name"], (cs.get("WEB") if isinstance(cs, dict) else None)
+
+    if isinstance(doc, list):
+        if not all(isinstance(v, dict) and isinstance(v.get("name"), str) for v in doc):
+            raise ValueError("a `variables` list whose items are not {name, …} objects")
+        return [one(v) for v in doc]
+    if not isinstance(doc, dict):
+        raise ValueError(f"a {type(doc).__name__}, not a variable map")
+    if doc and all(isinstance(v, dict) and isinstance(v.get("name"), str) for v in doc.values()):
+        return [one(v) for v in doc.values()]
+    out = []
+    for k, v in doc.items():
+        if isinstance(v, dict):
+            if not any(key in v for key in VAR_KEYS):
+                raise ValueError(f"{k!r} holds a group, not a variable — a nested token tree")
+            cs = v.get("codeSyntax")
+            out.append((k, cs.get("WEB") if isinstance(cs, dict) else None))
+        elif isinstance(v, list):
+            raise ValueError(f"{k!r} holds a list, not a variable's value")
+        else:
+            out.append((k, None))
+    return out
+
+
+def css_properties(text):
+    """Every custom property the token file DECLARES. Comments are stripped first, and a
+    `var(--x)` use is not a declaration."""
+    return set(CSS_DECL.findall(re.sub(r"/\*.*?\*/", "", text, flags=re.S)))
+
+
+def token_drift(variables, props):
+    """(problems, report) — names in one side and not the other, and code syntax that
+    disagrees with the property the token file actually has."""
+    problems, figma_only, syntax, used, owner = [], [], [], set(), {}
+    for name, cs in variables:
+        derived = css_property(name)
+        target = derived
+        if cs is not None:
+            m = CS_PROP.fullmatch(cs)
+            if not m:
+                syntax.append(f"{name}: WEB code syntax {cs!r} is not a CSS custom property")
+                continue
+            target = m.group(1)
+        if target in owner:
+            problems.append(f"{owner[target]!r} and {name!r} both map to {target} — one "
+                            "property cannot hold both")
+            continue
+        owner[target] = name
+        if target in props:
+            used.add(target)
+        elif cs is not None and derived in props:
+            used.add(derived)
+            syntax.append(f"{name}: code syntax names {target}, and the token file calls it "
+                          f"{derived}")
+        else:
+            figma_only.append(f"{name} → {target}")
+    css_only = sorted(props - used)
+    problems += [f"in Figma, not in the token file: {x}" for x in figma_only]
+    problems += [f"in the token file, not in Figma: {x}" for x in css_only]
+    problems += [f"code syntax: {x}" for x in syntax]
+    return problems, {"figma_only": figma_only, "css_only": css_only, "code_syntax": syntax,
+                      "matched": len(used)}
+
+
+def cmd_tokens(a):
+    try:
+        css = open(a.css, encoding="utf-8").read()
+    except OSError as e:
+        print(f"visual_gate: cannot read the token file {a.css} ({type(e).__name__})",
+              file=sys.stderr)
+        return 2
+    if not os.path.isfile(a.figma):
+        return _emit(a, "tokens", "NOT_RUN", [], [
+            f"no Figma variable export at {a.figma} — export it (`get_variable_defs`, or the "
+            "REST variables endpoint) and run again; until then the drift is unmeasured"])
+    try:
+        doc = json.load(open(a.figma, encoding="utf-8"))
+    except (OSError, ValueError) as e:  # JSONDecodeError and UnicodeDecodeError included
+        print(f"visual_gate: cannot read {a.figma} ({type(e).__name__})", file=sys.stderr)
+        return 2
+    try:
+        variables = figma_variables(doc)
+    except ValueError as e:
+        print(f"visual_gate: {a.figma} is not a variable export — {e}", file=sys.stderr)
+        return 2
+    if not variables:
+        return _emit(a, "tokens", "NOT_RUN", [], [
+            f"{a.figma} holds no variables — there is nothing to compare, and nothing "
+            "compared is not a pass"])
+    props = css_properties(css)
+    problems, rep = token_drift(variables, props)
+    notes = [f"{len(variables)} Figma variable(s), {len(props)} CSS custom propert"
+             f"{'y' if len(props) == 1 else 'ies'}, {rep['matched']} matched"]
+    return _emit(a, "tokens", "FAIL" if problems else "PASS", problems, notes, extra=rep)
+
+
 EXIT = {"PASS": 0, "FAIL": 1, "NOT_RUN": 3}
 
 
@@ -580,9 +713,15 @@ def main(argv):
     f.add_argument("--record", required=True)
     f.add_argument("--screens", required=True)
     f.add_argument("--json", action="store_true")
+    t = sub.add_parser("tokens", help="stages 5–6: Figma variable names against the CSS "
+                                      "custom properties of the pack's token file")
+    t.add_argument("--figma", required=True,
+                   help="the variable export (get_variable_defs JSON, or the REST export)")
+    t.add_argument("--css", required=True, help="the pack's token file")
+    t.add_argument("--json", action="store_true")
     a = p.parse_args(argv)
     return {"record": cmd_record, "sheet": cmd_sheet, "lint": cmd_lint,
-            "filekeys": cmd_filekeys}[a.cmd](a)
+            "filekeys": cmd_filekeys, "tokens": cmd_tokens}[a.cmd](a)
 
 
 if __name__ == "__main__":