@hegemonart/get-design-done 1.27.7 → 1.28.5

package/reference/proportion-systems.md

@@ -0,0 +1,267 @@
+---
+name: proportion-systems
+type: layout
+version: 1.0.0
+phase: 28
+tags: [proportion, spacing, baseline-grid, vertical-rhythm, modular-scale]
+last_updated: 2026-05-18
+---
+
+# Proportion Systems — Whole-UI Modular Relationships
+
+The existing [typography reference](./typography.md) covers the modular type scale — base 16px, a ratio (1.250 Major Third, 1.333 Perfect Fourth, 1.414 √2, 1.618 φ), and the geometric ladder of font sizes that scale produces. That ladder is one slice of a larger system. A proportion system is the rule that *every* dimension in the UI — type, spacing between elements, sizing of icons and avatars, and corner radius on components — derives from a single underlying unit and a small set of multipliers, so that values across the four systems land on the same grid and visibly belong to the same composition.
+
+This file exists because that whole-UI view is undocumented today: [design-system-guidance.md](./design-system-guidance.md) mentions 8pt spacing in passing, [style-vocabulary.md](./style-vocabulary.md) cites "8pt spacing grid" as a Flat Design 2.0 marker, and `typography.md` owns the type-scale slice — but nothing ties them together. An agent that picks `padding: 12px` next to body text at `16/24` on an 8pt grid is breaking proportion silently, because the cross-system relationship was never stated. This is the file an agent should consult any time it is *constructing* the underlying grid of a UI — choosing a baseline unit, deriving a spacing ladder, deciding whether icon-md should be 20px or 24px, or auditing why a layout "feels off" despite each token being internally consistent.
+
+The jump this file closes is from *"we use a modular type scale"* to *"we use a coherent proportion system across type + spacing + sizing + radius — the whole UI snaps to one grid."*
+
+## Baseline Grid Systems
+
+A baseline grid is the invisible underlying structure every dimension snaps to. It is one number — `4`, `8`, or `1.414` — and the rule that no value in the UI may be authored that is not a multiple of that number. The grid is not a layout grid (columns and gutters); it is the smallest atomic unit out of which both the column grid and every spacing / sizing / radius token are composed. Three baselines dominate: 4pt, 8pt, and √2. Pick one for the whole product; do not mix.
+
+### 4pt Grid
+
+When it fits: dense data UIs where rows must be visually compact (trading terminals, observability dashboards, IDE-style tooling, spreadsheet-derived layouts). The 4pt unit lets you author 12px / 20px / 28px row heights that an 8pt grid forbids, which matters when 10–20 horizontal rows need to fit above the fold. The cost is that fine increments invite drift — without strict review, a team will quickly have `13px`, `15px`, and `17px` in production.
+
+```css
+/* 4pt grid — dense data UI */
+:root {
+  --grid-unit: 4px;
+
+  --space-1: calc(var(--grid-unit) * 1);  /* 4px  */
+  --space-2: calc(var(--grid-unit) * 2);  /* 8px  */
+  --space-3: calc(var(--grid-unit) * 3);  /* 12px */
+  --space-4: calc(var(--grid-unit) * 4);  /* 16px */
+  --space-5: calc(var(--grid-unit) * 5);  /* 20px */
+  --space-6: calc(var(--grid-unit) * 6);  /* 24px */
+  --space-7: calc(var(--grid-unit) * 7);  /* 28px */
+  --space-8: calc(var(--grid-unit) * 8);  /* 32px */
+}
+
+.data-row {
+  height: var(--space-7);                 /* 28px — on-grid */
+  padding-inline: var(--space-3);         /* 12px — on-grid */
+}
+```
+
+### 8pt Grid
+
+When it fits: product UI, marketing surfaces, default for most consumer apps. Material Design, iOS Human Interface Guidelines, and the majority of modern design systems converge on 8pt because the unit is large enough to prevent drift (no one accidentally authors 9px) yet small enough to express every meaningful step. Half-units (4px) are permitted only at the smallest scale (icon padding, single-character chip insets) and are explicitly named — never freehand.
+
+```css
+/* 8pt grid — product UI default */
+:root {
+  --grid-unit: 8px;
+
+  --space-0\.5: 4px;                      /* explicit half-unit — only for chip insets */
+  --space-1: calc(var(--grid-unit) * 1);  /* 8px  */
+  --space-2: calc(var(--grid-unit) * 2);  /* 16px */
+  --space-3: calc(var(--grid-unit) * 3);  /* 24px */
+  --space-4: calc(var(--grid-unit) * 4);  /* 32px */
+  --space-5: calc(var(--grid-unit) * 5);  /* 40px */
+  --space-6: calc(var(--grid-unit) * 6);  /* 48px */
+  --space-8: calc(var(--grid-unit) * 8);  /* 64px */
+}
+
+.card {
+  padding: var(--space-3);                /* 24px — on-grid */
+  gap: var(--space-2);                    /* 16px — on-grid */
+}
+```
+
+### √2 Grid (root-2)
+
+When it fits: editorial layouts, print-adjacent surfaces, long-form article pages, document viewers. The √2 ratio (≈1.414) is the proportion that survives bisection — fold an A4 page in half and you get an A5 page with the same proportion. UIs that mirror physical paper (PDF readers, marketing landing pages with magazine layouts, layouts that breathe like print) feel right on √2 because subdivisions cascade self-similarly. The underlying spacing unit is still an integer (typically 8px or 16px) but the column and section *ratios* are √2, and key dimensions are generated by repeated multiplication or division by 1.414. See `./composition.md` §Root Rectangles — √2, √3, √5 for the geometry behind the ratio.
+
+```css
+/* √2 grid — editorial / print-adjacent */
+:root {
+  --base: 16px;
+
+  --space-2:  calc(var(--base) * 1);              /* 16px       */
+  --space-3:  calc(var(--base) * 1.414);          /* ≈22.6px → 24px on the 8pt grid */
+  --space-4:  calc(var(--base) * 2);              /* 32px       */
+  --space-5:  calc(var(--base) * 2.828);          /* ≈45.2px → 48px */
+  --space-6:  calc(var(--base) * 4);              /* 64px       */
+}
+
+.article-section {
+  aspect-ratio: 1 / 1.414;                        /* A-paper ratio */
+  padding-inline: var(--space-4);
+  padding-block: var(--space-5);
+}
+```
+
+**Decision rule:** if the product is a dense data UI where row density is the dominant constraint, pick 4pt. If the product is editorial or print-adjacent and pages should feel like documents, pick √2 (over an integer pixel unit). For everything else — and that is most product work — pick 8pt. Document the decision once at the design-system level; do not let individual surfaces pick their own grid.
+
+## Baseline-Grid Lock
+
+Baseline-grid lock is the discipline that every text baseline in the UI lands on a grid line — typically the same 4pt or 8pt unit used for spacing. The mechanism is the `line-height` of every text style: set line-height so the resulting line box is a whole multiple of the grid unit. Body text at 16px font with line-height `24px` consumes exactly three 8pt units per line. Heading text at 32px with line-height `40px` consumes five. Caption at 14px with line-height `24px` consumes three. Every block of text — regardless of size — stacks on the same invisible horizontal rulings.
+
+Lock matters because mixed-size text without it produces drift. A page that interleaves body, headings, and captions whose line-heights are *not* grid multiples will accumulate fractional-pixel errors block-by-block; by mid-page, the right column has slid out of alignment with the left. Visually the page looks "slightly wrong" without an obvious cause. Lock eliminates the symptom by construction.
+
+```css
+/* Baseline-grid lock on an 8pt grid */
+:root {
+  --grid-unit: 8px;
+
+  /* Every line-height is a multiple of --grid-unit */
+  --line-body:    calc(var(--grid-unit) * 3);  /* 24px — 3 units */
+  --line-heading: calc(var(--grid-unit) * 5);  /* 40px — 5 units */
+  --line-caption: calc(var(--grid-unit) * 3);  /* 24px — 3 units */
+}
+
+p           { font-size: 16px; line-height: var(--line-body);    }
+h2          { font-size: 32px; line-height: var(--line-heading); }
+.caption    { font-size: 14px; line-height: var(--line-caption); }
+```
+
+## Vertical Rhythm
+
+Vertical rhythm is the lived consequence of baseline-grid lock: because every text block consumes a whole number of grid units, block-level elements stack on the grid without ever needing manual margin tweaks. The page reads with a quiet, mechanical regularity that the eye registers as polish even when no one can articulate why. Vertical rhythm is what readers mean when they say a layout feels "professional" or "calm".
+
+The rule that produces it is: pick the baseline unit once, set every line-height in the type ramp as a multiple of that unit, and set every block-level margin (margin-top, margin-bottom, padding-block on cards and sections) as a multiple of the same unit. Once both type and spacing are on-grid, rhythm emerges automatically — no per-element adjustment.
+
+```css
+/* Vertical rhythm — body, heading, caption, all on the 8pt grid */
+:root {
+  --grid-unit: 8px;
+}
+
+body {
+  font-size: 16px;
+  line-height: calc(var(--grid-unit) * 3);   /* 24px — 3 units */
+}
+
+h2 {
+  font-size: 32px;
+  line-height: calc(var(--grid-unit) * 5);   /* 40px — 5 units */
+  margin-block-start: calc(var(--grid-unit) * 6);  /* 48px */
+  margin-block-end:   calc(var(--grid-unit) * 3);  /* 24px */
+}
+
+.caption {
+  font-size: 14px;
+  line-height: calc(var(--grid-unit) * 3);   /* 24px — 3 units, same as body */
+}
+
+article > * + * {
+  margin-block-start: calc(var(--grid-unit) * 2);  /* 16px between siblings */
+}
+```
+
+**Exceptions are explicit, not freehand.** Display-scale type (font-size ≥ 56px) is often set with optical line-height — a unitless ratio of 1.05–1.15 — because mechanical 8pt multiples look too sparse at hero scale. Single-line callouts (status badges, single-character chips) may use `line-height: 1` with vertical padding rounded to the grid. Treat both as named utilities (`.display-line-height`, `.chip-vertical`) rather than ad-hoc overrides — once the exception is a token, it remains visible to audit.
+
+## Modular Relationships
+
+The point of the proportion system is that the four sub-systems — type, spacing, sizing, radius — are not authored independently. Each derives from the same baseline unit, and certain pairs of values across systems are intentionally identical. Body line-height equals the spacing token that separates two body paragraphs equals the height of a medium icon. The numerical equality is the visible signature of an authored composition.
+
+| System  | Token       | Value | Grid relationship              | Cross-system pairing                  |
+| ------- | ----------- | ----- | ------------------------------ | ------------------------------------- |
+| type    | text-xs     | 12px  | 1.5 × baseline                 | matches `space-1.5` (4pt half-step)   |
+| type    | text-sm     | 14px  | non-grid (optical exception)   | line-height 20px (2.5 units) is grid  |
+| type    | text-base   | 16px  | 2 × baseline (8pt)             | matches `space-2`                     |
+| type    | text-lg     | 20px  | 2.5 × baseline                 | line-height 28px (3.5 units)          |
+| type    | text-xl     | 24px  | 3 × baseline                   | matches `space-3`, matches `icon-md`  |
+| type    | text-2xl    | 32px  | 4 × baseline                   | matches `space-4`, matches `icon-lg`  |
+| space   | space-1     | 8px   | 1 × baseline                   | matches `radius-md`                   |
+| space   | space-2     | 16px  | 2 × baseline                   | matches `text-base`                   |
+| space   | space-3     | 24px  | 3 × baseline                   | matches body line-height, `icon-md`   |
+| space   | space-4     | 32px  | 4 × baseline                   | matches `text-2xl`, `icon-lg`         |
+| space   | space-6     | 48px  | 6 × baseline                   | matches `avatar-md` height            |
+| radius  | radius-sm   | 4px   | 0.5 × baseline                 | half-step, only on chips and tags     |
+| radius  | radius-md   | 8px   | 1 × baseline                   | matches `space-1`                     |
+| radius  | radius-lg   | 16px  | 2 × baseline                   | matches `space-2`, `text-base`        |
+| size    | icon-sm     | 16px  | 2 × baseline                   | matches `text-base` cap-height        |
+| size    | icon-md     | 24px  | 3 × baseline                   | matches body line-height, `space-3`   |
+| size    | icon-lg     | 32px  | 4 × baseline                   | matches `text-2xl`, `space-4`         |
+| size    | avatar-sm   | 32px  | 4 × baseline                   | matches `icon-lg`, `space-4`          |
+| size    | avatar-md   | 48px  | 6 × baseline                   | matches `space-6`                     |
+| size    | avatar-lg   | 64px  | 8 × baseline                   | 8 grid units, matches hero spacing    |
+
+The pairing column is the asset. An agent picking a value reads across the table: "I need padding around 16px text on an 8pt grid" → `space-2` (16px) or `space-3` (24px), never `padding: 12px` (1.5 units — half-step, reserved for chips). "I need an icon next to body text" → `icon-md` (24px), because body line-height is 24px and the icon should occupy the same vertical band. The relationships make these decisions one-step.
+
+**A concrete pairing example.** Body text is 16px on 24px line-height (8pt grid). A button next to body text should have vertical padding such that the total button height is a clean multiple of the grid. Padding 8px + line-height 24px + padding 8px = 40px (5 units — on-grid). Padding 12px + line-height 24px + padding 12px = 48px (6 units — on-grid). Padding 10px gives 44px (5.5 units — off-grid, breaks rhythm); the only way to know that is to consult the matrix. Once a team internalizes the pairings, the choice between 8px and 12px stops being aesthetic — both are correct, both produce on-grid heights, and the team picks based on density.
+
+## Radius Scale as Proportion
+
+Corner radius is the easiest token to author ad-hoc — `border-radius: 6px` looks fine in isolation — and the easiest to break the system with. The radius scale belongs to proportion because it must derive from component height, not be chosen freehand. The common rule is `radius-md ≈ 0.25 × component height`: a 40px-tall button gets 8px radius, a 32px-tall chip gets 8px radius, a 24px-tall tag gets 4px or 8px. The 0.25× ratio is visually balanced — large enough to register as "rounded", small enough to keep the geometry of the rectangle dominant.
+
+Two exceptions matter and are named, not freehand. **Pill** sets `border-radius: 9999px` (or `border-radius: 50%` on a square) — explicit "fully rounded", used for tags, status badges, and avatar wrappers. **Square** sets `border-radius: 0` — explicit "no rounding", used inside data tables where rectangular cells must butt against each other, and on heavily geometric brand systems.
+
+```css
+/* Radius scale as proportion to component height */
+:root {
+  --radius-none: 0;
+  --radius-sm:   4px;       /* 0.25 × 16px (tag height) */
+  --radius-md:   8px;       /* 0.25 × 32px (chip / small button) */
+  --radius-lg:   10px;      /* 0.25 × 40px (default button) */
+  --radius-xl:   16px;      /* 0.25 × 64px (large input / card) */
+  --radius-full: 9999px;    /* pill */
+}
+
+.button-default {
+  block-size: 40px;
+  border-radius: var(--radius-lg);   /* 10px — 0.25 × 40px */
+}
+
+.chip {
+  block-size: 32px;
+  border-radius: var(--radius-md);   /* 8px — 0.25 × 32px */
+}
+
+.avatar {
+  inline-size: 48px;
+  block-size:  48px;
+  border-radius: var(--radius-full); /* pill (circle) — explicit named exception */
+}
+```
+
+## Sizing Scale Derivation
+
+Sizing tokens — icon dimensions, avatar dimensions, button heights, input heights — are not a separate ladder. They are derived from the spacing scale by consistent multipliers, so that every size token equals some `space-N` token. This is the rule that prevents sizing drift: a new size token must reuse an existing spacing value; it may not introduce a new pixel value.
+
+The derivation table for an 8pt grid:
+
+```css
+/* Sizing tokens derived from spacing tokens */
+:root {
+  --grid-unit: 8px;
+
+  /* Spacing ladder (canonical) */
+  --space-1:  calc(var(--grid-unit) * 1);   /*  8px */
+  --space-2:  calc(var(--grid-unit) * 2);   /* 16px */
+  --space-3:  calc(var(--grid-unit) * 3);   /* 24px */
+  --space-4:  calc(var(--grid-unit) * 4);   /* 32px */
+  --space-5:  calc(var(--grid-unit) * 5);   /* 40px */
+  --space-6:  calc(var(--grid-unit) * 6);   /* 48px */
+  --space-8:  calc(var(--grid-unit) * 8);   /* 64px */
+
+  /* Sizing tokens — every value is a spacing token, not a new pixel literal */
+  --icon-sm:    var(--space-2);   /* 16px */
+  --icon-md:    var(--space-3);   /* 24px */
+  --icon-lg:    var(--space-4);   /* 32px */
+
+  --avatar-sm:  var(--space-4);   /* 32px */
+  --avatar-md:  var(--space-6);   /* 48px */
+  --avatar-lg:  var(--space-8);   /* 64px */
+
+  --button-sm:  var(--space-4);   /* 32px height */
+  --button-md:  var(--space-5);   /* 40px height — default button */
+  --button-lg:  var(--space-6);   /* 48px height */
+
+  --input-md:   var(--space-5);   /* 40px height — matches button-md */
+}
+```
+
+The rule that makes this work: **a new sizing token must derive from spacing — never freehand.** If a designer needs a 36px button, the answer is not `--button-custom: 36px`; the answer is either 32px (`--space-4`) or 40px (`--space-5`), and the designer picks one. The token system declines to express off-grid sizes, which is the point.
+
+## Cross-References
+
+- [design-system-guidance.md](./design-system-guidance.md) — general design-system authoring context that this file deepens for proportion. That file mentions 8pt grids in passing; this file is the formal treatment.
+- [typography.md](./typography.md) §Type Scale Systems — the canonical modular-scale slice this file extends to the whole UI. Read that section first for the upstream type ladder.
+- [style-vocabulary.md](./style-vocabulary.md) — style rows that cite "8pt spacing grid" (Flat Design 2.0) and other proportional vocabulary surfaces. This file is the underlying mechanism behind those style-row markers.
+
+Forward reading: [composition.md](./composition.md) §Root Rectangles — √2, √3, √5 for the geometry behind the √2 grid baseline option above.
+
+Note: reciprocal inbound cross-links from these files into `proportion-systems.md` land in Phase 28-06 (additive-only, decision D-06). This file declares its three outbound links now; the inverse direction is a separate, batched edit.

package/reference/registry.json

@@ -1,7 +1,7 @@
 {
   "$schema": "./schemas/registry.schema.json",
   "version": 1,
-  "generated_at": "2026-04-24T00:00:00.000Z",
+  "generated_at": "2026-05-18T12:47:59.666Z",
   "entries": [
     {
       "name": "codex-tools",
@@ -115,6 +115,13 @@
       "tier": "L2",
       "description": "Per-category gate checklists"
     },
+    {
+      "name": "color-theory",
+      "path": "reference/color-theory.md",
+      "type": "palette",
+      "phase": 28,
+      "description": "Color-theory foundation — color spaces (sRGB / HSL / OKLCH / LCH), six harmonies in OKLCH, simultaneous contrast, color-blindness palettes (deutan/protan/tritan), color interpolation in animation (OKLCH path vs sRGB muddy-mid)"
+    },
     {
       "name": "component-accordion",
       "path": "reference/components/accordion.md",
@@ -337,12 +344,26 @@
       "type": "schema",
       "description": "Locked 12-section spec shape for component benchmarks (Purpose → Failing example)"
     },
+    {
+      "name": "composition",
+      "path": "reference/composition.md",
+      "type": "layout",
+      "phase": 28,
+      "description": "Compositional fundamentals — rule of thirds, φ/√2/√3/√5 root rectangles, Fibonacci, focal-point construction, visual-weight calculus (size × contrast × isolation × complexity), optical-vs-mathematical centering, Z/F/Gutenberg eye-flow"
+    },
     {
       "name": "config-schema",
       "path": "reference/config-schema.md",
       "type": "schema",
       "description": "Schema documentation for .design/config.json"
     },
+    {
+      "name": "contrast-advanced",
+      "path": "reference/contrast-advanced.md",
+      "type": "heuristic",
+      "phase": 28,
+      "description": "APCA (WCAG 3 draft) contrast — Lc 75/60/45/30 thresholds, why WCAG 2.1 4.5:1 misranks thin/large/colored text, dual-target pattern with WCAG 2.1 AA, Lc↔WCAG-2.1 conversion table"
+    },
     {
       "name": "css-grid-layout",
       "path": "reference/css-grid-layout.md",
@@ -417,6 +438,13 @@
       "tier": "L2",
       "description": "NNG heuristics + GDD-specific rubrics used by auditor / verifier"
     },
+    {
+      "name": "i18n",
+      "path": "reference/i18n.md",
+      "type": "heuristic",
+      "phase": 28,
+      "description": "i18n engineering primitives — text expansion per locale, CSS logical properties, RTL mirroring + directional-icon flip, bidi isolation, Intl.* family (DateTimeFormat / NumberFormat / PluralRules / RelativeTimeFormat / ListFormat / Collator / Segmenter), ICU MessageFormat, Unicode hygiene, multi-script font stacks, WCAG i18n; spec source for design-verifier i18n probes + explore i18n-readiness probe"
+    },
     {
       "name": "iconography",
       "path": "reference/iconography.md",
@@ -697,6 +725,13 @@
       "type": "heuristic",
       "description": "Guide for authoring project-skill artifacts (sketch/spike wrap-ups)"
     },
+    {
+      "name": "proportion-systems",
+      "path": "reference/proportion-systems.md",
+      "type": "layout",
+      "phase": 28,
+      "description": "Whole-UI proportion systems — 4pt / 8pt / √2 baseline grids, baseline-grid lock, vertical rhythm, modular relationships across type + spacing + sizing + radius scales"
+    },
     {
       "name": "protected-paths.default",
       "path": "reference/protected-paths.default.json",
@@ -776,6 +811,174 @@
       "path": "reference/visual-hierarchy-layout.md",
       "type": "heuristic",
       "description": "Z-order, whitespace, grids, F/Z patterns, 24 landing archetypes"
+    },
+    {
+      "name": "adr-format",
+      "path": "reference/adr-format.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "ADR (Architecture Decision Record) format — adapted from mattpocock/skills (MIT). 3-criteria offer gate (hard-to-reverse AND surprising-without-context AND real-tradeoff), 4-state status lifecycle. GDD addition: optional cycle-id + phase-id cross-refs to STATE.md."
+    },
+    {
+      "name": "apply-reflections-procedure",
+      "path": "reference/apply-reflections-procedure.md",
+      "type": "heuristic",
+      "phase": 28.5,
+      "description": "Phase 28.5 — apply-reflections procedure extracted from skills/apply-reflections per progressive-disclosure rule. Read by skills/apply-reflections/SKILL.md."
+    },
+    {
+      "name": "architecture-vocabulary",
+      "path": "reference/architecture-vocabulary.md",
+      "type": "principles",
+      "phase": 28.5,
+      "description": "Ousterhout glossary (A Philosophy of Software Design) ported via mattpocock/skills LANGUAGE.md (MIT). 8 core terms (Module / Interface / Implementation / Depth / Seam / Adapter / Leverage / Locality) + 3 principles (deletion test, interface-is-test-surface, two-adapters-rule)."
+    },
+    {
+      "name": "cache-policy",
+      "path": "reference/cache-policy.md",
+      "type": "heuristic",
+      "phase": 28.5,
+      "description": "Phase 28.5 — cache-policy reference extracted from skills/cache-manager + skills/warm-cache per progressive-disclosure rule (Bucket 3 orchestrator + utility rework)."
+    },
+    {
+      "name": "compare-rubric",
+      "path": "reference/compare-rubric.md",
+      "type": "heuristic",
+      "phase": 28.5,
+      "description": "Phase 28.5 — compare-rubric extracted from skills/compare per progressive-disclosure rule. Read by skills/compare/SKILL.md (Bucket 2 design-family rework)."
+    },
+    {
+      "name": "connections-onboarding",
+      "path": "reference/connections-onboarding.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "Phase 28.5 — connections-onboarding procedure extracted from skills/connections per progressive-disclosure rule (Bucket 2 design-family rework). Four-option setup prompt + onboarding flow."
+    },
+    {
+      "name": "context-md-format",
+      "path": "reference/context-md-format.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "CONTEXT.md format — adapted from mattpocock/skills (MIT) CONTEXT-FORMAT.md. DDD-style ubiquitous-language glossary schema, inline-write trigger, multi-context CONTEXT-MAP.md pattern. GDD additions: optional first-seen + aliases on term entries."
+    },
+    {
+      "name": "darkmode-audit-procedure",
+      "path": "reference/darkmode-audit-procedure.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "Phase 28.5 — darkmode audit procedure extracted from skills/darkmode per progressive-disclosure rule (Bucket 2 design-family rework)."
+    },
+    {
+      "name": "debug-feedback-loops",
+      "path": "reference/debug-feedback-loops.md",
+      "type": "heuristic",
+      "phase": 28.5,
+      "description": "Debug feedback-loop discipline — adapted from mattpocock/skills (MIT) engineering/diagnose Phase 1. 10 construction paths in priority order (failing test -> curl -> CLI fixture -> headless browser -> trace replay -> throwaway harness -> fuzz -> bisect harness -> differential loop -> HITL bash), iterate-on-loop sub-discipline, non-determinism reproduction-rate branch."
+    },
+    {
+      "name": "design-procedure",
+      "path": "reference/design-procedure.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "Phase 28.5 — design-stage procedure extracted from skills/design per progressive-disclosure rule (Bucket 1 pipeline-stage rework)."
+    },
+    {
+      "name": "discover-procedure",
+      "path": "reference/discover-procedure.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "Phase 28.5 — discover-stage procedure extracted from skills/discover per progressive-disclosure rule (Bucket 1 pipeline-stage rework)."
+    },
+    {
+      "name": "explore-procedure",
+      "path": "reference/explore-procedure.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "Phase 28.5 — explore-stage procedure extracted from skills/explore per progressive-disclosure rule (Bucket 1 pipeline-stage rework)."
+    },
+    {
+      "name": "health-mcp-detection",
+      "path": "reference/health-mcp-detection.md",
+      "type": "heuristic",
+      "phase": 28.5,
+      "description": "Phase 28.5 — health-MCP detection procedure extracted from skills/health per progressive-disclosure rule (D-10). Documents dismissal check, detection via scripts/lib/install/mcp-register.cjs, row rendering for claude/codex/both/neither, fallback for missing mcp-register.cjs."
+    },
+    {
+      "name": "health-skill-length-report",
+      "path": "reference/health-skill-length-report.md",
+      "type": "heuristic",
+      "phase": 28.5,
+      "description": "Phase 28.5 — health-skill-length-report contract documenting validate-skill-length.cjs JSON shape + threshold rationale. Read by skills/health/SKILL.md to render the skill-length report subsection."
+    },
+    {
+      "name": "milestone-completeness-rubric",
+      "path": "reference/milestone-completeness-rubric.md",
+      "type": "heuristic",
+      "phase": 28.5,
+      "description": "Phase 28.5 — milestone-completeness rubric extracted from skills/turn-closeout per progressive-disclosure rule (Bucket 4 analysis + audit rework). Turn-closeout / new-cycle completeness criteria."
+    },
+    {
+      "name": "peer-cli-protocol",
+      "path": "reference/peer-cli-protocol.md",
+      "type": "heuristic",
+      "phase": 28.5,
+      "description": "Phase 28.5 — peer-CLI protocol scaffold extracted from skills/peer-cli-add + skills/peer-cli-customize per progressive-disclosure rule (Bucket 4 analysis + audit rework). ACP + ASP adapter scaffolding patterns, verification ladder, Windows quirk handling."
+    },
+    {
+      "name": "plan-procedure",
+      "path": "reference/plan-procedure.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "Phase 28.5 — plan-stage procedure extracted from skills/plan per progressive-disclosure rule (Bucket 1 pipeline-stage rework)."
+    },
+    {
+      "name": "router-rules",
+      "path": "reference/router-rules.md",
+      "type": "heuristic",
+      "phase": 28.5,
+      "description": "Phase 28.5 — router-rules reference extracted from skills/router per progressive-disclosure rule (Bucket 3 orchestrator + utility rework). S/M/L/XL bucket assignments + path-selection heuristic."
+    },
+    {
+      "name": "scan-procedure",
+      "path": "reference/scan-procedure.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "Phase 28.5 — scan-stage procedure extracted from skills/scan per progressive-disclosure rule (Bucket 1 pipeline-stage rework)."
+    },
+    {
+      "name": "skill-authoring-contract",
+      "path": "reference/skill-authoring-contract.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "Phase 28.5 skill-authoring contract — adapted from mattpocock/skills (MIT). SKILL.md <=100-line cap (warn >=100, block >=250 in CI), 1024-char description cap, <what>. Use when <triggers>. form (lax-mode default per Phase 33 A/B pending), frontmatter required fields, progressive-disclosure one-level-deep rule. Validator at scripts/validate-skill-length.cjs."
+    },
+    {
+      "name": "start-procedure",
+      "path": "reference/start-procedure.md",
+      "type": "heuristic",
+      "phase": 28.5,
+      "description": "Phase 28.5 — start-procedure reference extracted from skills/start per progressive-disclosure rule (Bucket 4 analysis + audit rework)."
+    },
+    {
+      "name": "style-doc-procedure",
+      "path": "reference/style-doc-procedure.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "Phase 28.5 — style-doc procedure extracted from skills/style per progressive-disclosure rule (Bucket 2 design-family rework)."
+    },
+    {
+      "name": "threat-modeling",
+      "path": "reference/threat-modeling.md",
+      "type": "heuristic",
+      "phase": 28.5,
+      "description": "Phase 28.5 — STRIDE threat-modeling patterns extracted from skills/quality-gate + audit-side scanning per progressive-disclosure rule (Bucket 4 analysis + audit rework). Audit-side threat-model invariants."
+    },
+    {
+      "name": "verify-procedure",
+      "path": "reference/verify-procedure.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "Phase 28.5 — verify-stage procedure extracted from skills/verify per progressive-disclosure rule (Bucket 1 pipeline-stage rework)."
     }
   ]
 }

package/reference/registry.schema.json

@@ -45,7 +45,7 @@
             ]
           },
           "tier": { "enum": ["L0", "L1", "L2"] },
-          "phase": { "type": "integer", "description": "Phase that introduced this entry" },
+          "phase": { "type": "number", "description": "Phase that introduced this entry. Numbers are allowed (e.g., 19.6, 27.5, 27.6, 27.7, 28.5) — decimal phases are valid per the long-standing precedent established by Phases 19.6 / 27.5 / 27.6 / 27.7 / 28.5." },
           "description": { "type": "string" },
           "registered_at": { "type": "string", "format": "date-time" }
         },

package/reference/router-rules.md

@@ -0,0 +1,84 @@
+---
+name: router-rules
+type: heuristic
+version: 1.0.0
+phase: 28.5
+tags: [router, path-selection, complexity-class, model-tier, runtime-resolution, cost-estimation]
+last_updated: 2026-05-18
+---
+
+# Router Path-Selection + Runtime Resolution Rules
+
+Extracted from `skills/router/SKILL.md` per Phase 28.5 D-10 (extract-then-link, never delete
+content). The router SKILL keeps its invocation contract, output schema versioning table,
+integration point, and failure modes. The path-selection heuristic tables, the cost
+estimation algorithm, and the runtime-aware model resolution computation contract live
+here so the SKILL stays under the 100-line cap.
+
+## Path Selection Heuristic
+
+The router emits both `path` (legacy 3-tier enum) and `complexity_class` (Phase 25 4-tier enum). The canonical mapping is:
+
+| complexity_class | path | Behavior |
+|------------------|------|----------|
+| `S` | `fast` (short-circuited) | Skip router itself, skip cache-manager, skip telemetry write. Deterministic no-op decision. |
+| `M` | `fast` | Single Haiku + no checkers. |
+| `L` | `quick` | Sonnet mappers + Haiku verify. |
+| `XL` | `full` | Opus planners + full quality gates. Recommends worktree-isolation default + mandatory inter-stage checkpoint + reflector auto-spawn. |
+
+Bucket assignment:
+
+| Signal | complexity_class | path |
+|--------|------------------|------|
+| Command is `/gdd:help`, `/gdd:stats`, `/gdd:note`, `/gdd:health`, single-Haiku skill | `S` | `fast` (short-circuited — see below) |
+| Command is `/gdd:scan`, `/gdd:brief`, `/gdd:sketch`, `/gdd:spike`, `/gdd:fast` | `M` | `fast` |
+| Command spawns exactly one agent (no orchestration), not in S list | `M` | `fast` |
+| Command is `/gdd:explore`, `/gdd:discover`, standalone `/gdd:verify`, standalone `/gdd:plan` | `L` | `quick` |
+| Command spawns parallel mappers but no planners/auditors (`/gdd:discover` in `--auto` mode) | `L` | `quick` |
+| Command is `/gdd:next`, `/gdd:do`, `/gdd:autonomous`, end-to-end Brief→Verify, anything spawning planners + auditors + verifiers in series | `XL` | `full` |
+| Command spawns planners, auditors, verifiers, or integration-checkers (`/gdd:plan`, `/gdd:verify`, `/gdd:audit`) and is not standalone | `XL` | `full` |
+| `--dry-run` flag present on any command | downgrade one tier (XL→L→M→S; `path` follows the mapping table) |
+
+### S-class short-circuit
+
+When `complexity_class` would be `S`, the router itself **does not run** for that invocation — the deterministic skip list is encoded in the `/gdd:*` SKILL.md entry of the matching command. The budget-enforcer hook treats "no router decision payload + matching command name" as the S-class signal and skips enforcement entirely (no telemetry row, no cache lookup, no event emission). When the router *is* invoked explicitly (e.g., debugging) it still emits `complexity_class: "S"` in the JSON for observability, but the runtime path is the no-op.
+
+## Cost Estimation Algorithm
+
+```
+total = 0
+for each agent in planned spawn graph:
+  tier = resolve_tier(agent)   # budget.json tier_overrides > agent frontmatter default-tier
+  (in_tok, out_tok) = token_range_from_size_budget(agent.size_budget)  # from reference/model-prices.md
+  (in_rate, out_rate) = price_from_tier(tier)
+  total += (in_tok / 1e6) * in_rate + (out_tok / 1e6) * out_rate
+return total
+```
+
+## Runtime-aware model resolution
+
+The router emits `resolved_models` alongside `model_tier_overrides` so downstream consumers (budget-enforcer cost computation, Phase 22 cost telemetry, Phase 23.5 bandit posterior store) can read the **concrete model ID** for the active runtime without re-deriving it from the tier name. The resolution is per-agent and additive — `model_tier_overrides` keeps its `opus|sonnet|haiku` enum for back-compat across all 14 runtimes, and `resolved_models` runs the runtime-specific translation on top of it.
+
+Computation contract (per D-07):
+
+```
+runtime = runtimeDetect.detect() ?? 'claude'
+for each agent in planned spawn graph:
+  tier = resolve_tier(agent)                          # same merge as model_tier_overrides
+  resolved_models[agent] = tierResolver.resolve(runtime, tier)
+                                                       # → concrete model string OR null
+```
+
+Implementation surfaces (Phase 26 / Wave A):
+
+- `scripts/lib/runtime-detect.cjs` — `detect() → runtime-id | null`. Reads the same `*_CONFIG_DIR` / `*_HOME` env-vars Phase 24's installer uses (single source of truth in `scripts/lib/install/runtimes.cjs`). Returns `null` when no recognized runtime env-var is set; the router falls back to `'claude'` so the resolver always has a runtime ID to work with.
+- `scripts/lib/tier-resolver.cjs` — `resolve(runtime, tier, opts?) → model | null`. Translates `opus|sonnet|haiku` to the concrete model the runtime understands using the `./runtime-models.md` mapping (Phase 26 / Wave A). Fallback chain (D-04): runtime-specific entry → `claude` row default with `tier_resolution_fallback` event → `null` with `tier_resolution_failed` event. Never throws; `null` is a valid output the consumer must handle.
+
+Per-agent emission rules:
+
+- One key per agent in the planned spawn graph (same key set the cost-estimation loop iterates over). Keys MUST match agent names exactly so consumers can join `resolved_models` against `model_tier_overrides` and the spawn graph by name.
+- Value is the concrete model string returned by `tier-resolver.resolve(runtime, tier)`.
+- When the resolver returns `null` (missing tier-map row, missing tier, garbage input), the value is JSON `null` — NOT omitted, NOT the empty string. Consumers (budget-enforcer, telemetry) MUST handle `null`: typically by skipping the cost row for that spawn and emitting their own diagnostic event, never by crashing.
+- When `complexity_class` is `S` and the router itself short-circuits (see **S-class short-circuit** above), no payload is emitted at all and `resolved_models` does not exist for that invocation — the budget-enforcer's "no router decision payload" branch already handles this case.
+
+Back-compat assertion: a router invocation in a Claude runtime (or any environment where `runtime-detect.detect()` returns `null` and the router falls back to `'claude'`) produces `resolved_models` values that are the canonical Anthropic model IDs (`claude-opus-4-7`, `claude-sonnet-4-6`, `claude-haiku-4-5`) for the corresponding tiers. Pre-Phase-26 consumers that ignore `resolved_models` see the same `model_tier_overrides` they always saw (Plan 26-09 owns the runtime fixture diff that asserts this).

package/reference/rtl-cjk-cultural.md

@@ -1,5 +1,7 @@
 # RTL, CJK, and Cultural Localization — Reference Guide
 
+> For engineering primitives (CSS logical properties, Intl.\* family, bidi isolation, ICU MessageFormat, text-expansion budgets, multi-script font stacks, Unicode hygiene), see [`./i18n.md`](./i18n.md). This file owns cultural context (greeting forms, color symbolism, CJK family-name conventions, imagery norms).
+
 Designing for a global audience is not a matter of translating strings and calling the work done. Layout direction, typographic rendering, number formatting, color semantics, and imagery all carry culturally specific expectations that, when violated, signal to users that the product was not made for them. This reference consolidates the key technical and cultural considerations that the get-design-done framework requires designers and engineers to understand before shipping to any non-English or non-Western market.
 
 ---