@hegemonart/get-design-done 1.14.5 → 1.14.7

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.5",
+  "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/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$"
+  ]
+}

package/reference/meta-rules.md

@@ -0,0 +1,66 @@
+# Meta-Rules (L0)
+
+These rules are framework-invariant across the GDD pipeline. They do not change between cycles, phases, or tasks. Every agent imports `reference/shared-preamble.md`, which aggregates `reference/meta-rules.md` first.
+
+**Tier: L0** (frozen prefix; stabilizes the Anthropic 5-min prompt-cache prefix across agent spawns — the churning L2 body below does NOT invalidate this).
+
+---
+
+## Required Reading Discipline
+
+When the orchestrator's prompt contains a `<required_reading>` block, you MUST read every file it lists with the `Read` tool before taking any other action. Paths prefixed with `@` are file paths — pass them directly to `Read`. Skipping required reading is a hard violation: you will produce stale output that the downstream verifier catches, wasting a full spawn cycle.
+
+## Writes Protocol
+
+Only write files declared in your frontmatter `writes:` list. Agents with `reads-only: true` must never call `Write` or `Edit` on any file. If the task appears to require writing outside your declared scope, stop and return a `<blocker>` in STATE.md rather than expanding your write surface.
+
+If your agent runs in a phase that enforces atomic commits (most do), commit only files in your declared `writes:` list. Use the repo commit convention: `docs(phase-N-P): short imperative description` for documentation-class changes, `feat(phase-N-P): ...` for new capability, `fix(phase-N-P): ...` for bug fixes. Phase and plan numbers come from `.design/STATE.md` `phase:` and the invoking plan's frontmatter.
+
+## Deviation Handling
+
+If an expected file is missing, a required reading entry fails to load, or the prompt references an artifact that contradicts STATE.md, **stop** before taking any destructive action. Return a structured blocker to STATE.md and terminate your response with your completion marker:
+
+```markdown
+<blocker>
+type: missing-artifact | stale-state | contract-violation
+detail: <one sentence>
+suggested-fix: <one sentence or leave blank>
+</blocker>
+
+## {STAGE} COMPLETE
+```
+
+## Completion Markers
+
+Valid completion markers per agent class (from `agents/README.md` §Completion Markers):
+- Research agent → `## RESEARCH COMPLETE`
+- Planning agent → `## PLANNING COMPLETE`
+- Execution agent → `## EXECUTION COMPLETE`
+- Verification agent → `## VERIFICATION COMPLETE`
+- Stage-specific agents → the stage name: `## SCAN COMPLETE`, `## DISCOVER COMPLETE`, `## PLAN COMPLETE`, `## DESIGN COMPLETE`, `## VERIFY COMPLETE`.
+
+The orchestrator detects failure by reading STATE.md for a `<blocker>`, not by the absence of a marker. Always emit the marker.
+
+## Context-Exhaustion & Budget Awareness
+
+A PostToolUse hook at `hooks/context-exhaustion.js` watches your tool output for the string `<context-exhaustion>` in your response. If you determine you cannot finish the task in the remaining context, emit:
+
+```xml
+<context-exhaustion>
+reason: <one-sentence cause — e.g., "required_reading totals 47KB exceeding remaining context">
+resume-hint: <one-sentence instruction for a resumption spawn>
+</context-exhaustion>
+```
+
+…before your completion marker. The hook captures this into STATE.md so the orchestrator can re-spawn you with a narrower scope. Do not guess when you're near exhaustion — only emit when a concrete obstacle (file too large to read, required diff too wide) forced the call.
+
+A PreToolUse hook at `hooks/budget-enforcer.js` intercepts every `Task` spawn (including the one that invoked you). The hook may:
+- **Short-circuit** your spawn with a cached result from `.design/cache-manifest.json` (transparent — you never run).
+- **Downgrade** your tier to Haiku at the 80% per-task cap soft-threshold, silently (`auto_downgrade_on_cap: true` in `.design/budget.json`, D-03).
+- **Hard-block** your spawn at the 100% per-task or per-phase cap with an actionable error (D-02).
+
+Implication for you as the agent: **do not assume a specific model tier is live.** Your output must be correct whether you run on Haiku, Sonnet, or Opus. If a task genuinely requires reasoning density beyond Haiku, the `size_budget` + `default-tier` combination should have been set at authoring time so the router routes it correctly — the remedy is a frontmatter update (a Phase 11 reflector proposal), not a mid-run assumption.
+
+---
+
+*Framework-invariant meta-rules. Aggregated by `reference/shared-preamble.md`.*

package/reference/protected-paths.default.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "./schemas/protected-paths.schema.json",
+  "version": 1,
+  "description": "Paths the plugin refuses to Edit/Write or mutate via Bash without an explicit user override. User additions in .design/config.json.protected_paths MERGE into this list — they can extend but cannot reduce the default set.",
+  "protected_paths": [
+    "reference/**",
+    ".design/archive/**",
+    ".design/config.json",
+    ".design/telemetry/**",
+    "skills/**",
+    "commands/**",
+    "hooks/**",
+    ".git/**",
+    ".claude/settings.json",
+    ".claude-plugin/plugin.json",
+    ".claude-plugin/marketplace.json"
+  ]
+}

package/reference/registry.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "./schemas/registry.schema.json",
+  "version": 1,
+  "generated_at": "2026-04-24T00:00:00.000Z",
+  "entries": [
+    { "name": "shared-preamble",         "path": "reference/shared-preamble.md",         "type": "preamble",        "tier": "L0", "description": "L0 aggregator — imports meta-rules first and exposes Framework Identity + Ordering Convention + Pre-Warming" },
+    { "name": "meta-rules",              "path": "reference/meta-rules.md",              "type": "meta-rules",      "tier": "L0", "description": "Framework-invariant rules: Required Reading Discipline, Writes Protocol, Deviation Handling, Completion Markers, Context-Exhaustion & Budget awareness" },
+    { "name": "cycle-handoff-preamble",  "path": "reference/cycle-handoff-preamble.md",  "type": "preamble",                       "description": "Framing prose for archived cycle material — read as reference, not as current request" },
+    { "name": "retrieval-contract",      "path": "reference/retrieval-contract.md",      "type": "preamble",                       "description": "3-layer search → metadata → full-doc protocol with per-row token-cost labels" },
+    { "name": "heuristics",              "path": "reference/heuristics.md",              "type": "heuristic",       "tier": "L2", "description": "NNG heuristics + GDD-specific rubrics used by auditor / verifier" },
+    { "name": "anti-patterns",           "path": "reference/anti-patterns.md",           "type": "heuristic",       "tier": "L2", "description": "Catalog of design anti-patterns surfaced during audit" },
+    { "name": "checklists",              "path": "reference/checklists.md",              "type": "heuristic",       "tier": "L2", "description": "Per-category gate checklists" },
+    { "name": "accessibility",           "path": "reference/accessibility.md",           "type": "heuristic",                     "description": "WCAG + focus + keyboard-nav heuristics referenced by a11y-mapper" },
+    { "name": "debugger-philosophy",     "path": "reference/debugger-philosophy.md",     "type": "heuristic",                     "description": "Philosophy guide for systematic-debugging agents" },
+    { "name": "parallelism-rules",       "path": "reference/parallelism-rules.md",       "type": "heuristic",                     "description": "Rules for serial/parallel agent dispatch and Touches conflict detection" },
+    { "name": "priority-matrix",         "path": "reference/priority-matrix.md",         "type": "heuristic",                     "description": "Severity × Effort priority-score formula used by gap prioritizers" },
+    { "name": "project-skills-guide",    "path": "reference/project-skills-guide.md",    "type": "heuristic",                     "description": "Guide for authoring project-skill artifacts (sketch/spike wrap-ups)" },
+    { "name": "audit-scoring",           "path": "reference/audit-scoring.md",           "type": "output-contract",                "description": "6-pillar + 7-category audit score rubric and output schema" },
+    { "name": "review-format",           "path": "reference/review-format.md",           "type": "output-contract",                "description": "Format of code-review output documents" },
+    { "name": "authority-feeds",         "path": "reference/authority-feeds.md",         "type": "authority-feed",                 "description": "Whitelist of design-authority feed sources for the watcher" },
+    { "name": "motion",                  "path": "reference/motion.md",                  "type": "motion",                         "description": "Motion vocabulary seed (extended in Phase 18)" },
+    { "name": "typography",              "path": "reference/typography.md",              "type": "heuristic",                     "description": "Typography-system heuristics used by visual-hierarchy-mapper" },
+    { "name": "ai-native-tool-interface","path": "reference/ai-native-tool-interface.md","type": "surfaces",                       "description": "AI-native tool interface contract used across connections" },
+    { "name": "intel-schema",            "path": "reference/intel-schema.md",            "type": "schema",                         "description": "Schema documentation for .design/intel/ files" },
+    { "name": "config-schema",           "path": "reference/config-schema.md",           "type": "schema",                         "description": "Schema documentation for .design/config.json" },
+    { "name": "DEPRECATIONS",            "path": "reference/DEPRECATIONS.md",            "type": "schema",                         "description": "Deprecation records and redirect mappings" },
+    { "name": "STATE-TEMPLATE",          "path": "reference/STATE-TEMPLATE.md",          "type": "schema",                         "description": "Template for .design/STATE.md scaffolded by /gdd:scan" },
+    { "name": "model-prices",            "path": "reference/model-prices.md",            "type": "data",                           "description": "Anthropic model pricing table used by the telemetry aggregator" },
+    { "name": "model-tiers",             "path": "reference/model-tiers.md",             "type": "data",                           "description": "Per-agent default tier map and rationale" },
+    { "name": "figma-sandbox",           "path": "reference/figma-sandbox.md",           "type": "defaults",                       "description": "Four Figma plugin-sandbox pitfalls encoded as hard rules" },
+    { "name": "mcp-budget.default",      "path": "reference/mcp-budget.default.json",    "type": "defaults",                       "description": "Default MCP per-task budget (calls + consecutive-timeout thresholds)" },
+    { "name": "protected-paths.default", "path": "reference/protected-paths.default.json","type": "defaults",                       "description": "Default glob list the plugin refuses to Edit/Write/mutate-via-Bash without override" }
+  ]
+}

package/reference/registry.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/hegemonart/get-design-done/reference/schemas/registry.schema.json",
+  "title": "Reference Registry",
+  "description": "Typed index of every reference/*.md (and reference/*.json default) in the plugin. Enables agents to query by type instead of grep-hunting import strings. Round-trip enforced: every reference/*.md must appear in entries[], every entry must resolve to an existing file.",
+  "type": "object",
+  "required": ["version", "generated_at", "entries"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "const": 1 },
+    "generated_at": { "type": "string", "format": "date-time" },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "path", "type"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-._]*$" },
+          "path": { "type": "string", "minLength": 1 },
+          "type": {
+            "type": "string",
+            "enum": [
+              "easing",
+              "taxonomy",
+              "preamble",
+              "output-contract",
+              "heuristic",
+              "schema",
+              "defaults",
+              "surfaces",
+              "motion",
+              "influences",
+              "meta-rules",
+              "data",
+              "authority-feed",
+              "principles",
+              "emotional-design",
+              "experience",
+              "palette",
+              "style-vocabulary"
+            ]
+          },
+          "tier": { "enum": ["L0", "L1", "L2"] },
+          "description": { "type": "string" },
+          "registered_at": { "type": "string", "format": "date-time" }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/reference/retrieval-contract.md

@@ -0,0 +1,30 @@
+# Retrieval Contract — 3-Layer Search
+
+When an agent or skill needs information from `.design/` artifacts or the `reference/` library, apply this protocol in order. Token economy matters — ladder from cheapest to most expensive.
+
+## Layer 1 — Search (~50–100 tokens per hit)
+
+Open `reference/registry.json` or the intel index at `.design/intel/`. Read one row per candidate: `{name, path, type, tier, description}`. This is enough to decide whether to descend further.
+
+- `list({type})` — everything tagged with a given type (e.g., `"heuristic"`, `"motion"`, `"preamble"`).
+- `find(name)` — direct lookup for a specific reference file by short name.
+
+## Layer 2 — Metadata (~200–300 tokens per hit)
+
+Open the candidate file's frontmatter + first 20 lines + heading outline. Decide if the full body is on the critical path.
+
+## Layer 3 — Full document (~500–1000+ tokens)
+
+Read the file with the `Read` tool. Only do this when layers 1 and 2 confirmed the doc is load-bearing for the current task.
+
+## Token economy
+
+A `/gdd:recall "term"` query that returns 5 Layer-1 hits ≈ 400 tokens. Opening all 5 full docs blind ≈ 4000 tokens. **Always ladder.** Skipping to Layer 3 is the #1 cause of context exhaustion in long pipeline runs.
+
+## FTS5 backend (Phase 19.5)
+
+Layer 1 becomes `scripts/lib/design-search.cjs` — same protocol, same output shape, but backed by `.design/search.db` instead of grep. Agents do not need to change anything; the backend swap is transparent.
+
+---
+
+*Imported by every skill that reads `.design/` artifacts: `/gdd:progress`, `/gdd:resume`, `/gdd:reflect`, `/gdd:pause`, `/gdd:recall` (Phase 19.5+), `/gdd:timeline` (Phase 19.5+). Tier: preamble. Phase: 14.5.*

package/reference/schemas/mcp-budget.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/hegemonart/get-design-done/reference/schemas/mcp-budget.schema.json",
+  "title": "MCP Budget",
+  "description": "Thresholds for the MCP circuit-breaker hook. Applies to use_figma / use_paper / use_pencil and any tracked_tools entry the user extends.",
+  "type": "object",
+  "required": ["version", "max_calls_per_task", "max_consecutive_timeouts"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "const": 1 },
+    "description": { "type": "string" },
+    "max_calls_per_task": { "type": "integer", "minimum": 0, "maximum": 10000 },
+    "max_consecutive_timeouts": { "type": "integer", "minimum": 0, "maximum": 1000 },
+    "reset_on_success": { "type": "boolean" },
+    "tracked_tools": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    }
+  },
+  "additionalProperties": false
+}

package/reference/schemas/protected-paths.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/hegemonart/get-design-done/reference/schemas/protected-paths.schema.json",
+  "title": "Protected Paths",
+  "description": "Glob list describing paths the plugin refuses to Edit/Write or mutate via destructive Bash. User additions MERGE with this default list; users cannot reduce the default set.",
+  "type": "object",
+  "required": ["version", "protected_paths"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "const": 1 },
+    "description": { "type": "string" },
+    "protected_paths": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    }
+  },
+  "additionalProperties": false
+}