@hegemonart/get-design-done 1.46.0 → 1.47.0

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.46.0"
+    "version": "1.47.0"
   },
   "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.46.0",
+      "version": "1.47.0",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.46.0",
+  "version": "1.47.0",
   "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",

package/CHANGELOG.md

@@ -4,6 +4,53 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.47.0] - 2026-06-03
+
+### Phase 47 - In-Browser Design Iteration (Live Mode)
+
+GDD's design loop was repo-bound (edit, save, preview, screenshot) with no tight in-browser iteration. Phase 47
+ships `/gdd:live`: pick an element on a running dev server, generate N variants in one batch, post-check each with
+gdd-detect, hot-swap via HMR, accept or discard, and the session persists for resume. It drives the existing Preview
+MCP connection at runtime (the same surface verify screenshots and darkmode injection already use), so there is no
+new runtime dependency and no new egress. Planned and executed via the GSD pipeline (2 research agents + 3 parallel
+executor subagents).
+
+### Breaking changes
+
+- **`capability_matrix.mcp_support` now also gates live mode.** A harness declared `mcp_support: false` runs
+  `/gdd:live` in degraded screenshot-only mode (no element-pick or HMR swap). Harness authors adding a runtime must
+  set `mcp_support` honestly, since it now drives this behavioral split in addition to MCP tool availability.
+- **The live-session schema joins the validated set.** `reference/schemas/live-session.schema.json` is registered in
+  `validate:schemas`, and the six `live_*` event types are seeded into `reference/schemas/events.schema.json`.
+  Editing either must keep them valid (CI-gated).
+
+### Added
+
+- **`/gdd:live`** at `source/skills/live/SKILL.md`: boot (probe Preview, detect dev server Vite/Next/Bun/static,
+  degraded mode if no MCP), element pick, single-batch N-variant generation (default 3, loads the Phase 45 canonical
+  reference first), per-variant gdd-detect post-check (findings inline; `error` flagged, never auto-rejected),
+  accept/discard with canonical-edit selection, session persistence, and resume.
+- **`scripts/lib/live/` substrate** (all dependency-free, all unit-tested): `session-store` (the
+  `.design/live-sessions/<id>.json` lifecycle + resume), `scope-guard` (blocks writes outside the picked element's
+  implicated source set), `postcheck` (wraps the gdd-detect engine in-memory), `events` (the six typed `live_*`
+  emitters), `bandit-feed` (accepted variants call the Phase 38 store's `observe(..., {source:'dev_time'})` at a 0.5
+  dev-time weight; the `Beta(2,8)` prior keeps them advisory), `harness-mode` (mcp_support to puppeteer/degraded),
+  `runtime` (the browser-side pick/swap script injected via `preview_eval`, keyed on `data-gdd-variant`).
+- **`reference/live-mode-integration.md`** documents the loop, the Preview surface, the events, the session file, the
+  bandit feed, degraded mode, and the scope guard.
+
+### Notes
+
+- 6-manifest lockstep at **v1.47.0** + `OFF_CADENCE_VERSIONS.add('1.47.0')` + 37 `manifests-version.txt` baselines +
+  tarball golden 884 -> 895 (the `live` skill in `skills/` + `dist/claude-code/`, 7 `scripts/lib/live/*.cjs`,
+  `reference/live-mode-integration.md`, `reference/schemas/live-session.schema.json`).
+- Testability: the deterministic substrate is fully unit-tested (session, scope, postcheck, events, bandit-feed,
+  harness-mode, runtime shape) plus a deterministic session-replay baseline at `test/fixtures/baselines/phase-47/`.
+  Live element-pick, HMR swap, and screenshots are runtime behaviors driven by the skill through the Preview
+  connection, exercised by the existing conditional main-branch E2E rather than new browserless CI suites.
+
+---
+
 ## [1.46.0] - 2026-06-03
 
 ### Phase 46 - Skill UX Polish

package/README.md

@@ -253,6 +253,8 @@ All 14 runtimes receive their native artifact layout (`skills/`, `command/`, `ag
 
 **Skill UX polish (v1.46.0).** Skill frontmatter now has a single source of truth at `scripts/lib/manifest/skills.json` (description, argument hint, tools allow-list per skill); `scripts/generate-skill-frontmatter.cjs` regenerates each `source/skills/<id>/SKILL.md` from it, and `generate:skill-frontmatter:check` drift-gates the two in CI. The generator is order-preserving, so the committed tree stays a byte-for-byte fixed point and existing snapshots never churn. Power users get `/gdd:pin <skill>`, which writes standalone shortcut aliases (for example `/audit` alongside `/gdd:audit`) across every installed harness dir, each carrying a `gdd-pinned-skill` marker, plus `/gdd:unpin` and `/gdd:list-pins`. The 1024-character description budget (in place since the skill-authoring contract) is now an explicit `lint:agentskills` CI gate. **No new runtime dependency.**
 
+**In-browser design iteration (v1.47.0).** `/gdd:live` tightens the design loop: pick an element on a running dev server, generate N variants in one batch (default 3, grounded in the Phase 45 canonical reference), post-check each with `gdd-detect`, hot-swap them via HMR, then accept or discard. Accepted variants are applied as the canonical edit and feed the Phase 38 bandit store with a `dev_time` source tag (a conservative `Beta(2,8)` prior keeps them advisory until production outcomes accumulate). The session persists to `.design/live-sessions/<id>.json` with resume, a scope guard blocks writes outside the picked element's source files, and harnesses without MCP fall back to a screenshot-only degraded mode. It drives the existing Preview connection, so there is **no new runtime dependency**.
+
 Verify with:
 
 ```

package/SKILL.md

@@ -2,7 +2,7 @@
 name: get-design-done
 short_name: gdd
 description: "Master design pipeline for Claude Code. 5-stage workflow: Brief → Explore → Plan → Design → Verify. Run 'brief' first in any new project to capture the design problem, then 'explore' to inventory the codebase and interview for context. Invoke without arguments for status and auto-routing."
-argument-hint: "[brief|explore|plan|design|verify|handoff|map|next|help|status|style|darkmode|compare|figma-write|graphify|discuss|list-assumptions|progress|health|todo|stats|note|plant-seed|add-backlog|review-backlog|scan|discover|settings|update|reapply-patches|audit|pause|resume|new-cycle|debug|quick|new-project|complete-cycle|fast|do|ship|undo|pr-branch|sketch|sketch-wrap-up|spike|spike-wrap-up|reflect|apply-reflections|analyze-dependencies|extract-learnings|skill-manifest|pin|unpin|list-pins|warm-cache|optimize|cache-manager|watch-authorities|check-update|benchmark|recall|timeline|continue|zoom-out]"
+argument-hint: "[brief|explore|plan|design|verify|handoff|map|next|help|status|style|darkmode|live|compare|figma-write|graphify|discuss|list-assumptions|progress|health|todo|stats|note|plant-seed|add-backlog|review-backlog|scan|discover|settings|update|reapply-patches|audit|pause|resume|new-cycle|debug|quick|new-project|complete-cycle|fast|do|ship|undo|pr-branch|sketch|sketch-wrap-up|spike|spike-wrap-up|reflect|apply-reflections|analyze-dependencies|extract-learnings|skill-manifest|pin|unpin|list-pins|warm-cache|optimize|cache-manager|watch-authorities|check-update|benchmark|recall|timeline|continue|zoom-out]"
 user-invocable: true
 ---
 
@@ -33,6 +33,7 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `help` | `get-design-done:gdd-help` | List all commands with one-line descriptions |
 | `style [ComponentName]` | `get-design-done:gdd-style` | Generate component handoff doc → .design/DESIGN-STYLE-[Name].md |
 | `darkmode` | `get-design-done:gdd-darkmode` | Audit dark mode architecture + contrast + anti-patterns → .design/DARKMODE-AUDIT.md |
+| `live [--variants N] [--resume <id>] [url]` | `get-design-done:gdd-live` | Phase 47 - in-browser design iteration: pick an element on a running dev server (via the Preview connection), generate N variants, hot-swap via HMR, accept/discard; session persists to .design/live-sessions/. Degraded screenshot-only mode on harnesses without MCP |
 | `compare` | `get-design-done:gdd-compare` | Delta between DESIGN.md baseline and DESIGN-VERIFICATION.md → .design/COMPARE-REPORT.md |
 | `figma-write <mode>` | `get-design-done:gdd-figma-write` | Write design decisions to Figma (annotate/tokenize/mappings) |
 | `figma-extract <file-url-or-key>` | `get-design-done:gdd-figma-extract` | Off-context Figma design-system extraction → compact local digest (DESIGN.md + tokens.json + components.json), zero raw JSON in context |

package/dist/claude-code/.claude/skills/live/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: gdd-live
+description: "Live in-browser design mode. The user picks a DOM element on a running dev server (via the Claude Preview MCP), the agent generates N design variants in one batch, they hot-swap in place through HMR or preview_eval using a data-gdd-variant marker, the user accepts or discards, and the whole pick-generate-accept loop persists to .design/live-sessions so it survives a crash or resume. Use when the user wants to iterate on the look of a live component against a real running server, asks to try variants on a page, or runs the live command with a url; falls back to a screenshot-only degraded mode on harnesses without MCP support."
+argument-hint: "[--variants N] [--resume <session-id>] [url]"
+tools: Read, Write, Edit, Bash, Glob, Grep, Task
+user-invocable: true
+---
+
+# gdd-live - Live In-Browser Design Mode
+
+Pick a DOM element on a running dev server, generate competing design variants, hot-swap them in place, and accept the winner as a real source edit. Every step persists to `.design/live-sessions/<id>.json` so the session survives a crash or a later resume.
+
+The browser-side runtime, the harness-mode gate, the session store, the events feed, the post-check, the scope guard, and the bandit feed are all separate modules under `scripts/lib/live/`. This skill describes the loop and names the module that owns each step; it does not import them.
+
+For the full surface (the Preview MCP tools, the six `live_*` events, the session file, the bandit feed, degraded mode, the scope guard), see `../../reference/live-mode-integration.md`. For the SKILL.md structural contract, see `../../reference/skill-authoring-contract.md`.
+
+---
+
+## Arguments
+
+- `[url]` - the page to drive. Optional. When omitted, detect the dev server and use its root.
+- `--variants N` - how many variants to generate per pick. Default 3.
+- `--resume <session-id>` - reattach to an in-progress session in `.design/live-sessions/`.
+
+---
+
+## BOOT
+
+1. Probe the Preview MCP per `../../connections/preview.md`: `ToolSearch({ query: "Claude_Preview" })`, then `mcp__Claude_Preview__preview_list`. Empty ToolSearch means the MCP is not loaded.
+2. Resolve the harness live mode. The capability signal is `capability_matrix.mcp_support` in `scripts/lib/manifest/harnesses.json`, projected by `scripts/lib/live/harness-mode.cjs` (`liveModeFor(harnessId)`). A `puppeteer` result means full live mode; a `degraded` result means screenshot-only.
+3. If `mcp_support` is false for this harness, or Preview is unavailable, enter DEGRADED mode and say so plainly: variants are generated and captured as static screenshots, with no in-page hot-swap. Skip the INJECT and PICK steps; generate against the file the user names instead.
+4. Detect the dev server. Look for Vite, Next, Bun, or a static server (check `package.json` scripts plus a `preview_list` entry). Record the server descriptor on the session.
+5. Open or create the session via `scripts/lib/live/session-store.cjs` (`.design/live-sessions/<id>.json`). On `--resume`, load the named session (see RESUME).
+
+---
+
+## INJECT
+
+Inject the browser runtime once. Read `RUNTIME_JS` from `scripts/lib/live/runtime.cjs` and evaluate it in the page with `mcp__Claude_Preview__preview_eval`. The runtime is an idempotent IIFE bound to `window.__gddLive`, so a re-inject after navigation rebinds the same singleton rather than stacking listeners. It installs the pick handler and the variant-swap helpers, and stamps the live variant on the element via the `data-gdd-variant` attribute.
+
+---
+
+## PICK
+
+1. Arm the picker (`window.__gddLive.pick()`), then guide the user to click the target element. Use `preview_click` and `preview_inspect` to confirm the element and read its computed styles and bounding box.
+2. Read the pick report back. Its fields are documented in `pickReportShape` (selector, tagName, classList, boundingRect, computedStyle subset, current variant). The selector strategy prefers id, then a data-testid, then a tag plus class plus nth-of-type path.
+3. Emit a `live_pick` event through `scripts/lib/live/events.cjs` and append a `pick` entry to the session.
+
+---
+
+## GENERATE (one batch)
+
+1. Load the relevant Phase 45 canonical reference index FIRST, so variants are grounded in real guidance: the domain index that matches the picked element (for example `../../reference/spatial.md` for layout, `../../reference/interaction.md` for components and a11y, `../../reference/color.md` for color, `../../reference/typography.md` for type, `../../reference/motion.md` for animation).
+2. Generate all N variants in ONE batch (default 3), each a distinct, hypothesis-tagged design direction for the picked element. Do not generate them one at a time.
+3. For each variant: write the change atomically to the implicated source file, then make it live. With HMR running, the file write is enough; otherwise apply the variant in place with `window.__gddLive.swapVariant({ n, style, html })`, which sets `data-gdd-variant="n"` and applies the variant's style or markup.
+
+---
+
+## POST-CHECK
+
+Run the post-check on each variant via `scripts/lib/live/postcheck.cjs`, which invokes `gdd-detect`. Show the findings inline next to each variant. A variant that trips a finding is flagged, NOT auto-rejected: the user still decides. Append a `live_postcheck` event per variant.
+
+---
+
+## ACCEPT / DISCARD
+
+- ACCEPT one variant: apply the chosen variant as the canonical source edit, and revert the others in the page (`window.__gddLive.revert()` on each non-chosen element). Emit a `live_accept` event and feed the outcome to the design-variants bandit via `scripts/lib/live/bandit-feed.cjs` (a dev-time signal). Append an `accept` entry.
+- DISCARD: revert every variant in the page back to its captured original and leave the source untouched. Emit a `live_discard` event and append a `discard` entry.
+
+Either way, persist the result through `scripts/lib/live/session-store.cjs` before continuing.
+
+---
+
+## PERSIST
+
+Every step (boot, pick, generate, post-check, accept, discard) is written to the session file through `scripts/lib/live/session-store.cjs` as it happens. The on-disk event log uses the `pick`, `generate`, `accept`, `discard` kinds; the telemetry stream uses the six `live_*` event types. Writes are atomic, so an interrupted step never leaves a half-written session.
+
+---
+
+## RESUME
+
+With `--resume <session-id>`, load the named session from `.design/live-sessions/`. Only an `in_progress` session is resumable. Offer the user two choices: continue from the last recorded event (report what that was, for example "last pick was the primary button"), or start fresh (open a new session and leave the old one intact). Never silently replay completed events.
+
+---
+
+## SCOPE GUARD
+
+Never write outside the source files implicated by the picked element. Run every proposed write through `scripts/lib/live/scope-guard.cjs`, which maps the picked selector to its owning source files and rejects edits that fall outside them. If a variant would need a change beyond that scope (a shared token, a parent layout, a new dependency), stop and surface it to the user rather than widening the blast radius.
+
+## Constraints
+
+- Do NOT edit files outside the picked element's implicated sources (enforced by the scope guard).
+- Do NOT generate variants one at a time; generate the full batch, then swap.
+- Do NOT auto-reject a variant on a post-check finding; flag it and let the user decide.
+- In DEGRADED mode, state up front that hot-swap is unavailable and fall back to screenshots.
+- Persist before every user-facing prompt so a crash never loses accepted work.
+
+## LIVE COMPLETE

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.46.0",
+  "version": "1.47.0",
   "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/live-mode-integration.md

@@ -0,0 +1,80 @@
+---
+name: live-mode-integration
+type: meta-rules
+version: 1.0.0
+phase: 47
+tags: [live, preview-mcp, hot-swap, session, bandit, scope-guard, degraded-mode]
+last_updated: 2026-06-03
+---
+
+# Live Mode Integration
+
+This file is the meta-rules companion to the `gdd-live` skill (`source/skills/live/SKILL.md`). It describes how `/gdd:live` turns a running dev server into a live design surface: the user picks a DOM element, the agent generates N variants in one batch, the variants hot-swap in place, the user accepts or discards, and the whole session persists. For the SKILL.md structural contract (line cap, description budget, frontmatter), see `./skill-authoring-contract.md`. The variants themselves are grounded in the Phase 45 domain indexes (`./spatial.md`, `./interaction.md`, `./color.md`, `./typography.md`, `./motion.md`).
+
+There is NO bundled browser automation. The skill drives the Claude Preview MCP at runtime; the modules under `scripts/lib/live/` are pure and dependency-free.
+
+## The live loop
+
+The loop is seven stages, each owned by one module under `scripts/lib/live/`:
+
+1. BOOT. Probe the Preview MCP (see below), resolve the harness live mode, and detect the dev server (Vite, Next, Bun, or static). Open or create the session.
+2. INJECT. Read `RUNTIME_JS` from `scripts/lib/live/runtime.cjs` and evaluate it in the page via `preview_eval`. The runtime is an idempotent IIFE on `window.__gddLive`; re-injecting after a navigation rebinds the same singleton.
+3. PICK. The runtime arms a one-shot click handler. The clicked element is reported back as `{selector, tagName, classList, boundingRect, computedStyle subset, variant}` (the `pickReportShape` contract). The selector strategy prefers id, then a data-testid, then a tag plus class plus nth-of-type path.
+4. GENERATE. Load the matching domain index first, then generate all N variants (default 3) in ONE batch. Each variant is written atomically to its source file and made live, either through HMR or through the runtime swap helper.
+5. POST-CHECK. Each variant runs through `scripts/lib/live/postcheck.cjs`, which invokes `gdd-detect`. Findings show inline. A finding flags a variant; it never auto-rejects it.
+6. ACCEPT or DISCARD. Accept applies the chosen variant as the canonical source edit, reverts the others, and feeds the bandit. Discard reverts everything and leaves the source untouched.
+7. PERSIST. Every stage is written to the session file as it happens.
+
+## The Preview MCP surface
+
+Live mode drives the built-in Claude Preview MCP, the same connection documented in `../connections/preview.md`. The tools it uses:
+
+- `preview_list` and `ToolSearch` for the availability probe.
+- `preview_eval` to inject `RUNTIME_JS` and to read the pick report back.
+- `preview_inspect` and `preview_click` to confirm the picked element and read its computed styles.
+- `preview_navigate` to move between routes (the runtime re-inject is idempotent across navigations).
+- `preview_screenshot` for evidence, and as the only output in degraded mode.
+
+The `data-gdd-variant` attribute is the hot-swap marker. The runtime stamps `data-gdd-variant="N"` on the picked element when it applies variant N, and reads it back to know which variant is live.
+
+## The six live events
+
+Live mode emits six telemetry event types through `scripts/lib/live/events.cjs` onto the standard `.design/telemetry/events.jsonl` stream:
+
+| Event | Emitted when |
+|---|---|
+| `live_boot` | A session opens (BOOT completes). |
+| `live_pick` | The user picks an element. |
+| `live_generate` | A batch of N variants is generated. |
+| `live_postcheck` | A variant clears or trips its post-check. |
+| `live_accept` | The user accepts a variant. |
+| `live_discard` | The user discards the batch. |
+
+These telemetry events are distinct from the on-disk session log. The session file records the four lifecycle kinds (`pick`, `generate`, `accept`, `discard`); the telemetry stream carries the six `live_*` types above.
+
+## The session file
+
+`scripts/lib/live/session-store.cjs` owns one JSON document per session at `.design/live-sessions/<session-id>.json`, conforming to `./schemas/live-session.schema.json`. It carries `{schema_version, session_id, status, started_at, ended_at, url, dev_server, events[]}`. `status` is one of `in_progress`, `completed`, or `abandoned`; only an `in_progress` session is resumable. Writes are atomic (write to a temp file, then rename), so an interrupted step never leaves a half-written session.
+
+On `--resume <session-id>`, the skill loads the named session and offers two choices: continue from the last recorded event, or start fresh. It never silently replays completed events.
+
+## The bandit dev-time feed
+
+When the user accepts a variant, `scripts/lib/live/bandit-feed.cjs` feeds that outcome to the design-variants bandit described in `./design-variants.md`. This is a dev-time signal: it records which design pattern the developer chose during live iteration. It is advisory and separate from the user-outcome A/B loop and from the routing bandit. The user always wins; the bandit only learns.
+
+## Degraded mode
+
+Live mode is gated on `capability_matrix.mcp_support` in `scripts/lib/manifest/harnesses.json`. `scripts/lib/live/harness-mode.cjs` projects each harness onto a mode: `liveModeFor(harnessId)` returns `puppeteer` (full live mode) when `mcp_support` is true, and `degraded` otherwise. `degradedHarnesses()` lists every screenshot-only harness.
+
+In degraded mode there is no Preview MCP, so there is no runtime injection and no hot-swap. The skill states this up front, then generates variants against the file the user names and captures static screenshots for comparison. Degraded mode never errors; it is a documented fallback.
+
+## Scope guard
+
+`scripts/lib/live/scope-guard.cjs` maps the picked selector to its owning source files and rejects any write that falls outside them. A variant that would need a change beyond that scope (a shared token, a parent layout, a new dependency) stops the loop and surfaces the decision to the user, rather than silently widening the blast radius. The guard is the hard boundary on what live mode may edit.
+
+## See also
+
+- `./skill-authoring-contract.md` for the SKILL.md authoring rules.
+- `./design-variants.md` for the bandit the accept step feeds.
+- `../connections/preview.md` for the full Preview MCP connection spec.
+- The Phase 45 domain indexes (`./spatial.md`, `./interaction.md`, `./color.md`, `./typography.md`, `./motion.md`) the generate step loads.

package/reference/registry.json

@@ -856,6 +856,13 @@
       "phase": 46,
       "description": "Phase 46 skill-metadata single source of truth: scripts/lib/manifest/skills.json record shape, the generate-skill-frontmatter.cjs forward/extract/check modes, the skills.json to generator to build:skills to skills/+dist build chain, the six managed frontmatter keys (canonical order, always-quoted strings) vs extra_frontmatter passthrough, the 20..1024 description budget (validate-skill-length.cjs + lint-agentskills-spec.cjs R4, lint:agentskills CI gate), and the pin metadata catalogue consumer."
     },
+    {
+      "name": "live-mode-integration",
+      "path": "reference/live-mode-integration.md",
+      "type": "meta-rules",
+      "phase": 47,
+      "description": "Phase 47 live-mode contract for /gdd:live: the seven-stage pick to generate to accept loop, the Claude Preview MCP surface (preview_eval injects scripts/lib/live/runtime.cjs RUNTIME_JS, hot-swap via the data-gdd-variant marker), the six live_* telemetry events vs the four on-disk session kinds, the .design/live-sessions session file (scripts/lib/live/session-store.cjs + live-session.schema.json), the dev-time bandit feed (bandit-feed.cjs into design-variants), degraded screenshot-only mode gated on capability_matrix.mcp_support (harness-mode.cjs), and the scope guard (scope-guard.cjs)."
+    },
     {
       "name": "capability-gap-stage-gate",
       "path": "reference/capability-gap-stage-gate.md",

package/reference/schemas/events.schema.json

@@ -10,7 +10,7 @@
     "type": {
       "type": "string",
       "minLength": 1,
-      "description": "Free-form event type identifier. Pre-registered seeds: state.mutation, state.transition, stage.entered, stage.exited, hook.fired, error, capability_gap, kfm-candidate, router_pick, verify_outcome, rollout_started, rollout_advanced, rollout_stuck, budget_forecast, project_cap_warning, project_cap_halt."
+      "description": "Free-form event type identifier. Pre-registered seeds: state.mutation, state.transition, stage.entered, stage.exited, hook.fired, error, capability_gap, kfm-candidate, router_pick, verify_outcome, rollout_started, rollout_advanced, rollout_stuck, budget_forecast, project_cap_warning, project_cap_halt, live_session_start, live_pick, live_generate, live_accept, live_discard, live_session_end."
     },
     "timestamp": {
       "type": "string",

package/reference/schemas/live-session.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/hegemonart/get-design-done/reference/schemas/live-session.schema.json",
+  "title": "Live Session",
+  "description": "A single `/gdd:live` session record persisted at .design/live-sessions/<session-id>.json. Captures the pick -> generate -> accept/discard loop as an append-only event log so a session survives a crash or --resume. Written atomically by scripts/lib/live/session-store.cjs.",
+  "type": "object",
+  "required": ["schema_version", "session_id", "status", "started_at", "ended_at", "events"],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Schema version of this session record (e.g. \"47.0\")."
+    },
+    "session_id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stable id; also the basename of the on-disk file (no path separators)."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["in_progress", "completed", "abandoned"],
+      "description": "Lifecycle status. Only in_progress sessions are resumable."
+    },
+    "started_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp the session was created."
+    },
+    "ended_at": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "ISO-8601 timestamp the session was closed; null while in_progress."
+    },
+    "url": {
+      "type": "string",
+      "description": "The page the element was picked from (optional)."
+    },
+    "dev_server": {
+      "description": "Dev-server descriptor (url/port/command, or a plain string). Free-form by design.",
+      "type": ["string", "object", "null"]
+    },
+    "events": {
+      "type": "array",
+      "description": "Append-only log of session events, oldest first.",
+      "items": {
+        "type": "object",
+        "required": ["kind", "at"],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": ["pick", "generate", "accept", "discard"],
+            "description": "Event kind."
+          },
+          "at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO-8601 timestamp the event was recorded."
+          }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/scripts/lib/live/bandit-feed.cjs

@@ -0,0 +1,64 @@
+'use strict';
+/**
+ * scripts/lib/live/bandit-feed.cjs — Phase 47 (Live Mode) → Phase 38 design-arms bridge.
+ *
+ * When a user ACCEPTS a generated variant in /gdd:live, that acceptance is a weak,
+ * dev-time positive signal for the variant's design pattern. We fold it into the Phase 38
+ * `design_arms` posterior store as a WON observation — but at a discounted weight
+ * (DEV_TIME_WEIGHT = 0.5) because a developer's pick during authoring is advisory until
+ * real production A/B + user-research data arrives (Phase 38 D-03: advisory, never
+ * directive). The full posterior math + atomic persistence lives in the design-arms
+ * store; we only reuse it (variantKey + observe) and never duplicate the Beta math.
+ *
+ * Pure, dependency-free CommonJS. Persistence + `baseDir`/`armsPath` test-injection are
+ * inherited from the store. Ships in the npm package; requires only the in-repo store.
+ */
+
+const { variantKey, observe } = require('../ds-arms/design-arms-store.cjs');
+
+/**
+ * The dev-time acceptance weight. Half a win — a developer's accept is a discounted,
+ * advisory signal (Phase 38 D-03) until production user-outcome data shifts the arm.
+ */
+const DEV_TIME_WEIGHT = 0.5;
+
+/**
+ * Record an accepted Live Mode variant as a discounted WON observation on its design arm.
+ *
+ * @param {object} args
+ * @param {string} args.componentType   The component class (e.g. 'button', 'card').
+ * @param {string|object} args.pattern  The variant's design pattern (string or object;
+ *                                       hashed to the arm key via the store's variantKey).
+ * @param {string} [args.label]         Human-readable arm label, stored on first observe.
+ * @param {number} [args.weight]        Override the dev-time weight (defaults to DEV_TIME_WEIGHT).
+ * @param {string} [args.projectRoot]   Repo root — forwarded to the store as `baseDir` so the
+ *                                       arms file resolves under it (testable / hermetic).
+ * @param {string} [args.armsPath]      Explicit arms-file path override (forwarded to the store).
+ * @returns {object} The updated arm posterior (as returned by the store's observe()).
+ */
+function recordAccepted(args = {}) {
+  const { componentType, pattern, label, projectRoot, armsPath } = args;
+  if (typeof componentType !== 'string' || componentType.length === 0) {
+    throw new TypeError('recordAccepted: componentType is required (non-empty string)');
+  }
+  if (pattern == null) {
+    throw new TypeError('recordAccepted: pattern is required');
+  }
+
+  const weight = typeof args.weight === 'number' && args.weight > 0 ? args.weight : DEV_TIME_WEIGHT;
+  const hash = variantKey(componentType, pattern);
+
+  // Forward store options only when provided so the store keeps its own defaults otherwise.
+  const opts = {};
+  if (projectRoot) opts.baseDir = projectRoot;
+  if (armsPath) opts.armsPath = armsPath;
+
+  return observe(
+    componentType,
+    hash,
+    { won: true, weight, source: 'dev_time', label },
+    opts,
+  );
+}
+
+module.exports = { recordAccepted, DEV_TIME_WEIGHT };

package/scripts/lib/live/events.cjs

@@ -0,0 +1,86 @@
+'use strict';
+/**
+ * scripts/lib/live/events.cjs — Phase 47 (Live Mode) telemetry emitter.
+ *
+ * /gdd:live emits six event types across a session — start, pick, generate, accept,
+ * discard, end. This module is the single typed entry point: it validates the `type`
+ * against the closed LIVE_EVENT_TYPES allow-list (an unknown live type is a programmer
+ * error and is rejected) and appends the event via the in-repo event-chain emitter
+ * (scripts/lib/event-chain.cjs), the same write path router_pick uses.
+ *
+ * The emitted row carries the events.schema.json envelope fields verbatim
+ * (type / timestamp / sessionId / payload) so that, projected back to
+ * {type, timestamp, sessionId, payload}, it validates against the additive `live_*`
+ * seed types in reference/schemas/events.schema.json. `agent` + `outcome` are the
+ * chain emitter's two required fields; we set agent='live' and outcome=type.
+ *
+ * Pure, dependency-free CommonJS:
+ *   - NO top-level clock: the timestamp comes from an injectable `now` (default
+ *     `Date.now`), so tests are deterministic.
+ *   - `baseDir` is injectable (the emitter resolves the chain file relative to it),
+ *     so tests write to a temp project and never touch the repo's real stream.
+ *
+ * Ships in the npm package; requires only the in-repo event-chain emitter.
+ */
+
+const { appendChainEvent } = require('../event-chain.cjs');
+
+/** The six Live Mode event types. Closed allow-list — an unknown type is rejected. */
+const LIVE_EVENT_TYPES = Object.freeze([
+  'live_session_start',
+  'live_pick',
+  'live_generate',
+  'live_accept',
+  'live_discard',
+  'live_session_end',
+]);
+
+const LIVE_EVENT_TYPE_SET = new Set(LIVE_EVENT_TYPES);
+
+/**
+ * Emit a Live Mode telemetry event.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot   Repo root — injected as the emitter `baseDir` so the
+ *                                     chain file resolves under it (testable / hermetic).
+ * @param {string} args.type          One of LIVE_EVENT_TYPES. Anything else throws.
+ * @param {string} args.sessionId     Stable per-session id (correlates the event stream).
+ * @param {object} [args.payload]     Free-form, event-specific payload (MVP: opaque object).
+ * @param {(() => number)} [args.now] Injectable clock returning epoch ms (default Date.now).
+ * @returns {{event_id: string, type: string, timestamp: string, sessionId: string, payload: object}}
+ *          The projected envelope (also the shape that validates against events.schema.json).
+ */
+function emitLiveEvent(args = {}) {
+  const { projectRoot, type, sessionId, payload } = args;
+  const now = typeof args.now === 'function' ? args.now : Date.now;
+
+  if (!LIVE_EVENT_TYPE_SET.has(type)) {
+    throw new Error(
+      `emitLiveEvent: unknown live event type "${String(type)}". ` +
+        `Expected one of: ${LIVE_EVENT_TYPES.join(', ')}.`,
+    );
+  }
+  if (typeof sessionId !== 'string' || sessionId.length === 0) {
+    throw new TypeError('emitLiveEvent: sessionId is required (non-empty string)');
+  }
+
+  const timestamp = new Date(now()).toISOString();
+  const envelopePayload = payload && typeof payload === 'object' ? payload : {};
+
+  // Mirror the router_pick emit surface: write a chain row carrying the events-schema
+  // envelope fields verbatim. agent/outcome are the chain emitter's required fields.
+  const event_id = appendChainEvent({
+    baseDir: projectRoot,
+    agent: 'live',
+    outcome: type,
+    // Envelope fields preserved verbatim by appendChainEvent (opaque-extras pass-through):
+    type,
+    timestamp,
+    sessionId,
+    payload: envelopePayload,
+  });
+
+  return { event_id, type, timestamp, sessionId, payload: envelopePayload };
+}
+
+module.exports = { emitLiveEvent, LIVE_EVENT_TYPES };