@radicool/throughline 0.18.0 → 0.20.0

package/references/proof-bundle.md

@@ -0,0 +1,305 @@
+# The verification proof bundle (`design-system/proof/`)
+
+Each stage of the system leaves a durable record of what it changed, which checks
+ran, what each one found, and why it was allowed to advance. That record is the
+proof bundle. It exists because "run it twice, get the same structure" proves
+idempotency, not quality — and because the checks that do prove quality (the
+Figma read-back, a reviewer verdict, a build result) are prose today, and prose
+evaporates when the run ends.
+
+The bundle is **the record, not the enforcement mechanism**. Gates enforce:
+`docs:check` owns documentation drift, the `figma-executor` read-back owns
+structure, `adherence:check` owns code adherence. The bundle persists what each
+gate found. The `verify:check` gate reads it, recomputes what it can off disk,
+and fails when a stored result and a fresh run disagree.
+
+## Where it lives
+
+`design-system/proof/<stage>.json` — one file per stage, in the user's working
+folder, from the first component built. It is folder-resident exactly like
+`design-system/docs/` (see
+`${CLAUDE_PLUGIN_ROOT}/references/component-doc-schema.md`), so a stage can
+record an entry during the Figma-only *folder* stage, before any repo exists.
+The path is stable across folder→repo; files never move.
+
+## The file shape
+
+`{ "stage": "<name>", "subjects": { "<subject>": <entry> } }`
+
+A **subject** is the thing the entry is about: a component name for a
+per-component stage, or the literal `"system"` for a stage that is not
+per-component. One entry per stage-and-subject, latest wins — the store models
+current state, not history, the same way the manifest does.
+
+## The entry shape
+
+`{ at, changed, checks, screenshot?, advancedBecause }`
+
+- `at` — ISO timestamp, **supplied by the caller**. `Date.now()` is not available
+  in every execution context a skill runs in, so the recorder never invents it.
+- `changed` — array of one-line strings saying what this stage changed. May be
+  empty.
+- `checks` — non-empty array of `{ name, method, result, evidence }`, where
+  `method` is `"derived"` or `"attested"`, `result` is `"pass"` or `"fail"`, and
+  `evidence` is a string.
+- `checks[].accepted` — optional, and only on a check. An array of
+  `{ fg, bg, mode }` naming pairs a user explicitly accepted as failing. Only
+  `contrast-baseline` uses it today.
+- `screenshot` — optional pointer: a Figma node id, or a repo-relative path.
+- `advancedBecause` — one line saying why the stage was allowed to advance.
+
+**`accepted`, and why its two readers disagree.** `fg` and `bg` are the dotted
+`CONTRAST_PAIRS` paths, compared after the `normalizeText` fold, so
+`color.text.onEmphasis` and `color.text.on-emphasis` are one role. `mode` is the
+**Figma** mode name `token-builder` saw — `Light`, `Dark` — because at folder
+stage no DTCG file exists yet to name a mode after. A reader that matches on
+`mode` must translate it into that run's file label first.
+
+Two skills read the field, and they match on different things:
+
+- `token-sync-layer` drops from its own gate run's `color-contrast` failures
+  every one whose `(fg, bg, mode)` triple matches an entry. It is the only reader
+  that matches on the mode, because it is the only one that knows both names: it
+  read the Figma modes and it wrote the DTCG files.
+- `storybook-chromatic-builder` compares its own live run's failures against the
+  `fg`/`bg` **roles alone**, to decide whether the `verify:check` it registers
+  carries `--skip color-contrast`. A per-mode test would decide nothing there —
+  `--skip` is rule-wide, so there is no way to skip contrast in Dark and keep it
+  in Light — and that skill could not translate a mode name anyway, having
+  neither read the Figma modes nor written the DTCG files.
+
+The rule that keeps the field honest: **it is data a caller subtracts, never
+something `verify-check.mjs` reads.** The gate does not know the field exists, and
+an attested `fail` never switches a derived rule off inside it — that would be
+the self-attestation this store exists to avoid. A triple that no longer matches
+any failure is inert, which is how an acceptance retires itself once the pair is
+fixed.
+
+**Pointers, never content.** `evidence` and `screenshot` point at things; they do
+not carry them. This is the same rule `components.meta[name].doc` follows, for
+the same reason: the store is committed to the repo and read by humans. A diff
+of a stage file should be legible, and a design system's history should not carry
+inlined screenshots or file contents.
+
+## `derived` vs. `attested`
+
+This is the load-bearing distinction in the whole store, and the two are not
+equal.
+
+- **`derived`** — `verify:check` recomputes the check off disk on every run. The
+  stored result is a **cache**. When the rerun disagrees with it, the run fails as
+  `proof-contradicted`. A derived result is trustworthy because it is not
+  trusted.
+- **`attested`** — an agent observed it live, somewhere the CLI cannot look:
+  Figma, a build it ran, a review it received. It is printed on the report's
+  informational line and is **never the reason a run passes**.
+
+The house precedent for the honest half is `edit-unverified` in
+`${CLAUDE_PLUGIN_ROOT}/references/component-doc-schema.md` — `docs:check` records
+what it cannot read without pretending it verified it. Attested checks are the
+same posture: recorded, visible, never load-bearing.
+
+## The manifest pointer
+
+`design-system.json` carries a top-level `verification` key — `null` until the
+first stage records an entry. Content on disk, pointers and hashes in the
+manifest, exactly as `components.meta[name].doc` does it. See
+`${CLAUDE_PLUGIN_ROOT}/references/manifest-schema.md`.
+
+```json
+{
+  "verification": {
+    "path": "design-system/proof",
+    "stages": {
+      "component-builder": {
+        "at": "2026-09-12T18:04:00.000Z",
+        "adoptedAt": "2026-09-12T17:41:00.000Z",
+        "exempt": ["Card"],
+        "fingerprint": "3f9c1a7b2d4e6058"
+      },
+      "token-sync-layer": {
+        "at": "2026-09-12T18:20:00.000Z",
+        "adoptedAt": "2026-09-12T18:20:00.000Z",
+        "fingerprint": "8ab240df1c9e5567"
+      }
+    }
+  }
+}
+```
+
+- `path` — the store directory.
+- `fingerprint` — computed over the **whole stage file**, so a hand-edited entry
+  is caught (`proof-stale`), the same way `docs:check` catches a hand-edited
+  surface.
+- `at` — the timestamp of the latest entry recorded for that stage. It moves with
+  every record.
+- `adoptedAt` — **write-once**. Set on a stage's first recorded entry and never
+  rewritten: the human-readable "when did this system opt in". No gate reads it.
+- `exempt` — the names this stage has not yet proven. Present only on the
+  per-component stages; a system-wide stage omits the key entirely.
+
+**Skills write all of this only through `verify-check.mjs --record`.** No skill
+hand-writes a stage file, and none computes a fingerprint by hand — that is how
+the pointer and the file are kept from drifting apart.
+
+### `exempt` is capture-once-then-shrink
+
+Both halves of the rule are load-bearing, and a reader who implements only the
+first grandfathers the whole adoption batch:
+
+1. On a stage's **first** record, `exempt` captures **every** name then in
+   `components.built`, sorted.
+2. On **every** record, the first included, the record's own subject is removed
+   from `exempt`.
+
+The list never gains a name. It can only narrow. It is what scopes the
+per-component `proof-missing` rule to components the stage has not yet proven:
+an existing system that adopts the bundle does not light up with a failure for
+every component built before the bundle existed, and a name leaves the list the
+moment the stage actually proves that component.
+
+Capture has to read the whole of `components.built` rather than "everything but
+this subject", because a run's entire batch is already in `built` before the
+record loop reaches the first component. A capture that excluded only its own
+subject would permanently exempt its batch-mates — build four components on the
+upgrade run and three of them are never owed proof again.
+
+A stage listed in `verification.stages` with **no** `exempt` key at all exempts
+**nothing**, not everything. A missing list makes the gate louder, not quieter.
+
+### No gate compares `updatedAt` against `adoptedAt`
+
+However natural it looks, nothing in the verification gate compares
+`components.meta[name].updatedAt` against `adoptedAt`. That field has more than
+one writer: `storybook-chromatic-builder` refreshes it when it promotes a
+component to `"stable"`, which is a different stage from the one that owes the
+entry. So a single storying run drags every pre-existing component's timestamp
+past `component-builder`'s adoption moment, and a date gate would fail a system
+where nothing went wrong. A captured list of names cannot be moved by another
+stage's write, and it is readable in the manifest: the exemption is stated
+rather than inferred.
+
+For the same reason, neither `adoptedAt` nor `exempt` is derived from the stage
+file. Entries are latest-wins, so "the earliest `at` in the file" slides forward
+every time the earliest subject is rebuilt.
+
+## The stage vocabulary (v1)
+
+| Stage | Subject |
+|---|---|
+| `component-builder` | component name |
+| `storybook-chromatic-builder` | component name |
+| `token-sync-layer` | `"system"` |
+| `token-builder` | `"system"` |
+
+The machine-readable copy of that split is `PER_COMPONENT_STAGES` in
+`scripts/lib/proof.mjs`, and the full list is `STAGES` beside it. **A change here
+must change those constants** — they are what `verify:check` asks "is this stage
+keyed by component?"
+
+`/document-component` and the retrofit phases do not emit entries in v1.
+
+## The check names (v1)
+
+| Check | Method | Recorded by |
+|---|---|---|
+| `structural-read-back` | attested | `component-builder` |
+| `state-baseline` | attested | `component-builder` |
+| `figma-name` | attested | `component-builder` |
+| `review` | attested | the dispatching skill |
+| `build` | attested | `storybook-chromatic-builder` |
+| `orphan-token` | derived | not recorded: re-derived on every `verify:check` run |
+| `state-incomplete` | derived | `storybook-chromatic-builder` |
+| `name-drift` | derived | `storybook-chromatic-builder` |
+| `contrast-baseline` | attested | `token-builder` |
+| `tokens:validate-output` | attested | `token-sync-layer` |
+| `color-contrast` | derived | `token-sync-layer` |
+
+**Two stages record derived results — `storybook-chromatic-builder` and
+`token-sync-layer`** — and each qualifies for one reason and only that reason: it
+runs `verify:check` before it records, so it has the result in hand rather than
+asserting it. That is a property of what the stage does, not of which stage it
+is; a stage that does not run the gate never qualifies. `component-builder` and
+`token-builder` both run at folder stage, with no repo to scan, so they record
+attested checks only.
+
+A derived result sitting in a stage file is a cache the next run recomputes. A
+disagreement is `proof-contradicted`.
+
+### Contrast: two checks, two methods
+
+`contrast-baseline` and `color-contrast` ask the same question in two places,
+and neither substitutes for the other.
+
+- **`contrast-baseline`** — attested, recorded by `token-builder`. The ratio an
+  agent computed in Figma from the resolved variable values, per mode, at the
+  moment the semantic tier was built. Attested because the CLI cannot read Figma.
+- **`color-contrast`** — derived, recorded by `token-sync-layer`. The same
+  question recomputed off the DTCG source by `verify:check`, which can read it.
+
+This is the `state-baseline` / `state-incomplete` pairing one layer down: the
+agent asserts in the place where the thing is built, the CLI re-derives
+independently off disk, and a system wants both. Catching a bad pair at creation
+time is the point of the first; not having to take that catch on trust is the
+point of the second.
+
+## A worked example
+
+One stage file with two subjects — `Button`, freshly built and reviewed, and
+`Card`, rebuilt without a review:
+
+```json
+{
+  "stage": "component-builder",
+  "subjects": {
+    "Button": {
+      "at": "2026-09-12T17:41:00.000Z",
+      "changed": [
+        "Built Button as a COMPONENT_SET with 18 variants",
+        "Bound fills, strokes and radius to semantic variables"
+      ],
+      "checks": [
+        {
+          "name": "structural-read-back",
+          "method": "attested",
+          "result": "pass",
+          "evidence": "COMPONENT_SET 41:207, 18 children, axes type/size/state"
+        },
+        {
+          "name": "state-baseline",
+          "method": "attested",
+          "result": "pass",
+          "evidence": "state axis: default, hover, focus, active, disabled"
+        },
+        {
+          "name": "figma-name",
+          "method": "attested",
+          "result": "pass",
+          "evidence": "Figma node named Button"
+        },
+        {
+          "name": "review",
+          "method": "attested",
+          "result": "pass",
+          "evidence": "approved"
+        }
+      ],
+      "screenshot": "41:207",
+      "advancedBecause": "Read-back and review both passed; every variant resolves to bound variables."
+    },
+    "Card": {
+      "at": "2026-09-12T18:04:00.000Z",
+      "changed": ["Rebuilt Card with the elevation variant axis"],
+      "checks": [
+        {
+          "name": "structural-read-back",
+          "method": "attested",
+          "result": "pass",
+          "evidence": "COMPONENT_SET 41:418, 6 children, axes elevation/padding"
+        }
+      ],
+      "advancedBecause": "Structure verified; no review requested for a variant-axis rebuild."
+    }
+  }
+}
+```

package/references/sync-adapters.md

@@ -57,39 +57,35 @@ The cause was the transform group, not the adapter concept. That configuration
 now ships as tested code at
 `${CLAUDE_PLUGIN_ROOT}/scripts/lib/sd-native.mjs`, is installed into the
 consumer's repo, and is verified end to end against a real source (195 emitted
-symbols matched, zero rule failures under the shipping ruleset, on both light
-and dark builds). The badge is back on that basis.
+symbols matched, 107 of them with their magnitude also checked, zero rule
+failures under the shipping ruleset, on both light and dark builds).
+The badge is back on that basis. What "matched" does and does not check is in
+*Verify, always* in `${CLAUDE_PLUGIN_ROOT}/references/native-adapter-config.md`.
 
 **What the badge does not cover: nothing is compiled.** Every emitted value is
 checked to be a well-formed Swift or Kotlin *literal* — `tokens:validate-output`'s
 `invalid-literal` rule parses each one and fails on anything that is not
 (#53) — but no `swiftc` or `kotlinc` runs, so a type mismatch or a call to an
-undefined symbol would still pass. String-valued tokens (`fontFamily`, `string`,
-keyword `fontWeight`) are quoted by the module's own transforms, and a value with
-no native form at all — a CSS `linear-gradient(...)` — is filtered out of native
-output rather than emitted broken. That drop is reported as an unemitted token,
-not hidden.
+undefined symbol would still pass. Which values the module quotes, and which it
+drops for having no native form, is stated in §4 and §6 of
+`${CLAUDE_PLUGIN_ROOT}/references/native-adapter-config.md`. A dropped token is
+not hidden: `tokens:validate-output` reports it as unemitted — see
+`${CLAUDE_PLUGIN_ROOT}/scripts/README.md`.
 
 Since 0.17.0 that gap is measured rather than assumed on ThroughLine's side:
 this project's end-to-end runs compile what they generate — `kotlinc` typechecks
 `Tokens.kt` against Compose stubs, `swiftc -parse` checks `Tokens.swift` —
-against a real 322-token system. That is evidence about the adapter shipped to
+against a real 318-token system. That is evidence about the adapter shipped to
 you, not a gate on your build, and it does not widen what the badge asserts
 about your output.
 
 `android-kotlin` uses the same module and stays Tier 2: its remaining unknowns
 are on the consumption side — Compose `dp`/`sp` behaviour against a real Compose
 app, resource-qualifier conventions, package layout — which building tokens does
-not exercise. The `dp`/`sp` split itself is no longer among them: font sizes and
-line heights whose role a DTCG source states — the `fontSize`, `letterSpacing`
-and `lineHeight` member names of §9.8's typography composite — now emit as
-`sp`. What remains is narrower and documented in
-`${CLAUDE_PLUGIN_ROOT}/references/native-adapter-config.md`: a scale primitive
-**nothing references** carries no role and stays `dp`, named by a
-`tokens:validate-output` `unreferenced-text-sibling` advisory; and an `em`
-letterSpacing reaches Compose as a real `.em` TextUnit but is excluded from
-Swift deliberately, since letter spacing there needs a font size no constant
-Swift value could carry.
+not exercise. Which tokens emit as `sp`, and the text-unit limits that remain on
+each platform, are stated once, in §4 of
+`${CLAUDE_PLUGIN_ROOT}/references/native-adapter-config.md`, which is generated
+from the module itself.
 `tokens:validate-output` remains what decides whether any adapter can be
 trusted, and re-promotion is available to any adapter that passes it against a
 real source.
@@ -144,6 +140,9 @@ emit as references to primitive vars rather than flattened literals.
   Tailwind tokens; the standalone `tailwind` adapter maps tokens into the
   Tailwind theme config directly; `mui` emits a JS theme object whose palette
   references preserve the cascade through object structure.
+  `tokens:validate-output` checks the generated CSS against its source too, and
+  only the CSS: for `tailwind`, the file declaring the custom properties, not the
+  theme config. See `${CLAUDE_PLUGIN_ROOT}/scripts/README.md`.
 - **Native adapters** (`ios-swift`, and generated native targets like
   Android/Kotlin): `outputReferences: false` — references resolve to literal
   values at build time, because the target language has no runtime var
@@ -154,45 +153,31 @@ emit as references to primitive vars rather than flattened literals.
 
 ## What the stock configuration gets wrong
 
-These are all legal in a real DTCG source, and a **stock** Style Dictionary
-transform group mishandles every one of them silently — emitting output that
-compiles and is wrong, which is why `tokens:validate-output` exists.
-
-**None of these are Style Dictionary limitations.** All four are fixed by
-roughly 80 lines of preprocessor and transform code, which ships as a tested
-module at `${CLAUDE_PLUGIN_ROOT}/scripts/lib/sd-native.mjs` and is documented in
-`${CLAUDE_PLUGIN_ROOT}/references/native-adapter-config.md`. Against a real
-322-token source it emitted 195 symbols that all map to a source token, 107 of
-them with their numeric magnitude additionally verified, with zero rule failures
-— colour and string values are matched by name only and are checked by no rule.
-**Import that module** rather than configuring a native adapter from a stock
-`transformGroup` or transcribing the reference doc.
-
-- **CSS expressions in a value** — `color-mix(in srgb, {color.brand.500} 12%,
-  transparent)` is a runtime CSS construct. Style Dictionary does no colour
-  math, so it resolves only the inner reference and leaves the function wrapper
-  in the output. *Fix: a transform that computes the blend to a literal.*
-- **Dual-node tokens** — a node carrying both a `$value` and children (`text.sm`
-  with `$value: "14px"` plus a `text.sm.lineHeight` child). Style Dictionary's
-  resolver will not traverse into one, so every alias to the child fails to
-  resolve and emits as a bare literal; its collector also stops there, so the
-  child is never emitted at all. *Fix: a preprocessor that resolves aliases and
-  hoists the children.*
-- **`%` and `em` dimensions** — parent-relative or container-relative, so there
-  genuinely is no build-time native magnitude. This one is a real limit rather
-  than a configuration gap. *Handling: filter them out of native builds — on the
-  authored value, since a `100%` token may be typed `string`, not `dimension`.*
+Real token sources carry all of these, and a **stock** Style Dictionary
+transform group mishandles them silently — emitting output that compiles and is
+wrong, which is why `tokens:validate-output` exists.
+
+The native fixes ship as a tested module at
+`${CLAUDE_PLUGIN_ROOT}/scripts/lib/sd-native.mjs`. **Import that module** rather
+than configuring a native adapter from a stock `transformGroup` or transcribing
+the reference doc. What goes wrong in each case, and exactly what the module does
+about it, is stated once, in
+`${CLAUDE_PLUGIN_ROOT}/references/native-adapter-config.md`, which is generated
+from the module and checked for freshness in CI. This list only points there:
+
+- **`px`-authored dimensions** — the stock groups assume `rem` and multiply by
+  16. See §1, *Read the authored unit*.
+- **CSS expressions in a value**, such as `color-mix()` — see §2, *Compute
+  `color-mix()` to a literal*.
+- **Dual-node tokens**, a node carrying both a `$value` and children — see §3,
+  *Resolve aliases and hoist dual-node children*.
+- **`%` and `em` dimensions** — see `nativeFilter` in §4, *Assemble the platform
+  from the stock list*.
 - **A third mode axis** — this reference models theme (`.dark` /
   `[data-theme]`) and brand (`[data-brand]`). A viewport axis carrying its own
   spacing and type scales is common and has no mapping here; on native it is
   size classes and resource qualifiers, resolved by a different mechanism
-  entirely.
-
-**Native dimension transforms must read the authored unit.** The stock
-`ios-swift` and `compose` transform groups assume `rem` input and multiply by
-16. Against a `px`-authored source that silently produces output at sixteen
-times scale which compiles and ships. Emit 1:1 for `px` and unitless ratios;
-×16 only for `rem`.
+  entirely. The module does not address this one.
 
 ## Brownfield value transforms
 

package/scripts/README.md

@@ -10,9 +10,11 @@ tested here; copied verbatim by `token-crosswalk-builder` into the user's
 | `validate-crosswalk.mjs` | Resolve every `newToken` against the DTCG token source; assert resolved value == `newValue`, N/N. The CI gate. | `tokens:validate` |
 | `build-reverse-index.mjs` | Emit a `codeToken -> newToken` map from the crosswalk to semi-automate SCSS/Tailwind swaps. | `tokens:reverse-index` |
 | `guard-token-removal.mjs` | Grep `.ts/.tsx` (minus generated + tests) for about-to-be-deleted symbols; blocks cleanup until zero references remain. | run during the cleanup phase |
-| `validate-token-output.mjs` | Assert generated native token output matches its DTCG source: authored-unit fidelity, no leaked CSS syntax, no bare unit literals, no mode collisions. Fails when no emitted symbol matches a source token, and reports match rate, unparsed lines, and unemitted tokens on every run. | `tokens:validate-output` |
+| `validate-token-output.mjs` | Assert generated token output — Swift, Kotlin, or web CSS custom properties — matches its DTCG source: authored-unit fidelity and no mode collisions everywhere, plus no leaked CSS syntax and no bare unit literals in Swift and Kotlin. Fails when no emitted symbol matches a source token, and reports match rate, unparsed lines, and unemitted tokens on every run. | `tokens:validate-output` |
+| `validate-adherence.mjs` | Assert the code *consuming* a design system still adheres to it: every referenced component exists, every literal variant value is one the system declares, and no colour, spacing, radius or type literal duplicates a token that already holds that value. Fails when an enabled rule had nothing to check, so a green run always means something was verified. | `adherence:check` |
+| `lib/source-scan.mjs` | Shared source-tree walker (`walk`, `DEFAULT_EXCLUDES`, `SOURCE_EXT`) plus `normalizeName`, the display-name-to-code-identifier fold. Every gate that scans a consumer's repo reads it from here rather than carrying its own copy. | copied alongside `guard-token-removal.mjs`, and in the documentation set for `validate-adherence.mjs` and `verify-check.mjs` |
 | `lib/crosswalk.mjs` | Shared loader + structural validation for `crosswalk.json` (used by the validator and reverse-index). | copied alongside |
-| `lib/dtcg.mjs` | Shared DTCG flatten + `{alias}` resolution. Dual-node aware: a node carrying both a `$value` and children yields its own value **and** is descended into. Used by `validate-crosswalk.mjs` and `validate-token-output.mjs`. | copied alongside both |
+| `lib/dtcg.mjs` | Shared DTCG flatten + `{alias}` resolution. Dual-node aware: a node carrying both a `$value` and children yields its own value **and** is descended into. Used by `validate-crosswalk.mjs`, `validate-token-output.mjs`, `validate-adherence.mjs`, `verify-check.mjs`, and `lib/sd-native.mjs`. | copied alongside each of those |
 | `lib/sd-native.mjs` | The Style Dictionary native configuration as code: unit-aware dimension transforms, `color-mix` computation, dual-node preprocessing, platform assembly, and a per-mode source guard. Style Dictionary is a parameter, never an import. | copied alongside `validate-token-output.mjs` |
 | `lib/native-literal.mjs` | Shared grammar for "is this a well-formed Swift or Kotlin literal": parses rather than pattern-matches, so an unquoted string, a raw CSS function, or any other unanticipated case fails the same way. Used by `sd-native.mjs`'s output filter and by `validate-token-output.mjs`'s invalid-literal rule. | copied alongside `validate-token-output.mjs` and `lib/sd-native.mjs` |
 | `crosswalk.schema.json` | The finalized JSON Schema for `crosswalk.json` (contract + editor support). | copied beside `crosswalk.json` |
@@ -22,6 +24,10 @@ tested here; copied verbatim by `token-crosswalk-builder` into the user's
 | `lib/doc-record.mjs` | Canonical record load + `canonicalFingerprint` (sha256 over the record minus `provenance`). The fingerprint every surface is stamped with. | copied alongside docs-check.mjs |
 | `lib/doc-card-render.figma.js` | Figma renderer template for the doc card's `Usage` band and header. Inlined into `references/doc-card-builder.md`; never executed as a module. | plugin-internal (not installed) |
 | `lib/doc-card-plan.mjs` | Pure layout planner for the doc card's `Usage` band + `DOC_CARD_RENDERER_VERSION` (single source of the layout version). Inlined into `references/doc-card-builder.md`; imported by `docs-check.mjs`. | copied alongside docs-check.mjs; also inlined into the generated builder |
+| `verify-check.mjs` | The verification proof bundle: records each stage's entry, and re-derives what it can rather than trusting the record. Fails on an orphaned token, a component documented without its archetype's baseline interaction states, a name that drifts between the manifest, its record and its code surface, or a recorded result the rerun contradicts. | `verify:check` |
+| `lib/proof.mjs` | The proof store's vocabulary and mechanics: the stage list, entry validation, latest-wins merge, and the fingerprint the manifest pointer carries. | copied alongside `verify-check.mjs` |
+| `lib/component-states.mjs` | The archetype table and resolver behind `state-incomplete` — which baseline interaction states each kind of component owes, and when to abstain. | copied alongside `verify-check.mjs` |
+| `lib/contrast.mjs` | The WCAG contrast maths and the semantic colour pairs behind `color-contrast` — which text role must clear which surface, in every mode, and where the rule deliberately abstains. | copied alongside `verify-check.mjs` |
 | `build-doc-card-builder.mjs` | Generate `references/doc-card-builder.md` from the planner + the Figma renderer template (`lib/doc-card-render.figma.js`). `--check` gates CI. | plugin-internal (not installed) |
 | `build-native-adapter-config.mjs` | Generate `references/native-adapter-config.md` by slicing `lib/sd-native.mjs` on its `@doc-section` markers and interleaving each fragment under its prose. Fails when module code falls outside every section, so the doc cannot silently ship incomplete. `--check` gates CI. | plugin-internal (not installed) |
 
@@ -29,7 +35,7 @@ tested here; copied verbatim by `token-crosswalk-builder` into the user's
 registering them leaves a repo with a script on disk and no entry point, which
 is how a stale `docs:check` went unnoticed for a full release. Both
 `storybook-chromatic-builder` (first-time setup) and `/document-component`
-(freshness refresh) install the same five files and register the same three
+(freshness refresh) install the same twelve files and register the same five
 scripts:
 
 | File | npm script |
@@ -39,9 +45,29 @@ scripts:
 | `docs-lint.mjs` | `"docs:lint": "node scripts/docs-lint.mjs"` |
 | `lib/doc-record.mjs` | — (imported by the above) |
 | `lib/doc-card-plan.mjs` | — (imported by the above) |
+| `validate-adherence.mjs` | `"adherence:check": "node scripts/validate-adherence.mjs --root ../../apps --system ../.. --package <specifier> --tokens dtcg/tokens.json"` |
+| `lib/source-scan.mjs` | — (imported by the above) |
+| `lib/dtcg.mjs` | — (imported by the above) |
+| `verify-check.mjs` | `"verify:check": "node scripts/verify-check.mjs --root ../.. --tokens dtcg/tokens.json"` |
+| `lib/proof.mjs` | — (imported by the above) |
+| `lib/component-states.mjs` | — (imported by the above) |
+| `lib/contrast.mjs` | — (imported by the above) |
 
 A refresh that adds a file must also add its npm script; check `package.json`
-for all three every time, not just the file that changed.
+for all five npm scripts every time, not just the file that changed.
+
+`verify:check`, like `adherence:check`, carries placeholder paths the installing
+skill substitutes for the repo's real layout. Dropping `--tokens` rather than
+substituting it is how a repo ends up with a rule that never runs: with no token
+source there is nothing to read, so the gate reports both `orphan-token` and
+`color-contrast` as skipped on every run — two stop conditions disabled by their
+own registration.
+
+The registered form carries a single `dtcg/tokens.json`, and a system whose
+values span modes registers **one `--tokens` per mode file**, because each source
+file is its own mode. Registering a multi-mode system with a single `--tokens`
+flag leaves a script that checks Light and reports that it checked one mode —
+quieter than the dropped `--tokens` failure above it, and just as wrong.
 
 The crosswalk contract is documented in
 `${CLAUDE_PLUGIN_ROOT}/references/crosswalk-schema.md`.
@@ -52,15 +78,123 @@ The crosswalk contract is documented in
 node validate-crosswalk.mjs --crosswalk crosswalk.json --tokens dtcg/tokens.json
 node build-reverse-index.mjs --crosswalk crosswalk.json --out crosswalk.reverse.json
 node guard-token-removal.mjs --root . --symbols symbols-to-remove.txt
+node validate-adherence.mjs --root ../../apps --system ../.. --package @acme/ui --tokens dtcg/tokens.json
+node validate-token-output.mjs --source dtcg/primitives.json --source dtcg/semantic.dark.json --output css/tokens.css --platform shadcn --block .dark --min-match 1
+node verify-check.mjs --root ../.. --tokens dtcg/tokens.json
+node verify-check.mjs --record --stage component-builder --subject Button --entry entry.json
 ```
 
+`validate-adherence.mjs` takes every path explicitly because cwd is the package
+holding the script, not the repo root. `--system` has no default: defaulting it
+to `--root` resolves to a path that does not exist. `--tokens` is repeatable, so
+a system whose values span mode files passes each one. An alias resolves against
+every `--tokens` file, so a semantic file can point at primitives in another, and
+the report's `colour:` line counts the colour tokens it skipped as unresolvable or
+non-hex. Files inside the package
+that owns a `--tokens` file are not scanned when that package sits beneath
+`--root`, and the report prints an `excluded:` line naming it. A tag whose name
+starts with a built component's name and continues with a capital letter
+(`CardTitle` for `Card`) is read as part of that component, and the report lists
+each one on a `parts:` line. `--skip <rule>`
+switches a rule off entirely (a name that isn't a rule exits `2`, rather than
+skipping nothing), and a skipped rule is absent rather than inert, which
+is the supported answer for a repo the rule cannot apply to (a Vue, Svelte or
+Angular app has no JSX for the component rules to read). An Angular `.html`
+template is read through its styling attributes only: `style`, `class`,
+`ngStyle`, `ngClass`, the SVG colour attributes (`fill`, `stroke`, `stop-color`,
+`flood-color`, `lighting-color`, `color`), and their bindings (`[attr.fill]`,
+`[style.color]`). Text content, `data-*`, `href`, comments and unquoted values
+are not read. Colour is read from all of these. Dimensions are read only where a
+property name sits beside the value: `prop: value` in `style` or `ngStyle`, and
+an arbitrary-value class like `p-[12px]`. `[style.padding.px]="12"` is not.
+`--skip token-exists-for-dimension`
+is the answer for a system with no spacing, radius or type tokens, which
+otherwise fails as `dimension-rule-inert`.
+
+`validate-token-output.mjs` reads web output as CSS custom properties for
+`--platform shadcn`, `tailwind` and `vanilla-css`. `mui` exits `2`: a MUI theme,
+like a Tailwind v3 JavaScript config, has no custom properties to read, and
+isn't checked yet (#127). Web puts every mode in one file, so run the gate once
+per mode block, passing the sources that block was built from. `--block` names
+the block by its enclosing at-rules and selector, joined by single spaces:
+`:root`, `.dark`, `[data-theme="light"]`, `@media (min-width: 768px) :root`,
+`@theme inline`. A file with one block needs no `--block`. A file with several,
+or a `--block` that isn't there, exits `2` and lists every block with its
+declaration count, so the exact key is in the error. A build split across files
+passes each one as another `--output`: everything declared in any of them counts
+as declared, and a token declared in any block counts as emitted. Six rules fail
+a web run:
+
+- `unit-fidelity` — the value changed magnitude, or a ratio gained a unit, or a
+  length lost one (`16` → `16rem`, `1.1` → `1.1rem`, `16px` → `16`). `16` →
+  `1rem` passes.
+- `reference-fidelity` — a declaration's `var()`s don't name the tokens its
+  source references.
+- `dangling-reference` — a `var()` to a variable no `--output` declares, unless
+  the source wrote that `var()` itself.
+- `no-unresolved-reference` — a `{reference}` reached the CSS unresolved.
+- `invalid-value` — `[object Object]`, `NaN` or `undefined` was written into the
+  CSS.
+- `unverifiable-dimension` — a dimension came out in a form the gate can't
+  compare, so it was never checked.
+
+Nothing fails for being CSS: `var()`, `calc()`, `color-mix()` and units are all
+legal output. On `shadcn` and `tailwind`, a declaration with no source token
+whose whole value is a `var()` to a declared variable is an alias layer
+(`--background: var(--color-bg-canvas)`). The report counts aliases on their own
+line and leaves them out of the match rate, so `--min-match 1` still holds.
+
+`verify-check.mjs` has two modes. The **gate** — `--root <dir>`, repeatable
+`--tokens` and `--source`, repeatable `--skip` — reads the proof store at
+`design-system/proof/`, re-derives every check a stage recorded as `derived`, and
+fails on `orphan-token`, `state-incomplete`, `name-drift`, `color-contrast`,
+`proof-missing`, `proof-stale`, `proof-contradicted`, `nothing-verified`,
+`orphan-rule-inert` and `contrast-rule-inert`.
+`archetype-unknown` and `proof-unadopted` are informational. With no `--source`
+the walk covers `--root`; the package that owns a `--tokens` file is set aside
+either way, and the report prints an `excluded:` line naming it — without that,
+generated token output binds every semantic token to itself and `orphan-token`
+can never fire. The **recorder** — `--record --stage <name> [--subject <Name>]
+--entry <file.json>` — merges one entry into that stage's file, recomputes its
+fingerprint and stamps the manifest's `verification` pointer. Skills call it;
+nothing hand-writes the store or hand-computes a hash.
+
+`--skip <rule>` switches a rule off entirely, and a skipped rule is absent rather
+than inert. A name that isn't one of the four rules exits `2`: `colour-contrast`
+is a typo here, not a skip. With no `--tokens` there is no token source to read, so
+`orphan-token` and `color-contrast` are reported as skipped rather than passed.
+
+`color-contrast` compares the semantic colour pairs the system's own role
+definitions already promise — `text/onEmphasis` over `bg/emphasis`, each status
+text over its own status background, and so on. Each `--tokens` file is one
+**mode**, and a pair has to clear WCAG AA's 4.5:1 for normal text in every one of
+them: a system that passes in Light and fails in Dark fails. A pair whose roles
+are absent from a mode abstains rather than passing, which is why a run that
+recognised no role anywhere fails as `contrast-rule-inert` instead of reporting a
+clean sweep. `text/disabled` is excluded, because WCAG 1.4.3 exempts inactive
+components and a disabled role is deliberately low-contrast. A translucent
+foreground is composited over its background and compared; a translucent
+background is skipped and counted, because what sits behind it is a layout fact
+the token tier does not hold. Every number on the report's `contrast:` line is a
+pair, in the mode it occurred in. `--skip color-contrast` is the escape hatch for
+a system whose roles are named differently. The orphan rule counts
+a token as bound when its normalized key appears anywhere in a scanned file, so
+`color.bg.primary` is bound by a mention of `color.bg.primary.hover`: every miss
+is an orphan reported as bound, never a correct system failed. A `derived` check
+is one the gate recomputes off disk, and its recorded result is a cache that must
+agree — a disagreement is `proof-contradicted`. An `attested` check is an agent's
+live observation of something the CLI cannot read, printed informationally and
+never the reason a run passes. See
+`${CLAUDE_PLUGIN_ROOT}/references/proof-bundle.md`.
+
 Exit codes: `0` success, `1` validation/guard failure (mismatch, missing token,
 conflict, or remaining reference), `2` bad CLI arguments.
 
 ## How the skill installs these
 
 `token-crosswalk-builder` copies `lib/crosswalk.mjs`, `lib/dtcg.mjs`,
-`validate-crosswalk.mjs`, `build-reverse-index.mjs`, `guard-token-removal.mjs`, and
+`lib/source-scan.mjs`, `validate-crosswalk.mjs`, `build-reverse-index.mjs`,
+`guard-token-removal.mjs`, and
 `crosswalk.schema.json` into the user's `packages/tokens/scripts/` (schema beside `crosswalk.json`), then
 wires `packages/tokens/package.json`:
 
@@ -88,7 +222,7 @@ Run the suite from the repo root (no install step — uses only Node built-ins):
 node --test
 ```
 
-This auto-discovers every `**/*.test.mjs` recursively (31 tests). Don't use
+This auto-discovers every `**/*.test.mjs` recursively. Don't use
 `node --test scripts/` — a directory positional is treated as a test name on
 Node >=21 and errors; a `scripts/*.test.mjs` glob silently skips `scripts/lib/`.
 

package/scripts/build-doc-card-builder.mjs

@@ -130,7 +130,7 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
   });
   if (process.argv.includes('--check')) {
     let onDisk = null;
-    try { onDisk = readFileSync(OUT, 'utf8'); } catch (e) { /* missing counts as drift */ }
+    try { onDisk = readFileSync(OUT, 'utf8'); } catch { /* missing counts as drift */ }
     if (onDisk !== result) {
       console.error('✗ references/doc-card-builder.md out of date; run: node scripts/build-doc-card-builder.mjs');
       process.exit(1);