@hegemonart/get-design-done 1.41.5 → 1.43.0

package/reference/ds-bootstrap-rubric.md

@@ -1,24 +1,24 @@
 # Greenfield Design-System Bootstrap Rubric
 
-Emission rules for `/gdd:bootstrap-ds` + `agents/ds-generator.md` — how to turn a brand input (a primary color + optional secondary + tone tags + target framework) into a coherent token system, **without inventing a brand**. The deterministic math lives in `scripts/lib/ds/token-scale.cjs`; the color-theory grounding lives in `reference/color-theory.md`. This file is the rulebook the generator obeys.
+Emission rules for `/gdd:bootstrap-ds` + `agents/ds-generator.md` - how to turn a brand input (a primary color + optional secondary + tone tags + target framework) into a coherent token system, **without inventing a brand**. The deterministic math lives in `scripts/lib/ds/token-scale.cjs`; the color-theory grounding lives in `reference/color-theory.md`. This file is the rulebook the generator obeys.
 
-GDD does not author a brand identity (logomarks, voice) — it emits a **starter token system + a few proof components** a greenfield project can build on.
+GDD does not author a brand identity (logomarks, voice) - it emits a **starter token system + a few proof components** a greenfield project can build on.
 
 ---
 
 ## Color
 
-- **Primary → 9 tints/shades.** Convert the brand primary to OKLCH `{l, c, h}`, then call `oklchScale(primary)` → 9 stops (`100`…`900`) emitted as native CSS `oklch()`. Stop `500` is the primary exactly; lighter stops interpolate L toward white with damped chroma; darker stops toward black. Native `oklch()` — **no hex conversion, no color library**.
+- **Primary → 9 tints/shades.** Convert the brand primary to OKLCH `{l, c, h}`, then call `oklchScale(primary)` → 9 stops (`100`…`900`) emitted as native CSS `oklch()`. Stop `500` is the primary exactly; lighter stops interpolate L toward white with damped chroma; darker stops toward black. Native `oklch()` - **no hex conversion, no color library**.
 - **Never auto-generate more than 2 brand colors.** Primary is always emitted. A **secondary** scale is emitted **only if the user supplies one**. Never invent a third brand hue.
-- **Neutrals** — a low-chroma gray ramp (chroma ≤ 0.02) sharing the primary's hue for a subtle tint, or pure neutral (`c = 0`). 9 stops via `oklchScale({ l, c: 0.012, h: primary.h })`.
-- **Semantic colors** — success / warning / danger / info derived at fixed hues (≈145 / 85 / 25 / 255) at the brand's mid-lightness + chroma, so they sit in the same family. These are functional, not "brand" colors (they do not count against the ≤2 rule).
-- **Contrast** — every text-on-surface pairing must clear WCAG AA (see `reference/color-theory.md`); the generator checks the chosen `500`/`700` against white/`50`.
+- **Neutrals** - a low-chroma gray ramp (chroma ≤ 0.02) sharing the primary's hue for a subtle tint, or pure neutral (`c = 0`). 9 stops via `oklchScale({ l, c: 0.012, h: primary.h })`.
+- **Semantic colors** - success / warning / danger / info derived at fixed hues (≈145 / 85 / 25 / 255) at the brand's mid-lightness + chroma, so they sit in the same family. These are functional, not "brand" colors (they do not count against the ≤2 rule).
+- **Contrast** - every text-on-surface pairing must clear WCAG AA (see `reference/color-theory.md`); the generator checks the chosen `500`/`700` against white/`50`.
 
 ## Typography
 
-- **Modular scale** via `typeScale(baseRem, ratio, steps)`. Base `1rem` (16px). **Ratio ∈ {1.2 (minor third), 1.25 (major third), 1.333 (perfect fourth)}** — pick by tone (calm → 1.2, default → 1.25, editorial/bold → 1.333).
+- **Modular scale** via `typeScale(baseRem, ratio, steps)`. Base `1rem` (16px). **Ratio ∈ {1.2 (minor third), 1.25 (major third), 1.333 (perfect fourth)}** - pick by tone (calm → 1.2, default → 1.25, editorial/bold → 1.333).
 - Emit named steps (`xs`…`5xl`) from the scale; line-height pairs (tight 1.2 for headings, 1.5 for body).
-- Font family is a **slot**, not a choice — emit a system-font stack placeholder + a `--font-sans` / `--font-mono` variable the user swaps. GDD does not pick a typeface (brand territory).
+- Font family is a **slot**, not a choice - emit a system-font stack placeholder + a `--font-sans` / `--font-mono` variable the user swaps. GDD does not pick a typeface (brand territory).
 
 ## Spacing
 
@@ -27,9 +27,9 @@ GDD does not author a brand identity (logomarks, voice) — it emits a **starter
 ## Radius + Motion
 
 - **Radius** via `radiusScale(basePx)` → `sm/md/lg/xl/full` (`full = 9999` pill).
-- **Motion defaults** — durations `fast 150ms / base 250ms / slow 400ms`; easing `ease-out` for enters, a standard curve for moves; **always** respect `prefers-reduced-motion` (emit the media-query guard).
+- **Motion defaults** - durations `fast 150ms / base 250ms / slow 400ms`; easing `ease-out` for enters, a standard curve for moves; **always** respect `prefers-reduced-motion` (emit the media-query guard).
 
-## The 3 variants (D-02 — user picks one)
+## The 3 variants (D-02 - user picks one)
 
 The generator emits three coherent variants; the user picks ONE before first-component scaffolding:
 
@@ -42,10 +42,10 @@ The generator emits three coherent variants; the user picks ONE before first-com
 ## Emission format
 
 - Emit **CSS custom properties** (`:root { --color-primary-500: oklch(...); --space-4: 16px; ... }`) as the canonical artifact, plus a target-framework mapping:
-  - **web (default)** — a Tailwind `theme.extend` block (or shadcn CSS variables) + the `:root` tokens.
-  - **native** — route the token set through `reference/native-platforms.md` (Phase 34) for SwiftUI / Compose / Flutter theme objects.
+  - **web (default)** - a Tailwind `theme.extend` block (or shadcn CSS variables) + the `:root` tokens.
+  - **native** - route the token set through `reference/native-platforms.md` (Phase 34) for SwiftUI / Compose / Flutter theme objects.
 - Tokens are **named by role, not value** (`--color-primary-500`, not `--blue-500`) so a rebrand is a one-line hue change.
 
 ## First-component scaffolding (proof artifact)
 
-After the user picks a variant, emit **button + input + card** in the detected target framework, consuming only the emitted tokens — a proof the system is coherent, not a full component library (that is out of scope).
+After the user picks a variant, emit **button + input + card** in the detected target framework, consuming only the emitted tokens - a proof the system is coherent, not a full component library (that is out of scope).

package/reference/email-design.md

@@ -1,7 +1,7 @@
-# Email Design — Constraint Catalogue
+# Email Design - Constraint Catalogue
 
 This reference is the **email-constraint catalogue**: the hard email-client rules an
-email template MUST honor. Email is a *constrained* HTML/CSS surface — the modern
+email template MUST honor. Email is a *constrained* HTML/CSS surface - the modern
 HTML/CSS the web executor emits (flexbox, grid, `<style>` sheets, `position`) is
 dropped or mis-rendered by most email clients. This file is the **authority** that the
 email-executor (Phase 34.2-02) generates against and the design-verifier's email branch
@@ -14,8 +14,8 @@ 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 for native/web screens. |
-| `reference/email-design.md` (Phase 34.2, this file) | The email **constraint catalogue** — table-based layout, inline styles, MSO conditional comments, dark-mode `color-scheme`, ~600px max-width, image/alt rules, and top-20-client quirks. *Structural* knowledge an email template implements. |
+| `reference/platforms.md` (Phase 19) | Interaction **conventions** - navigation, safe areas, gestures, native typography, haptics. *Behavioral* knowledge for native/web screens. |
+| `reference/email-design.md` (Phase 34.2, this file) | The email **constraint catalogue** - table-based layout, inline styles, MSO conditional comments, dark-mode `color-scheme`, ~600px max-width, image/alt rules, and top-20-client quirks. *Structural* knowledge an email template implements. |
 
 Per **D-02** there is **no `mjml` runtime dependency**: MJML source is the agent's
 canonical artifact and the HTML is derived by the agent, not a build step. Per **D-03**
@@ -44,7 +44,7 @@ kept to 2–3 lines. The implementation is `validate-email-html.cjs`.
 
 ---
 
-## 2. Layout — tables, not flexbox/grid/position
+## 2. Layout - tables, not flexbox/grid/position
 
 Email layout uses nested `role="presentation"` **tables**, never the modern CSS box
 primitives. `display:flex`, `display:grid`, and `position:absolute|fixed|sticky` are
@@ -53,11 +53,11 @@ collapsing a layout to a single column or off-screen elements.
 
 | Rule-id | Constraint |
 | --- | --- |
-| **EM-LAYOUT-01** | Layout is built from `role="presentation"` tables. The forbidden modern primitives — `display:flex`, `display:grid`, `position:absolute`, `position:fixed` (and `position:sticky`) — MUST NOT appear in any `style`. *(Statically checkable: their presence is flagged.)* |
+| **EM-LAYOUT-01** | Layout is built from `role="presentation"` tables. The forbidden modern primitives - `display:flex`, `display:grid`, `position:absolute`, `position:fixed` (and `position:sticky`) - MUST NOT appear in any `style`. *(Statically checkable: their presence is flagged.)* |
 | EM-LAYOUT-02 | Body content sits in a fixed-/max-width container of ~**600px** (the safe width across the desktop preview pane and most mobile clients). Wider tables clip in Outlook and force horizontal scroll on mobile. |
 | EM-LAYOUT-03 | Use `cellpadding="0" cellspacing="0" border="0"` on layout tables and prefer cell `padding` over margins (margins are inconsistently honored). |
 | EM-LAYOUT-04 | Single primary column on mobile; multi-column desktop layouts degrade to stacked rows. Do not rely on `float` for columns (use side-by-side `<td>`s or `align`). |
-| EM-LAYOUT-05 | Set explicit `width` on tables/cells; never assume an intrinsic content width. Outlook ignores CSS `max-width` on many elements — pair it with a `<!--[if mso]>` ghost table (see §4). |
+| EM-LAYOUT-05 | Set explicit `width` on tables/cells; never assume an intrinsic content width. Outlook ignores CSS `max-width` on many elements - pair it with a `<!--[if mso]>` ghost table (see §4). |
 
 ```html
 <table role="presentation" width="600" cellpadding="0" cellspacing="0" border="0"
@@ -114,7 +114,7 @@ overrides.
 
 | Rule-id | Constraint |
 | --- | --- |
-| **EM-DARK-01** | Declare a `color-scheme` signal: a `<meta name="color-scheme" content="light dark">` and/or a `color-scheme: light dark;` CSS declaration and/or a `@media (prefers-color-scheme: dark)` block. At least one MUST be present. *(Statically checkable: total absence of any color-scheme signal is flagged. A `<meta name="color-scheme">` alone satisfies it — decoupled from any `<style>` block.)* |
+| **EM-DARK-01** | Declare a `color-scheme` signal: a `<meta name="color-scheme" content="light dark">` and/or a `color-scheme: light dark;` CSS declaration and/or a `@media (prefers-color-scheme: dark)` block. At least one MUST be present. *(Statically checkable: total absence of any color-scheme signal is flagged. A `<meta name="color-scheme">` alone satisfies it - decoupled from any `<style>` block.)* |
 | EM-DARK-02 | Pair `color-scheme` with `supported-color-schemes` (meta) for Apple Mail / Outlook. |
 | EM-DARK-03 | Beware forced color inversion: set explicit `background-color` AND `color` on text containers so an inverting client cannot produce unreadable low-contrast pairs. |
 | EM-DARK-04 | Provide dark-mode-friendly logos (transparent PNG or a `prefers-color-scheme` image swap) so a dark background does not hide a dark logo. |
@@ -124,7 +124,7 @@ overrides.
 ## 6. Images & accessibility
 
 Images are often blocked by default and must degrade gracefully; accessibility rules
-prevent broken layouts and unreadable content. *(Guidance — not all statically
+prevent broken layouts and unreadable content. *(Guidance - not all statically
 asserted; see §8.)*
 
 | Rule-id | Constraint |
@@ -139,19 +139,19 @@ asserted; see §8.)*
 
 ## 7. Top-20 client quirks
 
-The top-20-by-market-share email clients and their headline quirks. *(Catalogue —
+The top-20-by-market-share email clients and their headline quirks. *(Catalogue -
 most are render-tested via the optional Litmus / Email-on-Acid connection (34.2-02),
 NOT statically checkable; see §8.)*
 
 | Rule-id | Client | Headline quirk |
 | --- | --- | --- |
-| EM-CLIENT-01 | Apple Mail (iOS) | Most standards-compliant; honors `<style>` + media queries; auto-scales text — set `meta viewport`. |
-| EM-CLIENT-02 | Apple Mail (macOS) | WebKit-based, robust; respects `prefers-color-scheme`; watch auto-link of dates/addresses. |
+| EM-CLIENT-01 | Apple Mail (iOS) | Most standards-compliant; honors `<style>` + media queries; auto-scales text - set `meta viewport`. |
+| EM-CLIENT-02 | Apple Mail (macOS) | WebKit-based, solid; respects `prefers-color-scheme`; watch auto-link of dates/addresses. |
 | EM-CLIENT-03 | Gmail (web) | **Strips `<head>` styles** beyond a limited `<style>`; clips messages over ~102KB ("[Message clipped]"); requires inline styles. |
 | EM-CLIENT-04 | Gmail (mobile app, default account) | Supports a `<style>` block + media queries; same ~102KB clip; no `:hover` reliability. |
-| EM-CLIENT-05 | Gmail (mobile, non-default / IMAP "GANGA") | **Strips `<style>` entirely** — only inline styles survive; the strictest Gmail mode. |
+| EM-CLIENT-05 | Gmail (mobile, non-default / IMAP "GANGA") | **Strips `<style>` entirely** - only inline styles survive; the strictest Gmail mode. |
 | EM-CLIENT-06 | Outlook 2016–2021 (Windows) | **Word engine**: no flexbox/grid/`position`, ignores `max-width`/`border-radius`/CSS `background-image`; needs ghost tables + VML + `mso-line-height-rule:exactly`. |
-| EM-CLIENT-07 | Outlook (Microsoft 365, Windows) | Word engine like 2016/2019; DPI scaling bugs — set explicit image `width`/`height`. |
+| EM-CLIENT-07 | Outlook (Microsoft 365, Windows) | Word engine like 2016/2019; DPI scaling bugs - set explicit image `width`/`height`. |
 | EM-CLIENT-08 | Outlook.com (web) | Different (better) engine than desktop; **aggressive dark-mode color inversion**; rewrites some colors. |
 | EM-CLIENT-09 | Outlook (macOS) | WebKit-based (unlike Windows); far more capable; still test buttons/spacing. |
 | EM-CLIENT-10 | Outlook (mobile, iOS/Android) | Largely fine; respects media queries; watch link color overrides. |
@@ -173,15 +173,15 @@ NOT statically checkable; see §8.)*
 This table is the **contract** the validator's `rule` ids map to. The four rule-ids
 below are the deterministic subset that `scripts/lib/email/validate-email-html.cjs`
 asserts via regex/string analysis of the supplied HTML string. Every other rule-id in
-this catalogue is **render-tested guidance** — verified by the optional Litmus /
+this catalogue is **render-tested guidance** - verified by the optional Litmus /
 Email-on-Acid render-test connection (34.2-02), never asserted by the static validator.
 
 | Rule-id | Check | Statically checked by the validator? | How verified otherwise |
 | --- | --- | --- | --- |
-| **EM-LAYOUT-01** | No `display:flex` / `display:grid` / `position:absolute\|fixed` in any `style` | **YES** — presence flagged | — |
-| **EM-STYLE-01** | No `<style>` block as the PRIMARY styling mechanism (non-`@media` rules / large sheet); inline styling expected | **YES** — a non-trivial `<style>` block flagged; a small `@media`-only block tolerated | — |
-| **EM-MSO-01** | An MSO conditional comment (`<!--[if mso]>` / `<!--[if !mso]>`) is present in a full-email document | **YES** — absence flagged | — |
-| **EM-DARK-01** | A `color-scheme` signal is present (meta `color-scheme` and/or CSS `color-scheme` and/or `prefers-color-scheme`) | **YES** — total absence flagged (a `<meta name="color-scheme">` alone satisfies it) | — |
+| **EM-LAYOUT-01** | No `display:flex` / `display:grid` / `position:absolute\|fixed` in any `style` | **YES** - presence flagged | - |
+| **EM-STYLE-01** | No `<style>` block as the PRIMARY styling mechanism (non-`@media` rules / large sheet); inline styling expected | **YES** - a non-trivial `<style>` block flagged; a small `@media`-only block tolerated | - |
+| **EM-MSO-01** | An MSO conditional comment (`<!--[if mso]>` / `<!--[if !mso]>`) is present in a full-email document | **YES** - absence flagged | - |
+| **EM-DARK-01** | A `color-scheme` signal is present (meta `color-scheme` and/or CSS `color-scheme` and/or `prefers-color-scheme`) | **YES** - total absence flagged (a `<meta name="color-scheme">` alone satisfies it) | - |
 | EM-LAYOUT-02..05 | ~600px width, cellpadding, single-column, explicit widths | No | Render test (Litmus) |
 | EM-STYLE-02..04 | Longhand props, no external CSS, tolerated `@media` | No | Render test |
 | EM-MSO-02..04 | Ghost tables, VML, DPI/namespace head | No | Render test (Outlook) |
@@ -207,13 +207,13 @@ Notes on the four statically-checked rules:
 
 ## 9. Cross-references
 
-- [`reference/platforms.md`](./platforms.md) — the interaction-conventions sibling
+- [`reference/platforms.md`](./platforms.md) - the interaction-conventions sibling
   (navigation, safe areas, gestures). The email-executor reads **this** file for the
   email constraints, that file for general platform behavior.
 - [`scripts/lib/email/validate-email-html.cjs`](../scripts/lib/email/validate-email-html.cjs)
-  — the deterministic static validator that asserts the §8 subset; its `rule` ids are
+  - the deterministic static validator that asserts the §8 subset; its `rule` ids are
   the constraint-ids defined here.
-- [`reference/registry.json`](./registry.json) — this catalogue is registered as the
+- [`reference/registry.json`](./registry.json) - this catalogue is registered as the
   `email-design` entry (type `heuristic`, phase `34.2`) so the registry round-trip test
   (`test/suite/reference-registry.test.cjs`) stays green (D-05, the 33.5-01 / 34.1-01
   lesson).

package/reference/emotional-design.md

@@ -1,8 +1,8 @@
-# Emotional Design — Norman's Three Levels
+# Emotional Design - Norman's Three Levels
 
 Source: Don Norman, *Emotional Design: Why We Love (or Hate) Everyday Things* (2004). See also: `jnd.org`.
 
-Use this file as a **cross-cutting scoring lens** in design audits and reflections. The three levels apply simultaneously to every design decision — they are not sequential stages.
+Use this file as a **cross-cutting scoring lens** in design audits and reflections. The three levels apply simultaneously to every design decision - they are not sequential stages.
 
 ---
 
@@ -12,7 +12,7 @@ Use this file as a **cross-cutting scoring lens** in design audits and reflectio
 
 > The immediate, pre-cognitive, automatic reaction to sensory input.
 
-The visceral level operates before the user thinks. It is driven by appearance, proportion, colour, texture — the aesthetic surface. A user who says "I don't know why, but this feels cheap" is responding at the visceral level.
+The visceral level operates before the user thinks. It is driven by appearance, proportion, colour, texture - the aesthetic surface. A user who says "I don't know why, but this feels cheap" is responding at the visceral level.
 
 **What it governs:**
 - First impression within 50ms of page load (aesthetic-usability effect)
@@ -39,14 +39,14 @@ The visceral level operates before the user thinks. It is driven by appearance,
 
 ### Behavioral Level
 
-> The experience of use — whether actions feel controllable, predictable, and rewarding.
+> The experience of use - whether actions feel controllable, predictable, and rewarding.
 
 The behavioral level is what UX heuristics primarily address. It covers usability, feedback, error recovery, and responsiveness. A user who says "This is frustrating to use" is responding at the behavioral level.
 
 **What it governs:**
 - Interaction feedback (loading states, error messages, success confirmations)
 - Control and reversibility (undo, cancel, back navigation)
-- Response latency — the Doherty Threshold: feedback within 400ms
+- Response latency - the Doherty Threshold: feedback within 400ms
 - Error prevention and recovery
 - Learnability and consistency across screens
 
@@ -69,14 +69,14 @@ The behavioral level is what UX heuristics primarily address. It covers usabilit
 
 ### Reflective Level
 
-> The conscious, post-use evaluation — meaning, narrative, and self-image.
+> The conscious, post-use evaluation - meaning, narrative, and self-image.
 
 The reflective level is where brand identity, storytelling, and pride of ownership live. A user who says "I love showing this tool to colleagues" is responding at the reflective level. This level takes the longest to build and the longest to repair when damaged.
 
 **What it governs:**
 - Whether the product aligns with the user's self-image
 - Brand narrative consistency across all touchpoints
-- Delight and surprise moments — not gimmicks; earned moments
+- Delight and surprise moments - not gimmicks; earned moments
 - The **Peak** moment in the Peak-End Rule: the highest positive moment in the flow
 - Long-term loyalty and word-of-mouth referral
 
@@ -103,14 +103,14 @@ Apply this lens as a **secondary overlay** after scoring the primary audit pilla
 
 1. Identify 1–2 evidence items from the primary audit (e.g., Pillar 3 Color → Visceral Level)
 2. Note conflicts between levels (e.g., Behavioral score 4 but Visceral score 1 = technically functional but aesthetically repellent)
-3. Flag the weakest level as the highest-leverage improvement opportunity
+3. Flag the weakest level as the highest-impact improvement opportunity
 
 **Common cross-level conflict patterns:**
 
 | Conflict pattern | Diagnosis | Remedy |
 |---|---|---|
 | High behavioral, low visceral | Technically usable but aesthetically generic | Audit against `style-vocabulary.md`; commit to a stronger aesthetic type |
-| High visceral, low behavioral | Beautiful but broken | Fix H-01, H-09 violations first — UX before aesthetics |
+| High visceral, low behavioral | Beautiful but broken | Fix H-01, H-09 violations first - UX before aesthetics |
 | High visceral + behavioral, low reflective | Polished but forgettable | Design a peak moment; review `brand-voice.md` emotional arc |
 
 ---
@@ -119,6 +119,6 @@ Apply this lens as a **secondary overlay** after scoring the primary audit pilla
 
 **design-auditor:** After pillar scoring, apply emotional-design lens as a cross-cutting overlay. Add `## Emotional Design Overlay` section to `DESIGN-AUDIT.md` with scores for all three levels and any cross-level conflict notes.
 
-**design-reflector:** In Section 1 (What Surprised Us), flag if visceral vs behavioral scores diverge by ≥2 points — this is a leading indicator of the "beautiful but broken" pattern.
+**design-reflector:** In Section 1 (What Surprised Us), flag if visceral vs behavioral scores diverge by ≥2 points - this is a leading indicator of the "beautiful but broken" pattern.
 
 **design-discussant:** In `--spec` mode, include one reflective-level confidence-scored question: "What story does this product help the user tell about themselves?"

package/reference/error-recovery.md

@@ -10,7 +10,7 @@ On `status=429`, consult `scripts/lib/rate-guard.cjs` → `blockUntilReady(provi
 
 On network-transient (5xx, ECONNRESET), use jittered backoff (`scripts/lib/jittered-backoff.cjs`); max 3 retries.
 
-On auth-error, surface to user — do not retry.
+On auth-error, surface to user - do not retry.
 
 ## Recovery-action table
 
@@ -18,14 +18,14 @@ The `FailoverReason` enum in `scripts/lib/error-classifier.cjs` has eight values
 
 | FailoverReason      | Retryable | Action                                                                                                                                                     |
 | ------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `rate_limited`      | yes       | Call `rate-guard.ingestHeaders(provider, response.headers)` to record the rate-limit signal, then `rate-guard.blockUntilReady(provider)` before retrying. The blocker waits until `resetAt` on disk — synchronized siblings (watch-authorities + update-check) therefore share the backoff boundary. After the block returns, retry with jittered backoff at attempt 0. |
-| `context_overflow`  | yes       | Compress context — drop the oldest non-system turns (or the oldest attachments) targeting roughly 50 % token reduction. Retry **once** with the compressed payload. If the retry also raises `context_overflow`, escalate to the user as an unrecoverable block — further compression destroys information. |
-| `auth_error`        | no        | Surface the error to the user with actionable text: which credential, which provider, and the renewal path (OAuth re-auth URL, API-key environment variable, etc.). Do not retry automatically — a loop would just multiply the failure. |
-| `network_transient` | yes       | Retry with `scripts/lib/jittered-backoff.cjs` — `await sleep(attempt)` inside a bounded loop. Cap at 3 attempts before giving up. When retries exhaust, reclassify as `network_permanent` and surface to the user. |
+| `rate_limited`      | yes       | Call `rate-guard.ingestHeaders(provider, response.headers)` to record the rate-limit signal, then `rate-guard.blockUntilReady(provider)` before retrying. The blocker waits until `resetAt` on disk - synchronized siblings (watch-authorities + update-check) therefore share the backoff boundary. After the block returns, retry with jittered backoff at attempt 0. |
+| `context_overflow`  | yes       | Compress context - drop the oldest non-system turns (or the oldest attachments) targeting roughly 50 % token reduction. Retry **once** with the compressed payload. If the retry also raises `context_overflow`, escalate to the user as an unrecoverable block - further compression destroys information. |
+| `auth_error`        | no        | Surface the error to the user with actionable text: which credential, which provider, and the renewal path (OAuth re-auth URL, API-key environment variable, etc.). Do not retry automatically - a loop would just multiply the failure. |
+| `network_transient` | yes       | Retry with `scripts/lib/jittered-backoff.cjs` - `await sleep(attempt)` inside a bounded loop. Cap at 3 attempts before giving up. When retries exhaust, reclassify as `network_permanent` and surface to the user. |
 | `network_permanent` | no        | Surface to user. The endpoint is wrong, DNS is broken, or the resource was removed. A retry without operator action will just re-fail. |
 | `tool_not_found`    | no        | Surface to user. Either the tool name drifted (common for MCP servers whose prefixes change across sessions) or the MCP is not registered. Reprobe via the connection's probe sequence before retrying anything. |
-| `validation`        | no        | Surface the validation detail to the caller. Do not retry the same input — 4xx is the server saying "your payload is wrong". Fixing the payload is caller work. |
-| `unknown`           | no        | Surface the raw error to the user. Do not retry — we can't tell whether it's safe. Add a telemetry row so we can tighten the classifier over time. |
+| `validation`        | no        | Surface the validation detail to the caller. Do not retry the same input - 4xx is the server saying "your payload is wrong". Fixing the payload is caller work. |
+| `unknown`           | no        | Surface the raw error to the user. Do not retry - we can't tell whether it's safe. Add a telemetry row so we can tighten the classifier over time. |
 
 ## Integration points
 
@@ -34,7 +34,7 @@ The `FailoverReason` enum in `scripts/lib/error-classifier.cjs` has eight values
 | `hooks/budget-enforcer.ts` | pre-spawn rate-guard check (Plan 20-14)      | If upstream state already shows `rate_limited`, emit `decision: 'rate-limited'` and short-circuit before any spawn. |
 | Figma MCP probe           | live `get_metadata` call errors              | `network_transient` → jittered-backoff retry. `auth_error` → STOP with a reauth note. `rate_limited` → block then retry. |
 | Watch-authorities fetcher | per-feed HTTP fetch                          | Same policy as Figma probe; `validation` also possible on ETag stalemate (304). |
-| Update-check HTTP curl    | GitHub `releases/latest` fetch               | Silent failure by D-04 of Plan 13.3 — classify but don't surface; log and exit 0. |
+| Update-check HTTP curl    | GitHub `releases/latest` fetch               | Silent failure by D-04 of Plan 13.3 - classify but don't surface; log and exit 0. |
 | MCP transport             | tool-call errors (gdd-state, figma, 21st-dev)| Map `tool_not_found` to a probe-reissue; map `auth_error` to STOP; retry transient classes via the caller's own loop. |
 
 ## Fix-loop iteration interaction
@@ -43,9 +43,9 @@ Retries consume iteration budget when paired with the Layer-B cache:
 
 1. On cache hit, `iteration-budget.refund(1)` preserves the iteration that would otherwise have been spent.
 2. On each actual retry that does real work (no cache hit), the caller `iteration-budget.consume(1)` before the spawn.
-3. When the budget's `remaining === 0`, further retries throw `IterationBudgetExhaustedError` and the caller must surface to user — a retry cycle has become pathological.
+3. When the budget's `remaining === 0`, further retries throw `IterationBudgetExhaustedError` and the caller must surface to user - a retry cycle has become pathological.
 
-This protects the "infinite fix loop" case — a blocker that regenerates after every fix — from burning unbounded context.
+This protects the "infinite fix loop" case - a blocker that regenerates after every fix - from burning unbounded context.
 
 ## Telemetry
 
@@ -55,4 +55,4 @@ Every classification result that leads to a retry or a surfaced error should app
 { "type": "error.classified", "timestamp": "…", "sessionId": "…", "payload": { "reason": "rate_limited", "retryable": true, "caller": "figma-probe" } }
 ```
 
-The event subtype is defined in `scripts/lib/event-stream/types.ts`. Consumers (`gdd-reflector`, dashboard) aggregate by `reason` to detect classifier drift — if `unknown` spikes, the classifier needs tightening.
+The event subtype is defined in `scripts/lib/event-stream/types.ts`. Consumers (`gdd-reflector`, dashboard) aggregate by `reason` to detect classifier drift - if `unknown` spikes, the classifier needs tightening.

package/reference/export-formats.md

@@ -1,4 +1,4 @@
-# Export Formats — the `/gdd:export` contract
+# Export Formats - the `/gdd:export` contract
 
 How `/gdd:export <cycle> --format html|pdf|notion [--pseudonymize] [--pr]` turns a completed cycle's in-repo design output into a stakeholder-shareable artifact. Dep-free: the HTML/PDF assembler is pure (`scripts/lib/export/build-html.cjs`); Notion is MCP-based; no `paged`/`puppeteer`/`pdfkit`/markdown-lib runtime.
 
@@ -10,21 +10,21 @@ In cycle order: `EXPERIENCE.md` (Phase 19.5 cross-cycle memory) · `.design/DESI
 
 ## Formats
 
-- **`html`** (default) — `buildHtml({ title, subtitle, sections, images })` → a **single self-contained HTML** file: inline `<style>`, base64-embedded images, **zero external references** (safe to email / drop in Drive). Written to `.design/export/<cycle>.html`.
-- **`pdf`** — the same `buildHtml({ ..., print: true })` (adds a Paged.js-compatible `@page` print stylesheet). Written to `.design/export/<cycle>.print.html`; **the user renders it** via Paged.js / headless-Chrome. GDD ships **no** PDF runtime (the print-executor precedent, D-02).
-- **`notion`** — a Notion page via the Notion MCP (`connections/notion.md`): headings → section/toggle blocks, screenshots → image-upload blocks. Degrades to the `html` file when the Notion MCP is `not_configured`/disabled.
+- **`html`** (default) - `buildHtml({ title, subtitle, sections, images })` → a **single self-contained HTML** file: inline `<style>`, base64-embedded images, **zero external references** (safe to email / drop in Drive). Written to `.design/export/<cycle>.html`.
+- **`pdf`** - the same `buildHtml({ ..., print: true })` (adds a Paged.js-compatible `@page` print stylesheet). Written to `.design/export/<cycle>.print.html`; **the user renders it** via Paged.js / headless-Chrome. GDD ships **no** PDF runtime (the print-executor precedent, D-02).
+- **`notion`** - a Notion page via the Notion MCP (`connections/notion.md`): headings → section/toggle blocks, screenshots → image-upload blocks. Degrades to the `html` file when the Notion MCP is `not_configured`/disabled.
 
 ## Privacy (redact always; pseudonymize opt-in)
 
-Every section is passed through `scripts/lib/redact.cjs` (secrets — the floor). `--pseudonymize` additionally applies `scripts/lib/pseudonymize.cjs` (git identity / paths / hostname / repo origin) — use it when sharing externally. Default (no flag) = redact only.
+Every section is passed through `scripts/lib/redact.cjs` (secrets - the floor). `--pseudonymize` additionally applies `scripts/lib/pseudonymize.cjs` (git identity / paths / hostname / repo origin) - use it when sharing externally. Default (no flag) = redact only.
 
 ## PR integration (`--pr`)
 
-`--pr` hands the generated self-contained HTML preview to `agents/pr-commenter.md` (Phase 35.1) to post as a PR comment — degrade-to-noop when there's no PR or pr-commenter is unavailable (never blocks the export).
+`--pr` hands the generated self-contained HTML preview to `agents/pr-commenter.md` (Phase 35.1) to post as a PR comment - degrade-to-noop when there's no PR or pr-commenter is unavailable (never blocks the export).
 
 ## Self-contained guarantee (html/pdf)
 
-`build-html.cjs` emits no external `src=`/`<link>`/`<script>` — CSS is inline, images are base64 `data:` URIs. Content links (`<a href="https://…">`) are preserved (they're references, not load-bearing resources). Deterministic: same input → byte-identical output (the regression baseline freezes a fixture render).
+`build-html.cjs` emits no external `src=`/`<link>`/`<script>` - CSS is inline, images are base64 `data:` URIs. Content links (`<a href="https://…">`) are preserved (they're references, not essential resources). Deterministic: same input → byte-identical output (the regression baseline freezes a fixture render).
 
 ## Out of scope
 

package/reference/figma-sandbox.md

@@ -1,19 +1,19 @@
-# Figma Plugin Sandbox — Hard Rules
+# Figma Plugin Sandbox - Hard Rules
 
 The `use_figma` MCP runs every script inside the Figma plugin sandbox with a **~5–10s per-call budget**. Four pitfalls repeatedly burn quota in docs-authoring loops. Treat these as hard rules.
 
-**Rule 1 — `loadFontAsync` does NOT cache across `use_figma` calls.** Every new call re-fetches font metadata. Preload every style ONCE at the top of a script; clone existing text nodes via `node.clone()` or `figma.createText().fontName = ...` rather than calling `loadFontAsync` again.
+**Rule 1 - `loadFontAsync` does NOT cache across `use_figma` calls.** Every new call re-fetches font metadata. Preload every style ONCE at the top of a script; clone existing text nodes via `node.clone()` or `figma.createText().fontName = ...` rather than calling `loadFontAsync` again.
 
-**Rule 2 — `figma.root.findOne()` is O(tree-size) per call.** On a real file with thousands of frames this alone eats the budget. When you already know the node you want to act on, pass the node ID directly and call `figma.getNodeById(id)`. Never call `findOne` in a loop.
+**Rule 2 - `figma.root.findOne()` is O(tree-size) per call.** On a real file with thousands of frames this alone eats the budget. When you already know the node you want to act on, pass the node ID directly and call `figma.getNodeById(id)`. Never call `findOne` in a loop.
 
-**Rule 3 — `appendChild` on a large attached tree triggers full AutoLayout recomputation.** Build subtrees off-tree (on a detached parent) and attach the completed subtree once at the end. This avoids N + N-1 + ... + 1 full layout passes.
+**Rule 3 - `appendChild` on a large attached tree triggers full AutoLayout recomputation.** Build subtrees off-tree (on a detached parent) and attach the completed subtree once at the end. This avoids N + N-1 + ... + 1 full layout passes.
 
-**Rule 4 — per-call timeout is ~5–10s.** For docs-authoring (multi-row layouts populating from a library), budget **≤2 row-equivalents per `use_figma` call**. Exceeding this puts the script in the hill-climb-against-timeout failure mode: you retry with less content per call, each retry wastes another 5–10s, and MCP quota vanishes.
+**Rule 4 - per-call timeout is ~5–10s.** For docs-authoring (multi-row layouts populating from a library), budget **≤2 row-equivalents per `use_figma` call**. Exceeding this puts the script in the hill-climb-against-timeout failure mode: you retry with less content per call, each retry wastes another 5–10s, and MCP quota vanishes.
 
 ---
 
 ## When to skip `use_figma` entirely
 
-For **authoring new content** — creating pages, populating with library components, building documentation layouts from scratch — prefer `figma:figma-generate-design` from the Figma plugin. It runs outside the sandbox and has no per-call timeout.
+For **authoring new content** - creating pages, populating with library components, building documentation layouts from scratch - prefer `figma:figma-generate-design` from the Figma plugin. It runs outside the sandbox and has no per-call timeout.
 
 `use_figma` (and `/gdd:figma-write`) remain the right tools for **decision-writing**: attaching annotations, binding local-style tokens, registering Code Connect mappings, writing back implementation-status. Small, bounded, read-then-write operations where the four pitfalls don't apply.

package/reference/first-principles.md

@@ -1,4 +1,4 @@
-# First Principles — Invariant Design Constraints
+# First Principles - Invariant Design Constraints
 
 > These are the three invariants that no design decision can override. They are facts about human biology and cognition, not preferences or conventions. Every design choice is downstream of these three constraints.
 
@@ -53,7 +53,7 @@ Working memory holds approximately 7 items and degrades rapidly within seconds.
 | Recognition over recall (H-06) | Visible navigation labels, not icon-only; breadcrumbs on deep paths |
 | Context must be preserved | Multi-step forms: prior-step summary visible; form state not cleared on back-navigate |
 | Error memory fades fast | Inline validation: errors adjacent to the field that caused them |
-| Completion status reduces anxiety | Progress indicators: `Step 2 of 4`; Zeigarnik Effect — show percentage done |
+| Completion status reduces anxiety | Progress indicators: `Step 2 of 4`; Zeigarnik Effect - show percentage done |
 | Last action should be reversible | Undo available for destructive/irreversible actions within 5 seconds |
 
 **Reducibility check:** Does this screen require the user to remember something from a previous screen? If yes, surface that context inline.
@@ -64,11 +64,11 @@ Working memory holds approximately 7 items and degrades rapidly within seconds.
 
 For any proposed design element, apply in order:
 
-1. **Body test** — Is this element reachable by a person with limited motor precision on a small screen?
-2. **Attention test** — Does this element earn its place by directly supporting the primary task?
-3. **Memory test** — Does this element surface context the user would otherwise need to remember?
+1. **Body test** - Is this element reachable by a person with limited motor precision on a small screen?
+2. **Attention test** - Does this element earn its place by directly supporting the primary task?
+3. **Memory test** - Does this element surface context the user would otherwise need to remember?
 
-If an element fails all three tests, it is purely decorative. Decorative elements are not forbidden — but they are not invariant-justified, and they are the first candidates for removal when performance or clarity is at risk.
+If an element fails all three tests, it is purely decorative. Decorative elements are not forbidden - but they are not invariant-justified, and they are the first candidates for removal when performance or clarity is at risk.
 
 ---
 
@@ -76,7 +76,7 @@ If an element fails all three tests, it is purely decorative. Decorative element
 
 When `design-discussant` runs the brief stage, it prepends this invariants question before the main interview:
 
-> "Before we discuss the design direction, let me confirm three constraints: (1) Are there any accessibility requirements for motor-impaired users? (2) Is the primary use case on mobile or desktop — or both? (3) Are there any multi-step flows where the user must carry context between screens?"
+> "Before we discuss the design direction, let me confirm three constraints: (1) Are there any accessibility requirements for motor-impaired users? (2) Is the primary use case on mobile or desktop - or both? (3) Are there any multi-step flows where the user must carry context between screens?"
 
 Answers are recorded as D-XX decisions prefixed `[Invariant]` in STATE.md.
 
@@ -84,6 +84,6 @@ Answers are recorded as D-XX decisions prefixed `[Invariant]` in STATE.md.
 
 ## Relationship to Other References
 
-- `reference/heuristics.md` — H-01 through H-10 are the behavioral-level expression of Invariants 2 and 3
-- `reference/emotional-design.md` — Invariant 1 (Body) maps to the Visceral level; Invariants 2–3 map to the Behavioral level
-- `reference/component-authoring.md` — P-01 through P-06 are the component-level expression of all three invariants
+- `reference/heuristics.md` - H-01 through H-10 are the behavioral-level expression of Invariants 2 and 3
+- `reference/emotional-design.md` - Invariant 1 (Body) maps to the Visceral level; Invariants 2–3 map to the Behavioral level
+- `reference/component-authoring.md` - P-01 through P-06 are the component-level expression of all three invariants