@radicool/throughline 0.18.0 → 0.20.0

package/references/figma-component-standards.md

@@ -372,8 +372,20 @@ re-describing it:
    `${CLAUDE_PLUGIN_ROOT}/references/figma-scripting.md` — `getNodeByIdAsync`, and
    an explicit `timeout` since multi-card font-loading writes blow past the default
    ~5s budget), then inside it:
-   - set the `Status Label` text to the new status (e.g. `stable`);
-   - re-bind the `Status` chip fill to the matching semantic color variable
+   - locate the status chip under either header shape, the way the doc-card
+     builder's header guard does: find the header band structurally (the card's
+     child frame that is neither `Usage` nor the specimen nor an ancestor of it),
+     then search its first child, the title row, for a descendant named `Status`
+     (to-spec cards) or `Status Pill` (legacy cards). The chip's label is its
+     `Status Label` text node; a legacy pill has no named label, so use its one
+     TEXT descendant. If no chip is found, or the label doesn't resolve to exactly
+     one text node, **skip that card** without writing anything to it and record
+     its name — catch per card, so one miss never aborts the rest of a multi-card
+     write. After the loop, tell the user by name every card that still shows the
+     old status in Figma — the manifest already says `stable`, so a silent skip
+     leaves the card lying;
+   - set the label text to the new status (e.g. `stable`);
+   - re-bind the chip fill to the matching semantic color variable
      (`stable` → success, `draft`/`beta` → warning, `deprecated` → neutral/danger)
      — re-bind the variable, don't hardcode a hex, so it stays mode-aware.
    Then re-run the canonical doc-card builder

package/references/figma-scripting.md

@@ -51,8 +51,9 @@ wrong document.
 
 **So the preflight must assert the active file's *identity*, not just connection:**
 
-1. **Know your target `fileKey`** before writing (the one your architect read, or
-   the one the workflow is scoped to).
+1. **Know your target `fileKey`** before writing. It is `figma.fileKey` in
+   `design-system.json` at the working-directory root. If that field is absent,
+   stop and ask which file to write to — do not assume the active one is right.
 2. **Read the active file and compare.** `figma_get_status` reports
    `currentFileKey` / `currentFileName`; `figma_list_open_files` shows every
    connected file and which is active. Confirm the active `fileKey` equals your
@@ -61,6 +62,15 @@ wrong document.
 3. **If it drifted, navigate — don't just retry.** `figma_navigate` to the target
    file URL, then re-read status to confirm the switch took, then write. A bare
    re-run without navigating will hit the wrong file again.
+4. **If it still doesn't match, stop.** Name both files. The usual cause is that
+   the target file does not have the Desktop Bridge plugin open.
+
+Run this before the first write, and again right before any replace — the
+build-verify-then-replace finalize deletes the existing node, so it is the write
+that destroys work in the wrong file. The `figma-executor` agent runs it as step 1
+of its contract. **When a skill builds inline instead** (a host with no subagent
+dispatch, or a write-back the skill does itself), nothing runs it for you: the
+skill has to.
 
 This is the file-level analogue of the live-instance discipline above: the
 instance preflight guards against *two* live bridges; this guards against the *one*

package/references/manifest-schema.md

@@ -11,11 +11,11 @@ what changed. Gating decisions are made by reading this file: if a prerequisite
 field is unset, the skill **offers** to run the prerequisite skill rather than
 bailing or running silently.
 
-## Schema (schemaVersion 6)
+## Schema (schemaVersion 7)
 
 ```json
 {
-  "schemaVersion": 6,
+  "schemaVersion": 7,
   "user": {
     "codingLevel": "new"
   },
@@ -102,6 +102,7 @@ bailing or running silently.
     "completedAt": null,
     "journalScaffolded": false
   },
+  "verification": null,
   "completedSkills": []
 }
 ```
@@ -346,6 +347,41 @@ retrofit stands so a later session can resume.
 - `journalScaffolded` — whether the `docs/design-system/` decision journal has been
   created for this retrofit (offered default-on by `retrofit-planner`).
 
+### `verification`
+The pointer at the folder-resident proof store, where each stage records what it
+changed, which checks ran and why it was allowed to advance. `null` until the
+first stage records an entry. See
+`${CLAUDE_PLUGIN_ROOT}/references/proof-bundle.md`.
+- `path` — the store directory (`design-system/proof`).
+- `stages` — object keyed by stage name, each holding
+  `{ at, adoptedAt, exempt?, fingerprint }`.
+- `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 latest recorded entry's timestamp. It moves with every record.
+- `adoptedAt` — the first entry's timestamp: **write-once**, never rewritten, the
+  human-readable "when did this system opt in". No gate reads it.
+- `exempt` — present only on the per-component stages (`component-builder`,
+  `storybook-chromatic-builder`) and **capture-once-then-shrink**: the stage's
+  first record captures every name then in `components.built`, and every record,
+  the first included, removes its own subject. The list never gains a name. It is
+  what scopes the per-component `proof-missing` rule to components the stage has
+  not yet proven, so adopting the bundle does not light up a failure for every
+  component built before it existed. A listed stage with **no** `exempt` key
+  exempts **nothing**, not everything — a missing list makes the gate louder, not
+  quieter.
+
+**Pointers and hashes, never entries** — the entries themselves live in the
+store, for the same reason `components.meta[name].doc` keeps content out of the
+manifest. Skills write all of this only through `verify-check.mjs --record`; none
+hand-writes a stage file or computes a fingerprint by hand.
+
+No gate compares `components.meta[name].updatedAt` against `adoptedAt`. That
+field is refreshed by a status promotion as well as by a rebuild, so a stage
+other than the one that owes the entry can move it — and a date comparison would
+fail a pre-existing component the first time an unrelated storying run promotes
+it.
+
 ### `completedSkills`
 - Append-only list of skill identifiers that have run to completion at least
   once. Useful for the `/design-system-status` command and for friendly
@@ -379,3 +415,7 @@ are authored. Bump `schemaVersion` to `5`. No existing field changes.
 **v5 → v6 migration:** add `figma.docCardVariables` (default `null`), populated
 on the first doc-card render. Bump `schemaVersion` to `6`. No existing field
 changes.
+
+**v6 → v7 migration:** add `verification` (default `null`), populated on the
+first recorded stage entry. Bump `schemaVersion` to `7`. No existing field
+changes.

package/references/native-adapter-config.md

@@ -54,7 +54,8 @@ consumer's repo.
 import { readFileSync } from 'node:fs';
 import {
   flattenDtcg,
-  flattenDtcgTypes,
+  flattenPipelineTypes,
+  extNamespace,
   resolveValue,
   findModeCollisions,
   TEXT_UNIT_NAMES,
@@ -152,10 +153,25 @@ Both are fixed before Style Dictionary sees the tree.
 // Marks a node whose AUTHORED $value was a whole-value reference, so the hoist
 // can decline to override the type DTCG 5.2.2 rule 1 already determined from the
 // referent. A WeakSet keyed on the node object, rather than a property written
-// onto it, holds structural idempotency exactly: structuredClone drops the
-// membership along with the rest of the identity, so preprocess(preprocess(x))
-// is deepEqual to preprocess(x) with no leak question to manage.
+// onto it, keeps this mechanism from leaking across calls: structuredClone
+// drops the membership along with the rest of the identity, so a second pass
+// starts clean rather than inheriting the first pass's marks. That is exactly
+// what a property written onto the node would get wrong. It is not on its own a
+// guarantee that preprocess is idempotent — see the limit recorded at
+// nativePlatform's preprocessors line (#90).
 const WAS_REF = new WeakSet();
+
+// The path the AUTHOR wrote for a node the hoist has moved. hoistDualNodes
+// recurses depth-first, so by the time an outer frame takes Object.entries it
+// already contains names the inner frame synthesised — and a collision reported
+// from that frame named a path appearing nowhere in the source (#61). Recording
+// the authored path when a node is hoisted lets the outer frame report what the
+// author can actually search for.
+//
+// Keyed on node identity, like WAS_REF, and safe across calls for the same
+// reason: preprocess structuredClones its input, so every call works on fresh
+// objects.
+const AUTHORED_PATH = new WeakMap();
 const WHOLE_REF = /^\{[^}]+\}$/;
 
 function interpolate(value, flat) {
@@ -228,20 +244,27 @@ function hoistDualNodes(node, collisions, prefix = [], groupType = undefined) {
       for (const [childKey, childVal] of Object.entries(val)) {
         if (childKey.startsWith('$') || !childVal || typeof childVal !== 'object') continue;
         const hoisted = key + childKey[0].toUpperCase() + childKey.slice(1);
-        const from = [...prefix, key, childKey].join('.');
+        const from = AUTHORED_PATH.get(childVal) ?? [...prefix, key, childKey].join('.');
         if (Object.hasOwn(node, hoisted)) {
           const existingNode = node[hoisted];
-          const isGroup = existingNode !== null && typeof existingNode === 'object' && !('$value' in existingNode);
+          // An array has no $value either, and was therefore labelled "(a group)"
+          // (#61). It is neither — an array at this position is malformed DTCG.
+          // Say so, rather than naming a shape the author will go looking for.
+          const isArray = Array.isArray(existingNode);
+          const isGroup =
+            existingNode !== null && typeof existingNode === 'object' && !isArray && !('$value' in existingNode);
           collisions.push({
             from,
             onto: [...prefix, hoisted].join('.'),
             isGroup,
+            isArray,
             claimant: claimedBy.get(hoisted),
-            existing: isGroup
-              ? undefined
-              : existingNode && typeof existingNode === 'object'
-                ? existingNode.$value
-                : existingNode,
+            existing:
+              isGroup || isArray
+                ? undefined
+                : existingNode && typeof existingNode === 'object'
+                  ? existingNode.$value
+                  : existingNode,
           });
           continue;
         }
@@ -264,8 +287,17 @@ function hoistDualNodes(node, collisions, prefix = [], groupType = undefined) {
         // type suits the child badly, because the hoist is not entitled to
         // improve on what the source says; but the carry firing at all is the
         // hoist saying something the source did not.
+        //
+        // A GROUP child is excluded (#67). The carry's premise is that the dual
+        // node was the child's closest $type-bearing ancestor as authored, and
+        // the hoist took that away. For a group child the premise never held:
+        // 5.2.2 inherits from the closest parent GROUP, the dual node is not
+        // one, so it was never that group's inheritance source and the hoist
+        // removed nothing. Carrying there does not repair, it invents — and it
+        // invents for every token beneath the group, not just one node.
         if (
           !('$type' in childVal) &&
+          '$value' in childVal &&
           '$type' in val &&
           !WAS_REF.has(childVal) &&
           inherited === undefined
@@ -273,6 +305,7 @@ function hoistDualNodes(node, collisions, prefix = [], groupType = undefined) {
           childVal.$type = val.$type;
         }
         node[hoisted] = childVal;
+        AUTHORED_PATH.set(childVal, from);
         delete val[childKey];
         claimedBy.set(hoisted, from);
       }
@@ -371,6 +404,9 @@ function classifyTextUnits(node, types, prefix = []) {
       types[path.join('.')] === 'dimension' &&
       TEXT_ROLE_UNIT.test(String(val.$value).trim())
     ) {
+      // extNamespace throws with the token path if the source authored either
+      // level as a primitive — legal DTCG this module does not handle (#62).
+      extNamespace(val, path.join('.'));
       val.$extensions ??= {};
       val.$extensions[EXT_NS] ??= {};
       const ns = val.$extensions[EXT_NS];
@@ -379,7 +415,9 @@ function classifyTextUnits(node, types, prefix = []) {
       // one, so a unitless value is declined by every size transform regardless
       // of what is stamped here (see isRatio, #52). Declining to overwrite IS
       // the feature: it costs no configuration parameter, and it is what makes
-      // the pass idempotent.
+      // STAMPING idempotent — a second pass never rewrites a role a first pass
+      // set. What it does not settle is whether a second pass finds the same
+      // candidates; the hoist can rename a node between the two (#90).
       if (!('nativeUnit' in ns)) ns.nativeUnit = 'text';
     }
     classifyTextUnits(val, types, path);
@@ -402,7 +440,8 @@ function classifyTextUnits(node, types, prefix = []) {
 // A path may name no node at all. resolveInPlace deliberately leaves an
 // unresolvable reference in place for Style Dictionary to report, so the graph
 // can hold an edge to a token that does not exist. Skip it. This is also what
-// keeps the second preprocess pass from throwing, and idempotency with it.
+// keeps the second preprocess pass from throwing — which is a precondition for
+// idempotency, not the whole of it (#90).
 function applyTextRoleGraph(node, typographic, types) {
   for (const path of typographic) {
     let target = node;
@@ -412,6 +451,7 @@ function applyTextRoleGraph(node, typographic, types) {
     if (!target || typeof target !== 'object' || !('$value' in target)) continue;
     if (types[path] !== 'dimension') continue;
     if (!TEXT_ROLE_UNIT.test(String(target.$value).trim())) continue;
+    extNamespace(target, path);
     target.$extensions ??= {};
     target.$extensions[EXT_NS] ??= {};
     const ns = target.$extensions[EXT_NS];
@@ -426,14 +466,16 @@ export function preprocess(dict) {
   // the graph is made of.
   const { typographic } = textRoleGraph(dict);
   const resolved = resolveInPlace(structuredClone(dict), flattenDtcg(dict));
-  // DTCG 5.2.2 types for the whole tree, walked once and shared by both passes
-  // below. Neither writes $type or moves a node, so one map is correct for
-  // both, and sharing it is what makes them agree by construction rather than
-  // by two copies of the same rule staying in step (#85).
+  // Types for the whole tree, walked once and shared by both passes below.
+  // Neither writes $type or moves a node, so one map is correct for both, and
+  // sharing it is what makes them agree by construction rather than by two
+  // copies of the same rule staying in step (#85).
   //
-  // Computed on the RESOLVED clone, which is the tree both passes read.
-  // resolveInPlace rewrites $value strings only, so the types are the source's.
-  const types = flattenDtcgTypes(resolved);
+  // Computed on the RAW dict, not the resolved clone. resolveInPlace only
+  // rewrites $value strings, so paths and types are identical between the two —
+  // except for the carry, whose rule asks whether a value WAS a whole-value
+  // reference, and resolution has already destroyed that (#89).
+  const types = flattenPipelineTypes(dict);
   const out = hoistDualNodes(
     applyTextRoleGraph(classifyTextUnits(resolved, types), typographic, types),
     collisions,
@@ -443,6 +485,9 @@ export function preprocess(dict) {
       .slice(0, 5)
       .map((c) => {
         const line = `  ${c.from} -> ${c.onto}`;
+        if (c.isArray) {
+          return line + ' (an array — neither a token nor a group, and not valid DTCG here)';
+        }
         if (c.isGroup) {
           return line + (c.claimant ? ` (a group, already claimed by the hoist of ${c.claimant})` : ' (a group)');
         }
@@ -629,7 +674,14 @@ const DECLINED_STOCK_TRANSFORMS = {
 // Order is never compared: our lists are hand-ordered for our own reasons and
 // do not inherit stock order. Removals are never reported: a declined name
 // disappearing is a non-event.
-export function auditStockGroups(transformGroups) {
+// `platforms` and `declined` are parameters with the shipped config as their
+// default, so the contradiction branch below is reachable from a test. The
+// single caller passes neither; the audit's contract is unchanged.
+export function auditStockGroups(
+  transformGroups,
+  platforms = PLATFORMS,
+  declined = DECLINED_STOCK_TRANSFORMS,
+) {
   if (typeof transformGroups !== 'object' || transformGroups === null) {
     return [
       "throughline: could not read Style Dictionary's stock transform groups " +
@@ -638,7 +690,29 @@ export function auditStockGroups(transformGroups) {
     ];
   }
   const warnings = [];
-  for (const [platform, preset] of Object.entries(PLATFORMS)) {
+  for (const [platform, preset] of Object.entries(platforms)) {
+    // A name in BOTH lists is a contradiction the unaccounted filter below
+    // cannot see, because either membership alone suppresses the warning (#75).
+    // The config would be saying "we run this" and "we deliberately do not" at
+    // once, and whichever is wrong is silently the loser: if the decline is
+    // right the transform still runs, and if the run is right the decline is a
+    // lie the next maintainer will read as settled. Reported here rather than
+    // guarded at the definition, so it travels with the rest of the audit.
+    //
+    // Checked before stockGroup, because this is wrong regardless of whether
+    // Style Dictionary still has the group to compare against.
+    if (Array.isArray(preset.transforms)) {
+      const contradictory = preset.transforms.filter((name) => Object.hasOwn(declined, name));
+      if (contradictory.length) {
+        warnings.push(
+          `throughline: PLATFORMS['${platform}'] both runs and declines ` +
+            `${contradictory.join(', ')}. A transform cannot be in transforms and in ` +
+            'DECLINED_STOCK_TRANSFORMS at once — one of the two is wrong, and the ' +
+            'audit cannot tell which. This is a throughline packaging defect — ' +
+            'please report it.',
+        );
+      }
+    }
     const group = preset.stockGroup;
     if (!group || !Array.isArray(preset.transforms)) {
       warnings.push(
@@ -662,7 +736,7 @@ export function auditStockGroups(transformGroups) {
     const unaccounted = stock.filter(
       (name) =>
         !preset.transforms.includes(name) &&
-        !Object.hasOwn(DECLINED_STOCK_TRANSFORMS, name),
+        !Object.hasOwn(declined, name),
     );
     if (unaccounted.length) {
       const n = unaccounted.length;
@@ -764,8 +838,21 @@ export function nativePlatform({ platform, buildPath, className = 'Tokens', pack
     // Carried here, not left to the caller: authored() reads the ORIGINAL
     // $value, so without this preprocessor every aliased dimension still holds
     // an unresolved {spacing.space.4}, no size transform fires, and the build
-    // emits bare px literals. preprocess is idempotent, so a project that also
-    // declares it at top level is harmless.
+    // emits bare px literals.
+    //
+    // A project that ALSO declares this preprocessor at top level runs it twice,
+    // which is harmless in every shape measured — and is the wiring our own
+    // usage snippet shows, so it is the common case rather than a corner.
+    //
+    // Stated no wider than it holds (#90): preprocess is idempotent except where
+    // the hoist invents a name the second pass then classifies. `a.font` with a
+    // child `size` camel-joins to `a.fontSize`; the first pass correctly declines
+    // `size`, and the second sees a typographic member name the source never
+    // authored. It changes no emitted output — Style Dictionary runs
+    // typeDtcgDelegate between the two passes and types that child anyway, so
+    // both passes reach the same file — and the repair belongs with the hoist,
+    // which has no way to record the names it invented. Pinned by test rather
+    // than papered over.
     preprocessors: ['dtcg/resolve-dual-node'],
     buildPath,
     options: { outputReferences: false },