@hegemonart/get-design-done 1.56.0 → 1.57.1

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Get Design Done — 5-stage agent-orchestrated design pipeline with 9 connections, handoff-first workflow, bidirectional Figma write-back, 22+ specialized agents, queryable knowledge layer (intel store, dependency analysis, learnings extraction), and a self-improvement loop (reflector, frontmatter + budget feedback, global-skills layer). v1.20.0 ships the SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream, and resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) for rate-limit + 429 + context-overflow recovery. Full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.56.0"
+    "version": "1.57.1"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
       "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), Claude Design handoff, bidirectional Figma write-back, and a queryable intel store (.design/intel/) for dependency and learnings queries. Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation. Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
-      "version": "1.56.0",
+      "version": "1.57.1",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.56.0",
+  "version": "1.57.1",
   "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 59 specialized agents, 88 skills, 41 connection integrations (Figma, Refero, Preview, Storybook, Chromatic, Graphify, Slack, Linear, Jira, Notion, and more), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain. v1.27.7 ships gdd-mcp (Phase 27.7): 12 read-only MCP tools for sub-3s priming. v1.28.0 (Phase 28): Foundational References Tier 2 — 5 new reference files (color-theory, composition, proportion-systems, i18n, contrast-advanced), 2 verifier i18n probes + 1 explore i18n-readiness probe, 12 additive cross-link insertions across 10 existing references, 2 orthogonal audit-scoring lens-tags (composition_alignment + i18n_readiness).",
   "author": {
     "name": "hegemonart",

package/CHANGELOG.md

@@ -4,6 +4,79 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.57.1] - 2026-06-03
+
+### Fixed
+
+Post-wave debug analysis (a 4-agent sweep after Phase 57) found and fixed a set of latent bugs that surface only when
+`better-sqlite3` is installed (the CI surface, which has no module, was unaffected - so these never failed CI but did
+degrade real users who have the module). No new dependency; the markdown floor is unchanged.
+
+- **Recall returned nothing for every `.md` file when better-sqlite3 was present.** `scripts/lib/design-search.cjs`
+  passed unquoted query terms (e.g. `heuristics.md OR reference/heuristics.md`) to FTS5, whose trigram tokenizer rejects
+  `.` and `/` as a syntax error; the error was swallowed and recall came back empty. Each term is now double-quoted
+  (matching the instinct-store pattern), so FTS5 recall matches the JS-scan fallback.
+- **The Phase 57 fact-force freshness guard silently discarded hand-edits.** `state-store.cjs` detected an out-of-band
+  STATE.md edit but its re-sync body was empty, so the edit was overwritten and lost. It now folds the hand-edit back
+  into SQLite before the next mutation.
+- **Blocker rows duplicated on every re-migration** (no `ON CONFLICT`); migration now clears a cycle's blockers before
+  re-inserting. **FTS5 virtual tables were never populated** by the migration; they are now. **`/gdd:state recover`**
+  never awaited the async migration (always reported corruption); it is now async. **State getters threw** on an absent
+  `state.sqlite` (exposing the fact-force hook); they now return empty. **`migrationActive`** guards against a directory
+  named `state.sqlite`. **`WITH ... SELECT` CTEs** are allowed by the read-only query surface.
+- **The `risk_assessment` event did not conform to its own schema** (`tool`/`score` instead of `tool_name`/`risk_score`,
+  no `event_id`, extra fields); `hooks/gdd-risk-gate.js` now emits the schema-correct shape, and an Ajv validation test
+  guards it. The **dashboard risk column** read the wrong fields and case-mismatched the action vocabulary, so it was
+  permanently blank; it is now wired and case-correct.
+- **`budget-enforcer` PreToolUse blocks** used `message` instead of `stopReason`, so the block reason was invisible to
+  the user; they now use `stopReason`. The **read-injection scanner** loads its pattern file fail-open (a missing file
+  no longer crashes the hook). Three package-root walk-ups now match the scoped package name.
+
+## [1.57.0] - 2026-06-03
+
+### Phase 57 - SQLite State Backbone (Cross-Session Query Layer)
+
+GDD project state lives in per-file markdown (STATE.md blocks, recall, instincts). Cross-cycle queries ("every decision
+tagged accessibility across the last five cycles") require fan-out greps and are effectively infeasible. Phase 57 adds an
+opt-in `.design/state.sqlite` as an indexed query layer over that state, while markdown stays the human-editable source of
+truth. It is **built with zero new dependency**: SQLite is reached through the existing opportunistic
+`probeOptional('better-sqlite3')` runtime probe (the same pattern Phase 51 uses for the instinct store), with a guaranteed
+markdown / JS-scan fallback whenever the module is absent. Migration is opt-in (`--migrate-state`) in v1.57.0, dual-writes
+for one minor version, and is fully reversible (`/gdd:state demigrate`). When better-sqlite3 is not installed, GDD behaves
+exactly as before. Planned and executed via the GSD pipeline (3 + 1 + 2 parallel executors with one reconciliation pass).
+
+### Breaking changes
+
+- **Opt-in SQLite state backbone.** Running `node scripts/lib/state/migrate-to-sqlite.cjs --migrate-state` builds
+  `.design/state.sqlite` (14 tables plus FTS5) from your STATE.md. After migration, state mutations dual-write: SQLite is
+  the authoritative store and STATE.md is rendered from it byte-for-byte (the existing `gdd-state` `read`/`mutate`/`transition`
+  API is unchanged). Without migration, or when better-sqlite3 is absent, nothing changes - markdown stays authoritative.
+  Markdown is always human-editable; a hand-edit is detected on the next write and folded back into SQLite.
+- **New `/gdd:state` skill** with three subcommands: `query "<sql>"` (engine-level read-only SELECT over the
+  decisions/blockers/plans tables), `recover` (rebuild a corrupt `state.sqlite` from markdown), and `demigrate` (drop
+  `state.sqlite` and fall back to the markdown-only source of truth).
+
+### Added
+
+- **`scripts/lib/state/`** - `state-backend.cjs` (`probeOptional('better-sqlite3')` + FTS5 probe -> `{Database, BACKEND}`;
+  WAL / busy_timeout / foreign_keys pragmas; engine-level readonly opens), `state-store.cjs` (dual-backend dispatch; the
+  SQLite-authoritative -> render-markdown -> write-STATE.md transaction; hand-edit freshness guard), `migrate-to-sqlite.cjs`
+  (idempotent UPSERT migration, `--migrate-state` opt-in, `--dry-run`), `render-markdown.cjs` (byte-equal STATE.md
+  reconstruction from SQLite via the proven serializer), `query-surface.cjs` (readonly SQL + first-token denylist, recover,
+  demigrate, cap-10 `.bak` rotation).
+- **`sdk/state/schema.sql`** - 14 tables (state_position, decisions, blockers, must_haves, plans, findings, design_debt,
+  recall_records, instincts, sessions, worktree_state, conflict_incidents, plus `_meta`/`_block_meta`) with FTS5 virtual
+  tables on decisions/findings/recall/instincts.
+- **Consumers read SQLite when migrated** - `gdd_state__get` and the dashboard data plane read SQLite-direct (markdown
+  scrape fallback; the MCP tool schema is unchanged), and the Phase 56 fact-force gate gains an FTS5 tier-0 lookup with the
+  grep fallback intact.
+
+### Changed
+
+- **`sdk/state/index.ts`** routes `read`/`mutate`/`transition` through the SQLite dual-write path only when migration is
+  active for the resolved state file (a sibling `state.sqlite` exists); otherwise the markdown path runs byte-identically.
+  The new SQLite sibling lock (`state.sqlite.lock`) is always acquired before `STATE.md.lock`.
+
 ## [1.56.0] - 2026-06-03
 
 ### Phase 56 - Risk-Scoring + Fact-Forcing Gate (Quantified Action Confidence)

package/README.md

@@ -273,6 +273,8 @@ All 14 runtimes receive their native artifact layout (`skills/`, `command/`, `ag
 
 **Risk-scoring and fact-forcing gate (v1.56.0).** Writer actions now carry a quantified risk score instead of a binary allow/deny. A pure, deterministic scorer (`scripts/lib/risk/compute-risk.cjs`, frozen tables, no I/O) grades each Write / Edit / MultiEdit / Bash by tool, file sensitivity, and input shape, then two PreToolUse hooks act on it: `gdd-risk-gate.js` emits a `risk_assessment` event and blocks only the genuinely dangerous actions (destructive bash, high-sensitivity-file rewrites at or above 0.85), while `gdd-fact-force.js` holds the first write to a file until its DesignContext consumers and recorded decisions have actually been read this session. The fact-force hold is soft and softens to a warning when the Phase 52 graph is absent, so greenfield projects are never over-blocked. `/gdd:override` clears a block or a fact-force hold with an approver and reason (audit-trailed as a `D-XX` override decision), and `design-fixer` routes findings by confidence times risk. **Built dep-free** (a maintainer decision: a pure scorer plus static tables, no ML). **No new runtime dependency.**
 
+**SQLite state backbone (v1.57.0).** Project state (decisions, blockers, plans, findings, recall, instincts) lives in per-file markdown, which makes cross-cycle queries ("every accessibility decision across the last five cycles") infeasible. Phase 57 adds an opt-in `.design/state.sqlite` as an indexed query layer while markdown stays the human-editable source of truth. It is **built with zero new dependency**: SQLite is reached through the existing opportunistic `probeOptional('better-sqlite3')` runtime probe (the Phase 51 pattern), with a guaranteed markdown / JS-scan fallback whenever the module is absent. Run `migrate-to-sqlite.cjs --migrate-state` to build the database (14 tables plus FTS5); afterwards state mutations dual-write (SQLite authoritative, STATE.md rendered from it byte-for-byte) while the `gdd-state` read/mutate/transition API is unchanged. `/gdd:state query "<sql>"` runs read-only SELECTs (engine-level readonly), `/gdd:state recover` rebuilds a corrupt database from markdown, and `/gdd:state demigrate` reverts to markdown-only. When better-sqlite3 is not installed, GDD behaves exactly as before. **No new runtime dependency.**
+
 Verify with:
 
 ```

package/SKILL.md

@@ -117,6 +117,7 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `context [nodes --type X \| edges --type Z \| path <a> <b> \| consumers-of <id> \| unreachable \| cycles \| coverage]` | `get-design-done:gdd-context` | Phase 52 - read-only query front end for the typed DesignContext graph at `.design/context-graph.json`; lists/filters nodes and edges, traces a path between two nodes, finds a node's consumers, and reports unreachable nodes, dependency cycles, and coverage. Never writes |
 | `migrate-context [--dry-run]` | `get-design-done:gdd-migrate-context` | Phase 52 - migrate a pre-Phase-52 project from flat `.design/map/*.md` mapper notes to the typed DesignContext graph; runs the extract-*.mjs passes, merges fragments, validates with `validate-design-context.cjs`, and flags low-confidence transforms for review. Preview-first; `--dry-run` previews without writing |
 | `override <finding-id \| factforce <path>> [--approver <who>] [--reason <text>]` | `get-design-done:gdd-override` | Phase 56 - escalation surface for a risk-gate block or a first-write fact-force hold; with an approver and reason, writes a `D-XX` override-tagged decision (audit trail) for a blocked finding, or clears the fact-force `checked[path]` lock for a path you have legitimately reviewed. Mirrors unlock-decision; never overrides silently |
+| `state <query "<sql>" \| recover \| demigrate>` | `get-design-done:gdd-state` | Phase 57 - operate the opt-in SQLite state backbone: `query` runs a read-only SELECT over the decisions/blockers/plans tables (engine-level readonly), `recover` rebuilds a corrupt `state.sqlite` from the markdown STATE.md, `demigrate` removes `state.sqlite` to fall back to the markdown-only source of truth. Markdown stays the human-editable SoT; SQLite is opportunistic and reversible |
 
 ## Handoff Routing
 

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

@@ -0,0 +1,106 @@
+---
+name: gdd-state
+description: "Query, recover, or roll back the Phase 57 SQLite state backbone. Use when you need to inspect the decisions/blockers/plans tables with a raw SELECT, rebuild a corrupt state.sqlite from the markdown STATE.md, or revert to the markdown-only source of truth by removing state.sqlite. Activates for requests involving querying the SQLite state database, recovering from SQLite corruption, or reverting the migration (demigrate)."
+argument-hint: "<query \"<sql>\" | recover | demigrate>"
+user-invocable: true
+tools: Read, Bash, Grep, Glob
+---
+
+# /gdd:state
+
+The Phase 57 SQLite state backbone is opt-in (`--migrate-state`) and fully reversible.
+Markdown `.design/STATE.md` is always the human-editable SoT; SQLite is a faster query
+layer derived from it. This skill exposes three subcommands for operating on that layer.
+
+## Subcommands
+
+| Subcommand | What it does |
+|---|---|
+| `/gdd:state query "<sql>"` | Run a read-only SELECT against `.design/state.sqlite`. |
+| `/gdd:state recover` | Rotate the current sqlite to a `.bak` and rebuild from markdown. |
+| `/gdd:state demigrate` | Remove `.design/state.sqlite`; markdown becomes the SoT again. |
+
+---
+
+## query
+
+Execute a read-only SELECT against the state database.
+
+The engine opens the file with `readonly:true` so all writes are rejected at the
+engine level. A first-token denylist (Set membership, no regex) additionally blocks
+DROP, DELETE, UPDATE, INSERT, ALTER, ATTACH, CREATE, PRAGMA, VACUUM, ANALYZE,
+REINDEX, and REPLACE before the connection is opened.
+
+```bash
+node -e '
+  const qs = require("./scripts/lib/state/query-surface.cjs");
+  const result = qs.query(process.argv[1], { projectRoot: process.cwd() });
+  console.log(JSON.stringify(result, null, 2));
+' "<sql>"
+```
+
+Outputs `{ rows: [...], backend: "sqlite" }` on success, or
+`{ degraded: true, message: "..." }` when SQLite is not active.
+
+Degrades gracefully (no throw) when `BACKEND==='markdown'` or when
+`.design/state.sqlite` has not been created yet (run `--migrate-state` first).
+
+---
+
+## recover
+
+Rotate the current (possibly corrupt) `.design/state.sqlite` to `.bak.0`, then
+rebuild a fresh database from the markdown `.design/STATE.md` using
+`migrate-to-sqlite.cjs` in force mode. Runs `PRAGMA integrity_check` on the
+result and reports the outcome.
+
+```bash
+node -e '
+  const qs = require("./scripts/lib/state/query-surface.cjs");
+  const result = qs.recover({ projectRoot: process.cwd() });
+  console.log(JSON.stringify(result, null, 2));
+'
+```
+
+Outputs `{ recovered: true, integrity: true, message: "..." }` on success.
+
+Backup rotation keeps at most 10 files (`.bak.0` through `.bak.9`). The oldest
+backup is overwritten when the cap is reached.
+
+---
+
+## demigrate
+
+Remove `.design/state.sqlite` so the markdown `STATE.md` becomes the SoT again.
+Idempotent: if the file does not exist, returns a clear no-op message without error.
+A backup is taken in `.bak.0` before removal.
+
+```bash
+node -e '
+  const qs = require("./scripts/lib/state/query-surface.cjs");
+  const result = qs.demigrate({ projectRoot: process.cwd() });
+  console.log(JSON.stringify(result, null, 2));
+'
+```
+
+Outputs `{ demigrated: true, message: "..." }` when the file was removed, or
+`{ demigrated: false, message: "..." }` when it was already absent (no-op).
+
+To re-enable SQLite after a demigrate, run `--migrate-state` again.
+
+---
+
+## Key design decisions
+
+- **Markdown is always the SoT.** SQLite is opt-in via `--migrate-state` and
+  reversible via `demigrate`. The markdown file is never silently overwritten.
+- **Read-only queries only.** The `query` subcommand enforces SELECT-only via both
+  the engine (`readonly:true`) and a defense-in-depth denylist. No writes
+  are possible through this skill.
+- **Backup rotation cap.** `rotateBak` shifts `.bak.0..8` up by one index and caps
+  at `.bak.9` (10 files total). The oldest backup is overwritten automatically.
+- **Graceful degradation.** All subcommands return a clear `{ degraded, message }`
+  object (no throw) when `better-sqlite3` is not installed or when
+  `GDD_STATE_BACKEND=markdown` is set.
+
+## STATE COMPLETE

package/hooks/budget-enforcer.ts

@@ -332,6 +332,7 @@ interface ToolOutput {
   continue: boolean;
   suppressOutput?: boolean;
   message?: string;
+  stopReason?: string;
   modified_tool_input?: ToolInput;
   cached_result?: unknown;
 }
@@ -1046,7 +1047,7 @@ export async function main(): Promise<void> {
     const response: ToolOutput = {
       continue: false,
       suppressOutput: false,
-      message: `gdd-budget-enforcer: rate-limited on anthropic, retry in ${waitSeconds}s (resetAt=${rateState.resetAt})`,
+      stopReason: `gdd-budget-enforcer: rate-limited on anthropic, retry in ${waitSeconds}s (resetAt=${rateState.resetAt})`,
     };
     process.stdout.write(JSON.stringify(response));
     return;
@@ -1121,7 +1122,7 @@ export async function main(): Promise<void> {
         const response: ToolOutput = {
           continue: false,
           suppressOutput: false,
-          message: `Project budget cap reached: $${projClass.spend.toFixed(2)} of $${budget.project_cap_usd.toFixed(2)} (${projClass.pct.toFixed(0)}%). Raise project_cap_usd in .design/budget.json, or set project_cap_enforcement_mode to "warn" to keep going. (Graceful halt — the current stage's earlier spawns already completed; this blocks the next one.)`,
+          stopReason: `Project budget cap reached: $${projClass.spend.toFixed(2)} of $${budget.project_cap_usd.toFixed(2)} (${projClass.pct.toFixed(0)}%). Raise project_cap_usd in .design/budget.json, or set project_cap_enforcement_mode to "warn" to keep going. (Graceful halt — the current stage's earlier spawns already completed; this blocks the next one.)`,
         };
         process.stdout.write(JSON.stringify(response));
         return;
@@ -1162,7 +1163,7 @@ export async function main(): Promise<void> {
       const response: ToolOutput = {
         continue: false,
         suppressOutput: false,
-        message: `Budget cap reached for ${capLabel}. Estimated: $${estCost.toFixed(4)}, cap: $${perSpawnCap.toFixed(2)}. Raise cap in .design/budget.json or retry after next task.`,
+        stopReason: `Budget cap reached for ${capLabel}. Estimated: $${estCost.toFixed(4)}, cap: $${perSpawnCap.toFixed(2)}. Raise cap in .design/budget.json or retry after next task.`,
       };
       process.stdout.write(JSON.stringify(response));
       return;
@@ -1187,7 +1188,7 @@ export async function main(): Promise<void> {
       const response: ToolOutput = {
         continue: false,
         suppressOutput: false,
-        message: `Budget cap reached for per-phase (${phase}). Cumulative: $${(phaseSpend + estCost).toFixed(4)}, cap: $${budget.per_phase_cap_usd.toFixed(2)}. Raise cap in .design/budget.json or retry after next phase.`,
+        stopReason: `Budget cap reached for per-phase (${phase}). Cumulative: $${(phaseSpend + estCost).toFixed(4)}, cap: $${budget.per_phase_cap_usd.toFixed(2)}. Raise cap in .design/budget.json or retry after next phase.`,
       };
       process.stdout.write(JSON.stringify(response));
       return;

package/hooks/gdd-fact-force.js

@@ -148,13 +148,102 @@ function decisionSources(cwd) {
 }
 
 /**
- * Does any decision/blocker line mention this file? Best-effort substring grep
- * over the canonical docs for the file's basename or relPath (the same terms
- * the decision-injector greps on). Returns { found:boolean, where:string|null }.
+ * Lazy-require state-store.cjs (Phase 57 dual-backend layer).
+ * Returns null if not yet available (degrade to grep).
+ */
+function _requireStateStore() {
+  try {
+    const candidates = [
+      path.join(__dirname, '..', 'scripts', 'lib', 'state', 'state-store.cjs'),
+    ];
+    const root = findPackageRoot(__dirname);
+    if (root) candidates.push(path.join(root, 'scripts', 'lib', 'state', 'state-store.cjs'));
+    for (const c of candidates) {
+      try {
+        const m = require(c);
+        if (m && typeof m.queryDecisions === 'function') return m;
+      } catch { /* try next */ }
+    }
+  } catch { /* never throw */ }
+  return null;
+}
+
+/**
+ * Lazy-require state-backend.cjs to check if migration is active.
+ * Migration is active when BACKEND==='sqlite' AND the sibling .design/state.sqlite exists.
+ */
+function _isMigrationActive(cwd) {
+  try {
+    const candidates = [
+      path.join(__dirname, '..', 'scripts', 'lib', 'state', 'state-backend.cjs'),
+    ];
+    const root = findPackageRoot(__dirname);
+    if (root) candidates.push(path.join(root, 'scripts', 'lib', 'state', 'state-backend.cjs'));
+    let backend = null;
+    for (const c of candidates) {
+      try {
+        const m = require(c);
+        if (m && typeof m.BACKEND === 'string' && typeof m.sqlitePath === 'function') {
+          backend = m;
+          break;
+        }
+      } catch { /* try next */ }
+    }
+    if (!backend || backend.BACKEND !== 'sqlite') return false;
+    // Verify that the sibling .design/state.sqlite actually exists (migration-active gate).
+    const dbPath = backend.sqlitePath(cwd);
+    return fs.existsSync(dbPath);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Does any decision/blocker line mention this file?
+ *
+ * When migration is active (BACKEND==='sqlite' AND .design/state.sqlite exists):
+ *   - Tier-0: query state-store.cjs queryDecisions(term) for each search term.
+ *     Falls back to grep if the store query throws.
+ * When migration is NOT active (default, un-migrated):
+ *   - Substring grep over STATE.md/CYCLES.md/LEARNINGS.md (UNCHANGED).
+ *
+ * Returns { found:boolean, where:string|null }.
+ * The return shape and the soften-if-absent behavior are UNCHANGED.
  */
 function decisionMentions(cwd, relPath) {
   const basename = path.basename(relPath);
   const terms = Array.from(new Set([basename, relPath].filter(Boolean)));
+
+  // Tier-0: FTS5 path (migration-active only).
+  if (_isMigrationActive(cwd)) {
+    const store = _requireStateStore();
+    if (store) {
+      try {
+        for (const t of terms) {
+          if (!t) continue;
+          const rows = store.queryDecisions(t, { projectRoot: cwd, limit: 1 });
+          if (Array.isArray(rows) && rows.length > 0) {
+            return { found: true, where: 'state.sqlite' };
+          }
+        }
+        // FTS5 returned no matches; check blockers via getBlockers substring.
+        const blockers = store.getBlockers ? store.getBlockers({ projectRoot: cwd }) : [];
+        if (Array.isArray(blockers) && blockers.length > 0) {
+          for (const b of blockers) {
+            const body = (b.body_md || b.raw_line || '');
+            for (const t of terms) {
+              if (t && body.includes(t)) return { found: true, where: 'state.sqlite' };
+            }
+          }
+        }
+        return { found: false, where: null };
+      } catch {
+        // FTS5 query failed: fall through to grep.
+      }
+    }
+  }
+
+  // Tier-1 (always-on fallback): substring grep over canonical docs.
   for (const src of decisionSources(cwd)) {
     let content;
     try { content = fs.readFileSync(src, 'utf8'); } catch { continue; }

package/hooks/gdd-protected-paths.js

@@ -13,9 +13,32 @@
 
 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, '..');
+/**
+ * Walk up from startDir to find the package root by looking for a
+ * package.json with name '@hegemonart/get-design-done'. Returns null
+ * when the root cannot be found (e.g. in unusual installed layouts).
+ * Mirrors the pattern used by gdd-fact-force.js / gdd-risk-gate.js
+ * (Phase 56+) to be robust against esbuild/installed layouts that
+ * may relocate or rewrite __dirname.
+ */
+function findPackageRoot(startDir) {
+  let dir = startDir;
+  for (let i = 0; i < 12; i++) {
+    try {
+      const pkg = require(path.join(dir, 'package.json'));
+      if (pkg && pkg.name === '@hegemonart/get-design-done') return dir;
+    } catch { /* not this level */ }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+const REPO_ROOT = findPackageRoot(__dirname) || path.resolve(__dirname, '..');
+
+const { matches } = require(path.join(REPO_ROOT, 'scripts', 'lib', 'glob-match.cjs'));
 
 function loadProtectedPaths(cwd) {
   const defaultFile = path.join(REPO_ROOT, 'reference', 'protected-paths.default.json');

package/hooks/gdd-read-injection-scanner.ts

@@ -79,7 +79,15 @@ function loadPatterns(): readonly RegExp[] {
   );
 }
 
-const INJECTION_PATTERNS: readonly RegExp[] = loadPatterns();
+// Wrapped in try/catch so a missing injection-patterns.cjs does not throw
+// at import time (before main()'s catch guard is active). On failure the
+// hook falls back to an empty pattern list and emits a passthrough result.
+let INJECTION_PATTERNS: readonly RegExp[];
+try {
+  INJECTION_PATTERNS = loadPatterns();
+} catch {
+  INJECTION_PATTERNS = [];
+}
 
 // ── Types ───────────────────────────────────────────────────────────────────
 

package/hooks/gdd-risk-gate.js

@@ -2,6 +2,9 @@
 'use strict';
 /**
  * hooks/gdd-risk-gate.js — PreToolUse:Write|Edit|MultiEdit|Bash risk gate (Phase 56, RISK-02).
+ * Payload shape locked to RiskAssessmentPayload (events.schema.json): event_id, tool_name,
+ * risk_score, suggested_action, reasons (required). Optional: agent, decision_context.
+ * additionalProperties:false — do NOT add breakdown/paths/score/tool to the payload.
  *
  * Quantifies the confidence/risk of a writer action with the PURE scorer
  * `scripts/lib/risk/compute-risk.cjs` (executor A), emits a `risk_assessment`
@@ -39,6 +42,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { randomUUID } = require('node:crypto');
 
 // ── Package-root walk-up: locate scripts/lib/risk/compute-risk.cjs ──────────
 // Start at this file's dir and climb until we find the risk module (or a
@@ -325,7 +329,14 @@ async function main() {
       );
     } catch { /* swallow */ }
     emitHookFired('allow', { reason: 'scorer-error' });
-    emitRiskAssessment({ tool, agent: agent || undefined, error: 'scorer-error', suggested_action: 'allow' }, sessionId);
+    emitRiskAssessment({
+      event_id: randomUUID(),
+      tool_name: tool,
+      risk_score: 0,
+      suggested_action: 'allow',
+      reasons: [],
+      agent: agent || undefined,
+    }, sessionId);
     process.stdout.write(JSON.stringify(ALLOW));
     return;
   }
@@ -337,13 +348,12 @@ async function main() {
   // distribution. Best-effort.
   emitRiskAssessment(
     {
-      tool,
-      agent: agent || undefined,
-      score: assessment.score,
+      event_id: randomUUID(),
+      tool_name: tool,
+      risk_score: assessment.score,
       suggested_action: action,
-      reasons: assessment.reasons,
-      breakdown: assessment.breakdown,
-      paths: assessment.breakdown && assessment.breakdown.paths,
+      reasons: Array.isArray(assessment.reasons) ? assessment.reasons : [],
+      agent: agent || undefined,
     },
     sessionId,
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.56.0",
+  "version": "1.57.1",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",

package/reference/skill-graph.md

@@ -9,7 +9,7 @@ is a `composes_with` edge (the source calls the target as sub-orchestration); a
 a `next_skills` edge (a pipeline hint for what runs next). Stage grouping is best-effort and
 inferred from the skill name; skills with no stage keyword fall under Utility.
 
-Skills: 93. Composition edges: 0 composes_with, 6 next_skills.
+Skills: 94. Composition edges: 0 composes_with, 6 next_skills.
 
 ```mermaid
 flowchart TD
@@ -108,6 +108,7 @@ flowchart TD
     n_settings["settings"]
     n_ship["ship"]
     n_skill_manifest["skill-manifest"]
+    n_state["state"]
     n_stats["stats"]
     n_style["style"]
     n_synthesize["synthesize"]

package/scripts/lib/design-search.cjs

@@ -124,14 +124,32 @@ function reindex(projectRoot) {
   db.close();
 }
 
+/**
+ * Re-wrap each whitespace/OR-delimited term in FTS5 double-quote escaping so
+ * that tokens containing `.`, `/`, `-`, or other punctuation that the trigram
+ * tokenizer treats as illegal bare-term characters are accepted as quoted
+ * phrase queries. This matches the pattern used in instinct-store.cjs.
+ *
+ * Examples:
+ *   "heuristics.md OR reference/heuristics.md"
+ *     -> '"heuristics.md" OR "reference/heuristics.md"'
+ *   "color tokens"
+ *     -> '"color" OR "tokens"'
+ */
+function _quoteFts5Query(rawQuery) {
+  const terms = rawQuery.split(/\s+OR\s+|\s+/).filter(Boolean);
+  return terms.map(t => '"' + t.replace(/"/g, '""') + '"').join(' OR ');
+}
+
 function _searchFts5(query, projectRoot, limit) {
   const dbPath = _dbPath(projectRoot);
   if (!fs.existsSync(dbPath)) reindex(projectRoot);
   const db = new Database(dbPath, { readonly: true });
   try {
+    const matchExpr = _quoteFts5Query(query);
     const rows = db.prepare(
       `SELECT file, line, text FROM docs WHERE docs MATCH ? ORDER BY rank LIMIT ?`
-    ).all(query, limit);
+    ).all(matchExpr, limit);
     return rows.map(r => ({ file: r.file, line: r.line, text: r.text }));
   } finally {
     db.close();
@@ -203,4 +221,4 @@ function search(query, projectRoot, opts = {}) {
   return _searchNode(query, projectRoot, limit);
 }
 
-module.exports = { search, reindex, backendName };
+module.exports = { search, reindex, backendName, _quoteFts5Query };

package/scripts/lib/manifest/skills.json

@@ -542,6 +542,14 @@
       "tools": "Read, Grep, Glob, Bash, Write, Task",
       "disable_model_invocation": true
     },
+    {
+      "name": "state",
+      "description": "Query, recover, or roll back the Phase 57 SQLite state backbone. Use when you need to inspect the decisions/blockers/plans tables with a raw SELECT, rebuild a corrupt state.sqlite from the markdown STATE.md, or revert to the markdown-only source of truth by removing state.sqlite. Activates for requests involving querying the SQLite state database, recovering from SQLite corruption, or reverting the migration (demigrate).",
+      "argument_hint": "<query \"<sql>\" | recover | demigrate>",
+      "user_invocable": true,
+      "tools": "Read, Bash, Grep, Glob",
+      "registered_in_phase": "57"
+    },
     {
       "name": "stats",
       "description": "Cycle stats - decisions made, tasks completed, commits, timeline, git metrics.",