@hegemonart/get-design-done 1.14.4 → 1.14.7

package/hooks/gdd-decision-injector.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * hooks/gdd-decision-injector.js — PreToolUse:Read cross-cycle recall hook.
+ *
+ * When an agent opens any .design/**.md | reference/**.md | .planning/**.md
+ * file ≥1500 bytes, surface the top-N D-XX decisions + L-NN learnings + prior-cycle
+ * CYCLE-SUMMARY/EXPERIENCE excerpts that mention the opened file's basename or path.
+ *
+ * Grep backend now (ripgrep when available, Node fs scan fallback). Phase 19.5
+ * swaps in FTS5 transparently — same matcher, same output shape.
+ *
+ * Contract (PreToolUse:Read):
+ *   stdin  : { tool_name: "Read", tool_input: { file_path }, cwd }
+ *   stdout : on match  → { continue: true, hookSpecificOutput: { additionalContext } }
+ *            otherwise → { continue: true }
+ *   exit   : always 0
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const MIN_BYTES = 1500;
+const TOP_N = 15;
+const MATCHER_RE = /[\\/](?:\.design|reference|\.planning)[\\/][^\n]*\.md$/;
+
+function ripgrepAvailable() {
+  try {
+    const r = spawnSync('rg', ['--version'], { encoding: 'utf8', windowsHide: true });
+    return r.status === 0;
+  } catch { return false; }
+}
+
+function grepLinesNode(filePath, terms) {
+  let content;
+  try { content = fs.readFileSync(filePath, 'utf8'); } catch { return []; }
+  const hits = [];
+  const lines = content.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const ln = lines[i];
+    for (const t of terms) {
+      if (t && ln.includes(t)) { hits.push({ file: filePath, line: i + 1, text: ln.trim() }); break; }
+    }
+  }
+  return hits;
+}
+
+function grepLinesRg(filePath, terms) {
+  const pattern = terms.filter(Boolean).map(escapeRe).join('|');
+  if (!pattern) return [];
+  const r = spawnSync('rg', ['-n', '--no-heading', '-S', pattern, filePath], { encoding: 'utf8', windowsHide: true });
+  if (r.status !== 0 && r.status !== 1) return [];
+  const out = [];
+  for (const line of (r.stdout || '').split(/\r?\n/)) {
+    const m = line.match(/^(\d+):(.*)$/);
+    if (m) out.push({ file: filePath, line: Number(m[1]), text: m[2].trim() });
+  }
+  return out;
+}
+
+function escapeRe(s) { return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+
+function findSearchSources(cwd) {
+  const roots = [];
+  const learnings = path.join(cwd, '.design', 'learnings', 'LEARNINGS.md');
+  const state     = path.join(cwd, '.design', 'STATE.md');
+  const cycles    = path.join(cwd, '.design', 'CYCLES.md');
+  if (fs.existsSync(learnings)) roots.push(learnings);
+  if (fs.existsSync(state))     roots.push(state);
+  if (fs.existsSync(cycles))    roots.push(cycles);
+
+  // archive/**/CYCLE-SUMMARY.md + archive/**/EXPERIENCE.md
+  const archive = path.join(cwd, '.design', 'archive');
+  if (fs.existsSync(archive)) {
+    try {
+      for (const cycleDir of fs.readdirSync(archive)) {
+        for (const leaf of ['CYCLE-SUMMARY.md', 'EXPERIENCE.md']) {
+          const p = path.join(archive, cycleDir, leaf);
+          if (fs.existsSync(p)) roots.push(p);
+        }
+      }
+    } catch { /* unreadable archive → skip */ }
+  }
+  return roots;
+}
+
+function cycleTagFor(file) {
+  const m = file.match(/[\\/]cycle-(\d+)[\\/]/);
+  if (m) return `cycle-${m[1]}`;
+  if (file.endsWith('LEARNINGS.md')) return 'learnings';
+  if (file.endsWith('STATE.md')) return 'state';
+  if (file.endsWith('CYCLES.md')) return 'cycles';
+  return 'archive';
+}
+
+function sortKeyFor(tag) {
+  // cycle-N: highest cycle wins; state/cycles secondary; learnings last
+  if (tag.startsWith('cycle-')) return 1000 + Number(tag.slice(6));
+  if (tag === 'cycles') return 100;
+  if (tag === 'state') return 50;
+  if (tag === 'learnings') return 10;
+  return 0;
+}
+
+function buildRecallBlock(matches, basename) {
+  if (!matches.length) return null;
+  const uniq = [];
+  const seen = new Set();
+  for (const m of matches) {
+    // Dedup by (source-file + normalized text) so duplicate excerpts in the
+    // same file collapse even when they live on different lines.
+    const key = `${m.file}::${m.text.trim()}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    uniq.push(m);
+  }
+  uniq.sort((a, b) => sortKeyFor(cycleTagFor(b.file)) - sortKeyFor(cycleTagFor(a.file)));
+  const top = uniq.slice(0, TOP_N);
+  const lines = [];
+  lines.push('');
+  lines.push(`> ⌂ **Recall** — prior decisions & learnings referencing \`${basename}\`:`);
+  for (const m of top) {
+    const tag = cycleTagFor(m.file);
+    const excerpt = m.text.length > 140 ? m.text.slice(0, 137) + '…' : m.text;
+    lines.push(`> - [${tag}] ${excerpt} (${path.relative(process.cwd(), m.file)}:${m.line})`);
+  }
+  if (uniq.length > TOP_N) {
+    lines.push(`> … (${uniq.length - TOP_N} more matches; use \`/gdd:recall <term>\` to expand. Grep backend; FTS5 upgrade in Phase 19.5.)`);
+  } else {
+    lines.push(`> (${uniq.length} match${uniq.length === 1 ? '' : 'es'} surfaced. Grep backend; FTS5 upgrade in Phase 19.5.)`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+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 !== 'Read') {
+    process.stdout.write(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  const fp = payload?.tool_input?.file_path || '';
+  if (!MATCHER_RE.test(fp)) {
+    process.stdout.write(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  const cwd = payload?.cwd || process.cwd();
+  let size = 0;
+  try { size = fs.statSync(fp).size; } catch { /* missing file → silent */ }
+  if (size < MIN_BYTES) {
+    process.stdout.write(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  const basename = path.basename(fp);
+  const relPath = path.relative(cwd, fp).replace(/\\/g, '/');
+  const terms = Array.from(new Set([basename, relPath].filter(Boolean)));
+
+  const sources = findSearchSources(cwd);
+  if (sources.length === 0) {
+    process.stdout.write(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  const useRg = ripgrepAvailable();
+  const hits = [];
+  for (const src of sources) {
+    hits.push(...(useRg ? grepLinesRg(src, terms) : grepLinesNode(src, terms)));
+  }
+
+  const block = buildRecallBlock(hits, basename);
+  if (!block) {
+    process.stdout.write(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  process.stdout.write(JSON.stringify({
+    continue: true,
+    hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: block },
+  }));
+}
+
+main().catch(() => {
+  process.stdout.write(JSON.stringify({ continue: true }));
+});

package/hooks/gdd-mcp-circuit-breaker.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * hooks/gdd-mcp-circuit-breaker.js — PostToolUse counter for mutation-side
+ * MCP calls (use_figma / use_paper / use_pencil).
+ *
+ * Responsibilities:
+ *   - Parse tool outcome: success | timeout | error
+ *   - Append one JSONL row to .design/telemetry/mcp-budget.jsonl:
+ *       { ts, tool, outcome, consecutive_timeouts, total_calls }
+ *   - After the append, if consecutive_timeouts ≥ max OR total_calls > max_calls_per_task,
+ *     emit {continue:false, stopReason:"..."} and append a STATE.md blocker line.
+ *
+ * Defaults live in reference/mcp-budget.default.json; overrides merge from
+ * .design/config.json.mcp_budget.
+ *
+ * Exit code always 0 (advisory + JSON-on-stdout pattern).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const DEFAULT_FILE = path.join(REPO_ROOT, 'reference', 'mcp-budget.default.json');
+
+const TRACKED_TOOL_RE = /^mcp__.*use_(figma|paper|pencil)$/;
+
+function loadBudget(cwd) {
+  let defaults = { max_calls_per_task: 30, max_consecutive_timeouts: 3, reset_on_success: true };
+  try {
+    const d = JSON.parse(fs.readFileSync(DEFAULT_FILE, 'utf8'));
+    defaults = { ...defaults, ...d };
+  } catch { /* fall back */ }
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(cwd, '.design', 'config.json'), 'utf8'));
+    if (cfg && typeof cfg.mcp_budget === 'object') {
+      return { ...defaults, ...cfg.mcp_budget };
+    }
+  } catch { /* no user overrides */ }
+  return defaults;
+}
+
+function classifyOutcome(toolResponse) {
+  if (!toolResponse || typeof toolResponse !== 'object') return 'error';
+  const text = JSON.stringify(toolResponse).slice(0, 4000).toLowerCase();
+  // Check timeout FIRST — a timed-out call may also set is_error, but we want
+  // to classify it as "timeout" so consecutive_timeouts advances correctly.
+  if (text.includes('timeout') || text.includes('timed out') || text.includes('deadline exceeded')) return 'timeout';
+  if (toolResponse.is_error) return 'error';
+  if (text.includes('"error"') || text.includes('failed')) return 'error';
+  return 'success';
+}
+
+function readJsonlTail(filePath) {
+  if (!fs.existsSync(filePath)) return { lastRow: null, total_calls: 0, consecutive_timeouts: 0 };
+  let total = 0;
+  let lastTimeoutsChain = 0;
+  let lastRow = null;
+  try {
+    const text = fs.readFileSync(filePath, 'utf8');
+    for (const line of text.split(/\r?\n/)) {
+      const t = line.trim();
+      if (!t) continue;
+      let row;
+      try { row = JSON.parse(t); } catch { continue; }
+      total++;
+      if (row.outcome === 'timeout') lastTimeoutsChain++;
+      else lastTimeoutsChain = 0;
+      lastRow = row;
+    }
+  } catch { /* unreadable ledger → start fresh */ }
+  return { lastRow, total_calls: total, consecutive_timeouts: lastTimeoutsChain };
+}
+
+function appendJsonl(filePath, row) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.appendFileSync(filePath, JSON.stringify(row) + '\n', 'utf8');
+}
+
+function appendStateBlocker(cwd, message) {
+  const statePath = path.join(cwd, '.design', 'STATE.md');
+  if (!fs.existsSync(statePath)) return; // silent if STATE missing
+  const line = `\n<!-- mcp-circuit-breaker: ${new Date().toISOString()} --> 🛑 BLOCKER: ${message}\n`;
+  try { fs.appendFileSync(statePath, line, 'utf8'); } catch { /* best-effort */ }
+}
+
+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;
+  }
+
+  const tool = payload?.tool_name || '';
+  if (!TRACKED_TOOL_RE.test(tool)) {
+    process.stdout.write(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  const cwd = payload?.cwd || process.cwd();
+  const budget = loadBudget(cwd);
+  const ledgerPath = path.join(cwd, '.design', 'telemetry', 'mcp-budget.jsonl');
+
+  const prior = readJsonlTail(ledgerPath);
+  const outcome = classifyOutcome(payload?.tool_response);
+  const total_calls = prior.total_calls + 1;
+  const consecutive_timeouts = outcome === 'timeout'
+    ? prior.consecutive_timeouts + 1
+    : (budget.reset_on_success && outcome === 'success' ? 0 : prior.consecutive_timeouts);
+
+  const row = {
+    ts: new Date().toISOString(),
+    tool,
+    outcome,
+    consecutive_timeouts,
+    total_calls,
+  };
+  appendJsonl(ledgerPath, row);
+
+  const timeoutBreak = consecutive_timeouts >= budget.max_consecutive_timeouts;
+  const volumeBreak = budget.max_calls_per_task > 0 && total_calls > budget.max_calls_per_task;
+
+  if (timeoutBreak || volumeBreak) {
+    const reason = timeoutBreak
+      ? `${consecutive_timeouts} consecutive MCP timeouts on ${tool} (≥${budget.max_consecutive_timeouts}). Likely the sandbox hill-climb failure mode. Stop and redirect.`
+      : `MCP call count for this task is ${total_calls}, above max_calls_per_task=${budget.max_calls_per_task}. Stop and redirect.`;
+    const msg = `${reason} For authoring new Figma content, use figma:figma-generate-design. For decision-writing, use /gdd:figma-write. See reference/figma-sandbox.md.`;
+    appendStateBlocker(cwd, msg);
+    process.stdout.write(JSON.stringify({ continue: false, stopReason: `gdd-mcp-circuit-breaker: ${msg}` }));
+    return;
+  }
+
+  process.stdout.write(JSON.stringify({ continue: true }));
+}
+
+main().catch(() => {
+  process.stdout.write(JSON.stringify({ continue: true }));
+});

package/hooks/gdd-protected-paths.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * hooks/gdd-protected-paths.js — PreToolUse:Edit|Write|Bash guard
+ *
+ * Blocks Edit/Write on file paths matching the merged protected-paths glob list,
+ * and blocks destructive Bash targeting the same paths (rm/mv/cp/tee/sed -i/git rm).
+ *
+ * Defaults live in reference/protected-paths.default.json.
+ * User additions at .design/config.json.protected_paths are MERGED into the default
+ * list; users cannot reduce the default set by shipping an empty override.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { matches } = require(path.join(__dirname, '..', 'scripts', 'lib', 'glob-match.cjs'));
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+
+function loadProtectedPaths(cwd) {
+  const defaultFile = path.join(REPO_ROOT, 'reference', 'protected-paths.default.json');
+  let defaults = [];
+  try {
+    const parsed = JSON.parse(fs.readFileSync(defaultFile, 'utf8'));
+    defaults = Array.isArray(parsed.protected_paths) ? parsed.protected_paths : [];
+  } catch { /* fall back to an empty list; caller decides */ }
+
+  const userFile = path.join(cwd || process.cwd(), '.design', 'config.json');
+  let userList = [];
+  try {
+    const cfg = JSON.parse(fs.readFileSync(userFile, 'utf8'));
+    if (Array.isArray(cfg.protected_paths)) userList = cfg.protected_paths;
+  } catch { /* missing or invalid user config → defaults only */ }
+
+  return Array.from(new Set([...defaults, ...userList]));
+}
+
+/**
+ * Extract a target path from a Bash command, best-effort.
+ * Returns an array of candidate paths; empty if none parsed.
+ */
+function extractBashTargets(command) {
+  if (!command) return [];
+  const targets = [];
+  // rm / cp / mv / mkdir trailing arg(s)
+  const rmMatch = command.match(/\b(rm|cp|mv|mkdir|touch|rmdir|chmod|chown)\s+(?:-[A-Za-z]+\s+)*([^\s|;&>]+)/);
+  if (rmMatch) targets.push(rmMatch[2]);
+  // redirect / tee
+  const redirectMatch = command.match(/[>|]\s*(?:tee\s+)?([^\s|;&]+)$/);
+  if (redirectMatch) targets.push(redirectMatch[1]);
+  // sed -i <path> (BSD and GNU variants)
+  const sedMatch = command.match(/\bsed\s+-i(?:\s*['"][^'"]*['"])?\s+(?:-[A-Za-z]+\s+)*(?:['"][^'"]*['"]\s+)?([^\s|;&]+)/);
+  if (sedMatch) targets.push(sedMatch[1]);
+  // git rm / git mv
+  const gitMatch = command.match(/\bgit\s+(rm|mv|restore|checkout)\s+(?:-[A-Za-z]+\s+)*([^\s|;&]+)/);
+  if (gitMatch) targets.push(gitMatch[2]);
+
+  return targets
+    .filter(Boolean)
+    .map(p => p.replace(/^['"]|['"]$/g, ''));
+}
+
+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;
+  }
+
+  const tool = payload?.tool_name || '';
+  if (!['Edit', 'Write', 'MultiEdit', 'Bash'].includes(tool)) {
+    process.stdout.write(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  const cwd = payload?.cwd || process.cwd();
+  const protectedPaths = loadProtectedPaths(cwd);
+  if (protectedPaths.length === 0) {
+    process.stdout.write(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  const candidates = [];
+  if (tool === 'Edit' || tool === 'Write' || tool === 'MultiEdit') {
+    const fp = payload?.tool_input?.file_path;
+    if (fp) candidates.push(fp);
+  } else if (tool === 'Bash') {
+    candidates.push(...extractBashTargets(payload?.tool_input?.command || ''));
+  }
+
+  for (const cand of candidates) {
+    if (!cand) continue;
+    const rel = cand.startsWith('/') || /^[A-Z]:\\/i.test(cand)
+      ? path.relative(cwd, cand).replace(/\\/g, '/')
+      : cand.replace(/\\/g, '/');
+    const r = matches(rel, protectedPaths);
+    if (r.matched) {
+      process.stdout.write(JSON.stringify({
+        continue: false,
+        stopReason: `gdd-protected-paths: '${rel}' is a protected path (matched '${r.pattern}'). To override, lift the path from the default glob list or explicitly edit via an approved workflow (e.g., /gdd:update, plan execution).`,
+      }));
+      return;
+    }
+  }
+
+  process.stdout.write(JSON.stringify({ continue: true }));
+}
+
+main().catch(() => {
+  process.stdout.write(JSON.stringify({ continue: true }));
+});

package/hooks/hooks.json

@@ -27,6 +27,33 @@
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/budget-enforcer.js\""
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gdd-bash-guard.js\""
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gdd-protected-paths.js\""
+          }
+        ]
+      },
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gdd-decision-injector.js\""
+          }
+        ]
       }
     ],
     "PostToolUse": [
@@ -39,6 +66,15 @@
           }
         ]
       },
+      {
+        "matcher": "mcp__.*use_figma$|mcp__.*use_paper$|mcp__.*use_pencil$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gdd-mcp-circuit-breaker.js\""
+          }
+        ]
+      },
       {
         "hooks": [
           {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.14.4",
+  "version": "1.14.7",
   "description": "A Claude Code plugin for systematic design improvement",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",

package/reference/STATE-TEMPLATE.md

@@ -56,12 +56,21 @@ skipped_stages: ""
 </must_haves>
 
 <connections>
-<!-- Detected at scan entry; updated if connections become available mid-pipeline. -->
+<!-- Detected at scan entry or via /gdd:connections; updated if connections become available mid-pipeline. -->
 <!-- Format: <connection_name>: <available | unavailable | not_configured> -->
+<!-- Key normalization: hyphens become underscores; leading digits are spelled out (21st-dev → twenty_first). -->
 figma: not_configured
 refero: not_configured
+preview: not_configured
+storybook: not_configured
+chromatic: not_configured
+graphify: not_configured
 pinterest: not_configured
 claude_design: not_configured
+paper_design: not_configured
+pencil_dev: not_configured
+twenty_first: not_configured
+magic_patterns: not_configured
 </connections>
 
 <blockers>

package/reference/config-schema.md

@@ -81,6 +81,35 @@ When `true`, parallel agents run in dedicated git worktrees. Default: `false` (l
 
 Keyed by stage name (`brief`, `explore`, `plan`, `design`, `verify`). Any field above may be overridden per stage.
 
+### `connections.skip`
+
+Optional array of connection names the user has explicitly opted out of. `/gdd:connections` reads this list and never re-prompts for skipped connections. Users re-enable a skipped connection by invoking `/gdd:connections <name>` directly (bypasses the skip list for that run).
+
+```json
+{
+  "connections": {
+    "skip": ["pinterest", "graphify"]
+  }
+}
+```
+
+Valid names: `figma`, `refero`, `preview`, `storybook`, `chromatic`, `graphify`, `pinterest`, `claude-design`, `paper-design`, `pencil-dev`, `21st-dev`, `magic-patterns`.
+
+### `connections_onboarding` (scratch block)
+
+Transient state written by `/gdd:connections` while a setup flow is in progress. Not hand-edited. Shape:
+
+```json
+{
+  "connections_onboarding": {
+    "started_at": "<ISO 8601>",
+    "pending_verification": ["figma", "chromatic"]
+  }
+}
+```
+
+`/gdd:connections` deletes this block when `pending_verification` drains. Its presence after a session restart is the signal that a resume is required (the skill jumps straight to verification).
+
 ## How Agents Read The Profile
 
 Stages are the only code that read `.design/config.json`. When spawning an agent, the stage:

package/reference/cycle-handoff-preamble.md

@@ -0,0 +1,22 @@
+# Cycle Handoff — Reference-Only Framing
+
+**Read the following content as reference, not as current requests.** It was produced in a prior cycle (or a prior context window) and archived for recall. Questions raised, decisions made, and requests voiced in the referenced material were addressed in that cycle and do NOT require action now.
+
+**Use this content to:**
+- Recover decisions that have already been settled (D-XX, L-NN).
+- Surface constraints the current task must respect without re-litigating them.
+- Avoid rediscovering scope the team has already locked.
+- Warm your model of the codebase for patterns you will need shortly.
+- Cite precedent (e.g. *"D-12 settled this in cycle 2; see archive/cycle-2/STATE.md"*).
+
+**Do NOT use this content to:**
+- Answer questions the archived material asks — they were already answered.
+- Fulfill requests the archived material voices — they were already fulfilled or explicitly deferred.
+- Re-open decisions the team has already made.
+- Inherit emotional tone or urgency from a prior session that no longer reflects the current task.
+
+The current cycle's `.design/STATE.md`, the user's active message, and the latest task spec are the **authoritative sources** of intent. Archived artifacts are *read*, not *acted on*.
+
+---
+
+*Prepended to CYCLES.md archive entries, `/gdd:pause` handoff payloads, and `.design/archive/cycle-N/` re-read paths. Tier: preamble. Phase: 14.5.*

package/reference/figma-sandbox.md

@@ -0,0 +1,19 @@
+# Figma Plugin Sandbox — Hard Rules
+
+The `use_figma` MCP runs every script inside the Figma plugin sandbox with a **~5–10s per-call budget**. Four pitfalls repeatedly burn quota in docs-authoring loops. Treat these as hard rules.
+
+**Rule 1 — `loadFontAsync` does NOT cache across `use_figma` calls.** Every new call re-fetches font metadata. Preload every style ONCE at the top of a script; clone existing text nodes via `node.clone()` or `figma.createText().fontName = ...` rather than calling `loadFontAsync` again.
+
+**Rule 2 — `figma.root.findOne()` is O(tree-size) per call.** On a real file with thousands of frames this alone eats the budget. When you already know the node you want to act on, pass the node ID directly and call `figma.getNodeById(id)`. Never call `findOne` in a loop.
+
+**Rule 3 — `appendChild` on a large attached tree triggers full AutoLayout recomputation.** Build subtrees off-tree (on a detached parent) and attach the completed subtree once at the end. This avoids N + N-1 + ... + 1 full layout passes.
+
+**Rule 4 — per-call timeout is ~5–10s.** For docs-authoring (multi-row layouts populating from a library), budget **≤2 row-equivalents per `use_figma` call**. Exceeding this puts the script in the hill-climb-against-timeout failure mode: you retry with less content per call, each retry wastes another 5–10s, and MCP quota vanishes.
+
+---
+
+## When to skip `use_figma` entirely
+
+For **authoring new content** — creating pages, populating with library components, building documentation layouts from scratch — prefer `figma:figma-generate-design` from the Figma plugin. It runs outside the sandbox and has no per-call timeout.
+
+`use_figma` (and `/gdd:figma-write`) remain the right tools for **decision-writing**: attaching annotations, binding local-style tokens, registering Code Connect mappings, writing back implementation-status. Small, bounded, read-then-write operations where the four pitfalls don't apply.

package/reference/mcp-budget.default.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "./schemas/mcp-budget.schema.json",
+  "version": 1,
+  "description": "Default per-task MCP ceilings enforced by hooks/gdd-mcp-circuit-breaker.js. User overrides merge from .design/config.json.mcp_budget.",
+  "max_calls_per_task": 30,
+  "max_consecutive_timeouts": 3,
+  "reset_on_success": true,
+  "tracked_tools": [
+    "mcp__.*use_figma$",
+    "mcp__.*use_paper$",
+    "mcp__.*use_pencil$"
+  ]
+}