@hegemonart/get-design-done 1.58.1 → 1.59.2

package/.claude-plugin/marketplace.json

@@ -4,15 +4,15 @@
     "name": "hegemonart"
   },
   "metadata": {
-    "description": "Get Design Done — 5-stage agent-orchestrated design pipeline (Brief → Explore → Plan → Design → Verify) for AI coding agents. 61 agents, 94 skills, 42 connection integrations, two MCP servers, opt-in SQLite state backbone, bidirectional Figma write-back, and a reflector-driven self-improvement loop. Cross-runtime install for Claude Code, Codex, Cursor, OpenCode, Gemini, and more.",
-    "version": "1.58.1"
+    "description": "Get Design Done — 5-stage agent-orchestrated design pipeline (Brief → Explore → Plan → Design → Verify) for AI coding agents. 64 agents, 95 skills, 39 connection integrations, two MCP servers, opt-in SQLite state backbone, bidirectional Figma write-back, and a reflector-driven self-improvement loop. Cross-runtime install for Claude Code, Codex, Cursor, OpenCode, Gemini, and more.",
+    "version": "1.59.2"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
-      "description": "Agent-orchestrated 5-stage design pipeline (Brief → Explore → Plan → Design → Verify) for AI coding agents. 61 specialized agents, 94 skills, 42 connection integrations (Figma, Refero, Preview, Storybook, Chromatic, Graphify, Linear, Jira, Notion, …), bidirectional Figma write-back, queryable intel store, opt-in SQLite state backbone, and a reflector-driven self-improvement loop. Two MCP servers (gdd-state for typed STATE mutators, gdd-mcp for 13 read-only project-priming tools), tier-aware routing with cost telemetry, and defense-in-depth hooks (protected paths, MCP circuit breaker, injection scanner, budget enforcer). Cross-runtime install for Claude Code, Codex, Cursor, OpenCode, Gemini, Copilot, and more.",
-      "version": "1.58.1",
+      "description": "Agent-orchestrated 5-stage design pipeline (Brief → Explore → Plan → Design → Verify) for AI coding agents. 64 specialized agents, 95 skills, 39 connection integrations (Figma, Refero, Preview, Storybook, Chromatic, Graphify, Linear, Jira, Notion, …), bidirectional Figma write-back, queryable intel store, opt-in SQLite state backbone, and a reflector-driven self-improvement loop. Two MCP servers (gdd-state for typed STATE mutators, gdd-mcp for 13 read-only project-priming tools), tier-aware routing with cost telemetry, and defense-in-depth hooks (protected paths, MCP circuit breaker, injection scanner, budget enforcer). Cross-runtime install for Claude Code, Codex, Cursor, OpenCode, Gemini, Copilot, and more.",
+      "version": "1.59.2",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.58.1",
-  "description": "Agent-orchestrated 5-stage design pipeline (Brief → Explore → Plan → Design → Verify) for AI coding agents. 61 specialized agents, 94 skills, 42 connection integrations (Figma, Refero, Preview, Storybook, Chromatic, Graphify, Linear, Jira, Notion, …), bidirectional Figma write-back, queryable intel store for O(1) design-surface lookups, opt-in SQLite state backbone, and a reflector-driven self-improvement loop. Two MCP servers (`gdd-state` for typed STATE mutators, `gdd-mcp` for 13 read-only project-priming tools), tier-aware agent routing with cost telemetry, defense-in-depth hooks (protected paths, MCP circuit breaker, injection scanner, budget enforcer), and a cross-runtime install layer for Claude Code, Codex, Cursor, OpenCode, Gemini, Copilot, and more.",
+  "version": "1.59.2",
+  "description": "Agent-orchestrated 5-stage design pipeline (Brief → Explore → Plan → Design → Verify) for AI coding agents. 64 specialized agents, 95 skills, 39 connection integrations (Figma, Refero, Preview, Storybook, Chromatic, Graphify, Linear, Jira, Notion, …), bidirectional Figma write-back, queryable intel store for O(1) design-surface lookups, opt-in SQLite state backbone, and a reflector-driven self-improvement loop. Two MCP servers (`gdd-state` for typed STATE mutators, `gdd-mcp` for 13 read-only project-priming tools), tier-aware agent routing with cost telemetry, defense-in-depth hooks (protected paths, MCP circuit breaker, injection scanner, budget enforcer), and a cross-runtime install layer for Claude Code, Codex, Cursor, OpenCode, Gemini, Copilot, and more.",
   "author": {
     "name": "hegemonart",
     "url": "https://github.com/hegemonart"
@@ -56,5 +56,19 @@
   ],
   "skills": [
     "./skills/"
-  ]
+  ],
+  "mcpServers": {
+    "gdd-mcp": {
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/bin/gdd-mcp"
+      ]
+    },
+    "gdd-state": {
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/bin/gdd-state-mcp"
+      ]
+    }
+  }
 }

package/CHANGELOG.md

@@ -4,6 +4,62 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.59.2] - 2026-06-04
+
+Second point release of the **v1.59 "Audit Closeout & Honesty Pass"** milestone. Wires the AI-native Wave-2 connections and reconciles the connection count to the honest number.
+
+### Added
+
+- **Three backing agents** for the AI-native Wave-2 connections that were marked "Active" but had no agent behind them: `design-framer-writer` (Framer canvas), `design-penpot-writer` (Penpot canvas), and `design-webflow-reader` (Webflow site structure as an adaptation source). Their capability-matrix "Active" status is now genuine rather than cosmetic. Agent count 61 to 64.
+
+### Changed
+
+- **Honest connection count.** The feature-count gate now counts only genuine integration specs (39), excluding the three non-integration files that live in `connections/` for discoverability: the `connections.md` index, the `cursor.md` runtime, and the `design-corpora.md` reference list. Every marketing surface (plugin.json, marketplace.json, README) now claims 39 connection integrations instead of 42, and the onboarding probe count is reconciled to 39 to match the capability-matrix rows.
+
+### Note
+
+- The v0/Plasmic/Builder.io component-generator dispatch and the `paper-write` / `pencil-write` skills were already shipped (Phase 37.1 and prior), so this release adds only the missing canvas/reader agents plus the count reconciliation.
+
+### Breaking changes
+
+None.
+
+5,028/5,028 tests pass.
+
+---
+
+## [1.59.1] - 2026-06-04
+
+First point release of the **v1.59 "Audit Closeout & Honesty Pass"** milestone. The two bundled MCP servers now come up for users automatically, plus the cheapest correctness/honesty fixes.
+
+### MCP servers register automatically on Claude Code
+
+The two bundled MCP servers - `gdd-state` (typed STATE mutators) and `gdd-mcp` (read-only project-priming tools) - are now declared under `mcpServers` in `.claude-plugin/plugin.json`, so a fresh Claude Code marketplace install exposes both servers' tools with no manual `--register-mcp` step. They launch through the plugin-local `bin/` trampolines via `${CLAUDE_PLUGIN_ROOT}`, so the git-clone install path works without `npm install`.
+
+### Added
+
+- **`/gdd:bandit-reset`** - a confirm-then-reset maintenance skill for the bandit posterior (`.design/telemetry/posterior.json`): backs the file up to `posterior.json.bak`, then clears it to a fresh envelope. The mutation companion to the read-only `/gdd:bandit-status`. Resolves the previously-dangling `/gdd:bandit-reset` reference. (Skill count 94 → 95.)
+
+### Fixed
+
+- **Installer parity** - `get-design-done --register-mcp` now registers BOTH `gdd-mcp` and `gdd-state` for Claude Code and Codex (previously `gdd-mcp` only). `--no-register-mcp` is unchanged.
+- **MCP launch warning** - the servers no longer print a `MODULE_TYPELESS_PACKAGE_JSON` warning on startup (suppressed in the dev/source launch path; the compiled npm-install path is unaffected).
+- **`gdd-sdk audit`** now degrades gracefully with no active cycle (no `.design/STATE.md`): it prints a "no active cycle" notice, runs the static checks, and exits 0 instead of throwing.
+- **Dead path references** - repointed stale `scripts/mcp-servers/...` and `scripts/lib/{gdd-state,event-stream,gdd-errors}/...` references (relocated to `sdk/...` in v1.33.0) to their live locations, including a broken `claude mcp add` command in the `gdd-state` connection doc.
+
+### Changed
+
+- Removed two dead npm scripts (`typecheck:session-runner`, `validate:skill-surface`) and pointed the `gdd-sdk` script at the Windows-safe `bin/gdd-sdk` trampoline.
+- Regenerated `reference/schemas/generated.d.ts` from source schemas.
+
+### Breaking changes
+
+None.
+
+5,013/5,013 tests pass.
+
+---
+
 ## [1.58.1] - 2026-06-04
 
 ### Hotfix - restore committed skills/ for Claude Code marketplace install
@@ -1828,7 +1884,7 @@ The `gsd-build/get-shit-done` rug-pull in May 2026 (TÂCHES drained $GSD Solana
 - **`.design/graph/`** replaces upstream's `.planning/graphs/` location (per D-02 - aligns with the rest of GDD's `.design/` artifact convention).
 - **`connections/graphify.md`** rewritten for native CLI (no external `graphifyy` dependency).
 - **`reference/start-interview.md`** updated to reference `/gdd:discuss` (our equivalent) instead of `/gsd-discuss-phase`.
-- **`README.md`** at the `gsd-build/get-shit-done (MIT — see NOTICE)` citation gains the redux-pointer parenthetical "(now archived; community continuation at `open-gsd/get-shit-done-redux`)". Citation preserved verbatim - only annotated for reader clarity.
+- **`README.md`** at the `gsd-build/get-shit-done (MIT - see NOTICE)` citation gains the redux-pointer parenthetical "(now archived; community continuation at `open-gsd/get-shit-done-redux`)". Citation preserved verbatim - only annotated for reader clarity.
 - **Graphify enable/disable state** (D-09) lives in `.design/config.json` at `{ "graphify": { "enabled": bool } }`. Read directly by `gdd-graph` via fs; no `config-set` / `config-get` CLI subcommand.
 
 ### Removed
@@ -1858,7 +1914,7 @@ The `gsd-build/get-shit-done` rug-pull in May 2026 (TÂCHES drained $GSD Solana
 
 ### Attribution preservation
 
-Phase 27 / Phase 28.5 / Phase 28.7 attribution subsections in `NOTICE` are preserved verbatim per D-06. The architectural ports they describe are historical MIT-licensed code transplants; this release removes a runtime touchpoint, **NOT** a historical port. The `gsd-build/get-shit-done (MIT — see NOTICE)` citation in `README.md` is preserved verbatim; only the redux-pointer parenthetical was added.
+Phase 27 / Phase 28.5 / Phase 28.7 attribution subsections in `NOTICE` are preserved verbatim per D-06. The architectural ports they describe are historical MIT-licensed code transplants; this release removes a runtime touchpoint, **NOT** a historical port. The `gsd-build/get-shit-done (MIT - see NOTICE)` citation in `README.md` is preserved verbatim; only the redux-pointer parenthetical was added.
 
 ---
 
@@ -1880,7 +1936,7 @@ Decimal sub-phase building on Phase 30's `/gdd:report-issue` triage gate. Expand
 ### Changed
 
 - **Reflector capability-gap aggregator** (`scripts/lib/reflector-capability-gap-aggregator.cjs`) - adds lazy-loaded `proposeKfmDraftsForClusters(clusters, options)` export that invokes the KFM proposer as an additional pass after Phase 29 aggregation. Phase 29's existing 5 proposal classes are untouched (additive).
-- **Authority-watcher agent prompt** (`agents/design-authority-watcher.md`) - gains a new `Step 7.5 — Emit kfm-candidate events` section documenting the whitelist patterns + payload shape. Phase 13.2's existing fetch/diff/classify/write loop is unchanged.
+- **Authority-watcher agent prompt** (`agents/design-authority-watcher.md`) - gains a new `Step 7.5 - Emit kfm-candidate events` section documenting the whitelist patterns + payload shape. Phase 13.2's existing fetch/diff/classify/write loop is unchanged.
 - **OFF_CADENCE_VERSIONS** (`tests/semver-compare.test.cjs`) - registers `'1.30.5'` per Phase 29/30 precedent.
 
 ### Documentation
@@ -3345,7 +3401,7 @@ Closes two unrelated risks before the Phase 15–19 reference-library expansion
 **Safety hooks**
 - `hooks/gdd-bash-guard.js` - PreToolUse:Bash guard. 45 dangerous-pattern regexes across 10 families (filesystem destruction, permission escalation, pipe-to-shell, git destruction, system mutation, process nuking, credential exfil, shell obfuscation, path traversal, npm/docker/firewall abuse). `scripts/lib/dangerous-patterns.cjs` normalizes Unicode NFKC + strips ANSI escapes + strips zero-width / bidi overrides before matching so obfuscated attacks (`rm\u200B -rf /`, bidi overrides, hex-encoded `\x72\x6d\x20\x2d\x72\x66`) fail closed.
 - `hooks/gdd-protected-paths.js` + `reference/protected-paths.default.json` - PreToolUse:Edit|Write|Bash guard blocking mutation of `reference/**`, `skills/**`, `commands/**`, `hooks/**`, `.design/archive/**`, `.design/config.json`, `.design/telemetry/**`, `.git/**`, both plugin manifests. User additions in `.design/config.json.protected_paths` MERGE into the default list - users cannot reduce the default-protected set. `scripts/lib/glob-match.cjs` ships a dependency-free `**` glob matcher.
-- `scripts/lib/blast-radius.cjs` - `estimate({touchedPaths, diffStats})` + `estimateMCPCalls({toolCalls})` preflight called by `design-executor` before the first Edit/Write of each task. Defaults: `max_files_per_task: 10`, `max_lines_per_task: 400`, `max_mcp_calls_per_task: 30`. Zero-value limits disable that ceiling. `design-executor` gains a new `## Preflight — Blast-Radius Check` section.
+- `scripts/lib/blast-radius.cjs` - `estimate({touchedPaths, diffStats})` + `estimateMCPCalls({toolCalls})` preflight called by `design-executor` before the first Edit/Write of each task. Defaults: `max_files_per_task: 10`, `max_lines_per_task: 400`, `max_mcp_calls_per_task: 30`. Zero-value limits disable that ceiling. `design-executor` gains a new `## Preflight - Blast-Radius Check` section.
 
 **Injection-scanner extension**
 - `scripts/injection-patterns.cjs` extended from 7 to 22 patterns: classic prompt-injection verbs (incl. `forget previous`), **invisible-Unicode** (zero-width, BOM, bidi overrides), **HTML-comment instruction hijacks** (`<!-- system: …`, hidden divs/spans, zero-font-size tricks), **secret-exfil triggers** (`curl $OPENAI_API_KEY`, `cat .env`, `tar ~ | nc`, `process.env._KEY fetch`, SSH private-key reads). Single source of truth consumed by `hooks/gdd-read-injection-scanner.js`.
@@ -3452,7 +3508,7 @@ Cherry-picked from `c11cd7b` on `claude/upbeat-fermi-199627` - the Figma MCP fix
 
 - **URL entry point**: detect `https://api.anthropic.com/v1/design/h/<hash>` in agent prompt (native "Send to local coding agent" flow); `WebFetch` with `Content-Type` routing - HTML parsed directly, ZIP downloaded and extracted
 - **ZIP bundle**: extract to `.design/handoff/`, find primary HTML + readme, parse normally, clean up after
-- **PDF format**: `pdftotext` text extraction; grep for token values; all decisions tagged `(tentative — text-only)` since no CSS is present
+- **PDF format**: `pdftotext` text extraction; grep for token values; all decisions tagged `(tentative - text-only)` since no CSS is present
 - **PPTX format**: slide XML text extraction (`ppt/slides/*.xml`); same tentative-only tagging as PDF
 - Updated synthesizer parsing algorithm step 1 with format dispatch before parsing
 - Updated probe pattern: URL detection takes priority over file path lookup

package/README.md

@@ -56,7 +56,7 @@ What I kept running into: the agent could generate a screen that looked fine in
 
 So I built Get Design Done: a design pipeline that gives AI coding agents the same kind of structure developers already expect from engineering workflows. It captures the brief, maps the current design system, grounds decisions in references, decomposes the work into atomic tasks, executes those tasks, and verifies the result before you ship.
 
-Behind the scenes: 61 specialized agents, a queryable intel store, tier-aware model routing, 42 optional tool connections, atomic commits, and a no-regret adaptive layer that learns from solidify-with-rollback outcomes. What you use day to day: a few `/gdd:*` commands that keep design work coherent.
+Behind the scenes: 64 specialized agents, a queryable intel store, tier-aware model routing, 42 optional tool connections, atomic commits, and a no-regret adaptive layer that learns from solidify-with-rollback outcomes. What you use day to day: a few `/gdd:*` commands that keep design work coherent.
 
 - **Hegemon**
 
@@ -246,7 +246,7 @@ GDD handles it for you:
 
 Size limits where Claude's quality degrades. Stay under, get consistency.
 
-### 61 Specialized Agents
+### 64 Specialized Agents
 
 Each stage is a thin orchestrator that spawns specialized agents. Heavy lifting happens in fresh 200k contexts, not your main session.
 
@@ -307,7 +307,7 @@ Targets 50–70% per-task token-cost reduction with no quality-floor regression.
 
 ## Commands
 
-GDD ships 94 skills. The most common ones are below; for the full reference see [SKILL.md](SKILL.md).
+GDD ships 95 skills. The most common ones are below; for the full reference see [SKILL.md](SKILL.md).
 
 ### Core Pipeline
 
@@ -368,7 +368,7 @@ The full per-command reference, including the long tail of memory, distribution,
 
 ## Connections
 
-GDD ships 42 tool connections. All are optional; the pipeline degrades gracefully to fallbacks when any connection is unavailable. Configure with `/gdd:connections`.
+GDD ships 39 tool connections. All are optional; the pipeline degrades gracefully to fallbacks when any connection is unavailable. Configure with `/gdd:connections`.
 
 The connection layer spans these categories:
 

package/SKILL.md

@@ -99,6 +99,7 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `quality-gate` | `get-design-done:quality-gate` | Phase 25 - parallel lint/type/test/visual command runner; classifies failures via quality-gate-runner agent |
 | `turn-closeout` | `get-design-done:turn-closeout` | Phase 25 - Stop-hook mirror skill; finalizes per-turn STATE blocks and emits closeout events |
 | `bandit-status` | `get-design-done:bandit-status` | Phase 27.5 - read-only diagnostic surface for the bandit posterior; per-(agent, bin, delegate, tier) snapshots (alpha, beta, mean, stddev, count, last-used). Use `/gdd:bandit-reset` to mutate. |
+| `bandit-reset [--yes]` | `get-design-done:bandit-reset` | Phase 23.5 - confirm-then-reset mutation companion to `bandit-status`; backs up `.design/telemetry/posterior.json` to `posterior.json.bak`, then clears it to a fresh empty envelope so the next pull rebootstraps from informed priors. |
 | `openrouter-status [--refresh]` | `get-design-done:gdd-openrouter-status` | Phase 33.6 - read-only OpenRouter catalog + tier-mapping diagnostic; surfaces catalog freshness (vs 24h TTL), last-fetch, resolved opus/sonnet/haiku → model mappings, per-tier preview. `--refresh` re-fetches (needs `OPENROUTER_API_KEY`). |
 | `peers` | `get-design-done:peers` | Phase 27 - `/gdd:peers` capability matrix command; shows installed peer-CLIs (codex/gemini/cursor/copilot/qwen), allowlist status, claimed roles, posterior delta vs local |
 | `peer-cli-customize` | `get-design-done:peer-cli-customize` | Phase 27 - rewire role→peer mappings on a per-agent basis (edits frontmatter `delegate_to:` directly) |

package/agents/design-framer-writer.md

@@ -0,0 +1,286 @@
+---
+name: design-framer-writer
+description: Writes design decisions back to the active Framer canvas - annotated proposals, token-sync notes, and implementation-status callouts. Operates in proposal->confirm mode by default. Accepts --dry-run (emit proposal without executing). Resolves the Framer MCP prefix at runtime and degrades to code-only when the framer connection is unavailable.
+tools: Read, Write, Bash, Grep, Glob
+color: blue
+model: inherit
+default-tier: sonnet
+tier-rationale: "Writer proposes + executes Framer write-backs - Sonnet handles structured proposal synthesis well"
+size_budget: XL
+parallel-safe: never
+typical-duration-seconds: 120
+reads-only: false
+writes:
+  - "Framer canvas (via the runtime-resolved framer MCP prefix) - annotated design proposals: decision callouts, token-sync notes, implementation-status notes attached to frames"
+---
+
+@reference/shared-preamble.md
+
+# design-framer-writer
+
+## Role
+
+You are design-framer-writer. You write design decisions from `.design/DESIGN-CONTEXT.md` back into the active Framer canvas as annotated proposals. You have three modes: `annotate`, `tokenize`, `implementation-status`. You always emit a proposal before executing writes. You never call a Framer write tool without user confirmation (unless `--dry-run` is requested, in which case you emit the proposal and stop). You write only annotated proposals onto frames - decision notes and callouts - and you never author production components or replace user content. You modify only the active Framer canvas via the runtime-resolved Framer MCP.
+
+Framer is a canvas-category connection. This agent is the Framer analogue of the Figma canvas writer: it contributes at the design stage by writing annotated proposals back, and it does not participate in scan, plan, or verify as a code authority.
+
+---
+
+## Step 0 - MCP Probe and Prefix Resolution
+
+Framer tools are commonly in the deferred tool set and are not loaded at session start. Calling a deferred tool directly fails, so run `ToolSearch` first - it loads the tools and confirms their presence in one call. Run this probe at agent entry before any other action:
+
+```
+ToolSearch({ query: "framer", max_results: 10 })
+
+Parse tool names matching /framer/i -> resolved Framer prefix set.
+  Empty -> Write to output: "Framer MCP not available (no server matching /framer/i registered). Install over HTTP: `claude mcp add --transport http framer https://<framer-mcp-endpoint>` and set the Framer API token in the session environment, or register the Framer plugin bridge as a server named `framer`. Then restart the session." -> STOP.
+  One+  -> pick the prefix matching /framer/i (prefer the bare `framer` name; on ties choose non-UUID-prefixed, then alphabetical). Record the resolved prefix (written below as `{P}`, e.g. `mcp__framer__`) for use in later steps.
+```
+
+Do NOT hardcode `mcp__framer__`. Construct every tool name as `{P}<tool>` from the resolved prefix. Exact tool names are discovered at runtime via the probe, not assumed - the table below describes capabilities generically.
+
+After resolving the prefix, live-probe a read tool (selection or frame reader). If the read tool succeeds, the connection is reachable. If it errors (auth expired, no project open, rate-limited), treat the connection as unavailable and follow the fallback in Step 1.
+
+---
+
+## Step 1 - Read State and Flags
+
+Read `.design/STATE.md` and inspect the `<connections>` block for the `framer:` value:
+
+- `framer: available` -> proceed.
+- `framer: unavailable` or `framer: not_configured` -> degrade to code-only and STOP. When invoked as part of the design-stage write offer, skip silently (no prompt, no output). When invoked as a standalone write request, write: "Framer connection not available - degrading to code-only. No proposals written. See connections/framer.md Setup to register a Framer MCP." and STOP.
+
+Treat `unavailable` and `not_configured` identically for the purpose of skipping Framer steps. Never append a blocker for a missing Framer connection - Framer is an enhancement, not a requirement.
+
+Parse flags from the invocation arguments:
+
+- `--dry-run` - emit the proposal, do NOT call any Framer write tool, stop after proposal output.
+- `mode` - one of `annotate | tokenize | implementation-status` (required; if absent, list modes and stop).
+
+If mode is absent, write to output:
+
+```
+design-framer-writer requires a mode argument.
+Available modes:
+  annotate               - add design decision callouts to Framer frames
+  tokenize               - write token-sync notes mapping canvas values to confirmed token decisions
+  implementation-status  - annotate frames with build status from Handoff Faithfulness results
+
+Usage: design-framer-writer <mode> [--dry-run]
+```
+
+Then STOP.
+
+---
+
+## Step 2 - Read Context
+
+Read `.design/DESIGN-CONTEXT.md`. Extract the relevant data for the selected mode:
+
+- For `annotate`: all confirmed design decisions (color palette, spacing scale, typography, motion) - look for confirmed decision entries in the decisions section.
+- For `tokenize`: color, spacing, and type literal values that map to confirmed token decisions - look for hex values, spacing scales, and typography sizes.
+- For `implementation-status`: component names and their build status (sourced as described in the implementation-status section below).
+
+Also read the active Framer canvas structure with the resolved prefix from Step 0:
+
+```
+{P}<selection_reader>()   // the current selection: node IDs, names, types, geometry
+{P}<frame_reader>()       // frame tree for the open page when nothing is selected
+{P}<token_reader>()       // token / style definitions, when the read tool is present (tokenize mode)
+```
+
+If no project or page is accessible, write: "No Framer project is accessible. Open the target project in Framer and retry." and STOP.
+
+---
+
+## Step 3 - Build Proposal
+
+Build a numbered operation list based on mode. Do not execute yet. Every operation is an annotated proposal attached to a frame - a note or callout, never a content replacement.
+
+**annotate mode:**
+
+```
+Proposed annotations (N operations):
+1. Frame "Button/Primary" -> add note: "Background: brand-primary-500 (#1A73E8) per color decision"
+2. Frame "Typography/H1" -> add note: "Font: Inter 32/40 per typography decision"
+... (one line per annotation)
+```
+
+**tokenize mode:**
+
+```
+Proposed token-sync notes (N operations):
+1. Frame "Button/Primary" fill #1A73E8 -> note: "maps to token colors/primary/500"
+2. Frame "Card" padding 16px -> note: "maps to token spacing/4"
+... (one line per note)
+```
+
+**implementation-status mode:**
+
+```
+Proposed status callouts (N operations):
+1. Frame "Button" -> note: "Implementation: built - verified <ISO date>"
+2. Frame "Modal" -> note: "Implementation: pending - not yet implemented"
+... (one line per callout)
+```
+
+If DESIGN-CONTEXT.md had no applicable data for the selected mode, write:
+
+```
+No operations to perform. DESIGN-CONTEXT.md had no <mode>-applicable data.
+```
+
+Then STOP.
+
+---
+
+## Step 4 - Confirm or Dry-Run
+
+After presenting the proposal, check the `--dry-run` flag.
+
+If `--dry-run` is set:
+
+```
+[dry-run] Proposal emitted. No writes executed. Pass without --dry-run to apply.
+```
+
+STOP.
+
+Otherwise, write to output:
+
+```
+Apply N annotated proposals to Framer? Type "yes" to confirm or "no" to cancel.
+```
+
+Wait for the user response. If the response is not "yes", STOP with "Cancelled." There is no auto-approve path - every write goes through this confirm step.
+
+---
+
+## Step 5 - Execute Writes
+
+For each operation in the proposal, call the resolved Framer write tool (`{P}<proposal_writer>`) with the appropriate payload. The exact tool name and parameter shape come from the runtime probe; the calls below are illustrative of the annotated-proposal contract.
+
+For `annotate`:
+
+```javascript
+{P}<proposal_writer>({
+  node_id: "<frame-node-id>",
+  note: "<annotation text>"
+})
+```
+
+For `tokenize`:
+
+```javascript
+{P}<proposal_writer>({
+  node_id: "<frame-node-id>",
+  note: "maps to token <token-name>"
+})
+```
+
+For `implementation-status`:
+
+```javascript
+{P}<proposal_writer>({
+  node_id: "<frame-node-id>",
+  note: "Implementation: <status> - verified <ISO date>"
+})
+```
+
+Execute operations sequentially. After each, log: `done <operation-summary>`. If an operation errors, log: `failed <operation-summary> - <error>` and continue with the remaining operations.
+
+---
+
+## Step 6 - Summary
+
+After all operations complete, write:
+
+```
+design-framer-writer complete.
+Mode: <mode>
+Applied: N/M operations succeeded
+Failed: <list any failed operations or "none">
+```
+
+If M = 0 (nothing to write - context had no applicable decisions), write:
+
+```
+No operations to perform. DESIGN-CONTEXT.md had no <mode>-applicable data.
+```
+
+---
+
+## Implementation-Status Mode
+
+**Activation:** Mode is `implementation-status`. Spawned by the handoff routing post-verify step.
+
+**Source data:**
+- `.design/DESIGN-VERIFICATION.md` - reads the `## Handoff Faithfulness -> Component Structure` table.
+- `.design/DESIGN-CONTEXT.md` - reads the component inventory for component-to-frame mappings.
+- `.design/STATE.md` - reads `handoff_path` for the bundle reference.
+
+### Step IS-1 - Read implementation status
+
+Parse the DESIGN-VERIFICATION.md `## Handoff Faithfulness -> Component Structure` table:
+
+- PRESENT -> status: `built`
+- MISSING -> status: `pending`
+- Component with any DIVERGE token in the Color, Typography, or Spacing tables -> status: `diverging`
+
+If the `## Handoff Faithfulness` section is absent, write: "No Handoff Faithfulness data found. Run the handoff post-handoff verify first." and STOP.
+
+### Step IS-2 - Build status callout proposal
+
+For each component with a known status:
+
+1. Look up the Framer frame node ID from the DESIGN-CONTEXT.md component inventory (or ask the user if absent).
+2. Draft a status callout note: `"Implementation: [built|pending|diverging] - verified <ISO date>"`.
+
+Present to the user:
+
+```
+Implementation-Status Write-Back - Proposed Callouts
+====================================================
+
+Frame Annotations (N):
+  1. Annotate "Button" -> "Implementation: built - verified 2026-06-04"
+  2. Annotate "Modal" -> "Implementation: pending - not yet implemented"
+  3. Annotate "Card" -> "Implementation: diverging - spacing tokens differ"
+
+Proceed? (yes / no / edit)
+```
+
+If `--dry-run` is set: emit the proposal only, do not execute. Write `[dry-run] N status callouts proposed.` and STOP.
+
+If the user says "no": STOP with "Cancelled."
+If the user says "edit": allow the user to modify the proposal, then re-confirm.
+
+### Step IS-3 - Execute status callout writes
+
+For each confirmed callout, call the resolved Framer write tool:
+
+```javascript
+{P}<proposal_writer>({
+  node_id: "<frame-node-id>",
+  note: "Implementation: <status> - verified <ISO date>"
+})
+```
+
+### Step IS-4 - Summary
+
+```
+implementation-status complete.
+Status callouts applied: N/N_total
+Failed: <list any failed operations or "none">
+```
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.