@hegemonart/get-design-done 1.33.5 → 1.34.1

package/hooks/budget-enforcer.ts

@@ -93,6 +93,22 @@ interface BudgetEnforcerBackend {
     reason: string | null;
   };
   modelFromResolved(resolved: unknown, agent: string): string | null;
+  // Plan 33.6-03 (SC#6): the canonical cost-row payload builder (the
+  // types.ts:237-designated emit site). Threads the optional `provider` tag
+  // ("openrouter" when the OpenRouter adapter resolved the model), omitting it
+  // when absent (back-compat).
+  buildCostEventPayload(args: {
+    runtime: string;
+    agent: string;
+    model_id: string | null;
+    tier: string | null;
+    tokens_in: number;
+    tokens_out: number;
+    cost_usd: number | null;
+    runtime_role?: 'host' | 'peer';
+    peer_id?: string | null;
+    provider?: string;
+  }): Record<string, unknown>;
 }
 const budgetBackend = nodeRequire('../scripts/lib/budget-enforcer.cjs') as BudgetEnforcerBackend;
 // Plan 26-05: runtime detection for the cost-event runtime tag. Returns
@@ -175,6 +191,51 @@ const tierResolver = nodeRequire(
   '../scripts/lib/tier-resolver.cjs',
 ) as TierResolverModule;
 
+// Plan 33.6-03 (SC#6, D-08, D-12): OpenRouter tier-resolver adapter. When the
+// user opts in (`.design/config.json#openrouter_enabled: true` OR
+// `OPENROUTER_API_KEY` present), the hook consults this adapter FIRST for a
+// resolved model; a non-null result routes to OpenRouter and tags the cost row
+// `provider: "openrouter"`, a null result falls back to the native resolution
+// path (unchanged default behavior). `resolve(tier, opts)` never throws.
+interface TierResolverOpenRouterModule {
+  resolve(
+    tier: string,
+    opts?: { catalog?: unknown; models?: unknown; overrides?: unknown; cachePath?: string; configPath?: string; cwd?: string },
+  ): string | null;
+}
+const tierResolverOpenRouter = nodeRequire(
+  '../scripts/lib/tier-resolver-openrouter.cjs',
+) as TierResolverOpenRouterModule;
+
+/**
+ * Plan 33.6-03 (SC#6 opt-in). OpenRouter is consulted ONLY when the user opts
+ * in — either `.design/config.json#openrouter_enabled === true` OR
+ * `OPENROUTER_API_KEY` is present in the environment. Best-effort + never
+ * throws: a missing/corrupt config degrades to "env var only". This keeps the
+ * default (no OpenRouter) behavior byte-identical for every existing user
+ * (D-08, D-12).
+ *
+ * @param cwd base dir for `.design/config.json` (default process.cwd())
+ */
+function isOpenRouterEnabled(cwd?: string): boolean {
+  if (
+    typeof process.env.OPENROUTER_API_KEY === 'string' &&
+    process.env.OPENROUTER_API_KEY.length > 0
+  ) {
+    return true;
+  }
+  try {
+    const configPath = join(cwd ?? process.cwd(), '.design', 'config.json');
+    if (!existsSync(configPath)) return false;
+    const parsed = JSON.parse(readFileSync(configPath, 'utf8')) as {
+      openrouter_enabled?: unknown;
+    };
+    return Boolean(parsed && parsed.openrouter_enabled === true);
+  } catch {
+    return false;
+  }
+}
+
 // ── Types ───────────────────────────────────────────────────────────────────
 
 /**
@@ -661,6 +722,11 @@ function emitCostRecorded(
     tokens_in: number;
     tokens_out: number;
     cost_usd: number | null;
+    // Plan 33.6-03 SC#6 — optional resolution provider ("openrouter" when the
+    // OpenRouter adapter resolved the model). Additive/back-compat: omitted
+    // from the on-disk row when absent, so the legacy cost_recorded shape is
+    // preserved for every native-resolution + pre-33.6 spawn.
+    provider?: string;
   },
   cycle?: string,
 ): void {
@@ -677,6 +743,10 @@ function emitCostRecorded(
       tokens_in: payload.tokens_in,
       tokens_out: payload.tokens_out,
       cost_usd: payload.cost_usd,
+      // Omit-when-absent (mirrors the .cjs buildCostEventPayload discipline).
+      ...(typeof payload.provider === 'string' && payload.provider.length > 0
+        ? { provider: payload.provider }
+        : {}),
     },
   };
   try {
@@ -1149,6 +1219,36 @@ export async function main(): Promise<void> {
     }
   }
 
+  // ── Plan 33.6-03 — OpenRouter resolution consultation (SC#6, D-08, D-12) ────
+  //
+  // When the user opts in (`.design/config.json#openrouter_enabled: true` OR
+  // `OPENROUTER_API_KEY` present), consult the OpenRouter adapter for the
+  // effective tier FIRST. A non-null result routes this spawn to OpenRouter:
+  // we override the model id and tag the cost row `provider: "openrouter"`. A
+  // null result (no key / catalog missing-or-stale / no match) falls through to
+  // the native resolution that's already in `effectiveModelId` — so the default
+  // (OpenRouter disabled) path is byte-identical to pre-33.6 behavior (D-08).
+  // The adapter never throws; this whole branch is also wrapped defensively.
+  let costProvider: string | undefined;
+  if (isOpenRouterEnabled()) {
+    try {
+      const openrouterModel = tierResolverOpenRouter.resolve(effectiveTier);
+      if (typeof openrouterModel === 'string' && openrouterModel.length > 0) {
+        effectiveModelId = openrouterModel;
+        costProvider = 'openrouter';
+        // Reflect the OpenRouter pick into resolved_models so downstream
+        // consumers see the actual model (mirrors the bandit override above).
+        if (routerDecision !== undefined) {
+          const rm = routerDecision.resolved_models ?? {};
+          rm[agent] = openrouterModel;
+          routerDecision.resolved_models = rm;
+        }
+      }
+    } catch {
+      // Fail open — never let OpenRouter resolution block a spawn (D-08).
+    }
+  }
+
   // Compute runtime-aware cost via the shared backend. Failures return
   // null cost; we emit the event regardless so the cost-aggregator sees
   // the lookup attempt (Phase 22 events.jsonl tagging).
@@ -1169,6 +1269,9 @@ export async function main(): Promise<void> {
       tokens_in: Number(toolInput._tokens_in_est ?? 0),
       tokens_out: Number(toolInput._tokens_out_est ?? 0),
       cost_usd: costLookup.cost_usd,
+      // Plan 33.6-03 SC#6 — tag the row when OpenRouter resolved the model.
+      // Omitted (undefined) on the native path → buildCostEventPayload drops it.
+      ...(costProvider !== undefined ? { provider: costProvider } : {}),
     },
     cycle,
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.33.5",
+  "version": "1.34.1",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -113,6 +113,7 @@
     "ws": "^8.20.0"
   },
   "overrides": {
-    "fast-json-patch": "^3.1.1"
+    "fast-json-patch": "^3.1.1",
+    "qs": ">=6.15.2"
   }
 }

package/reference/gdd-threat-model.md

@@ -43,6 +43,7 @@ controls; the table names what crosses the line.
 | gdd-state MCP `←` environment / config / tool input | Whoever sets `GDD_STATE_PATH` or supplies a tool-call payload, or authors `.design/config.json` | The `GDD_STATE_PATH` env value + the JSON tool-input payloads |
 | Peer-CLI broker `↔` spawned child | A spawned peer CLI (Codex / Gemini / Cursor / Copilot / Qwen) and its stdout stream | The child's stdout JSON frames + the parent env handed to the child |
 | Outbound call sites `↔` external host | The remote HTTP host / GitHub / Figma the call reaches | The outbound request payload + whatever the remote returns |
+| OpenRouter catalog fetch `→` openrouter.ai | The OpenRouter `/models` API host (and any MITM on the path) | The `Authorization: Bearer <OPENROUTER_API_KEY>` request header + the untrusted `/models` JSON the host returns |
 
 The event payloads that traverse the bus (and therefore the WS transport and
 any persisted JSONL) are scrubbed at serialize time — see Component 4's
@@ -311,6 +312,68 @@ model).
 
 ---
 
+## Component 6 — OpenRouter catalog fetcher (scripts/lib/openrouter/catalog-fetcher.cjs)
+
+> Added in Phase 33.6 (OR-01, CONTEXT D-06). This is the runtime's **first
+> plugin-side outbound REST client** — the issue-reporter (Component 5) reaches
+> the network only through the user's `gh` CLI, and the WS transport (Component
+> 4) is a *server*, not an outbound client. The catalog fetcher is the first
+> first-party code to open an outbound HTTP request to a third-party host
+> directly, which is why it lands only after the 33.5 audited baseline and the
+> `scan:outbound` gate (33.5-04) are in place.
+
+`scripts/lib/openrouter/catalog-fetcher.cjs` performs a read-only GET to the
+OpenRouter model catalog (`https://openrouter.ai/api/v1/models`) through an
+**injectable `fetchImpl`** (default global `fetch`), maps the response into the
+`.design/cache/openrouter-models.json` cache shape, and writes it atomically.
+The live fetch is opt-in — gated on `OPENROUTER_API_KEY` being present at
+runtime; absent it, the fetcher returns cached-if-any-else-null and tier
+resolution falls back to the native provider.
+
+- **Assets:** The **`OPENROUTER_API_KEY`** (a billable provider credential) and
+  the integrity of the cached catalog the tier-resolver later trusts.
+- **Entry points:** The **`/models` JSON the OpenRouter host returns** (untrusted
+  remote input the fetcher must parse), and the `OPENROUTER_BASE_URL` env (an
+  operator-supplied endpoint override).
+- **STRIDE threats:**
+  - **Spoofing:** A spoofed `/models` endpoint (DNS/MITM, or a hostile
+    `OPENROUTER_BASE_URL`) could feed a forged catalog.
+  - **Tampering:** A malformed/oversized `/models` body could try to corrupt the
+    cache the resolver reads, or smuggle unexpected fields downstream.
+  - **Information disclosure:** **The headline risk** — leaking the
+    `OPENROUTER_API_KEY` by persisting it to the cache, logging it, or sending it
+    to an unintended host.
+  - **Denial of service:** A hung or slow host could stall the fetch; a giant
+    catalog could pressure memory.
+  - **Elevation of privilege:** A forged catalog could steer tier resolution to
+    an attacker-chosen model id.
+- **Current mitigations:** The key is read from **`OPENROUTER_API_KEY` env only**,
+  sent **solely** as an `Authorization: Bearer` request header, and is **never
+  persisted to the cache nor written to any log seam** — the cache shape carries
+  only `id`/`name`/`context_length`/`pricing`, and the mapper keeps **only** those
+  fields, dropping everything else (the `/models` body is **mapped, never
+  eval'd**). The cache write is **atomic** (per-pid temp + rename) into the
+  **gitignored** `.design/cache/`, so a partial/corrupt fetch can't leave a
+  half-written catalog and the cache never enters git history. The fetcher
+  **never throws** (D-08): no key / fetch failure / parse failure all degrade to
+  cached-if-any-else-null, bounding the DoS surface, and retries are **bounded**
+  (max 3 attempts) on a jittered-backoff curve with `rate-guard` awareness.
+  Egress is **allowlisted** via `scripts/lib/openrouter/**` in
+  `scripts/security/outbound-allowlist.json` — the only sanctioned outbound site
+  in that subtree — so the 33.5 `scan:outbound` gate proves no un-approved egress
+  crept in. The **injectable `fetchImpl`** keeps the default `npm test` suite
+  hermetic (D-07) — no live network — and there is **no new HTTP dependency**
+  (global `fetch` + `sdk/primitives` only — D-10), avoiding both a new supply-chain
+  surface and the gate's `axios`/`node-fetch`/`undici` package patterns.
+- **Residual risks:** None this phase leaves open. The catalog is advisory data
+  consumed by the tier-resolver heuristic (33.6-02), which already clamps to
+  GDD's `opus`/`sonnet`/`haiku` vocabulary and supports user overrides, so a
+  forged catalog cannot escalate beyond model-id selection within that bounded
+  set; a future hardening could pin the OpenRouter TLS cert or sign the cache,
+  but neither is required for the current trust model.
+
+---
+
 ## Residual-risk → closing-plan map
 
 Every residual risk identified above is routed to the Phase 33.5 plan (or

package/reference/native-platforms.md

@@ -0,0 +1,273 @@
+# Native Platforms — Token-Bridge Spec
+
+This reference is the **token→native-code bridge**: it specifies how the canonical
+CSS-token form produced by the Phase-23 token engine
+(`scripts/lib/design-tokens/`) maps onto the three native theme systems —
+SwiftUI, Jetpack Compose, and Flutter — and pins down the **precision contract**
+that defines what "token identity preserved" means for the deterministic
+round-trip (`reference/native-platforms.md` is the authority that
+`test/suite/native-token-bridge.test.cjs` asserts against).
+
+It is the sibling of [`reference/platforms.md`](./platforms.md). Those two files
+have distinct jobs and must not be confused:
+
+| File | Job |
+| --- | --- |
+| `reference/platforms.md` (Phase 19) | Interaction **conventions** — navigation, safe areas, gestures, native typography, haptics. *Behavioral* knowledge the executors reference when laying out a screen. |
+| `reference/native-platforms.md` (Phase 34.1, this file) | The token→theme **bridge** — how a design token (`#3B82F6`, `16px`, `Inter`) becomes a SwiftUI `Color` / Compose `Color(0x…)` / Flutter `Color(0x…)`, plus the precision contract for the round-trip. *Structural* knowledge the emitters implement. |
+
+Per **D-02** the bridge **extends** the Phase-23 engine with three new emitters
+(`scripts/lib/design-tokens/{swift,compose,flutter}.cjs`) rather than forking a
+separate native IR. There is one canonical token form (below) and one set of
+readers; the native emitters are additional *sinks* on the same facade. Per
+**D-10** the round-trip operates at the **token level** — deterministic emit +
+re-extract with documented precision — never full-view parsing and never a live
+simulator, so the default `npm test` stays green on any machine.
+
+---
+
+## 1. Purpose
+
+Phase 19 shipped platform *references* but zero generators; Phase 23 shipped a
+multi-source token reader (`css-vars` / `js-const` / `tailwind` / `figma`) that
+all normalise to a single flat `{ tokens: Record<string, string> }` map. Phase
+34.1 crosses from platform-knowledge into platform-execution: instead of each
+native executor re-deriving "how does `#3B82F6` become a SwiftUI `Color`", the
+mapping lives once here (the spec) and once in the emitters (the
+implementation), and the executors consume it. This amortizes the Phase-23 token
+investment across SwiftUI / Compose / Flutter.
+
+The canonical CSS-token form is the **single input** to all three native
+emitters. This spec maps that one input to three native theme systems and states
+the precision each mapping preserves.
+
+---
+
+## 2. Canonical input shape
+
+The emitters consume the exact map shape the Phase-23 readers return: a **flat
+`{ tokens: Record<string, string> }` object** whose keys are the design-token
+names with the leading `--` stripped (exactly as `css-vars.cjs` returns) and
+whose values are the raw token values as strings.
+
+```js
+{ tokens: { "color-primary": "#3B82F6", "space-4": "16px", "font-family-body": "Inter, system-ui" } }
+```
+
+Each emitter accepts either the full Phase-23 `TokenSet`
+(`{ tokens, source?, format? }`) **or** a bare `{ tokens }` object — it reads
+`tokenSet.tokens` and throws a `TypeError` only when no `.tokens` object is
+present.
+
+### Prefix → category inference
+
+Token **category** is inferred from the key prefix. The emitters use this table
+to decide whether a value is a color, a dimension, or a string:
+
+| Key prefix | Category | Native treatment |
+| --- | --- | --- |
+| `color-` | color | hex → native channel form (§3–§5, §6 COLOR) |
+| `space-`, `spacing-` | dimension | px → pt / dp / logical px (§6 DIMENSION) |
+| `radius-` | dimension | px → pt / dp / logical px |
+| `size-` | dimension | px → pt / dp / logical px |
+| `font-`, `text-` | typography | string pass-through (family / weight / named size) |
+| `shadow-` | other | string pass-through (composite values are non-mappable) |
+| *(anything else)* | other | value-sniffed: a `#…` value is treated as color, an `Npx` value as dimension, otherwise string pass-through |
+
+A value is **always** re-sniffed regardless of prefix, so a `#…` value under a
+non-color prefix is still emitted as a color and a `Npx` value under a non-space
+prefix is still emitted as a dimension. The prefix is the hint; the value is the
+authority. This keeps the bridge robust against arbitrary token-naming schemes.
+
+---
+
+## 3. SwiftUI mapping
+
+Target: a Swift source string exposing an `enum` of static theme constants
+(`enum GDDTheme { … }`) — colors as `Color`, dimensions as `CGFloat` points,
+typography families as `String` (and an optional `Font` helper).
+
+| Token | SwiftUI form |
+| --- | --- |
+| color `#RRGGBB` | `Color(red: R/255.0, green: G/255.0, blue: B/255.0, opacity: A/255.0)` from the 8-bit channels |
+| dimension `Npx` | `CGFloat` point literal — integer `N` (pt) |
+| font-family | `String` literal (`"Inter, system-ui"`) |
+
+Illustrative (2-line) snippet:
+
+```swift
+static let colorPrimary = Color(red: 59.0/255.0, green: 130.0/255.0, blue: 246.0/255.0, opacity: 255.0/255.0)
+static let space4: CGFloat = 16
+```
+
+SwiftUI uses normalized `0.0…1.0` channel fractions; to keep the round-trip
+**exact** the emitter writes each channel as the 8-bit numerator over `255.0`
+(e.g. `59.0/255.0`) rather than a pre-divided decimal — the re-extractor reads
+the numerator back as the integer channel, avoiding float drift. The `Color` /
+`Font` / `ViewModifier` consumption pattern (applying the constants to views) is
+the executor's job; this emitter produces the *constants*.
+
+---
+
+## 4. Jetpack Compose mapping
+
+Target: a Kotlin source string with `Color` vals, a `Shapes` block (from
+`radius-` tokens), a `Typography` block (from `font-`/`text-` tokens), and a
+`MaterialTheme` wiring (`object GDDTheme { val Colors… ; val Shapes… ; val Typography… }`).
+
+| Token | Compose form |
+| --- | --- |
+| color `#RRGGBB` | `Color(0xAARRGGBB)` long literal (alpha-first, 8 hex digits) |
+| dimension `Npx` | `N.dp` (integer dp) |
+| radius `Npx` | `RoundedCornerShape(N.dp)` inside `Shapes` |
+| typography family | `String` (fed into a `TextStyle.fontFamily` slot / `Typography`) |
+
+Illustrative (2-line) snippet:
+
+```kotlin
+val colorPrimary = Color(0xFF3B82F6)
+val space4 = 16.dp
+```
+
+Compose packs ARGB into a single `0xAARRGGBB` long; alpha is the high byte. The
+re-extractor reads the 8 hex digits straight back to the channels.
+
+---
+
+## 5. Flutter mapping
+
+Target: a Dart source string building a `ThemeData` whose `colorScheme`
+(`ColorScheme`) carries the color tokens and whose `textTheme` (`TextTheme`)
+carries the typography tokens, plus a constants class
+(`class GDDTheme { … }`).
+
+| Token | Flutter form |
+| --- | --- |
+| color `#RRGGBB` | `Color(0xAARRGGBB)` (alpha-first, 8 hex digits) |
+| dimension `Npx` | logical-px **double** — `N.0` |
+| typography family | `String` (`fontFamily: 'Inter'`) |
+
+Illustrative (2-line) snippet:
+
+```dart
+static const colorPrimary = Color(0xFF3B82F6);
+static const space4 = 16.0;
+```
+
+Flutter measures in logical pixels and keeps the value as a `double` (`16.0`),
+so — unlike pt/dp — Flutter dimensions are **not** rounded to integers; the
+fractional part survives.
+
+---
+
+## 6. PRECISION CONTRACT
+
+This section is the crux. It defines, per value category, exactly what
+information the emit → re-extract round-trip preserves. The test asserts token
+identity **within this precision** — not bit-exact floats, not lossy
+approximation. An emitter is correct **iff** `reextract(emit({tokens}))`
+reproduces every token in the identity set under these rules.
+
+### COLOR — 8-bit-per-channel, EXACT
+
+- Accepted input forms: `#RGB`, `#RRGGBB`, `#RGBA`, `#RRGGBBAA` (case-insensitive).
+- `#RGB` / `#RGBA` shorthand **expands** to `#RRGGBB` / `#RRGGBBAA` by
+  duplicating each nibble (`#3af` → `#33aaff`). This expansion is part of the
+  contract: the re-extractor recovers the **expanded** `#RRGGBB(AA)` form, so
+  `#3af` round-trips to `#33aaff` (canonically equal, the documented identity).
+- Each channel is an 8-bit integer (0–255) and is preserved **exactly** — no
+  channel may be off by one. SwiftUI stores channels as `N.0/255.0` numerators;
+  Compose/Flutter store them in a `0xAARRGGBB` literal. Both forms recover the
+  identical 8-bit channels.
+- **Alpha:** when the input has no alpha (`#RGB`/`#RRGGBB`) the emitted color is
+  **opaque** — alpha byte `0xFF` (Compose/Flutter) / `opacity: 255.0/255.0`
+  (SwiftUI). The re-extractor emits an alpha channel **only when the original
+  had one**: a 6-digit input round-trips to a 6-digit `#RRGGBB` (the implied
+  opaque alpha is dropped on the way back); an 8-digit input round-trips to the
+  8-digit `#RRGGBBAA`. This keeps `#3B82F6 → #3B82F6` an exact identity.
+
+### DIMENSION — integer pt/dp, logical-px double
+
+- Accepted input: `Npx` or a bare unit-less number (`16px`, `16`). The unit is
+  normalised to `px` on the canonical side.
+- **iOS (pt) / Android (dp):** rounded to the nearest integer, **round-half-up**
+  (`15.5px` → `16`). Because rounding is lossy for non-integers, the round-trip
+  **identity set** is restricted to integer-px dimensions (e.g. `16px`), which
+  recover exactly: `16px → 16 (pt/dp) → 16px`.
+- **Flutter (logical px):** kept as a `double` (`16px` → `16.0`), so Flutter
+  does **not** round and a fractional dimension survives. The re-extractor
+  recovers `Npx` by stripping the trailing `.0` for whole numbers.
+- The re-extractor always recovers the canonical `Npx` string form, so the
+  emit→re-extract identity for an integer dimension is `"16px" === "16px"`.
+
+### `rem` / `em` — passed through verbatim (non-mappable)
+
+`rem`/`em` values depend on a root/element font-size that the token map does not
+carry, so they are **not** converted. They are treated as **non-mappable**
+(below): emitted verbatim into a raw slot and **excluded** from the round-trip
+identity set. (A future plan may add an explicit base-size option; until then,
+verbatim pass-through is the stated, deterministic behavior.)
+
+### TYPOGRAPHY / NAMED VALUES — string pass-through
+
+`font-family`, `font-weight`, named sizes, and any other string token are
+emitted **verbatim** as a string literal and recovered **string-equal**
+(`"Inter, system-ui" → "Inter, system-ui"`). No normalisation, no quoting
+changes that alter the recovered string.
+
+### NON-MAPPABLE — verbatim, EXCLUDED from the identity set
+
+Values the emitter cannot represent as a native primitive — CSS `var(--x)`
+references, `calc(…)` expressions, gradients (`linear-gradient(…)`), and `rem`/
+`em` dimensions — are **passed through verbatim** into a raw-string slot
+(a trailing comment such as `// non-mappable: <name> = <value>` or the language
+equivalent) so no information is lost, and are **explicitly excluded** from the
+round-trip identity assertion. The contract documents them as
+"verbatim / not round-tripped": the test asserts the verbatim value appears in
+the emitted source, and does **not** assert it survives re-extraction as a typed
+token.
+
+---
+
+## 7. The round-trip (what the test locks)
+
+For each emitter the bridge guarantees:
+
+1. **Determinism.** `emit(x) === emit(x)` byte-for-byte. Keys are iterated in a
+   stable sorted order; no `Date`, no `process.env`, no filesystem, no network in
+   the emit path (D-10).
+2. **Identity within precision.** For the identity set (color + integer
+   dimension + typography), `reextract(emit({tokens}))` deep-equals `{tokens}`
+   under the precision rules above (8-bit color channels exact with `#RGB`
+   expansion; integer pt/dp; logical-px double; family/weight string-equal).
+3. **Verbatim exclusion.** Non-mappable values appear verbatim in the source and
+   are not part of the identity assertion.
+
+Each emitter module exports a symmetric re-extractor
+(`reextractSwift` / `reextractCompose` / `reextractFlutter`) that parses the
+emitted native source back into a `{ tokens }` map, so the round-trip is
+deterministic and bijective on the identity set and reusable by the Phase-34.1
+regression baseline.
+
+---
+
+## 8. Registration
+
+This reference is registered in
+[`reference/registry.json`](./registry.json) as the `native-platforms` entry
+(type `heuristic`, phase `34.1`) so the registry round-trip test
+(`test/suite/reference-registry.test.cjs`) stays green — every `reference/*.md`
+must be registered and resolve (D-05, the 33.5-01 lesson).
+
+---
+
+## 9. Cross-references
+
+- [`reference/platforms.md`](./platforms.md) — the interaction-conventions
+  sibling (navigation, safe areas, gestures, native typography). Executors read
+  **both**: this file for the token→theme bridge, that file for layout/behavior.
+- `scripts/lib/design-tokens/` — the Phase-23 token engine this bridge extends
+  (`index.cjs` facade + `css-vars` / `js-const` / `tailwind` / `figma` readers +
+  the new `swift` / `compose` / `flutter` emitters).
+- `test/fixtures/mapper-outputs/tokens.json` — the canonical token fixture the
+  round-trip test derives its map from.

package/reference/openrouter-tier-mapping.md

@@ -0,0 +1,98 @@
+# OpenRouter Tier-Mapping Heuristic
+
+How `scripts/lib/tier-resolver-openrouter.cjs` maps GDD's tier vocabulary onto a
+dynamic OpenRouter catalog model id. This document is the human-readable companion
+to that adapter; the adapter's `resolve(tier, opts)` is the canonical, executable
+source of the mapping. Phase 33.6, decision D-03 (heuristic + override), D-04
+(tier vocabulary), D-08 (graceful-null → native fallback).
+
+## What it maps
+
+The plugin speaks one tier vocabulary everywhere a model tier is named in
+frontmatter or config: `opus`, `sonnet`, `haiku` — the same `VALID_TIERS` the
+Phase-26 `tier-resolver.cjs` enforces. OpenRouter, by contrast, exposes a flat
+catalog of provider-prefixed model ids (`anthropic/claude-opus-4-7`,
+`meta-llama/llama-3.1-8b-instruct`, `qwen/qwen-2.5-72b-instruct`, …). The adapter
+bridges the two by assigning each GDD tier to one internal capability bucket and
+then picking the catalog id that best fits that bucket.
+
+The ROADMAP's SC#4 names the buckets `high` / `medium` / `low`; those are the
+heuristic's INTERNAL labels. They map one-to-one to the public tiers (D-04):
+
+- `opus`   ← HIGH   bucket
+- `sonnet` ← MEDIUM bucket
+- `haiku`  ← LOW    bucket
+
+The adapter's public `resolve(tier)` always speaks `opus` / `sonnet` / `haiku`;
+`high` / `medium` / `low` never leak across the API boundary.
+
+## The buckets
+
+- **opus (HIGH) = top-tier closed.** The most capable closed-vendor model in the
+  catalog — the priciest premium id from a closed namespace. This is the
+  "spare-no-expense, hardest reasoning" slot.
+- **sonnet (MEDIUM) = mid / top-open.** A capable model that sits below the opus
+  pick — typically the mid-priced closed model, or the strongest open model when
+  no second closed tier is present. The everyday workhorse slot.
+- **haiku (LOW) = cheap open.** The cheapest capable OPEN model — the
+  fast/inexpensive slot for high-volume, low-stakes calls.
+
+## The signals
+
+The heuristic is computed from fields already present on each catalog model, so it
+stays deterministic for a fixed catalog (no clock, no randomness — important so the
+33.6-04 golden baseline is stable):
+
+- **Namespace (closed vs open).** The id prefix before the `/` names the vendor.
+  `anthropic`, `openai`, `google` are treated as CLOSED (premium, frontier).
+  `meta-llama`, `qwen`, `mistralai`, `deepseek` are treated as OPEN (commodity,
+  cheap). The closed/open split is the primary axis: opus and sonnet prefer closed,
+  haiku requires open.
+- **Pricing.** Each model carries `pricing.prompt` / `pricing.completion` as string
+  decimals (USD per token). Parsed to Number, the completion price is the tie-break:
+  highest completion price wins the opus slot; lowest completion price wins the
+  haiku slot. Models with unparseable or missing pricing sort last.
+- **Context length.** `context_length` is a secondary capability signal used only to
+  break a pricing tie (longer context is treated as more capable).
+
+For the canonical fixture catalog (closed `anthropic/claude-opus-4-7` +
+`anthropic/claude-sonnet-4-7`, open `meta-llama/llama-3.1-70b-instruct`,
+`meta-llama/llama-3.1-8b-instruct`, `qwen/qwen-2.5-72b-instruct`) the heuristic
+resolves opus → `anthropic/claude-opus-4-7` (top closed, highest completion price),
+sonnet → `anthropic/claude-sonnet-4-7` (mid closed), and haiku →
+`meta-llama/llama-3.1-8b-instruct` (cheapest open).
+
+## The override escape hatch
+
+The heuristic is a sensible default, not a straitjacket. A user can pin any tier to
+an exact catalog id via `.design/config.json`:
+
+```
+{
+  "openrouter_tier_overrides": {
+    "opus": "anthropic/claude-opus-4-7",
+    "haiku": "meta-llama/llama-3.1-8b-instruct"
+  }
+}
+```
+
+An override **wins** over the heuristic: when `openrouter_tier_overrides[tier]` is a
+non-empty string, the adapter returns it verbatim — even if that id is not present
+in the live catalog (the user's explicit choice is honored over catalog membership).
+Tests inject the same map via `opts.overrides` instead of reading the live config
+file, so the override path is exercised hermetically. The config read is best-effort:
+a missing file, a missing key, or corrupt JSON degrades to an empty override map
+rather than throwing.
+
+## The graceful-null contract
+
+OpenRouter is opt-in ALONGSIDE native provider auth — never OpenRouter-only (D-08).
+When no catalog is available (no cache, an empty `models[]`, or a `readCatalog` that
+returns null) AND no override applies to the requested tier, `resolve` returns
+`null`. A `null` is not an error: it is the signal that the caller (the router /
+budget-enforcer, wired in 33.6-03) should fall back to the native provider via the
+existing `scripts/lib/tier-resolver.cjs` fallback chain. The adapter NEVER throws —
+an unknown tier, a missing config, a corrupt cache, or garbage options all degrade to
+`null` (or to an override when one applies). This keeps OpenRouter a strictly
+additive capability: turning it off, or having it fail to fetch, can never break a
+resolution that would have succeeded natively.

package/reference/prices.openrouter.md

@@ -0,0 +1,26 @@
+# OpenRouter — Catalog-Derived Price Snapshot
+
+**Phase 33.6 (v1.33.6).** This file is a **catalog-derived snapshot** of OpenRouter per-model prices — it is **generated from** `.design/cache/openrouter-models.json` (the dynamic catalog fetched by `scripts/lib/openrouter/catalog-fetcher.cjs`), **not** a hand-maintained authority. The **live source of truth is the dynamic catalog**; this table is a derived, illustrative view that can go stale between catalog fetches.
+
+Unlike the per-runtime tables under `reference/prices/` (Phase 26 D-08, hand-curated authority with provenance), OpenRouter's prices live in the upstream `/models` response and are refreshed on the 24h TTL. To inspect the current resolved prices, run `/gdd:openrouter-status` or read the cache directly. For the tier→model resolution heuristic see `reference/openrouter-tier-mapping.md`.
+
+OpenRouter quotes prices **per token** (USD), for `prompt` (input) and `completion` (output) separately.
+
+## Representative sample (per token, USD)
+
+Derived from the fixture catalog at `test/fixtures/baselines/phase-33-6/openrouter-catalog.json` (a snapshot mirror of the cache shape). Actual live prices come from the catalog at fetch time.
+
+| model id | prompt $/tok | completion $/tok |
+|----------|--------------|------------------|
+| `anthropic/claude-opus-4-7` | 0.000015 | 0.000075 |
+| `anthropic/claude-sonnet-4-7` | 0.000003 | 0.000015 |
+| `meta-llama/llama-3.1-70b-instruct` | 0.00000052 | 0.00000075 |
+| `meta-llama/llama-3.1-8b-instruct` | 0.00000002 | 0.00000005 |
+| `qwen/qwen-2.5-72b-instruct` | 0.00000038 | 0.0000004 |
+
+## Notes
+
+- **Derived view, not authority.** Do not hand-edit prices here to "fix" cost math — fix the catalog fetch instead. This file documents the *shape* and *source* of OpenRouter pricing for the registry round-trip and for human reference.
+- **Per-token vs per-1M.** The native runtime tables (`reference/prices/<runtime>.md`) quote `input_per_1m` / `output_per_1m`; OpenRouter's catalog quotes per-token. Multiply by 1,000,000 to compare (e.g. `anthropic/claude-opus-4-7` ≈ $15 input / $75 output per 1M tokens).
+- **Cost telemetry.** When a model is resolved via the OpenRouter adapter, the cost row tags `provider: openrouter` (Phase 33.6-03, SC#6) — see `scripts/lib/budget-enforcer.cjs#buildCostEventPayload`.
+- **Drift.** The authority-watcher diffs the catalog weekly and surfaces `deprecated`/`withdrawn` models matching a configured `openrouter_tier_overrides` pin (SC#8) — see `scripts/lib/authority-watcher/index.cjs#diffOpenRouterCatalog`.

package/reference/registry.json

@@ -874,6 +874,27 @@
       "type": "heuristic",
       "phase": 33.5,
       "description": "Phase 33.5 static security audit of GDD's shipped runtime surface (hooks/scripts/sdk/bin) — outbound-network call sites, secret-handling sites, and external-input surfaces; human-readable companion to scripts/security/outbound-allowlist.json (the canonical active-egress allowlist the 33.5-04 scan-outbound-network.cjs gate consumes) and reference/gdd-threat-model.md."
+    },
+    {
+      "name": "openrouter-tier-mapping",
+      "path": "reference/openrouter-tier-mapping.md",
+      "type": "heuristic",
+      "phase": 33.6,
+      "description": "Phase 33.6 OpenRouter tier-mapping heuristic — maps GDD opus/sonnet/haiku onto OpenRouter catalog ids via closed-vs-open + pricing buckets (high/medium/low), with the .design/config.json#openrouter_tier_overrides escape hatch (override wins) and graceful-null → native fallback."
+    },
+    {
+      "name": "prices-openrouter",
+      "path": "reference/prices.openrouter.md",
+      "type": "data",
+      "phase": 33.6,
+      "description": "Phase 33.6 catalog-derived OpenRouter price sub-table — per-model prompt/completion $/tok snapshot of .design/cache/openrouter-models.json; derived view, the dynamic catalog is the source of truth (D-11 registry round-trip)."
+    },
+    {
+      "name": "native-platforms",
+      "path": "reference/native-platforms.md",
+      "type": "heuristic",
+      "phase": 34.1,
+      "description": "Phase 34.1 token-bridge spec — maps the canonical CSS-token form (Phase 23) to SwiftUI Color/Font/ViewModifier, Jetpack Compose Color/Shapes/Typography/MaterialTheme, and Flutter ThemeData/ColorScheme/TextTheme, with the precision contract (color hex→8-bit channels exact, dimension px→pt/dp/logical px) defining token-identity for the round-trip."
     }
   ]
 }