@hegemonart/get-design-done 1.33.6 → 1.34.1

package/agents/swift-executor.md

@@ -0,0 +1,226 @@
+---
+name: swift-executor
+description: Executes one plan task by generating compilable SwiftUI views for a native-iOS brief — following reference/platforms.md iOS conventions and consuming the token-bridge (reference/native-platforms.md / emitSwift) for Color/Font/ViewModifier. Single-shot; writes the Swift source, makes an atomic commit. The Xcode simulator is OPTIONAL (D-03).
+tools: Read, Write, Edit, Bash, Grep, Glob
+color: orange
+default-tier: sonnet
+tier-rationale: "Follows an Opus-authored plan task; executes (generates SwiftUI) rather than plans"
+size_budget: XXL
+size_budget_rationale: "Native executor carries the iOS-convention contract + the token-bridge consumption arc + the simulator-optional degrade rule, mirroring design-executor.md (itself XXL). Detailed token→primitive rules live in reference/native-platforms.md and the iOS conventions in reference/platforms.md, so the body stays well under the XXL cap; XXL is declared upfront because an executor's contract surface is substantial and must not trip the line-count gate as the arc fills in."
+parallel-safe: conditional-on-touches
+typical-duration-seconds: 60
+reads-only: false
+writes:
+  - ".design/tasks/*.md"
+  - "src/**"
+---
+
+@reference/shared-preamble.md
+
+# swift-executor
+
+## Role
+
+You execute **exactly one task** from `.design/DESIGN-PLAN.md` whose target is **native iOS** (SwiftUI). Your scope is a single task — generate the compilable SwiftUI view(s) the task describes, write the output, make an atomic commit, emit the completion marker. You do **not** re-plan, coordinate waves, spawn other agents, or ask clarifying questions. The design stage handles wave coordination and dispatch; you handle one task completely and correctly.
+
+You are an **agent-prompt** (D-04): GDD generates native code when an LLM invokes you — exactly as `design-executor.md` does for web. You are **not** a bundled compiler. You produce Swift source; the optional simulator (`connections/xcode-simulator.md`) is the verify stage's concern, never a precondition for you (D-03/D-10).
+
+You are a single-shot agent: receive context, read the references, generate the SwiftUI, write `.design/tasks/task-NN.md`, commit, emit marker, done.
+
+---
+
+## Required Reading
+
+The orchestrating stage supplies a `<required_reading>` block in the prompt. Read every listed file before taking any action. At minimum the stage provides:
+
+- `.design/STATE.md` — pipeline state (decisions, blockers, must-haves, `<connections>`)
+- `.design/DESIGN-PLAN.md` — full task list (your task is identified by `task_id`)
+- `.design/DESIGN-CONTEXT.md` — brand decisions, constraints, locked choices
+
+**Two authoritative references you MUST read for every SwiftUI task** (do not re-derive what they specify):
+
+- **`reference/platforms.md`** — the iOS interaction-**conventions** authority. §1 navigation (`NavigationStack` / `TabView`, ≤ 5 tabs, no hamburger), §2 safe areas (notch / Dynamic Island / home indicator), §3 gesture reservations (the left-edge back-swipe), §5 native typography (SF Pro Dynamic Type scale), §6 haptics. Cite it; do not paste it.
+- **`reference/native-platforms.md`** — the token→theme **bridge** spec. How a canonical token (`#3B82F6`, `16px`, `Inter`) becomes a SwiftUI `Color` / `CGFloat` / `Font` and the precision contract. The implementation lives in `scripts/lib/design-tokens/swift.cjs` (the `emitSwift` emitter on the Phase-23 facade). **Consume it; do not re-derive the Color/Font mapping.**
+
+**Invariant:** read all listed files FIRST, before generating any Swift.
+
+---
+
+## Prompt Context Fields
+
+The stage embeds the following fields in the prompt:
+
+| Field | Description |
+|-------|-------------|
+| `task_id` | Integer task number (NN) — matches the task header in DESIGN-PLAN.md |
+| `task_type` | The task type (typically `component` or `layout` for a SwiftUI view) |
+| `task_scope` | The task's `Scope:` field — one sentence describing what to build |
+| `task_acceptance_criteria` | Bulleted list of acceptance criteria from the plan |
+| `wave` | Integer wave number this task belongs to |
+| `is_parallel` | true/false — whether this agent runs inside a git worktree |
+| `auto_mode` | true/false — whether to proceed without mid-task prompts |
+
+---
+
+## Consuming the Token-Bridge
+
+Tokens become SwiftUI primitives through the bridge — **you never hand-author hex→Color math or px→CGFloat conversions.** The mapping is fixed in `reference/native-platforms.md` and implemented by `emitSwift` (`scripts/lib/design-tokens/swift.cjs`, re-exported from `scripts/lib/design-tokens/index.cjs`):
+
+- **Colors** — a `#RRGGBB(AA)` token emits as `Color(red: R/255.0, green: G/255.0, blue: B/255.0, opacity: A/255.0)` (8-bit channels exact; opaque alpha when the source had none).
+- **Dimensions** — an `Npx` token emits as a `CGFloat` point literal (integer pt).
+- **Typography family** — a `String` literal passed through verbatim.
+
+The emitter produces a `GDDTheme` enum of static constants. **Your job is to apply those constants to views** — `.foregroundStyle(GDDTheme.colorPrimary)`, `.padding(GDDTheme.space4)`, `.font(...)` — not to recompute them. If the canonical token set is available in the brief/context, reference the emitted constants; do not inline raw hex or magic point values into the SwiftUI.
+
+---
+
+## iOS Conventions to Honor (cite `reference/platforms.md`)
+
+Generate SwiftUI that obeys the platform — these are structural decisions, follow them per `reference/platforms.md` (do not duplicate the whole guide here):
+
+1. **Safe areas** — respect the notch / Dynamic Island / home indicator. Use SwiftUI's automatic safe-area handling; do not place interactive controls under the home indicator. Reach for `.safeAreaInset` / `.ignoresSafeArea` deliberately, never accidentally.
+2. **Gesture reservations** — **never** shadow the system left-edge back-swipe (the interactive pop gesture). Do not attach a custom pan gesture that begins at the left edge. Other OS-reserved gestures (Notification/Control Center pull-downs) are likewise off-limits.
+3. **Navigation** — use `NavigationStack` for hierarchy and `TabView` for lateral switching (2–5 tabs, no hamburger drawer — that is a web/Android import).
+4. **Native typography** — use SF Pro Dynamic Type text styles (`.font(.body)`, `.font(.headline)`, …) so text participates in user text-scaling; **never render text below 11pt** at any Dynamic Type setting.
+5. **Components** — prefer native idioms (action sheet, `UIAlertController`-style alert ≤ 2 actions, segmented control, `Toggle`) over foreign shapes; brand lives in color/type/icon, not in re-shaped OS chrome.
+
+When `reference/platforms.md` and a brand decision conflict on a **structural** matter, the platform convention wins (flag it via Rule 4 if a locked `D-XX` demands otherwise).
+
+---
+
+## Output
+
+1. Emit **compilable Swift** — SwiftUI `View` structs (and any small supporting types) for the task. The code must build under a standard SwiftUI toolchain; balanced braces, valid `import SwiftUI`, no placeholder `// TODO` left in load-bearing positions.
+2. Apply the token-bridge constants for all color/dimension/typography values (see above).
+3. Write the Swift to the output path the task declares (under the project's SwiftUI source tree — the `writes: src/**` glob).
+4. **State the file(s) written** in the task output and your closing summary.
+
+The Xcode **simulator is OPTIONAL** — you do **not** need a running simulator to produce the code (D-03/D-10). Rendered verification (snapshot capture) is the verify stage's degraded-mode concern, documented in `connections/xcode-simulator.md`; it is **not** a precondition for this task. Never spawn a simulator from here.
+
+---
+
+## Decision Authority
+
+When encountering a decision not specified in the task file:
+
+- **Tier 1 — proceed autonomously** when the decision is contained entirely within the task's files and conflicts with no `D-XX`. Example: choosing between two equivalent SwiftUI layout containers (`VStack` vs `Grid`) for the same result.
+- **Tier 2 — flag and proceed** when the decision affects files/tasks beyond this one but is unambiguous in the DESIGN-CONTEXT.md direction. Log it in `.design/STATE.md` and your summary.
+- **Tier 3 — stop and ask (Rule 4)** when the decision contradicts DESIGN-CONTEXT.md or needs a new `D-XX`. Halt, write a `<blocker>`, mark the task `status: deviation`, still emit `## EXECUTION COMPLETE`.
+
+---
+
+## Deviation Rules
+
+Apply automatically during execution; track all deviations in the task-NN.md `## Deviations` section.
+
+- **Rule 1 — Bug:** broken behavior, type errors, non-compiling Swift in files you are editing → fix inline, note it. Track as `[Rule 1 - Bug] description`.
+- **Rule 2 — Missing Critical:** missing safe-area handling on a bottom control, a text style below 11pt, a gesture that shadows the back-swipe, missing accessibility labels on icon-only controls you are creating → add/fix it. Track as `[Rule 2 - Missing Critical] description`.
+- **Rule 3 — Blocking:** a missing file the task references, a broken import preventing the view from compiling → fix it. Track as `[Rule 3 - Blocking] description`.
+- **Rule 4 — Architectural:** the fix needs a structural change (new state-management architecture, switching UI frameworks, schema-level change, or a change contradicting a locked `D-XX`) → STOP, write a `<blocker>` to `.design/STATE.md`, mark task `status: deviation`, still emit `## EXECUTION COMPLETE`.
+
+**Scope boundary:** only auto-fix issues DIRECTLY caused by this task's changes. Pre-existing issues in files you are not touching are out of scope.
+
+**Fix-attempt limit:** after 3 auto-fix attempts on a single issue, stop fixing, document the remainder in Deviations, continue to output + commit.
+
+---
+
+## Task Output — `.design/tasks/task-NN.md`
+
+After completing the implementation, write `.design/tasks/task-NN.md` (NN = `task_id`). Create `.design/tasks/` first if absent. Format (locked):
+
+```
+---
+task: NN
+type: [task-type]
+status: complete | deviation
+---
+
+## What was done
+[2–4 sentences: which SwiftUI views, which token-bridge constants applied, which file(s) written.]
+
+## Files changed
+- [path]: [what changed]
+
+## Acceptance criteria
+- [✓/✗] [criterion from plan]
+
+## Design choices made
+[Choices beyond DESIGN-CONTEXT.md decisions, or "none beyond plan"]
+
+## Deviations (if any)
+[Rule-tagged deviations, or "none"]
+```
+
+`status: complete` — all acceptance criteria pass. `status: deviation` — one or more failed, or a Rule 4 blocker was hit.
+
+---
+
+## Atomic Commit
+
+After writing `.design/tasks/task-NN.md` and BEFORE emitting the completion marker, make an atomic git commit. **Stage files individually — NEVER `git add .` or `git add -A`:**
+
+```bash
+git add .design/tasks/task-NN.md
+git add [each Swift file this task wrote, listed individually]
+```
+
+**Commit message format:**
+
+```
+feat(design-NN): [task-type] — [task-scope truncated to 60 chars]
+```
+
+**CRITICAL PROHIBITION: NEVER run `git clean` inside a worktree.** When running as a parallel executor inside a git worktree, `git clean` treats files committed on the feature branch as "untracked" and will delete them, causing data loss when the worktree merges. Use `git checkout -- path/to/specific/file` to discard changes to a single file if needed. Never use blanket reset or clean operations.
+
+---
+
+## Worktree Semantics (Parallel Mode)
+
+**If `is_parallel: true`:** the stage has already created a git worktree and runs you inside it. Commit within the worktree normally; the stage merges worktrees back after all parallel agents complete. Do not merge, switch branches, or touch the main working tree.
+
+**If `is_parallel: false`:** you commit directly to the main branch. In both cases: commit only the files this task touched.
+
+---
+
+## Output Format
+
+End your response with:
+
+1. A one-paragraph summary (which SwiftUI files, which token-bridge constants, which acceptance criteria passed).
+2. A list of files touched (path + one-line description).
+3. The git commit SHA, if available: `Commit: [sha]`.
+4. If a Rule 4 blocker was hit: a brief failure note before the marker, plus the `<blocker>` entry in `.design/STATE.md`.
+
+Terminate with exactly this line (on its own line, no trailing text):
+
+```
+## EXECUTION COMPLETE
+```
+
+---
+
+## Constraints
+
+This agent MUST NOT:
+
+- Run `git clean` (any flags) — absolute prohibition, enforced unconditionally
+- Spawn or boot an Xcode simulator / run `xcodebuild` / any device emulator — code generation needs no simulator (D-03/D-10); rendered verification is the verify stage's job
+- Re-derive the token→SwiftUI mapping — consume the bridge (`reference/native-platforms.md` / `emitSwift`)
+- Modify `.design/DESIGN-PLAN.md` or `.design/DESIGN-CONTEXT.md` — flag contradictions via Rule 4
+- Re-plan tasks or change task scope
+- Spawn other agents via the `Task` tool
+- Ask clarifying questions (single-shot — use best judgment, note choices)
+- Commit files from other tasks in the same commit
+- Use `git add .` or `git add -A`
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"swift-executor","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<which SwiftUI view(s) + iOS conventions (safe areas / gestures / type) applied>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`.
+
+## EXECUTION COMPLETE

package/connections/android-emulator.md

@@ -0,0 +1,107 @@
+# Android Emulator — Connection Specification
+
+This file is the connection specification for the **Android emulator** within the get-design-done pipeline. Its role is to provide rendered evidence for the **verify** stage when generating native-Android (Jetpack Compose) output — capturing screenshots of a running app on an emulator so the native-verify branch can compare against supplied baselines.
+
+It is the Android sibling of `connections/xcode-simulator.md` (iOS). Both mirror the `connections/preview.md` template (Setup / Tools / Probe / three-value status / Fallback). Per **D-03** the emulator is **OPTIONAL with a degraded mode**: the default test suite and the typical user have no Android SDK, so this connection **NEVER hard-requires an emulator** — when it is absent the verify stage degrades to a code-only structural audit. The capability-matrix row for this connection is owned by a later plan (34.1-06); this file is the standalone spec.
+
+---
+
+## Setup
+
+**Prerequisites (ALL OPTIONAL — most users and CI have none):**
+
+- The **Android SDK** (`ANDROID_HOME` / `ANDROID_SDK_ROOT` set), which provides:
+  - `adb` (Android Debug Bridge) on `PATH` — talks to a running device/emulator.
+  - `emulator` on `PATH` — launches an Android Virtual Device (AVD).
+- At least one configured **AVD** (created via `avdmanager` / Android Studio).
+
+**There is no install step performed by the pipeline.** The Android SDK is a multi-gigabyte developer toolchain; the connection only *detects* it. If it is absent, that is the expected state for the default suite — all emulator steps are skipped and verification falls back to code-only (see Fallback). Never auto-install the SDK and never edit shell-rc files to add it.
+
+---
+
+## Tools
+
+This connection is **CLI-based** (not an MCP). Detection and capture use the Android SDK command-line tools:
+
+| Tool | Use |
+|------|-----|
+| `adb devices` | **Lightweight probe** — lists attached devices/emulators; the availability check (does NOT launch anything) |
+| `adb -s <serial> exec-out screencap -p` | **Capture workhorse** — grabs a PNG screenshot of the running emulator; save to `.design/screenshots/<route>.png` by path, do NOT embed base64 inline |
+| `emulator -list-avds` | Enumerate configured AVDs (used to decide whether an emulator *could* be started) |
+| `emulator -avd <name>` | Start an AVD (interaction mode only — never required for code generation) |
+
+`adb devices` is preferred for probing because it returns the current device list without starting an emulator. `screencap` is the capture workhorse for the verify stage.
+
+---
+
+## Availability Probe
+
+The probe is a lightweight, read-only check — it must NOT launch an emulator. Run it where the capture calls will actually happen (the verify stage), and write the result to `.design/STATE.md <connections>` immediately.
+
+```
+Step P1 — toolchain check:
+  is `adb` resolvable on PATH (and ANDROID_HOME / ANDROID_SDK_ROOT set)?
+  → No   → android-emulator: not_configured   (no Android SDK — the default/typical state; skip all emulator steps)
+  → Yes  → proceed to Step P2
+
+Step P2 — device check (lightweight, no launch):
+  run `adb devices` and parse the device list
+  → at least one `emulator-*` / device line in state `device`  → android-emulator: available
+  → adb present but the list is empty (no emulator running)     → android-emulator: unavailable
+  → adb errors (server won't start, timeout)                    → android-emulator: unavailable
+```
+
+**Three-value status schema** (mirrors `connections/preview.md`):
+
+| Value | Meaning |
+|-------|---------|
+| `available` | `adb devices` lists at least one running emulator/device — rendered capture is possible |
+| `unavailable` | The Android SDK / `adb` is present but no emulator is currently running (or `adb` errored) — degrade for this session |
+| `not_configured` | No Android SDK detected (`adb` not on PATH) — the default state for most users + CI; degrade |
+
+---
+
+## Fallback Behavior (THE D-03 GUARANTEE)
+
+When `android-emulator` is `unavailable` or `not_configured`, the verify stage **degrades gracefully — no error is raised, no blocker is appended**. This is the core D-03 guarantee: the emulator is an **enhancement, not a requirement**.
+
+The degrade ladder (most → least evidence), mirroring the native-verify branch:
+
+1. **Emulator present (`available`)** — capture rendered screenshots via `adb … screencap` and run the snapshot-based audit.
+2. **No emulator, but a screenshot was SUPPLIED** — run snapshot-diff against the supplied screenshot using the Phase-23 visual primitives (no live emulator needed).
+3. **No emulator and no screenshot → CODE-ONLY** — perform a structural / static audit of the generated Kotlin Compose source (Material 3 usage, inset handling, `sp` type sizes, token-bridge theme consumption). This is the default path on a machine **without an emulator**.
+
+The verify stage marks the skipped rendered checks `[SKIPPED — emulator not available]` and continues with partial scores. It does **NOT** append a `<blocker>` for a missing emulator. **Only** if a `must_have` *explicitly* demands rendered (on-device) evidence does the stage append a blocker — otherwise the code-only audit is sufficient and the run proceeds.
+
+---
+
+## Which Stages Use This Connection
+
+| Stage | Skill/Agent | Purpose |
+|-------|------------|---------|
+| design | `agents/compose-executor.md` | **Code generation — emulator NOT required.** The Compose executor produces Kotlin statically (D-03/D-10); it never probes or launches an emulator. |
+| verify | `agents/design-verifier.md` (native-verify branch) | Rendered evidence **when an emulator is available**, else the degrade ladder above (supplied screenshot → code-only). This connection feeds the 34.1-05 native-verify adaptation. |
+
+---
+
+## STATE.md Integration
+
+Every probing stage writes its result to `.design/STATE.md` under the `<connections>` section:
+
+```xml
+<connections>
+preview: available
+android-emulator: not_configured
+</connections>
+```
+
+The verify stage re-probes at stage entry (emulator availability can change between sessions); if a prior stage in the SAME session already wrote an `android-emulator:` status, that value can be trusted for the rest of that session.
+
+---
+
+## Caveats and Pitfalls
+
+1. **`screencap` returns a PNG — save by path.** Save captures to `.design/screenshots/<route>.png` and reference by file path in markdown; do not embed base64 inline (it bloats reports).
+2. **`.design/screenshots/` is gitignored.** The `.design/` directory is already gitignored in get-design-done projects; confirm before saving captures.
+3. **The probe must never launch an emulator.** Use `adb devices` (and at most `emulator -list-avds`) for detection. Starting an AVD is slow and is reserved for explicit interaction-mode verification — never for the availability check.
+4. **`not_configured` is the normal default, not an error.** No Android SDK simply means code-only verification (D-03). Treat it as expected, not as a failure.

package/connections/connections.md

@@ -24,6 +24,8 @@ This directory contains connection specifications for external tools and MCPs th
 | 21st.dev Magic MCP | Active | [`connections/21st-dev.md`](connections/21st-dev.md) | Uses `mcp__21st*` tools; `TWENTY_FIRST_API_KEY` required |
 | Magic Patterns | Active | [`connections/magic-patterns.md`](connections/magic-patterns.md) | Claude connector (`mcp__magic_patterns*`) + API key fallback |
 | 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) |
 
 ---
 
@@ -47,6 +49,8 @@ Each cell describes what the connection contributes at that pipeline stage, or `
 | 21st.dev | — | prior-art gate: marketplace search before greenfield build | — | component-generator (21st impl) | — | — | ✓ |
 | Magic Patterns | — | — | — | component-generator (magic-patterns impl) | preview_url → `? VISUAL` check | — | ✓ |
 | 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) | — | — |
 
 **Column definitions:**
 

package/connections/xcode-simulator.md

@@ -0,0 +1,108 @@
+# Xcode Simulator — Connection Specification
+
+This file is the connection specification for the **Xcode iOS Simulator** within the get-design-done pipeline. Its role is to provide *rendered* evidence for native-iOS work: it lets the verify stage capture a SwiftUI snapshot from a booted simulator so a native screen can be audited against its design intent, the same way `connections/preview.md` provides browser screenshots for web. It is the iOS half of the native-verify connection pair (the Android half is `connections/android-emulator.md`).
+
+**It is OPTIONAL.** Most users — and CI — have no Xcode installed. Per **D-03** this connection is **never hard-required**: when it is absent the verify stage degrades gracefully to code-only structural verification, and no blocker is raised unless a `must_have` explicitly demands rendered evidence. The `swift-executor` agent generates compilable SwiftUI **without** any simulator (D-04/D-10); the simulator only adds rendered confirmation when it happens to be available.
+
+See `connections/preview.md` for the sibling browser-preview connection this spec mirrors. (The connection index + capability matrix is maintained separately as part of phase closeout, not by this doc.)
+
+---
+
+## Setup
+
+**Prerequisites (all OPTIONAL — absence is the common, supported case):**
+
+- **macOS** — the iOS Simulator runs only on macOS. On Linux/Windows this connection is permanently `not_configured`; that is expected and never an error.
+- **Xcode** (full app, not just the Command Line Tools) — provides the Simulator runtimes.
+- **`simctl`** — Apple's simulator-control CLI, available once Xcode is installed.
+
+**Why it is optional:** GDD's default test suite and the typical design user have no Xcode. Hard-requiring a simulator would block native-iOS work for the majority of environments. The pipeline therefore treats rendered iOS evidence as an **enhancement, not a requirement** (mirroring `connections/preview.md`'s stance) — exactly the D-03 guarantee.
+
+---
+
+## Tools
+
+This connection is driven by Apple's simulator CLI rather than an MCP server.
+
+| Capability | Command (illustrative) | Returns | Pipeline use |
+|------------|------------------------|---------|--------------|
+| Availability check | list installed simulator devices | device list (may be empty) | **Lightweight probe** — see below |
+| Boot a device | boot a named device by UDID | boot confirmation | Bring a simulator up before snapshot capture (verify stage only) |
+| Capture a snapshot | screenshot the booted device | PNG image | Rendered evidence for the verify stage |
+| Shut down | shut down the booted device | confirmation | Clean up after capture |
+
+The **availability check** is preferred for probing because it does not boot a device — it only reports whether the toolchain and runtimes are present. Booting and capture happen **only** in the verify stage, **only** when a `must_have` calls for rendered evidence and the probe reported `available`.
+
+> The default `npm test` suite **never** invokes these commands. Static validation of the native executors is hermetic (D-10) — frontmatter + reference checks only, no Xcode, no simulator, no spawn.
+
+---
+
+## Which Stages Use This Connection
+
+| Stage | Skill/Agent | Purpose | Simulator required? |
+|-------|------------|---------|---------------------|
+| design | `agents/swift-executor.md` | Generate compilable SwiftUI views | **No** — code generation needs no simulator (D-04/D-10) |
+| verify | `agents/design-verifier.md` (native-verify branch) | Rendered SwiftUI snapshot audit **when available**, else degrade | No — optional; degrades per Fallback below |
+
+This connection feeds the **34.1-05 native-verify branch**: verify probes it at stage entry and either captures a rendered snapshot (if `available`) or follows the degrade path. The `swift-executor` (design stage) never touches it.
+
+---
+
+## Availability Probe
+
+Probe **before** any boot/capture, and write the result to `.design/STATE.md` `<connections>` immediately.
+
+```
+Step P1 — toolchain check:
+  detect whether Xcode + the simulator CLI are present on this machine
+  → not macOS, or Xcode absent          → xcode-simulator: not_configured
+  → present                             → proceed to Step P2
+
+Step P2 — runtime/device check:
+  list installed simulator devices (does NOT boot one)
+  → list returns successfully (even empty)   → xcode-simulator: available
+  → command errors / permission denied       → xcode-simulator: unavailable
+```
+
+**Three-value status schema** (mirrors `connections/preview.md`'s three-value model):
+
+| Value | Meaning |
+|-------|---------|
+| `available` | Xcode + the simulator CLI are present and the device-list command succeeded (array, even empty). Rendered snapshots are possible. |
+| `unavailable` | The toolchain is present but the device-list command errored (no runtimes installed, permission denied, internal error). Treat as no-simulator. |
+| `not_configured` | Not macOS, or Xcode is not installed. The common, fully-supported case — never an error. |
+
+Write the result to `.design/STATE.md`:
+
+```xml
+<connections>
+preview: available
+xcode-simulator: not_configured
+</connections>
+```
+
+---
+
+## Fallback Behavior
+
+When `xcode-simulator` is `not_configured` or `unavailable`, the verify stage **degrades gracefully — no error is raised, no blocker is appended** (the D-03 guarantee: this connection **never hard-requires a simulator**). The degrade is a two-step ladder, exactly mirroring how `connections/preview.md` falls back when no browser is available:
+
+1. **Snapshot-diff on a supplied screenshot** — if the brief/context provides a reference screenshot of the intended iOS screen, the verify stage diffs against that supplied image (using the Phase-23 visual primitives). No live simulator is needed.
+2. **Code-only structural audit** — if no screenshot exists either, the verify stage falls back to a **code-only** audit of the generated SwiftUI: structural checks against `reference/platforms.md` (safe-area handling present, no left-edge gesture conflict, Dynamic Type styles used, no sub-11pt text) and token-bridge conformance, with **no rendered evidence**. The native screen is verified **without a simulator**.
+
+Phase-4B-style rendered-evidence checks are marked `[SKIPPED — simulator not available]`; the verifier continues to gap analysis with partial scores. **No `<blocker>` is appended for a missing simulator** — rendered iOS evidence is an enhancement, not a requirement. The **only** exception: if a `must_have` *explicitly* requires simulator-rendered evidence, THEN (and only then) the verifier appends a blocker noting the simulator is unavailable.
+
+---
+
+## STATE.md Integration
+
+Every stage that uses this connection writes its probe result to `.design/STATE.md` under `<connections>` (see schema above). The verify stage **re-probes at stage entry** rather than blindly trusting a prior status, because toolchain availability can change between sessions — however, a status already written earlier in the **same session** can be trusted for the rest of that session (mirroring `connections/preview.md`).
+
+---
+
+## Caveats and Pitfalls
+
+1. **Absence is the default, not a failure.** On the vast majority of machines this connection is `not_configured`. That is the supported, expected state — the pipeline produces SwiftUI and verifies it code-only without ever touching a simulator (D-03/D-10). Never treat `not_configured` as an error or a reason to block.
+2. **The probe must not boot a device.** Use the device-**list** command for probing; booting a simulator just to check availability is slow and unnecessary. Boot only in the verify stage, only when rendered evidence is actually required and the probe said `available`.
+3. **Snapshots are screenshots — save by path.** A captured simulator snapshot is a full PNG. Save it to `.design/screenshots/<screen>.png` and reference it by path in markdown; do not embed base64 inline. `.design/` is gitignored, so snapshots are not committed.
+4. **The default test suite never spawns a simulator.** All native-executor validation is structural and hermetic (D-10). A live simulator is exclusively the verify stage's opt-in, degraded-mode enhancement (D-03) — it is never part of `npm test`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.33.6",
+  "version": "1.34.1",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",