@hegemonart/get-design-done 1.56.0 → 1.57.0

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.0"
   },
   "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.0",
       "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.0",
   "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,51 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.56.0",
+  "version": "1.57.0",
   "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/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.",