feat(designbook): technology-neutral IR + stack-adapter pipeline (WHYNOT-WP-0002 T01-T06)

Author the design language once in the canonical React designbook and project it
one-way onto each stack: React -> designbook/ -> ir/ -> adapters/<stack>/.

Phase 0 — contracts & governance (T01-T03):
- ir/SCHEMA.md + ir/schema/{component,tokens}.schema.json — neutral IR contract
  (W3C DTCG tokens; React prop -> HTML attribute mapping; non-portable props flagged).
- adapters/ADAPTER_CONTRACT.md — inputs, drift-report + parity-result shapes,
  idempotency rules, CI exit codes (0 ok / 2 usage / 3 drift / 4 parity / 5 internal).
- .claude/rules/designbook-propagation.md + DesignSystemIntroduction.md §5.1 —
  one-way directionality + drift-resolution workflow.

T04 — canonical React designbook + the missing pull tool:
- The bundled /design-sync skill only PUSHES repo->cloud; it cannot populate
  designbook/. Added scripts/designbook_pull.py + `make designbook-pull`, which drives
  the local claude binary headless (acceptEdits) so DesignSync fetch+write runs in a
  subprocess (contents never hit the orchestrator's context). Pulled 44 files;
  excludes the _whynot-design-seed/ self-copy. Corrected the docs that wrongly called
  /design-sync the pull.

T05 — IR extractor (scripts/ir-extract.mjs + `make ir`):
- ir/tokens.json (80 tokens, DTCG, var() -> {ref} alias resolution); ir/components/*.json
  (10 contracts parsed from .jsx signatures: enum/boolean/number inference, prop->attr
  map, style/callback marked non-portable); ir/exemplars/*.

T06 — Lit token adapter (adapters/lit/ + `make adapt-lit`):
- Full-gen tokens into src/styles/colors_and_type.css :root (marker-bounded, idempotent
  no-op on re-run; hand-authored type CSS preserved).

NOTE: token regen synced Lit to canonical React — fonts IBM Plex -> system stacks and 8
status tokens added. This is a VISUAL change: review and run `pnpm test:visual:update`
before merge. Remaining: T07 scaffold+drift, T08 parity, T09 runbook, T10 2nd-adapter.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.claude/rules/designbook-propagation.md

@@ -0,0 +1,59 @@
+## Designbook propagation & adapter governance (WHYNOT-WP-0002)
+
+The whynot design language is **technology-neutral**. It is authored once and
+projected onto each UI stack through an intermediate representation. These rules
+keep that flow one-way and the stacks in sync.
+
+### Directionality — one way only
+
+```
+Claude Design (React, canonical)  →  designbook/  →  ir/  →  adapters/<stack>/ → stack source
+```
+
+- **Claude Design (the React designbook) is the source of truth** for the *language*.
+- **Never hand-edit `ir/`** — `ir/tokens.json`, `ir/components/*.json`, and
+  `ir/exemplars/*` are written only by the extractor (`scripts/ir-extract.mjs`,
+  `make ir`). They are committed so blueprint changes show up as a git diff.
+  Authored-by-hand exceptions: `ir/schema/`, `ir/SCHEMA.md`, `ir/README.md`.
+- **Never back-edit React/Claude Design from a stack.** A Lit (or any stack) change
+  that should alter the shared language must be made in Claude Design and
+  re-propagated. A direct stack→React edit that bypasses Claude Design is a
+  governance violation — it desyncs the canonical source from the implementation.
+- **Adapters never overwrite hand-authored behaviour.** Tokens regenerate fully;
+  new components get stubs; changed components get a **drift report**, never a
+  rewrite. See `adapters/ADAPTER_CONTRACT.md`.
+
+### When the cloud designbook moves
+
+Run the refresh sequence (orchestrated by `make designbook-refresh`, WHYNOT-WP-0002
+Phase 5); do not shortcut it:
+
+1. `make designbook-check` — detect the cloud designbook moved ahead.
+2. `make designbook-pull` — pull the latest React designbook into `designbook/`
+   (drives the local `claude` binary headless via `DesignSync`; stamps freshness
+   itself). The bundled `/design-sync` skill *pushes* repo→cloud and does **not**
+   populate `designbook/` — use `make designbook-pull` for the pull.
+3. `make designbook-sync` — record the diff in `RecentChanges.md`.
+4. `make ir` — re-extract the IR; **review the `ir/` git diff** (the blueprint change).
+5. `make adapt-lit` — regenerate tokens, scaffold new components, emit drift reports.
+6. **Resolve drift** (human) — fill/adjust Lit behaviour per `adapters/lit/drift/*.md`.
+7. `make parity-lit` — confirm appearance + contract parity (gate).
+
+### Drift triage
+
+A drift report (`adapters/lit/drift/<Name>.md`, command exit code `3`) is resolved
+by a human, not the adapter:
+
+- Decide direction: stale stack → fix the stack to match IR; language should change
+  → edit Claude Design and re-propagate (never patch only the stack).
+- **Non-portable props** (React objects, render props, callbacks) are surfaced as
+  drift on purpose and must be handled explicitly — never silently dropped.
+- A report is closed when a fresh `make ir && make adapt-lit` produces no issues
+  for that component and `make parity-lit` passes (exit `0`).
+
+### Exit codes (CI)
+
+`0` ok · `2` usage/config error · `3` drift detected (stop for human triage) ·
+`4` parity failure (fail) · `5` internal error. See `adapters/ADAPTER_CONTRACT.md`.
+
+Full narrative: `DesignSystemIntroduction.md` §5.1.

.claude/rules/stack-and-commands.md

@@ -28,7 +28,7 @@ There is no unit-test suite — correctness is verified by full-page Playwright
 
 The **designbook** is the upstream atelier — the **Claude Design project** (cloud, `claude.ai/design`), source of truth for the *language*. Its local mirror lives in-repo at `designbook/` (see `designbook/README.md`). Sync is **agent-driven and incremental** (one component at a time, never a wholesale replace):
 
-1. **Pull** — run `/design-sync` in Claude Code (the `DesignSync` tool over the claude.ai login); it writes into `designbook/`. Immediately stamp the time: `node scripts/designbook-sync.mjs --mark-synced`. A Makefile cannot invoke the MCP tool, so the pull is always an agent step.
+1. **Pull** — run `make designbook-pull` (`scripts/designbook_pull.py`). It drives the local `claude` binary headless (`claude --print --permission-mode acceptEdits`), which has the `DesignSync` tool over the claude.ai login, to fetch the React designbook and write it into `designbook/`; the file contents stay in that subprocess, so the pull is cheap regardless of size. Selection is governed by `designbook/.design-pull.json` (it excludes `_whynot-design-seed/**`, the cloud project's copy of this repo). The script stamps freshness itself on success. **Note:** the bundled `/design-sync` skill goes the *other* way — it *pushes* a repo up to Claude Design — so it does **not** populate `designbook/`; use `make designbook-pull` for the pull (see `designbook-propagation.md`).
 2. **Record** — `make designbook-sync` runs `scripts/designbook-sync.mjs`, writing `RecentChanges.md`: a **snapshot** (not a log) of what changed across `designbook/` + the derived surfaces (`tokens/`, `src/styles/`, `src/elements/`, `examples/`), grouped by layer.
 
 **Freshness** is tracked in `designbook/.design-sync.json` (`lastSyncAt`, `remoteUpdatedAt`, `projectId`, `projectName`). Every report states **"Last /design-sync: <datetime>"** so it's clear whether the snapshot reflects the latest design. The cloud-ahead check is backed by **llm-connect** (`make designbook-check` → `scripts/check_designbook_staleness.py`): it uses the `claude-code` adapter to ask the local `claude` binary for the project's current `updatedAt` via `DesignSync.list_projects`, then records it with `node scripts/designbook-sync.mjs --remote-updated <iso>`. Only the `claude-code` adapter can reach the user's Claude Design project (Gemini/OpenRouter/OpenAI cannot), and no secret goes in the prompt — DesignSync uses the claude.ai login (see `credential-routing.md`). The check needs `llm_connect` importable; the Makefile auto-selects `~/llm-connect/.venv/bin/python`. Use `--remote-updated <iso>` to run the comparison offline/manually, or `--fail-if-stale` (exit 3) in automation. When `remoteUpdatedAt` is newer than `lastSyncAt`, the report and stdout **warn that the local mirror is OUTDATED** until the next `/design-sync`. If no sync was ever recorded, it warns that `/design-sync` has not run. The reporter is deterministic (built from `git status`/`git diff`), only writes the working tree, never commits, and never edits `designbook/` content. Fold notable entries into `CHANGELOG.md` under `## [Unreleased]` before releasing — `RecentChanges.md` is overwritten every run and is **not** the CI-enforced artifact.