@hegemonart/get-design-done 1.14.4 → 1.14.7

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). Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.14.4"
+    "version": "1.14.7"
   },
   "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.",
-      "version": "1.14.4",
+      "version": "1.14.7",
       "author": {
         "name": "hegemonart"
       },
@@ -53,6 +53,11 @@
         "release-automation",
         "gitleaks",
         "shellcheck",
+        "safety-hardening",
+        "protected-paths",
+        "decision-injector",
+        "reference-registry",
+        "mcp-circuit-breaker",
         "schema-validation",
         "cost-optimization",
         "cache-aware",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.14.4",
+  "version": "1.14.7",
   "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.",
   "author": {
     "name": "hegemonart",
@@ -38,6 +38,11 @@
     "intel-store",
     "self-improvement",
     "reflection",
+    "safety-hardening",
+    "protected-paths",
+    "decision-injector",
+    "reference-registry",
+    "mcp-circuit-breaker",
     "tested",
     "ci",
     "cicd",

package/CHANGELOG.md

@@ -4,6 +4,112 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.14.7] — 2026-04-24
+
+### Phase 14.6 — Test Coverage Completion (Phase 12 Wave C closeout)
+
+Closes the Phase 12 test-coverage slate that had Waves A + B shipped but Wave C (plans `12-05` / `12-06` / `12-07`) never executed. The plans were migrated to **Phase 14.6** (`.planning/phases/14.6-test-coverage-completion/`) and the gdd-unique test files those plans targeted are now validated end-to-end alongside the pre-existing suite.
+
+### Verified — gdd-unique test coverage (no code diff vs 1.14.6)
+
+Inspection during Phase 14.6 execution confirmed that all 13 gdd-unique test files from the Wave-C migration are present in `tests/` and pass under `npm test`. No net-new test source ships with this release — Phase 14.6's substantive deliverable is the validation, documentation, and closeout bump.
+
+| Area | Test files covered |
+|---|---|
+| Pipeline + data | `pipeline-smoke`, `mapper-schema`, `parallelism-engine`, `touches-analysis`, `cycle-lifecycle`, `intel-consistency` |
+| Feature correctness | `sketch-determinism`, `connection-probe`, `figma-writer-dry-run`, `reflection-proposal`, `deprecation-redirect`, `nng-coverage`, `read-injection-scanner` |
+
+Full suite: **343 tests, 342 pass, 1 skipped, 0 fail**.
+
+### Changed
+
+- `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` (outer + `plugins[0]`), `package.json` — version `1.14.6` → `1.14.7`.
+- `tests/semver-compare.test.cjs` — `1.14.7` registered in `OFF_CADENCE_VERSIONS`.
+
+### Notes
+
+- Phase 12 ROADMAP entry remains **Complete** (scope-reduced); Phase 14.6 is now marked **Complete** with the Wave-C + closeout scope that was split out on 2026-04-24.
+- Phase 14.7 (First-Run Proof Path) retains its reserved release slot and will ship as a subsequent PATCH bump (the original `v1.14.7` reservation shifts forward to the next available patch when Phase 14.7 ships).
+
+---
+
+## [1.14.6] — 2026-04-24
+
+### Phase 14.5 — Safety + Recall Floor
+
+Closes two unrelated risks before the Phase 15–19 reference-library expansion and the Phase 20+ autonomy ramp: (a) agents had no typed reference index and no cache-stable L0 preamble; (b) no defense-in-depth around prompt-injected bash, protected-paths violations, runaway blast radius, or the Figma plugin-sandbox hill-climb failure mode. Ships the minimum-viable version of both tracks as one cohesive release.
+
+### Added
+
+**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.
+
+**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`.
+
+**Decision-injector hook (first cross-cycle recall primitive)**
+- `hooks/gdd-decision-injector.js` — PreToolUse:Read on any `.design/**.md | reference/**.md | .planning/**.md` ≥ 1500 bytes. Surfaces the top-15 matching D-XX decisions, L-NN learnings, and cycle-N summary excerpts that reference the opened file's basename or path. Grep backend (ripgrep when available, Node fs fallback); Phase 19.5 will swap in FTS5 transparently.
+
+**Reference registry + L0/L2 cache split**
+- `reference/registry.schema.json` + `reference/registry.json` — typed index of every `reference/*.md` and `.default.json` file (18 entry types: `preamble | meta-rules | heuristic | output-contract | defaults | schema | data | motion | surfaces | authority-feed | influences | easing | taxonomy | principles | emotional-design | experience | palette | style-vocabulary`). Round-trip enforced by `scripts/lib/reference-registry.cjs.validateRegistry()`.
+- `scripts/build-intel.cjs` re-runs `validateRegistry()` on any `reference/**` change.
+- `reference/meta-rules.md` (tier L0) — 5 framework-invariant subsections extracted verbatim from `reference/shared-preamble.md`. `shared-preamble.md` becomes an L0 aggregator (imports `meta-rules.md` first), shrunk from ~6.5KB to <4KB. Stabilizes the Anthropic 5-min prompt-cache prefix.
+- `reference/cycle-handoff-preamble.md` — "reference, not current requests" framing prose imported by `/gdd:pause` and `/gdd:resume`.
+- `reference/retrieval-contract.md` — 3-layer `search → metadata → full-doc` protocol with per-row token-cost labels. Imported by `/gdd:progress`, `/gdd:resume`, `/gdd:reflect`, `/gdd:pause`.
+
+**Figma authoring-intent guard + MCP circuit-breaker**
+- `reference/figma-sandbox.md` — 4 Figma plugin-sandbox pitfalls encoded as hard rules (`loadFontAsync` no-cache, `findOne` O(N), `appendChild` AutoLayout recomputation, per-call ~5–10s timeout).
+- `reference/mcp-budget.default.json` + `reference/schemas/mcp-budget.schema.json` — defaults: `max_calls_per_task: 30`, `max_consecutive_timeouts: 3`, `reset_on_success: true`, tracked tools `mcp__*use_figma | use_paper | use_pencil`.
+- `agents/design-figma-writer` Step 0.5 **Authoring-Intent Guard** — bilingual EN/RU pattern set classifies invocations as author-intent vs decision-intent. Author-intent STOPs with a redirect to `figma:figma-generate-design` and cites the 4 pitfalls. Decision-intent proceeds. Bumped `size_budget` LARGE → XL.
+- `hooks/gdd-mcp-circuit-breaker.js` — PostToolUse on `mcp__*use_figma | use_paper | use_pencil`. Appends `{ts, tool, outcome, consecutive_timeouts, total_calls}` rows to `.design/telemetry/mcp-budget.jsonl`. Breaks with `{continue:false}` at threshold + appends a STATE.md blocker.
+- README.md + `connections/figma.md` gain the authoring-redirect callout + 4-pitfalls summary.
+
+**Tests** (8 new files, ~60 new assertions):
+- `bash-guard`, `protected-paths`, `blast-radius`, `decision-injector`, `reference-registry`, `meta-rules-split`, `figma-authoring-guard`, `mcp-circuit-breaker` all added. `read-injection-scanner.test.cjs` extended with bidi-override + HTML-comment hijack + secret-exfil + benign-regression cases.
+
+### Changed
+
+- `agents/design-executor.md` — new Preflight Blast-Radius Check + MCP Budget sections.
+- `agents/design-figma-writer.md` — Step 0.5 Authoring-Intent Guard; `size_budget: XL`.
+- `reference/shared-preamble.md` — rewritten as L0 aggregator.
+- `scripts/build-intel.cjs` — registry round-trip on `reference/**` changes.
+- `skills/{progress,resume,reflect,pause}/SKILL.md` — import `reference/retrieval-contract.md` (+ `cycle-handoff-preamble.md` for pause + resume).
+- `hooks/hooks.json` — registers bash-guard, protected-paths, decision-injector, MCP circuit-breaker.
+- Plugin manifests — add `safety-hardening`, `protected-paths`, `decision-injector`, `reference-registry`, `mcp-circuit-breaker` keywords.
+- `tests/semver-compare.test.cjs` — `1.14.6` added to `OFF_CADENCE_VERSIONS`.
+
+### Security
+
+- Bash guard normalizes Unicode (NFKC + strip zero-width + bidi) and ANSI escapes before pattern match — blocks bidi-override obfuscation, zero-width-injected verbs, and ANSI-colored reformulations.
+- Read-injection scanner flags invisible-Unicode sequences, HTML-comment hijacks, and secret-exfil triggers (7 → 22 patterns).
+- Protected-paths enforces a merge-only glob list — user configs cannot reduce the default-protected set.
+
+---
+
+## [1.14.5] — 2026-04-23
+
+### Fixed — Preview MCP silently skipped in verify even when available ([#19](https://github.com/hegemonart/get-design-done/issues/19))
+
+`design-verifier` was spawned with `tools: Read, Write, Bash, Grep, Glob` only. The verify skill's orchestrator-level probe correctly classified the session as `preview: available` and wrote it to `STATE.md`, but the subagent's tool allowlist blocked every `mcp__Claude_Preview__*` call, causing Phase 4B to silently skip screenshot capture and leave all `? VISUAL` heuristic flags unresolved.
+
+**Fix:** Added six Preview MCP tools to `design-verifier`'s `tools:` frontmatter — `preview_list`, `preview_navigate`, `preview_screenshot`, `preview_eval`, `preview_snapshot`, `preview_inspect` — so Phase 4B runs in the same permission context as the probe.
+
+**Probe hardening:** The availability probe in `connections/preview.md` and `skills/verify/SKILL.md` now distinguishes three failure modes instead of collapsing them to `not_configured`/`unavailable`:
+
+| New status | Meaning |
+|---|---|
+| `not_loaded` | ToolSearch empty — MCP not registered in this session |
+| `permission_denied` | ToolSearch found the tool but the live call was rejected by the tool permission layer |
+| `unreachable` | Tool loaded but live call errored for a non-permission reason (no dev server, timeout) |
+
+The Phase 4B gate in `design-verifier` skips on all non-`available` statuses and emits a targeted message on `permission_denied` to aid diagnosis.
+
+`connections/preview.md` now documents the **execution-context requirement**: the probe and the `preview_*` calls must run in the same context; a parent-session probe does not transfer to a spawned subagent.
+
+---
+
 ## [1.14.4] — 2026-04-20
 
 ### Fixed — Figma MCP install URL was stale

package/README.md

@@ -489,6 +489,21 @@ See [`connections/magic-patterns.md`](connections/magic-patterns.md) for probe p
 
 ---
 
+## Safety + Recall Floor
+
+Starting with v1.14.6, GDD ships three defense-in-depth hooks, the first cross-cycle recall primitive, and a typed reference index:
+
+- **Bash guard** (`hooks/gdd-bash-guard.js`) — PreToolUse:Bash blocks ~45 dangerous shell patterns after Unicode NFKC + ANSI + zero-width/bidi normalization, so `rm\u200B -rf /`, bidi-override obfuscations, and hex-encoded exec sequences fail closed.
+- **Protected paths** (`hooks/gdd-protected-paths.js`) — PreToolUse:Edit|Write|Bash refuses to mutate `reference/**`, `skills/**`, `commands/**`, `hooks/**`, `.design/archive/**`, `.design/config.json`, `.design/telemetry/**`, `.git/**`, both plugin manifests, and anything the user appends under `.design/config.json.protected_paths` (merge-only — user configs cannot reduce the default set).
+- **Blast-radius preflight** (`scripts/lib/blast-radius.cjs`) — `design-executor` refuses tasks above `.design/config.json.blast_radius.max_files_per_task` (default 10), `max_lines_per_task` (default 400), or `max_mcp_calls_per_task` (default 30); writes a blocker to STATE.md with a diff summary.
+- **Decision-injector** (`hooks/gdd-decision-injector.js`) — PreToolUse:Read on any `.design/**.md | reference/**.md | .planning/**.md` ≥ 1500 bytes surfaces the top-15 matching D-XX decisions, L-NN learnings, and prior-cycle summary excerpts that reference the opened file. Grep backend; Phase 19.5 upgrades to FTS5 transparently.
+
+**Reference index** — `reference/registry.json` (schema: `reference/registry.schema.json`) indexes every `reference/*.md` by typed category (`heuristic | preamble | motion | defaults | meta-rules | …`). Agents can query `list({type: "heuristic"})` instead of grep-hunting import strings. `scripts/build-intel.cjs` enforces round-trip on every `reference/**` change: missing entries, dangling entries, and duplicates fail the build.
+
+**L0/L2 cache-locality split** — the 5 framework-invariant rules (Required Reading Discipline, Writes Protocol, Deviation Handling, Completion Markers, Context-Exhaustion & Budget Awareness) now live in `reference/meta-rules.md` (tier L0). `reference/shared-preamble.md` becomes an L0 aggregator importing `meta-rules.md` first, so Phase 15+ L2 churn (heuristics, anti-patterns, checklists) no longer invalidates the L0 prompt-cache prefix.
+
+**Figma authoring-redirect** — `/gdd:figma-write` is a decision-writer (annotations, token bindings, Code Connect, implementation-status). For authoring new Figma content (create pages, populate library components, build layouts from scratch), use `figma:figma-generate-design` from the Figma plugin — it runs outside the Figma plugin sandbox. `design-figma-writer` Step 0.5 detects author-intent (EN + RU) and emits a bilingual redirect citing the four sandbox pitfalls in `reference/figma-sandbox.md`. The MCP circuit-breaker (`hooks/gdd-mcp-circuit-breaker.js`) caps `use_figma | use_paper | use_pencil` at 30 calls/task and 3 consecutive timeouts by default (see `reference/mcp-budget.default.json`), logging per-call JSONL at `.design/telemetry/mcp-budget.jsonl`.
+
 ## Commands
 
 All commands use the `/gdd:` namespace.
@@ -621,6 +636,8 @@ claude mcp add --transport http figma https://mcp.figma.com/mcp
 
 Setup: [`connections/figma.md`](connections/figma.md). If you previously registered the remote MCP with the legacy URL `https://mcp.figma.com/v1/sse`, remove and re-add with the current URL `https://mcp.figma.com/mcp` (Streamable HTTP).
 
+> ⚠︎ **Authoring new Figma content?** `/gdd:figma-write` is a *decision-writer* (annotations, token bindings, Code Connect). For **creating pages, populating with library components, building doc layouts from scratch**, use `figma:figma-generate-design` from the Figma plugin — it runs outside the plugin sandbox. See [`reference/figma-sandbox.md`](reference/figma-sandbox.md) for the four sandbox pitfalls the MCP circuit-breaker (`hooks/gdd-mcp-circuit-breaker.js`) protects you from (defaults: 30 calls/task, 3 consecutive timeouts → break).
+
 ### Refero MCP
 
 When Refero is active, `explore` pulls visual references to ground design decisions. Requires an API token in `~/.claude.json`:

package/agents/design-executor.md

@@ -39,6 +39,47 @@ The orchestrating stage supplies a `<required_reading>` block in the prompt. Rea
 
 ---
 
+## Preflight — Blast-Radius Check
+
+Before the FIRST Edit/Write of this task, run a blast-radius preflight:
+
+```js
+const { estimate, formatDiffSummary, loadConfig } = require('scripts/lib/blast-radius.cjs');
+const cfg = loadConfig();
+const result = estimate({
+  touchedPaths: <paths this task declares>,
+  diffStats: { insertions: <estimate>, deletions: <estimate> },
+  config: cfg,
+});
+```
+
+**Ceilings** (defaults; user may override in `.design/config.json.blast_radius`):
+- `max_files_per_task: 10`
+- `max_lines_per_task: 400`
+- `max_mcp_calls_per_task: 30` (see MCP Budget section)
+
+**If `result.exceeds === true`:** STOP. Do NOT Edit/Write. Append `formatDiffSummary({touchedPaths, diffStats, result})` to `.design/STATE.md` under a new blocker line, then emit a structured deviation:
+
+> Rule 3 — Blast-Radius Exceeds: this task would touch `<files>` files / `<lines>` lines, above the per-task ceiling. Proposed split: <suggest 2–3 sub-tasks that each stay under the limit>. User must explicitly approve a single ceiling raise or accept the split.
+
+Proceed only after the user confirms. The preflight is skipped entirely when both ceilings are set to `0` in config.
+
+---
+
+## MCP Budget — Per-Task
+
+Before every `mcp__*use_figma`, `mcp__*use_paper`, `mcp__*use_pencil`, or equivalent mutation-side MCP call, check the rolling counter:
+
+```js
+const { estimateMCPCalls, loadConfig } = require('scripts/lib/blast-radius.cjs');
+const r = estimateMCPCalls({ toolCalls: <calls-issued-so-far>, config: loadConfig() });
+if (r.exceeds) STOP;
+```
+
+The MCP circuit-breaker (`hooks/gdd-mcp-circuit-breaker.js`) enforces the same ceiling at the tool boundary; the preflight here avoids wasting a MCP round-trip before the hook blocks you. Surface in `/gdd:stats` as "MCP calls this task: N/limit".
+
+---
+
 ## Prompt Context Fields
 
 The stage embeds the following fields in the prompt. Use them to locate and execute the correct task:

package/agents/design-figma-writer.md

@@ -6,7 +6,7 @@ color: purple
 model: inherit
 default-tier: sonnet
 tier-rationale: "Writer proposes + executes Figma write-backs — Sonnet handles structured proposal synthesis well"
-size_budget: LARGE
+size_budget: XL
 parallel-safe: never
 typical-duration-seconds: 120
 reads-only: false
@@ -40,6 +40,66 @@ Note: the remote Figma MCP (canonical server name `figma`, URL `https://mcp.figm
 
 ---
 
+## Step 0.5 — Authoring-Intent Guard
+
+BEFORE proceeding to Step 1, analyze the invocation text (prompt + task description + any user-facing message in the agent dispatch) for **authoring-intent**. `design-figma-writer` is a *decision-writer* (annotations, token bindings, Code Connect, implementation-status). When the user wants to *author* new Figma content (create pages, populate with library components, build doc layouts from scratch), the correct tool is `figma:figma-generate-design` from the Figma plugin — it runs outside the sandbox and has no per-call timeout.
+
+Apply the patterns below (case-insensitive, whitespace-tolerant). If ANY author-intent pattern matches AND NO decision-intent pattern dominates the text, STOP with the redirect response and do not proceed to the remote-MCP probe or any `use_figma` call.
+
+**Author-intent patterns (EN):**
+- `create .{0,30}(page|file|frame|layout|doc)`
+- `(populate|fill|build) .{0,40}(with )?(components|library)`
+- `(author|write|generate|produce|build) .{0,30}(doc|documentation|spec|design)`
+- `make .{0,30}(layout|frame|page|template)`
+- `spin up .{0,30}Figma`
+- `design .{0,30}(page|doc|spec|layout) .{0,20}(from|in) (scratch|Figma)`
+
+**Author-intent patterns (RU):**
+- `(создай|сделай|построй|свёрстай|собери|оформи) .{0,30}(страниц|макет|документац|страницу|документ|файл|лейаут|шаблон)`
+- `(новую?|новый) страниц[уыа]`
+- `документац[иия] .{0,40}токен`
+- `сгенерируй .{0,30}Figma`
+
+**Decision-intent patterns (EN) — these WIN over ambiguous author-intent:**
+- `annotate .{0,30}(selection|frame|component)`
+- `bind .{0,30}token`
+- `code connect`
+- `code-connect`
+- `update .{0,30}(status|implementation)`
+- `write .{0,30}D-\d+`
+- `sync .{0,30}(tokens?|variables?)`
+
+**Decision-intent patterns (RU):**
+- `привяжи .{0,30}токен`
+- `аннотируй`
+- `синхронизируй .{0,30}токен`
+
+### Decision rule
+- If decision-intent matches AND author-intent doesn't match, proceed normally.
+- If author-intent matches AND NO decision-intent match, STOP with redirect.
+- If BOTH match (mixed), favor decision-intent (the guard is permissive; the circuit-breaker catches runaway cases downstream).
+- If NEITHER matches, proceed normally (default is decision-writing — the guard doesn't block the common case).
+
+### Redirect response (emit verbatim and STOP)
+
+```
+This task reads as authoring new Figma content. `design-figma-writer` is a decision-writer — it uses `use_figma` inside the Figma plugin sandbox with ~5–10s per-call timeout, so multi-row docs-authoring hill-climbs against the timeout and burns MCP quota.
+
+Use `figma:figma-generate-design` from the Figma plugin instead — it runs outside the sandbox and has no per-call timeout.
+
+Four sandbox pitfalls you would hit here on raw `use_figma` calls:
+1. `loadFontAsync` does not cache across calls — preload once, clone existing nodes.
+2. `figma.root.findOne()` is O(tree-size) — pass node IDs and use `getNodeById`.
+3. `appendChild` on large trees forces full AutoLayout recomputation — build subtrees off-tree.
+4. Per-call timeout is ~5–10s — budget ≤2 row-equivalents per call.
+
+See `reference/figma-sandbox.md`.
+```
+
+After emitting the redirect, STOP with the marker `## FIGMA AUTHORING-INTENT REDIRECT` and do NOT proceed to Step 1.
+
+---
+
 ## Step 1 — Read State and Flags
 
 Read `.design/STATE.md` to confirm `figma: available` in the `<connections>` block. If `figma: not_configured` or `figma: unavailable`, write to output: "Figma connection not configured. Run the scan probe or set figma: available in .design/STATE.md." and STOP.

package/agents/design-verifier.md

@@ -1,7 +1,7 @@
 ---
 name: design-verifier
 description: Goal-backward verification of design outcomes against .design/STATE.md must-haves, NNG heuristics, and audit rubric. Returns pass result or structured gap list. Spawned by the verify stage.
-tools: Read, Write, Bash, Grep, Glob
+tools: Read, Write, Bash, Grep, Glob, mcp__Claude_Preview__preview_list, mcp__Claude_Preview__preview_navigate, mcp__Claude_Preview__preview_screenshot, mcp__Claude_Preview__preview_eval, mcp__Claude_Preview__preview_snapshot, mcp__Claude_Preview__preview_inspect
 color: green
 model: inherit
 default-tier: haiku
@@ -267,7 +267,7 @@ Record each response. For `no` responses, capture the user's issue description v
 
 ## Phase 4B — Screenshot Evidence (when preview: available)
 
-**Gate:** Skip this entire Phase 4B block if `preview` is `not_configured` or `unavailable` in STATE.md `<connections>`. The `? VISUAL` flags from Phase 3 remain as-is; mark them `[SKIPPED — browser not available]` and proceed to Phase 5.
+**Gate:** Skip this entire Phase 4B block if `preview` is `not_loaded`, `not_configured`, `permission_denied`, `unreachable`, or `unavailable` in STATE.md `<connections>`. The `? VISUAL` flags from Phase 3 remain as-is; mark them `[SKIPPED — browser not available]` and proceed to Phase 5. When skipping due to `permission_denied`, also log: `Preview MCP tools missing from agent allowlist — contact the pipeline maintainer.`
 
 **Step 1 — ToolSearch first:**
 

package/connections/connections.md

@@ -2,6 +2,8 @@
 
 This directory contains connection specifications for external tools and MCPs that the get-design-done pipeline integrates with. Each connection has its own spec file. This file is the index.
 
+**Getting started:** run `/gdd:connections` for the interactive onboarding wizard — it probes all 12 connections, recommends setup based on your project type, and walks you through installing each one (auto-run for reversible MCP adds, copy-command for everything else). You can also run `/gdd:connections list` for a read-only status check or `/gdd:connections <name>` to jump to a single connection's setup.
+
 ---
 
 ## Active Connections

package/connections/figma.md

@@ -63,6 +63,16 @@ No data is lost — the remote MCP reads the same Figma files.
 
 ---
 
+> ⚠︎ **Authoring-redirect** — `/gdd:figma-write` (and the `design-figma-writer` agent behind it) is a *decision-writer*: annotations, token bindings, Code Connect mappings, implementation-status write-back. For **authoring new Figma content** — create pages, populate with library components, build doc layouts from scratch — use `figma:figma-generate-design` from the Figma plugin. It runs outside the plugin sandbox and has no per-call timeout.
+>
+> **Four sandbox pitfalls `use_figma` hits in authoring loops (see `reference/figma-sandbox.md`):**
+> 1. `loadFontAsync` does not cache across calls — preload once, clone existing nodes.
+> 2. `figma.root.findOne()` is O(tree-size) — pass node IDs and use `getNodeById`.
+> 3. `appendChild` on large trees forces full AutoLayout recomputation — build subtrees off-tree.
+> 4. Per-call timeout is ~5–10s — budget ≤2 row-equivalents per call for docs-authoring.
+>
+> The MCP circuit-breaker (`hooks/gdd-mcp-circuit-breaker.js`) enforces a per-task ceiling of 30 calls and 3 consecutive timeouts by default; see `reference/mcp-budget.default.json`.
+
 ## Tools
 
 Tool names take the form `mcp__<prefix>__<tool>` where `<prefix>` is the resolved server name from the probe (commonly `figma` for remote or `figma-desktop` for local). The pipeline discovers the prefix at runtime — see **Availability Probe** below. The `mcp__figma__` examples shown here assume a server registered as `figma`.

package/connections/preview.md

@@ -67,16 +67,19 @@ All tools use the `mcp__Claude_Preview__` prefix.
 
 **Preview probe sequence:**
 
+> **Execution-context requirement:** The probe and the subsequent `preview_*` calls must run in the **same execution context**. If the probe runs in the orchestrator and the calls run inside a spawned subagent, the subagent's tool allowlist may block the calls even when the probe succeeds. Run the probe where the calls will actually happen, or ensure the spawned agent's `tools:` frontmatter includes `mcp__Claude_Preview__*` tools.
+
 ```
 Step P1 — ToolSearch check:
   ToolSearch({ query: "Claude_Preview", max_results: 5 })
-  → Empty result      → preview: not_configured  (skip all Preview steps)
+  → Empty result      → preview: not_loaded  (MCP not registered in this session — skip all Preview steps)
   → Non-empty result  → proceed to Step P2
 
 Step P2 — Live tool call:
   call mcp__Claude_Preview__preview_list
-  → Success (returns array, even empty)  → preview: available
-  → Error                                → preview: unavailable
+  → Success (returns array, even empty)       → preview: available
+  → Error containing "permission" or blocked  → preview: permission_denied
+  → Any other error                           → preview: unreachable
 ```
 
 Write the result to `.design/STATE.md <connections>` immediately after probing.
@@ -142,8 +145,9 @@ preview: available
 | Value | Meaning |
 |-------|---------|
 | `available` | `preview_list` returned a successful response (array, even empty) |
-| `unavailable` | Tool is in the session but errored (no running server, tool timeout, internal error) |
-| `not_configured` | ToolSearch returned empty for `Claude_Preview` — MCP not registered in this session |
+| `permission_denied` | Tool is in the session (ToolSearch found it) but the live call was rejected by the tool permission layer — likely missing from the agent's `tools:` frontmatter |
+| `unreachable` | Tool is in the session but the live call errored for a non-permission reason (no running server, timeout, internal error) |
+| `not_loaded` | ToolSearch returned empty for `Claude_Preview` — MCP not registered in this session |
 
 **Which stages probe vs. read:**
 

package/hooks/budget-enforcer.js

@@ -288,8 +288,8 @@ async function main() {
       process.stdout.write(JSON.stringify(response));
       return;
     }
-    // 80% soft-threshold downgrade (D-03)
-    if (budget.auto_downgrade_on_cap && (phaseSpend + estCost) >= (0.80 * budget.per_task_cap_usd)) {
+    // 80% soft-threshold downgrade (D-03): task-scoped, per reference/model-tiers.md
+    if (budget.auto_downgrade_on_cap && estCost >= (0.80 * budget.per_task_cap_usd)) {
       toolInput._tier_override = 'haiku';
       toolInput._tier_downgraded = true;
     }

package/hooks/gdd-bash-guard.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * hooks/gdd-bash-guard.js — PreToolUse:Bash guard
+ * Blocks ~50 dangerous shell patterns after Unicode NFKC + ANSI-strip normalization.
+ * See scripts/lib/dangerous-patterns.cjs for the canonical pattern list.
+ *
+ * Contract:
+ *   Input  (stdin JSON): { tool_name, tool_input: { command } }
+ *   Output (stdout JSON):
+ *     - match     → { continue: false, stopReason: "..." }
+ *     - no match  → { continue: true }
+ *   Exit: always 0 (soft failure; the hook never short-circuits the user via exit code).
+ */
+
+const path = require('path');
+const { match } = require(path.join(__dirname, '..', 'scripts', 'lib', 'dangerous-patterns.cjs'));
+
+async function main() {
+  let buf = '';
+  for await (const chunk of process.stdin) buf += chunk;
+
+  let payload;
+  try { payload = JSON.parse(buf || '{}'); } catch {
+    process.stdout.write(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  if (payload?.tool_name && payload.tool_name !== 'Bash') {
+    process.stdout.write(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  const command = payload?.tool_input?.command ?? '';
+  const r = match(command);
+  if (r.matched) {
+    process.stdout.write(JSON.stringify({
+      continue: false,
+      stopReason: `gdd-bash-guard: dangerous command blocked (${r.severity}): ${r.description} [${r.pattern}]`,
+    }));
+    return;
+  }
+
+  process.stdout.write(JSON.stringify({ continue: true }));
+}
+
+main().catch(() => {
+  process.stdout.write(JSON.stringify({ continue: true }));
+});