@hegemonart/get-design-done 1.34.1 → 1.34.2

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Get Design Done — 5-stage agent-orchestrated design pipeline with 9 connections, handoff-first workflow, bidirectional Figma write-back, 22+ specialized agents, queryable knowledge layer (intel store, dependency analysis, learnings extraction), and a self-improvement loop (reflector, frontmatter + budget feedback, global-skills layer). v1.20.0 ships the SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream, and resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) for rate-limit + 429 + context-overflow recovery. Full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.34.1"
+    "version": "1.34.2"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
       "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), Claude Design handoff, bidirectional Figma write-back, and a queryable intel store (.design/intel/) for dependency and learnings queries. Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation. Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
-      "version": "1.34.1",
+      "version": "1.34.2",
       "author": {
         "name": "hegemonart"
       },
@@ -74,7 +74,8 @@
         "design-system-sync",
         "swift",
         "compose",
-        "flutter"
+        "flutter",
+        "email"
       ]
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.34.1",
+  "version": "1.34.2",
   "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain. v1.27.7 ships gdd-mcp (Phase 27.7): 12 read-only MCP tools for sub-3s priming. v1.28.0 (Phase 28): Foundational References Tier 2 — 5 new reference files (color-theory, composition, proportion-systems, i18n, contrast-advanced), 2 verifier i18n probes + 1 explore i18n-readiness probe, 12 additive cross-link insertions across 10 existing references, 2 orthogonal audit-scoring lens-tags (composition_alignment + i18n_readiness).",
   "author": {
     "name": "hegemonart",
@@ -68,7 +68,8 @@
     "design-system-sync",
     "swift",
     "compose",
-    "flutter"
+    "flutter",
+    "email"
   ],
   "skills": [
     "./skills/"

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.34.2] - 2026-05-31
+
+### Phase 34.2 — Non-Web Output Layer: Email
+
+Second sub-phase of the split Phase 34 (Non-Web Output Layer). Adds **email-template output** — a dedicated executor that generates email honoring the real client constraints (table-based layout, inline styles, MSO conditional comments for Outlook's Word engine, dark-mode `color-scheme` handling, and the top-20-client quirks) that modern web HTML/CSS breaks on — behind the same project-type detector that routes native (34.1). Email generation is **opt-in via project-type detection — web remains the default**. A decimal release on the v1.34.x arc (CHANGELOG-only, D-01); **no new runtime dependency** — the executor generates the email as an agent-prompt and the plugin checks it with a deterministic static validator, no `mjml` runtime (D-02/D-10). Native (Phase 34.1) shipped; Print/PDF (Phase 34.3) is the next sub-phase, out of 34.2 (D-07). 4 plans across Waves A–C.
+
+### Added
+
+- **Email-constraint catalogue + static validator (no `mjml` dependency, D-02/D-03).** `reference/email-design.md` — the authoritative email-constraint catalogue (~30 catalogued constraints: table-based layout, inline styles, MSO conditional comments, dark-mode `color-scheme`, ~600px width, image/alt rules, and the top-20-client quirks), registered in `reference/registry.json`. `scripts/lib/email/validate-email-html.cjs` — a pure, deterministic static checker (zero `require`, no fs/network/mjml) that flags the statically-verifiable subset: `EM-LAYOUT-01` (no flexbox/grid/`position`), `EM-STYLE-01` (no `<style>` as the primary styling mechanism; a small `@media`-only block is tolerated), `EM-MSO-01` (an MSO conditional comment in a full email), `EM-DARK-01` (a `color-scheme` signal present) — returning `{ ok, violations:[{ rule, detail }] }`.
+- **`email-executor` agent (MJML canonical + derived HTML, D-02/D-04).** `agents/email-executor.md` — generates **one email template per task**: an MJML source (the canonical artifact) plus the equivalent derived HTML, generated against the `reference/email-design.md` catalogue and run through the static validator as its own self-check. It is an agent-prompt (like `design-executor`/`flutter-executor`), **not** a compiler — no running `mjml`, no Litmus account, no network is required to produce the email. Carries a `## Record` section from the start (the record-contract lesson) and an honest `size_budget`.
+- **`litmus` connection (optional render-test, degrade-to-static-validator, D-03).** `connections/litmus.md` — cross-client rendered screenshots (Email-on-Acid is the documented alternative) for the verify stage when present, mirroring `connections/chromatic.md`. **Never hard-required**: when absent the verify stage degrades to the static email-HTML validator / code-only structural audit. Added to the `connections/connections.md` index + Capability Matrix in this closeout.
+- **`design-context-builder` `email` project-type route + `design-verifier` email-verify branch (delegated, D-06/D-09).** The context-builder appends the `email` enum + the `email-executor` route at the 34.1 seam (the seam is left open for 34.3/print). The verifier gains an email-verify branch by **delegation** to `reference/email-design.md` (the verifier stayed within its ≤700-line budget).
+- **Regression baseline.** `test/fixtures/baselines/phase-34-2/` freezes the email surface — a valid email fixture (`email-good.html`), a validator golden (`validator-golden.json`, the recorded `validateEmailHtml` output for a passing + a failing fixture, proving the rule-output shape is frozen), and `manifests-version.txt`=1.34.2 — pinned by `test/suite/phase-34-2-baseline.test.cjs` so a future change cannot silently break the validator or its verdict shape.
+
+### Notes
+
+- All Phase 34.2 tests are hermetic (D-10): the static email-HTML validator is a pure string→verdict function (fixture HTML → constraint checks, no network/mjml), the email-executor is validated **structurally** (frontmatter + catalogue reference + validator reference + presence), and the default `npm test` invokes **no** Litmus/Email-on-Acid and pulls in **no** `mjml` runtime. Rendered cross-client verification is the opt-in degraded-mode path (D-03).
+- The 31.5 tarball golden (`test/fixtures/baselines/phase-31-5/tarball-manifest.txt`) was regenerated as a reviewed delta: **+2** newly-shipped files (`agents/email-executor.md`, `connections/litmus.md`), zero removals (641 paths). The other two new email files (`reference/email-design.md`, `scripts/lib/email/validate-email-html.cjs`) were already in the golden from their Wave-A (34.2-01) commit — so the four new shipped files net to a +2 line-delta on the golden.
+- 6-manifest lockstep at **v1.34.2** (`package.json` + `package-lock.json` (root + `packages.""`) + `.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json` (metadata.version + plugins[0].version) + `.cursor-plugin/plugin.json` + `.codex-plugin/plugin.json`); marketplace `plugins[0].keywords` + plugin keywords gain `email`. Version-sync hygiene done upfront (D-08): `OFF_CADENCE_VERSIONS.add('1.34.2')` + the 16 live-pinned `manifests-version.txt` baselines forward-propagated 1.34.1 → 1.34.2 (phase-34-1, the prior closeout's own baseline, joined the set).
+
+---
+
 ## [1.34.1] - 2026-05-31
 
 ### Phase 34.1 — Non-Web Output Layer: Native Mobile

package/README.md

@@ -114,6 +114,14 @@ GDD now generates **native mobile** UI, not just web. A project-type detector ro
 
 All three are fed by a shared **token-bridge** ([`reference/native-platforms.md`](reference/native-platforms.md)) that extends the Phase-23 token engine with `swift`/`compose`/`flutter` emitters — mapping your canonical tokens (`#3B82F6`, `16px`, `Inter`) deterministically onto each platform's theme primitives (`Color`/`Font`, `MaterialTheme`, `ThemeData`) with a documented, round-trippable precision contract, so the executors never hand-author colour or dimension math. Rendered verification via the iOS Simulator / Android emulator is **optional** — when no simulator is present the verify stage degrades to a code-only structural audit (the simulator only *adds* rendered confirmation).
 
+### Email output (v1.34.2)
+
+GDD also generates **email templates** — the project-type detector routes an `email` brief to a dedicated executor that honors the real client constraints web HTML/CSS breaks on:
+
+- **[`email-executor`](agents/email-executor.md)** — generates one email per task as **MJML source (canonical) + the derived HTML**, against the constraint catalogue, with the static validator as its own self-check. It is an agent-prompt, not a compiler — **no `mjml` runtime, no Litmus account, no network** is needed to produce the email.
+
+The constraints live in [`reference/email-design.md`](reference/email-design.md) — table-based layout (no flexbox/grid/`position`), inline styles (no `<style>` sheet in Gmail), MSO conditional comments for Outlook's Word engine, dark-mode `color-scheme` handling, ~600px width, and the top-20-client quirks. A deterministic static checker ([`scripts/lib/email/validate-email-html.cjs`](scripts/lib/email/validate-email-html.cjs)) flags the statically-verifiable subset (`EM-LAYOUT`/`EM-STYLE`/`EM-MSO`/`EM-DARK`). Cross-client rendered verification via [`Litmus`](connections/litmus.md) (or Email-on-Acid) is **optional** — when absent the verify stage degrades to the static validator. Email generation is opt-in; **web stays the default**.
+
 ### Previous releases
 
 - **v1.26.0** — Headless Model Resolver (per-runtime tier→model map, `resolved_models` router field, per-runtime price tables, `reasoning-class` runtime-neutral alias).

package/agents/design-context-builder.md

@@ -218,18 +218,19 @@ Proceed to Step 0E regardless of whether Step 0D ran or was skipped.
 
 Detect the **project type** so the pipeline routes the brief to the correct executor. Reuse the Step 0C / Step 1 grep/glob idiom (file reads only, < 1 second, no skip condition).
 
-**Enum (4 values — D-06):** `web` (DEFAULT) · `native-ios` · `native-android` · `flutter`.
+**Enum (5 values — D-06):** `web` (DEFAULT) · `native-ios` · `native-android` · `flutter` · `email`.
 
-**Detection signals + precedence** (first match wins; brief overrides — if the user explicitly says "iOS app" / "Android app" / "Flutter app", honor that):
+**Detection signals + precedence** (first match wins; brief overrides — if the user explicitly says "iOS app" / "Android app" / "Flutter app" / "email" / "newsletter" / "email template", honor that):
 
 ```bash
 ls pubspec.yaml 2>/dev/null                       # → flutter
 ls *.xcodeproj Package.swift 2>/dev/null          # → native-ios   (when no pubspec)
 ls build.gradle build.gradle.kts settings.gradle 2>/dev/null  # → native-android (when no pubspec)
+ls **/*.mjml email/ emails/ templates/email 2>/dev/null  # → email (email-template signals)
 ls package.json 2>/dev/null                       # → web          (default; also the fallback when none match)
 ```
 
-Precedence: `pubspec.yaml` (flutter) > `*.xcodeproj`/`Package.swift` (native-ios) > `build.gradle*`/`settings.gradle` (native-android) > `package.json` / none (web — DEFAULT).
+Precedence: an explicit brief override (the user says "email" / "newsletter" / "email template") wins like the other brief-overrides; otherwise `pubspec.yaml` (flutter) > `*.xcodeproj`/`Package.swift` (native-ios) > `build.gradle*`/`settings.gradle` (native-android) > `.mjml` files / an `email/` templates directory (email) > `package.json` / none (web — DEFAULT).
 
 **Routing table** (project type → executor — one row per type, trivially appendable):
 
@@ -239,10 +240,11 @@ Precedence: `pubspec.yaml` (flutter) > `*.xcodeproj`/`Package.swift` (native-ios
 | native-ios       | swift-executor    |
 | native-android   | compose-executor  |
 | flutter          | flutter-executor  |
+| email            | email-executor    |
 
-<!-- 34.2 (email) / 34.3 (print) append their project type + executor row here — this enum and routing table are intentionally OPEN and extensible; 34.1 adds the native types ONLY (D-06). Do NOT add email/print rows in 34.1. -->
+<!-- 34.2 added `email` (above) → email-executor; 34.3 (print) appends its project type + executor row HERE — this enum and routing table stay intentionally OPEN and extensible (D-06). 34.2 adds email ONLY; do NOT add a print row until 34.3. -->
 
-Record the detected type in DESIGN-CONTEXT.md as a `<project_type>` line (e.g. `<project_type>native-ios</project_type>`) so downstream stages route correctly. The native specifics (token→theme bridge) live in `reference/native-platforms.md` — do not inline them here.
+Record the detected type in DESIGN-CONTEXT.md as a `<project_type>` line (e.g. `<project_type>native-ios</project_type>`) so downstream stages route correctly. The native specifics (token→theme bridge) live in `reference/native-platforms.md`; the email specifics (table layout, inline styles, MSO/dark-mode constraints) live in `reference/email-design.md` — do not inline either here.
 
 Proceed to Step 1 regardless of outcome.
 

package/agents/design-verifier.md

@@ -359,9 +359,16 @@ In DESIGN-VERIFICATION.md, add a `## Phase 4B — Screenshot Evidence` section l
 When `<project_type>` in DESIGN-CONTEXT.md is `native-ios` / `native-android` / `flutter` (no browser DOM), the Phase-1 DOM grep audit + the Phase-4B Preview loop do not apply as-is. Run instead:
 
 - **Snapshot audit** — IF a simulator/emulator screenshot is supplied (via `connections/xcode-simulator.md`, `connections/android-emulator.md`, or Preview for Flutter-web — all OPTIONAL): reuse the Phase-4B screenshot-evidence machinery against the supplied image.
-- **Code-only structural audit** (DEFAULT — no screenshot/simulator): verify the generated native source structurally — expected SwiftUI views / Compose composables / Flutter widgets present + token-bridge usage — instead of rendered pixels. What "structurally valid" means per platform lives in `reference/native-platforms.md` (do not inline it).
+- **Code-only structural audit** (DEFAULT — no screenshot/simulator): verify the generated native source structurally — expected SwiftUI views / Compose composables / Flutter widgets present + token-bridge usage — instead of rendered pixels. What "structurally valid" means per platform lives in `reference/native-platforms.md` (do not inline it). Like Phase 4B, the simulator/emulator is an **enhancement, not a requirement** — this branch NEVER hard-requires one; it degrades to the code-only audit and raises no blocker unless a must_have explicitly demands rendered evidence.
 
-Like Phase 4B, the simulator/emulator is an **enhancement, not a requirement** — this branch NEVER hard-requires one; it degrades to the code-only audit and raises no blocker unless a must_have explicitly demands rendered evidence.
+---
+
+## Phase 4E — Email Verify (project_type: email)
+
+When `<project_type>` is `email` (no browser DOM — the Phase-1 DOM grep + Phase-4B Preview loop do not apply), run an email-constraint audit BY DELEGATION (the ~30 constraints live in `reference/email-design.md` — the authority; do NOT inline them):
+
+- **Static constraint audit** (DEFAULT) — run `scripts/lib/email/validate-email-html.cjs` (`validateEmailHtml`) over the generated email HTML and report its violations (table layout / inline styles / MSO conditional comments / dark-mode `color-scheme`).
+- **Rendered enhancement** (OPTIONAL) — IF the Litmus connection (`connections/litmus.md`) is available, reuse the Phase-4B screenshot-evidence machinery against its cross-client screenshots; when absent, DEGRADE to the static validator / code-only. Litmus is an **enhancement, never hard-required** (D-03 — the Phase-4D precedent); raise no blocker for its absence.
 
 ---
 

package/agents/email-executor.md

@@ -0,0 +1,148 @@
+---
+name: email-executor
+description: Executes one plan task by generating an email template — MJML source (canonical) + the derived HTML — honoring reference/email-design.md constraints, validated by the static email-HTML checker. Single-shot; mirrors design-executor.
+tools: Read, Write, Edit, Bash, Grep, Glob
+color: magenta
+default-tier: sonnet
+tier-rationale: "Follows an Opus-authored plan; executes email codegen rather than plans it"
+size_budget: M
+size_budget_rationale: "Honest tier sized to the actual ~148-line body (M cap 300), NOT inflated to the design-family XXL default. Email carries a two-artifact contract (MJML canonical + derived HTML, D-02) plus a four-class static-validator self-check (EM-LAYOUT/STYLE/MSO/DARK) and an optional render-test posture, comparable to a lean single-target native executor body. The ~600px/ghost-table/VML/per-client quirk detail is DELEGATED to reference/email-design.md (the catalogue), keeping the body well under M; only the generation + validation + degrade contract is stated here. Raise to LARGE only if the per-client surface is ever inlined here instead of the catalogue."
+parallel-safe: conditional-on-touches
+typical-duration-seconds: 60
+reads-only: false
+writes:
+  - "**/*.mjml"
+  - "**/*.html"
+---
+
+@reference/shared-preamble.md
+
+# email-executor
+
+## Role
+
+You execute **exactly one task** from the plan: you generate **one email template** — an **MJML source** file (the canonical artifact) and the **equivalent derived HTML** — honoring the email-client constraints. Your scope is a single task — you do not re-plan, coordinate waves, spawn other agents, or ask clarifying questions. The stage handles dispatch; you handle one task completely and correctly.
+
+You are a single-shot agent: receive context, read the references, generate the MJML + HTML, write the file(s), run the static validator, commit, emit the completion marker, done.
+
+You are an **agent-prompt**, not a compiler (D-04): GDD generates the email when an LLM (you) invokes this prompt, consistent with `design-executor.md` / `flutter-executor.md`. You do **not** require a running `mjml` compiler, a Litmus account, or any network to produce the email — rendered cross-client verification is the verify stage's degraded-mode concern, never a precondition here (D-03/D-10).
+
+---
+
+## Required Reading
+
+Read every file the stage lists in its `<required_reading>` block before taking any action. At minimum:
+
+- `.design/STATE.md` — pipeline state (decisions, blockers, must-haves)
+- `.design/DESIGN-PLAN.md` — your task is identified by `task_id`
+- `.design/DESIGN-CONTEXT.md` — brand decisions, constraints, locked choices
+- **`reference/email-design.md`** — the **authoritative** email-constraint catalogue: table-based layout (no flexbox/grid/`position`), inline styles (no `<style>` sheet), MSO conditional comments for Outlook's Word engine, dark-mode `color-scheme`, ~600px max-width, image/alt rules, and the top-20-client quirks. This is how you pick the correct email idiom — you **generate against the catalogue**, you do **not** re-derive these rules (the `flutter-executor`→`reference/native-platforms.md` precedent).
+
+**Invariant:** read all listed files FIRST, before making any changes.
+
+---
+
+## MJML canonical + HTML derived (the D-02 two-artifact contract)
+
+Per **D-02** the executor emits **two artifacts**, and **you (the LLM) perform the MJML→HTML expansion as your contract** — there is **NO `mjml` build step / runtime dependency** (an opt-in real `mjml` compile is out of scope, like the simulator connections):
+
+| Artifact | Role | Notes |
+| --- | --- | --- |
+| **`*.mjml`** | **CANONICAL** — the source of truth | Semantic MJML the maintainer edits |
+| **`*.html`** | **DERIVED** — generated by you from the MJML | The shippable email; what the static validator checks |
+
+- Emit **both**: write the MJML source, then write the equivalent table-based HTML you expand from it (inline styles, ghost tables, MSO comments, color-scheme — per the catalogue).
+- State, in **each file's header comment** and in your output, **which file is canonical (MJML)** and **which is derived (HTML)**, mirroring Phase 31's two-stage source→derived framing.
+- Do **not** add `mjml` to `package.json` or shell out to an `mjml` binary — the expansion is your job.
+
+---
+
+## Token Consumption — the canonical token form
+
+Where the task themes the email (colors, spacing, type), consume the **canonical design tokens** (the css-vars token form) for those values rather than inventing ad-hoc hex/px — consistent with the design-family executors. Email cannot use CSS custom properties reliably across clients, so **resolve** the token values to literals **inline** at generation time (the token is the source; the email carries the resolved value). Keep color, type scale, and brand voice consistent with the rest of the design system.
+
+---
+
+## Self-check via the static validator (the deterministic gate)
+
+Before completing, **run the static email-HTML validator** on your **derived HTML**:
+
+```js
+const { validateEmailHtml } = require('scripts/lib/email/validate-email-html.cjs');
+const { ok, violations } = validateEmailHtml(htmlString);
+```
+
+`validateEmailHtml` (Phase 34.2-01) deterministically checks the four statically-verifiable constraint classes — **EM-LAYOUT-01** (no flexbox/grid/`position`), **EM-STYLE-01** (no `<style>` block as the primary styling mechanism), **EM-MSO-01** (an MSO conditional comment in a full email), **EM-DARK-01** (a `color-scheme` signal present). **Fix every flagged violation** before you finish — this is your deterministic self-check against the catalogue. The remaining catalogue rules (~600px width, ghost tables/VML, image width/height/alt, per-client quirks) are render-tested guidance, not statically asserted — honor them from the catalogue.
+
+---
+
+## Optional Litmus render-test (degraded / not a precondition)
+
+Code generation needs **no** render service (D-04/D-10). Cross-client **rendered** verification is the **verify stage's** degraded-mode concern (D-03): point it at the `connections/litmus.md` render-test connection **as an enhancement**, **never** a precondition.
+
+- When **Litmus** (or **Email-on-Acid**, the documented alternative) is available → the verify stage captures cross-client screenshots.
+- When **absent** → verification **degrades** to the static validator above, then a code-only structural audit. Never hard-require Litmus.
+
+Email ships its render-test connection at `connections/litmus.md`; you only **name** it — you never run it to generate.
+
+---
+
+## Execution Principles
+
+1. **Honor DESIGN-CONTEXT.md decisions as locked.** `D-XX:` decisions are non-negotiable.
+2. **`reference/email-design.md` is authoritative** for the email constraints. Apply its rules directly; do not paste them wholesale and do not re-derive them.
+3. **Observable outcomes only.** Acceptance criteria describe observable states ("the HTML uses `role="presentation"` tables", "an MSO conditional comment is present", "validateEmailHtml returns `ok: true`").
+4. **Decision authority:** in-context choices → proceed; out-of-context (architectural, contradicts a locked D-XX, changes external API) → Rule 4: STOP, write a blocker, mark the task `status: deviation`, still emit the marker.
+5. **Single-task scope.** Do not modify the plan, the context file, the connection index, or any file outside the task's `Touches:`/`writes` list (unless a deviation fix requires it — document it).
+
+---
+
+## Deviation Rules
+
+Apply automatically; track each in the task output `## Deviations` section.
+
+- **Rule 1 — Bug:** broken HTML/MJML, a flagged `validateEmailHtml` violation, wrong token resolution in files you author → fix inline.
+- **Rule 2 — Missing Critical:** missing MSO comment, missing `color-scheme` signal, a flexbox/grid/`position` style, a missing `alt`/`width`/`height` on an `<img>` → add it (the catalogue requires it).
+- **Rule 3 — Blocking:** a referenced file/import missing, the validator not resolvable → fix (resolve import, create stub) and note it.
+- **Rule 4 — Architectural:** switching the email framework, restructuring the template system, a schema-level change, or anything contradicting a locked D-XX → STOP, write a `<blocker>`, mark `status: deviation`, still emit the marker.
+
+**Scope boundary:** only fix issues directly caused by this task's changes. **Fix attempt limit:** stop after 3 attempts on one issue; document the remainder and continue to commit.
+
+---
+
+## Output
+
+Emit the **MJML source** + the **derived HTML** to the path(s) the task declares. In your final response, state: the file(s) written, **which is canonical (MJML)** and **which is derived (HTML)**, how tokens were resolved, and the `validateEmailHtml` result (`ok: true` / the violations you fixed). Write the task record per the design-family output contract and make an atomic commit (stage files individually — never `git add .`/`-A`; never run `git clean`).
+
+Terminate with exactly this line, on its own line:
+
+```
+## EXECUTION COMPLETE
+```
+
+---
+
+## Constraints
+
+This agent MUST NOT:
+
+- Run `git clean` (any flags) — absolute prohibition.
+- Require a running `mjml` compiler, a Litmus/Email-on-Acid account, or any network to generate the email (D-04/D-10).
+- Add a `mjml` dependency to `package.json` or shell out to an `mjml` binary — the MJML→HTML expansion is the agent's contract (D-02).
+- Re-derive the email constraints — consume `reference/email-design.md` (the catalogue).
+- Emit only HTML or only MJML — both artifacts are the contract (MJML canonical, HTML derived).
+- Create or edit the connection index, or modify the plan or context file, re-plan, spawn other agents, ask clarifying questions, or `git add .`/`-A`.
+
+---
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"email-executor","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<which email template (MJML+HTML) was generated + the validateEmailHtml result>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`.
+
+## EXECUTION COMPLETE

package/connections/connections.md

@@ -26,6 +26,7 @@ This directory contains connection specifications for external tools and MCPs th
 | OpenRouter | Active | [`connections/openrouter.md`](connections/openrouter.md) | Model-router (no MCP); env: `OPENROUTER_API_KEY` (optional `OPENROUTER_BASE_URL`); opt-in tier-resolution overlay, graceful-degrade-to-native |
 | Xcode Simulator | Active | [`connections/xcode-simulator.md`](connections/xcode-simulator.md) | **Optional** (macOS-only); CLI: `simctl` (no MCP); native-iOS rendered evidence for verify; degrade-to-code-only when absent (D-03) |
 | Android Emulator | Active | [`connections/android-emulator.md`](connections/android-emulator.md) | **Optional**; CLI: `adb` / `emulator` (no MCP); native-Android rendered evidence for verify; degrade-to-code-only when absent (D-03) |
+| Litmus | Active | [`connections/litmus.md`](connections/litmus.md) | **Optional** render-test (email; Email-on-Acid alternative); cross-client rendered screenshots for verify; degrade-to-static-validator / code-only when absent (D-03) |
 
 ---
 
@@ -51,6 +52,7 @@ Each cell describes what the connection contributes at that pipeline stage, or `
 | OpenRouter | — | — | — | — | — | — | ✓ (model-router: tier→model resolution, all stages) |
 | Xcode Simulator | — | — | — | native iOS code-gen target (swift-executor / emitSwift) | rendered SwiftUI snapshot when simulator available, else degrade to code-only structural audit (D-03) | — | — |
 | Android Emulator | — | — | — | native Android code-gen target (compose-executor / emitCompose) | rendered Compose screenshot when emulator available, else degrade to code-only structural audit (D-03) | — | — |
+| Litmus | — | — | — | email render-test target (email-executor) | cross-client rendered evidence when Litmus available, else degrade to the static email-HTML validator / code-only (D-03) | — | — |
 
 **Column definitions:**
 

package/connections/litmus.md

@@ -0,0 +1,134 @@
+# Litmus — Connection Specification
+
+This file is the connection specification for Litmus within the get-design-done pipeline. It lives in `connections/` alongside other connection specs. See the connection index for the full connection capability matrix (the litmus row is added at the 34.2 closeout).
+
+---
+
+Litmus is the **verify stage's cross-client email render-test** for the `email` project type. It renders an email's HTML across the **top-20 email clients** (Outlook's Word engine, the various Gmail modes, Apple Mail, Yahoo/AOL, Proton, etc.) and returns per-client screenshots. Its pipeline role: after the `email-executor` generates an email (MJML source + derived HTML), the verify stage uses Litmus — **when available** — to surface per-client rendering breakage that the static validator cannot see, and narrates the result in plain English.
+
+**Key relationship to the static validator:** Litmus is the *rendered* complement to the *static* checker `scripts/lib/email/validate-email-html.cjs`. The static validator deterministically checks constraint **classes** (table layout, inline styles, MSO comments, color-scheme — `EM-LAYOUT/STYLE/MSO/DARK`); Litmus checks **rendered pixels** across real clients. Litmus is **optional** — its absence is a quality reduction, not a blocking error (D-03).
+
+---
+
+## Setup
+
+**Prerequisites:**
+
+- A Litmus account at [litmus.com](https://www.litmus.com) — paid (a trial is available)
+- API access enabled on the account (the Litmus Email Previews / Instant API), or the Litmus CLI
+
+**Account and token:**
+
+1. Create a Litmus account and enable API access in the account settings
+2. Copy the API key / token from the account's API settings page
+3. Set the environment variable — **NEVER commit the token to git or to a tracked `.env` file:**
+
+```bash
+export LITMUS_API_KEY=<your-token>
+```
+
+Add this to your shell profile or CI environment secrets. `LITMUS_API_KEY` grants access to your Litmus account (create previews, consume render quota) — treat it like a password: never commit it (not in source files, not in `.env`, not in configuration files), never log it in CI output, and rotate it if it is exposed.
+
+**Verification:**
+
+```bash
+test -n "${LITMUS_API_KEY}" && echo "litmus token present" || echo "litmus token absent"
+```
+
+---
+
+## Why Litmus is useful
+
+Email rendering breakage is invisible to both code review and the static validator. An email's HTML can pass every static class-check (`validateEmailHtml` returns `ok: true`) and still render broken in a specific client: Outlook's Word engine collapses a layout that lacked a ghost table, Outlook.com inverts colors in dark mode and produces unreadable low-contrast text, the strict Gmail IMAP mode strips a `<style>` block the static heuristic tolerated, a retina image overflows on a mobile client.
+
+The static validator checks constraint **classes**; it cannot render. Litmus renders the **actual** email across real clients and returns a screenshot per client, so per-client breakage surfaces as a visible image rather than a user report weeks later.
+
+---
+
+## When to use Litmus
+
+**Verify stage:** After the `email-executor` generates the email, run Litmus — when available — to capture cross-client screenshots and check for per-client rendering breakage. The verify stage narrates the per-client delta and notes it in `DESIGN-VERIFICATION.md`.
+
+Litmus is **not** used at generation time. The `email-executor` needs no Litmus account, no network, and no render service to produce the MJML + HTML — generation is gated by the static validator only (D-04/D-10).
+
+---
+
+## CLI / API Commands (Bash, not MCP tools)
+
+Litmus is consumed via its HTTP API (or the Litmus CLI), not an MCP. All interactions are via Bash.
+
+| Interaction | Auth | Returns | Pipeline use |
+|---|---|---|---|
+| Create an Email Preview (POST the HTML) | `LITMUS_API_KEY` | A preview id + per-client screenshot URLs | verify: cross-client render evidence |
+| Poll the preview's client results | `LITMUS_API_KEY` | Per-client screenshot status (ready / processing) | verify: delta narration |
+
+Write the rendered results to `.design/litmus-results.json` for the verify stage to narrate, mirroring the chromatic-results.json pattern. Exact endpoint shapes are documented at the Litmus API reference; this connection only requires the token-present probe + the degrade contract below.
+
+---
+
+## Availability Probe
+
+Litmus is consumed via API/CLI — the probe is Bash-based, not ToolSearch-based.
+
+**Step L1 — CLI/API presence:**
+
+```bash
+command -v litmus 2>/dev/null || test -n "${LITMUS_API_KEY}"
+```
+
+- A Litmus CLI is found, OR an API key is present → proceed to Step L2
+- Neither → `litmus: not_configured` (skip all Litmus steps)
+
+**Step L2 — Token check:**
+
+```bash
+test -n "${LITMUS_API_KEY}"
+```
+
+- Non-empty → `litmus: available`
+- Empty → `litmus: unavailable` (no API key to authenticate render requests)
+
+**Write litmus status to `.design/STATE.md` `<connections>` after probing.**
+
+---
+
+## Fallback Behavior
+
+**verify stage:**
+
+- `litmus: unavailable` → skip cross-client render-testing; **degrade** to the static validator `scripts/lib/email/validate-email-html.cjs` (the `EM-LAYOUT/STYLE/MSO/DARK` class-checks), then a **code-only** structural audit of the HTML; note in `DESIGN-VERIFICATION.md`: "Cross-client render-test skipped — LITMUS_API_KEY not set; verified via the static email-HTML validator + a code-only structural audit."
+- `litmus: not_configured` → same as unavailable; note: "Cross-client render-test skipped — Litmus not configured; verified via the static validator + a code-only audit. (Alternative: Email-on-Acid.)"
+
+**Graceful degradation required:** the pipeline must continue when Litmus is unavailable. Missing cross-client render data is a **quality reduction, not a blocking error** (D-03 — the email render-test is an enhancement, never hard-required, mirroring the 34.1 simulator connections). The static validator is always available and is the deterministic floor; Litmus is the rendered ceiling on top of it.
+
+---
+
+## STATE.md Integration
+
+Every stage that probes Litmus writes the result to `.design/STATE.md` under the `<connections>` section:
+
+```xml
+<connections>
+figma: available
+litmus: unavailable
+</connections>
+```
+
+**Status values:**
+
+| Value | Meaning |
+|---|---|
+| `available` | CLI/API reachable AND `LITMUS_API_KEY` is set |
+| `unavailable` | CLI/API present but `LITMUS_API_KEY` is empty |
+| `not_configured` | No Litmus CLI and no API key — Litmus not set up |
+
+---
+
+## Alternative render-test services
+
+Litmus is **not** the only cross-client render-test. If you prefer a different provider, the connection's contract (probe → available/unavailable/not_configured; degrade to the static validator when absent) is identical — only the token name and endpoint change:
+
+- **Email on Acid** — the documented primary alternative; comparable cross-client previews and an API. Swap `LITMUS_API_KEY` for the Email-on-Acid API key and keep the same degrade behavior.
+- **Putsmail** / **Mailtrap** — lighter options for sending an email to your own inboxes for manual spot-checks (not full cross-client screenshot matrices, but useful when no render-test account exists).
+
+In every case the **static validator remains the deterministic floor**; the render-test service is the optional rendered enhancement that degrades gracefully when absent.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.34.1",
+  "version": "1.34.2",
   "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",

package/reference/email-design.md

@@ -0,0 +1,219 @@
+# 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
+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
+(34.2-03) audits against; neither re-derives these rules. The deterministic subset of
+this catalogue is checked by [`scripts/lib/email/validate-email-html.cjs`](../scripts/lib/email/validate-email-html.cjs),
+whose emitted `rule` ids are the constraint-ids defined below (the spec is the authority).
+
+It is the sibling of [`reference/platforms.md`](./platforms.md). The 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 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**
+email verify is this catalogue's *static* validator plus an *optional* Litmus /
+Email-on-Acid render-test connection that degrades to the static validator when absent.
+Per **D-10** the static checks are deterministic (same HTML string → same result), with
+no network and no `mjml`, so the default `npm test` stays green on any machine.
+
+Each constraint carries a **rule-id** (`EM-<CLASS>-NN`). Section 8 marks exactly which
+ids the static validator asserts versus which are render-tested guidance only.
+
+---
+
+## 1. Purpose
+
+Phase 19 shipped platform *references*; Phase 23 shipped the token engine; Phase 34.1
+added native generators. Email is the remaining untouched product surface, and its
+constraints are unlike both web and native: a fifteen-year-old rendering engine
+(Outlook/Word), aggressive `<head>` stripping (Gmail), and a long tail of per-client
+quirks. Instead of each email being authored from memory, the constraints live once
+here (the catalogue) and once in the validator (the statically-checkable subset), and
+the executor + verifier consume them. This file is the single SC#9-email authority.
+
+The catalogue is **prose + tables**, not an implementation. Illustrative snippets are
+kept to 2–3 lines. The implementation is `validate-email-html.cjs`.
+
+---
+
+## 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
+dropped or mis-rendered by Outlook (Word engine), older Gmail, and many mobile clients,
+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-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). |
+
+```html
+<table role="presentation" width="600" cellpadding="0" cellspacing="0" border="0"
+       style="max-width:600px;margin:0 auto;"><tr><td>…</td></tr></table>
+```
+
+---
+
+## 3. Styling — inline, not a `<style>` block
+
+Visual styling lives in **inline `style="…"` attributes** on each element, NOT in a
+`<head><style>` sheet. Gmail (and several webmail clients) strip or heavily limit
+`<head>` styles, so any rule that *must* apply is inlined. A `<style>` block is
+**tolerated only** for progressive enhancement that degrades gracefully — chiefly
+`@media` queries for responsive/dark-mode — never as the primary styling mechanism.
+
+| Rule-id | Constraint |
+| --- | --- |
+| **EM-STYLE-01** | Core/visual styling is inline. A `<style>` block used as the PRIMARY styling mechanism (non-`@media` rules, or a large sheet) is forbidden because Gmail strips it. *(Statically checkable: a non-trivial `<style>` block carrying non-`@media` rules is flagged; a small `@media`-only block is tolerated.)* |
+| EM-STYLE-02 | Avoid CSS shorthand that clients mangle (`background` shorthand, unitless line-heights in some clients); prefer longhand (`background-color`). |
+| EM-STYLE-03 | No external stylesheets (`<link rel="stylesheet">`) and no `@import` — clients strip them. |
+| EM-STYLE-04 | A small `@media`-only `<style>` for responsive breakpoints / dark-mode is the one accepted `<style>` use; it must enhance, not be required for, a readable layout. |
+
+---
+
+## 4. Outlook / MSO conditional comments
+
+Outlook on Windows renders with Microsoft Word's HTML engine. It needs **MSO
+conditional comments** to apply Outlook-specific fallbacks (ghost tables for centering
+and width, VML for background images and bulletproof buttons) and to hide modern markup
+it would mangle.
+
+| Rule-id | Constraint |
+| --- | --- |
+| **EM-MSO-01** | A full email document MUST include at least one MSO conditional comment — `<!--[if mso]> … <![endif]-->` and/or `<!--[if !mso]><!--> … <!--<![endif]-->`. *(Statically checkable: absence in a full-email document is flagged.)* |
+| EM-MSO-02 | Use `<!--[if mso]>` **ghost tables** to give Outlook an explicit fixed width and centering that it would otherwise drop from CSS `max-width`/`margin:auto`. |
+| EM-MSO-03 | Use **VML** (`<v:roundrect>`, `<v:fill>`) inside `<!--[if mso]>` for rounded "bulletproof" buttons and background images, since Outlook ignores `border-radius` and CSS `background-image`. |
+| EM-MSO-04 | Add the MSO DPI/namespace head fixes (`o:OfficeDocumentSettings`, `xmlns:v`/`xmlns:o`, `mso-line-height-rule:exactly`) to stabilize spacing and image scaling. |
+
+```html
+<!--[if mso]><table role="presentation" width="600"><tr><td><![endif]-->
+  <!-- modern markup here -->
+<!--[if mso]></td></tr></table><![endif]-->
+```
+
+---
+
+## 5. Dark mode
+
+Clients invert or remap colors in dark mode inconsistently (Outlook.com fully inverts;
+Apple Mail and Gmail partially; some not at all). Declare a **`color-scheme`** signal so
+clients keep the intended palette, and use `prefers-color-scheme` for explicit dark
+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-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. |
+
+---
+
+## 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
+asserted; see §8.)*
+
+| Rule-id | Constraint |
+| --- | --- |
+| EM-IMG-01 | Every `<img>` carries explicit `width` and `height` attributes (Outlook needs them; prevents reflow when images load). |
+| EM-IMG-02 | Every `<img>` carries meaningful `alt` text (shown when images are blocked) and `display:block` to avoid the baseline gap below images. |
+| EM-IMG-03 | Serve retina images at 2× and constrain with `width`/`height` so they render crisp without breaking the layout. |
+| EM-IMG-04 | Buttons are **bulletproof** (table/`<a>` with padding + VML fallback for Outlook), never an image-only CTA that vanishes when images are blocked. |
+| EM-A11Y-01 | Set the document `lang`, a real `<title>`, and a logical heading/reading order; ensure WCAG-AA text contrast that survives dark-mode inversion. |
+
+---
+
+## 7. Top-20 client quirks
+
+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-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-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-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. |
+| EM-CLIENT-11 | Yahoo Mail | Supports media queries; strips/rewrites some `class`/`id`; avoid unsupported pseudo-classes. |
+| EM-CLIENT-12 | AOL Mail | Shares Yahoo's engine; similar class/id handling. |
+| EM-CLIENT-13 | Samsung Mail (Android) | Webview-based; media-query support varies by version; test stacking. |
+| EM-CLIENT-14 | Android default / Gmail-for-non-Gmail | Inline-only safe mode; treat like the strict Gmail IMAP mode. |
+| EM-CLIENT-15 | Thunderbird | Gecko-based, capable; honors most CSS; test dark theme. |
+| EM-CLIENT-16 | Windows 10/11 Mail | EdgeHTML/Chromium-ish; generally capable; watch padding. |
+| EM-CLIENT-17 | Proton Mail | Sanitizes aggressively; strips remote content until approved; inline-safe. |
+| EM-CLIENT-18 | Fastmail | Standards-friendly; respects media queries and dark mode. |
+| EM-CLIENT-19 | Zoho Mail | Reasonable CSS support; test buttons + dark mode. |
+| EM-CLIENT-20 | GMX / Web.de | EU webmail; limited CSS; lean on inline styles + tables. |
+
+---
+
+## 8. Statically-checkable vs render-tested
+
+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 /
+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-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) |
+| EM-DARK-02..04 | `supported-color-schemes`, explicit bg+color, dark logos | No | Render test (dark mode) |
+| EM-IMG-01..04, EM-A11Y-01 | width/height, alt, display:block, bulletproof buttons, lang/contrast | No | Render test + a11y review |
+| EM-CLIENT-01..20 | Per-client headline quirks | No | Render test (cross-client screenshots) |
+
+Notes on the four statically-checked rules:
+
+- **EM-STYLE-01 heuristic (deterministic).** A `<style>…</style>` block is flagged as the
+  primary styling mechanism when, after removing `@media { … }` groups and `@font-face`
+  from the block, residual CSS rules remain **or** the block exceeds a generous size
+  threshold. A small dark-mode/responsive `@media`-only block (per EM-STYLE-04) is
+  therefore tolerated and does NOT trip the check.
+- **EM-DARK-01 is decoupled from `<style>`.** A `<meta name="color-scheme" content="…">`
+  in `<head>` satisfies EM-DARK-01 on its own, so a fully-inline email with only a
+  color-scheme meta (and no `<style>` at all) passes both EM-STYLE-01 and EM-DARK-01.
+- **EM-MSO-01 fires only on a full email.** A document is treated as a full email when it
+  has `<html>`/`<body>` or a layout `<table>`; a bare fragment is not flagged for a
+  missing MSO comment.
+
+---
+
+## 9. Cross-references
+
+- [`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 constraint-ids defined here.
+- [`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/registry.json

@@ -895,6 +895,13 @@
       "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."
+    },
+    {
+      "name": "email-design",
+      "path": "reference/email-design.md",
+      "type": "heuristic",
+      "phase": 34.2,
+      "description": "Phase 34.2 email-constraint catalogue — table-based layout (not flexbox/grid/position), inline styles (not a <style> block), MSO conditional comments for Outlook, dark-mode color-scheme/prefers-color-scheme handling, ~600px max-width, image/alt rules, and top-20-client quirks; the authority the email-executor generates against and the design-verifier email branch audits against, and the rule-id source for scripts/lib/email/validate-email-html.cjs."
     }
   ]
 }

package/scripts/lib/email/validate-email-html.cjs

@@ -0,0 +1,157 @@
+/**
+ * email/validate-email-html.cjs — static email-HTML constraint validator
+ * (Phase 34.2-01).
+ *
+ * Pure, deterministic regex/string analysis of an email-HTML STRING. Same
+ * input -> identical output. It checks the statically-verifiable SUBSET of the
+ * constraint catalogue in `reference/email-design.md` §8 — the spec is the
+ * authority; the `rule` ids emitted here are constraint-ids defined there.
+ *
+ * WHAT IS CHECKED (the four deterministic classes, emitted in a stable order):
+ *   EM-LAYOUT-01  no `display:flex` / `display:grid` / `position:absolute|fixed`
+ *                 (and `sticky`) in any style — modern box primitives email
+ *                 clients drop. (Presence is flagged; table layout is expected.)
+ *   EM-STYLE-01   no `<style>` block used as the PRIMARY styling mechanism. A
+ *                 `<style>` block is flagged when, after removing `@media { … }`
+ *                 groups, `@font-face`, `@import` and comments, residual CSS
+ *                 rules remain OR the block exceeds a generous size threshold.
+ *                 A small `@media`-only dark-mode/responsive block (EM-STYLE-04)
+ *                 is tolerated.
+ *   EM-MSO-01     a full-email document (has <html>/<body> or a layout <table>)
+ *                 contains at least one MSO conditional comment
+ *                 (`<!--[if mso]>` / `<!--[if !mso]>`). Absence is flagged.
+ *                 A bare fragment is NOT flagged.
+ *   EM-DARK-01    a color-scheme signal is present — a `<meta name="color-scheme">`
+ *                 and/or a CSS `color-scheme:` declaration and/or a
+ *                 `prefers-color-scheme` query. Total absence is flagged. A meta
+ *                 alone satisfies it (decoupled from any <style>).
+ *
+ * WHAT IS *NOT* CHECKED (catalogued in reference/email-design.md as render-tested
+ * guidance — verified by the optional Litmus / Email-on-Acid connection at
+ * 34.2-02, never by this validator): ~600px width, ghost tables/VML, bulletproof
+ * buttons, image width/height/alt, per-client (EM-CLIENT-01..20) pixel quirks.
+ *
+ * PURITY (D-02 / D-10): operates only on the passed string — no fs of the
+ * document, no network, no child-process spawn, no mjml runtime import, no Date,
+ * no process.env. This file has zero require() calls (node builtins included).
+ */
+
+'use strict';
+
+// Modern box primitives email clients drop (EM-LAYOUT-01). Whitespace-tolerant.
+const FLEX_RE = /display\s*:\s*flex\b/i;
+const GRID_RE = /display\s*:\s*grid\b/i;
+const POSITION_RE = /position\s*:\s*(?:absolute|fixed|sticky)\b/i;
+
+// <style>…</style> block capture (EM-STYLE-01).
+const STYLE_BLOCK_RE = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
+const AT_MEDIA_GROUP_RE = /@media[^{]*\{(?:[^{}]*\{[^{}]*\})*[^{}]*\}/gi;
+const AT_FONTFACE_GROUP_RE = /@font-face\s*\{[^{}]*\}/gi;
+const AT_IMPORT_RE = /@import[^;]*;/gi;
+const CSS_COMMENT_RE = /\/\*[\s\S]*?\*\//g;
+// A CSS rule = a selector followed by a `{ … }` declaration block.
+const CSS_RULE_RE = /[^{}@;]+\{[^{}]*\}/;
+// Generous size threshold: a <style> body this large is a primary sheet even if
+// it parsed as @media-only (deterministic guard against huge tolerated blocks).
+const STYLE_PRIMARY_CHAR_THRESHOLD = 1024;
+
+// MSO conditional comments (EM-MSO-01).
+const MSO_COMMENT_RE = /<!--\[if\s+(?:!\s*)?mso/i;
+// "Full email" signal — only then is a missing MSO comment flagged.
+const FULL_EMAIL_RE = /<html[\s>]|<body[\s>]|<table[\s>]/i;
+
+// color-scheme signals (EM-DARK-01) — any one satisfies the check.
+const META_COLOR_SCHEME_RE = /<meta\b[^>]*name\s*=\s*["']?\s*color-scheme\b/i;
+const CSS_COLOR_SCHEME_RE = /color-scheme\s*:/i;
+const PREFERS_COLOR_SCHEME_RE = /prefers-color-scheme/i;
+
+/**
+ * Decide whether a captured <style> block body is a PRIMARY styling mechanism.
+ * Tolerates an @media-only (responsive/dark) block per EM-STYLE-04.
+ *
+ * @param {string} body raw inner text of a <style>…</style>
+ * @returns {boolean} true when the block carries non-@media rules or is oversized
+ */
+function isPrimaryStyleBlock(body) {
+  if (body.length > STYLE_PRIMARY_CHAR_THRESHOLD) return true;
+  const residual = body
+    .replace(CSS_COMMENT_RE, '')
+    .replace(AT_MEDIA_GROUP_RE, '')
+    .replace(AT_FONTFACE_GROUP_RE, '')
+    .replace(AT_IMPORT_RE, '');
+  return CSS_RULE_RE.test(residual);
+}
+
+/**
+ * Validate an email-HTML string against the statically-checkable constraint
+ * subset of reference/email-design.md §8.
+ *
+ * @param {string} html the email HTML (the caller reads the file and passes the
+ *   content — this function never touches the filesystem)
+ * @param {{ checks?: string[] }} [opts] reserved for future toggles; default
+ *   runs all four classes
+ * @returns {{ ok: boolean, violations: Array<{ rule: string, detail: string }> }}
+ *   `ok === (violations.length === 0)`; each violation's `rule` is a catalogued
+ *   constraint-id and `detail` is a short human string.
+ */
+function validateEmailHtml(html, opts) {
+  if (typeof html !== 'string') {
+    throw new TypeError('validateEmailHtml(html): html must be a string');
+  }
+  void opts; // reserved
+  /** @type {Array<{ rule: string, detail: string }>} */
+  const violations = [];
+
+  // --- EM-LAYOUT-01: no flexbox/grid/absolute|fixed positioning -------------
+  const layoutHits = [];
+  if (FLEX_RE.test(html)) layoutHits.push('display:flex');
+  if (GRID_RE.test(html)) layoutHits.push('display:grid');
+  if (POSITION_RE.test(html)) layoutHits.push('position:absolute|fixed|sticky');
+  if (layoutHits.length > 0) {
+    violations.push({
+      rule: 'EM-LAYOUT-01',
+      detail: `email layout must use role="presentation" tables, not modern box primitives (found ${layoutHits.join(', ')})`,
+    });
+  }
+
+  // --- EM-STYLE-01: no <style> block as the primary styling mechanism -------
+  STYLE_BLOCK_RE.lastIndex = 0;
+  let m;
+  let primaryStyle = false;
+  while ((m = STYLE_BLOCK_RE.exec(html)) !== null) {
+    if (isPrimaryStyleBlock(m[1])) {
+      primaryStyle = true;
+      break;
+    }
+  }
+  if (primaryStyle) {
+    violations.push({
+      rule: 'EM-STYLE-01',
+      detail: 'visual styling must be inline; a <style> block with non-@media rules is stripped by Gmail (only a small @media-only block is tolerated)',
+    });
+  }
+
+  // --- EM-MSO-01: an MSO conditional comment in a full-email document -------
+  if (FULL_EMAIL_RE.test(html) && !MSO_COMMENT_RE.test(html)) {
+    violations.push({
+      rule: 'EM-MSO-01',
+      detail: 'a full email must include an MSO conditional comment (<!--[if mso]> … <![endif]-->) for Outlook\'s Word rendering engine',
+    });
+  }
+
+  // --- EM-DARK-01: a color-scheme signal is present -------------------------
+  const hasColorScheme =
+    META_COLOR_SCHEME_RE.test(html) ||
+    CSS_COLOR_SCHEME_RE.test(html) ||
+    PREFERS_COLOR_SCHEME_RE.test(html);
+  if (!hasColorScheme) {
+    violations.push({
+      rule: 'EM-DARK-01',
+      detail: 'declare a color-scheme signal (<meta name="color-scheme">, CSS color-scheme:, or @media prefers-color-scheme) so clients keep the intended palette',
+    });
+  }
+
+  return { ok: violations.length === 0, violations };
+}
+
+module.exports = { validateEmailHtml };