@hegemonart/get-design-done 1.57.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.57.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.57.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.57.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,34 @@ 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)

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-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.57.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/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/state/migrate-to-sqlite.cjs

@@ -47,7 +47,7 @@ function findPackageRoot(startDir) {
     try { pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')); } catch { pkg = null; }
     if (pkg) {
       if (firstWithPkg === null) firstWithPkg = dir;
-      if (pkg.name === 'get-design-done') return dir;
+      if (pkg.name === '@hegemonart/get-design-done') return dir;
     }
     const parent = path.dirname(dir);
     if (parent === dir) break;
@@ -214,19 +214,24 @@ function buildDryRunDiff(ops) {
  * Migrate .design/STATE.md (and supplementary stores) into the SQLite database.
  *
  * @param {object} opts
- * @param {string} [opts.projectRoot]  - project root dir (defaults to cwd / env)
- * @param {boolean} [opts.dryRun=false] - wrap writes in BEGIN/ROLLBACK + print diff
- * @param {boolean} [opts.force=false]  - same as --migrate-state flag; required to actually write
+ * @param {string} [opts.projectRoot]    - project root dir (defaults to cwd / env)
+ * @param {string} [opts.statePath]      - explicit path to STATE.md (overrides projectRoot lookup)
+ * @param {boolean} [opts.dryRun=false]  - wrap writes in BEGIN/ROLLBACK + print diff
+ * @param {boolean} [opts.force=false]   - same as --migrate-state flag; required to actually write
+ * @param {boolean} [opts.upsertOnly=false] - re-parse markdown and UPSERT without wiping unrelated rows
+ *                                            (used by the R8 freshness guard to fold hand-edits into SQLite)
  * @returns {Promise<{migrated:boolean, tables:object, dryRun:boolean, skipped:boolean, reason:string}>}
  */
 async function migrateToSqlite(opts = {}) {
-  const { dryRun = false, force = false } = opts;
+  const { dryRun = false, force = false, upsertOnly = false } = opts;
+  // upsertOnly implies force (it's always an internal call, not user-facing opt-in).
+  const effectiveForce = force || upsertOnly;
   const projectRoot = resolveProjectRoot(opts.projectRoot);
 
   // Opt-in guard: --migrate-state / force required.
   // This fires first (before the SQLite probe) so the message is consistent
   // regardless of whether better-sqlite3 is installed.
-  if (!force) {
+  if (!effectiveForce) {
     const notice =
       'Migration is opt-in in v1.57.0. Re-run with --migrate-state to proceed.';
     return {
@@ -254,7 +259,7 @@ async function migrateToSqlite(opts = {}) {
   }
 
   // Read STATE.md.
-  const statePath = path.join(projectRoot, '.design', 'STATE.md');
+  const statePath = opts.statePath || path.join(projectRoot, '.design', 'STATE.md');
   if (!fs.existsSync(statePath)) {
     return {
       migrated: false,
@@ -440,9 +445,20 @@ async function migrateToSqlite(opts = {}) {
       );
       counts.decisions++;
       ops.push({ action: 'upsert', table: 'decisions', id: d.id, fields: { status: d.status, body_md: d.text, raw_line: rawLine } });
+      // BUG-05: populate FTS5 table so queryDecisions returns hits.
+      // FTS5 virtual tables do not support ON CONFLICT — use DELETE + INSERT pattern.
+      // Guard: if FTS5 tables are absent (no-fts5 build), skip without throwing.
+      try {
+        db.prepare('DELETE FROM decisions_fts WHERE id = ?').run(d.id);
+        db.prepare('INSERT INTO decisions_fts (id, body_md, tags) VALUES (?, ?, ?)').run(d.id, d.text, null);
+      } catch { /* FTS5 table absent - skip */ }
     }
 
     // --- blockers ---
+    // BUG-02: DELETE existing rows for this cycle_id before re-inserting to prevent duplication.
+    // The blockers table uses AUTOINCREMENT PK with no natural-key ON CONFLICT, so
+    // re-running migrate without this delete would DUPLICATE every blocker row.
+    db.prepare('DELETE FROM blockers WHERE cycle_id = ?').run(cycleId);
     for (let i = 0; i < blockers.length; i++) {
       const b = blockers[i];
       const rawLine = `[${b.stage}] [${b.date}]: ${b.text}`;

package/scripts/lib/state/query-surface.cjs

@@ -128,8 +128,13 @@ function _firstToken(sql) {
 }
 
 /**
- * Assert that the SQL query is a safe readonly SELECT.
- * Throws with a descriptive message when the first token is denied or not SELECT.
+ * Assert that the SQL query is a safe readonly SELECT (or CTE: WITH ... SELECT).
+ * Throws with a descriptive message when the first token is denied or not SELECT/WITH.
+ *
+ * BUG-11: allow a leading WITH token for CTEs (WITH ... SELECT ...).
+ * The engine-level readonly connection already blocks any write CTE.
+ * We keep blocking all other non-SELECT first tokens.
+ *
  * @param {string} sql
  */
 function _assertReadonly(sql) {
@@ -142,7 +147,8 @@ function _assertReadonly(sql) {
       `query-surface: statement type '${token}' is not allowed (denylist). Only SELECT is permitted.`
     );
   }
-  if (token !== 'SELECT') {
+  // Allow WITH for CTEs (WITH ... SELECT ...) — engine readonly blocks any write CTE.
+  if (token !== 'SELECT' && token !== 'WITH') {
     throw new Error(
       `query-surface: first token '${token}' is not SELECT. Only SELECT queries are permitted.`
     );
@@ -305,10 +311,13 @@ function demigrate(opts = {}) {
  *   3. Invoke migrate-to-sqlite with force:true to rebuild from markdown.
  *   4. Run integrity_check on the new database.
  *
+ * BUG-03/08: recover() is now async — it awaits migrateToSqlite() so that
+ * state.sqlite actually exists before the integrity check is run.
+ *
  * @param {{ projectRoot?: string, dbPath?: string }} [opts]
- * @returns {{ recovered: boolean, message: string, integrity?: boolean }}
+ * @returns {Promise<{ recovered: boolean, message: string, integrity?: boolean }>}
  */
-function recover(opts = {}) {
+async function recover(opts = {}) {
   const backend = _requireBackend();
   if (!backend || backend.BACKEND !== 'sqlite') {
     return {
@@ -343,13 +352,16 @@ function recover(opts = {}) {
   let migrateResult = null;
   try {
     if (typeof migrate.migrateToSqlite === 'function') {
-      migrateResult = migrate.migrateToSqlite({
+      // BUG-03/08: await the async migrateToSqlite so state.sqlite is written before
+      // the integrity check below. Without await, recover() returned before the DB
+      // existed, causing integrity:false on every call.
+      migrateResult = await migrate.migrateToSqlite({
         projectRoot: opts.projectRoot,
         dbPath,
         force: true,
       });
     } else if (typeof migrate.migrate === 'function') {
-      migrateResult = migrate.migrate({ projectRoot: opts.projectRoot, dbPath, force: true });
+      migrateResult = await migrate.migrate({ projectRoot: opts.projectRoot, dbPath, force: true });
     } else {
       return { recovered: false, message: 'recover: migrate-to-sqlite.cjs has no recognized export.' };
     }

package/scripts/lib/state/render-markdown.cjs

@@ -376,21 +376,33 @@ function renderStateMarkdown(db, cycle_id, sdk) {
   }
 
   // --- blockers raw_body ---
-  // Only unresolved blockers go in the STATE.md <blockers> block.
+  // activeBlockers is used both for raw_bodies reconstruction and the blockers state array below.
   const activeBlockers = blockerRows.filter((r) => !r.resolved_at);
-  if (activeBlockers.length > 0) {
-    const lines = activeBlockers.map((row) => {
-      // ALWAYS prefer raw_line for blockers (date-format hazard).
-      if (row.raw_line) return row.raw_line;
-      return canonicalBlocker({ stage: row.stage || '', date: row.date || '', text: row.body_md || '' });
-    });
-    raw_bodies.blockers = lines.join('\n');
-  } else if ('blockers' in blockGaps) {
-    raw_bodies.blockers = blockRawBodies['blockers'] !== undefined
-      ? blockRawBodies['blockers']
-      : '';
-  } else if (blockRawBodies['blockers'] !== undefined) {
-    raw_bodies.blockers = blockRawBodies['blockers'];
+
+  // BUG-09: when _block_meta stores a non-null raw_body for 'blockers', emit it
+  // verbatim (like unstructured blocks). This preserves comment lines inside
+  // <blockers> that would otherwise be silently dropped when rebuilding from rows.
+  //
+  // Fall through to row-reconstruction only when raw_body is absent (null), which
+  // happens after an appendBlocker() call that doesn't update _block_meta.raw_body.
+  const blockersRawBody = blockRawBodies['blockers'];
+  if (blockersRawBody !== undefined && blockersRawBody !== null) {
+    // Verbatim round-trip: emit stored raw_body (preserves comments).
+    raw_bodies.blockers = blockersRawBody;
+  } else {
+    // Reconstruct from rows (no stored raw_body).
+    // Only unresolved blockers go in the STATE.md <blockers> block.
+    if (activeBlockers.length > 0) {
+      const lines = activeBlockers.map((row) => {
+        // ALWAYS prefer raw_line for blockers (date-format hazard).
+        if (row.raw_line) return row.raw_line;
+        return canonicalBlocker({ stage: row.stage || '', date: row.date || '', text: row.body_md || '' });
+      });
+      raw_bodies.blockers = lines.join('\n');
+    } else if ('blockers' in blockGaps) {
+      raw_bodies.blockers = '';
+    }
+    // If no blockGaps entry for blockers, raw_bodies.blockers stays null (block omitted).
   }
 
   // --- unstructured blocks: verbatim from _block_meta.raw_body ---

package/scripts/lib/state/state-store.cjs

@@ -56,7 +56,7 @@ function findPackageRoot(startDir) {
     try { pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')); } catch { pkg = null; }
     if (pkg) {
       if (firstWithPkg === null) firstWithPkg = dir;
-      if (pkg.name === 'get-design-done') return dir;
+      if (pkg.name === '@hegemonart/get-design-done') return dir;
     }
     const parent = path.dirname(dir);
     if (parent === dir) break;
@@ -198,12 +198,12 @@ function _onDiskSha(statePath) {
  * If they differ, the user has hand-edited STATE.md since the last SQLite write.
  * In that case, run a mini-migration (upsert SQLite from markdown) before proceeding.
  *
- * This is called BEFORE the db.transaction() so it can be async.
+ * This is ASYNC - must be awaited before entering the db.transaction().
  *
  * @param {import('better-sqlite3').Database} db
  * @param {string} statePath absolute path to STATE.md
  */
-function _applyFreshnessGuard(db, statePath) {
+async function _applyFreshnessGuard(db, statePath) {
   try {
     const onDisk = _onDiskSha(statePath);
     if (onDisk === null) return; // STATE.md doesn't exist yet - skip
@@ -211,20 +211,21 @@ function _applyFreshnessGuard(db, statePath) {
     const stored = metaRow ? metaRow.value : null;
     if (stored === onDisk) return; // No drift - proceed normally
     // Drift detected: user hand-edited STATE.md.
-    // Run mini-migration to upsert SQLite from the current markdown state.
+    // Run mini-migration (upsertOnly) to fold the hand-edit into SQLite before
+    // proceeding with the intended mutation.
     const migrate = _requireMigrate();
     if (migrate && typeof migrate.migrateToSqlite === 'function') {
       try {
-        // migrateToSqlite is async but we handle it best-effort here.
-        // For the freshness guard we do a best-effort synchronous approach:
-        // if the module is loaded, call it. If it's async we can't await here
-        // (this is called outside the transaction but may be called from sync context).
-        // The mini-migration is best-effort.
+        // Close db first if needed - migrateToSqlite opens its own connection.
+        // We pass the resolved projectRoot (dirname of .design/STATE.md's parent).
+        const projectRoot = path.resolve(path.dirname(statePath), '..');
+        await migrate.migrateToSqlite({ statePath, projectRoot, force: true, upsertOnly: true });
       } catch {
         // Migration failed - log and continue rather than blocking the write.
+        // Still update the sha to prevent infinite re-triggering.
       }
     }
-    // Update stored sha to prevent re-triggering on every call even if migrate fails.
+    // Update stored sha to reflect the current on-disk content.
     db.prepare('INSERT OR REPLACE INTO _meta(key, value) VALUES (?, ?)').run('last_render_sha256', onDisk);
   } catch {
     /* Freshness guard must never break a write path */
@@ -326,8 +327,12 @@ async function appendDecision(decision, opts = {}) {
   const statePath = _statePath(opts.projectRoot);
   const db = openStateDb(dbPath);
   try {
-    _applyFreshnessGuard(db, statePath);
+    await _applyFreshnessGuard(db, statePath);
     const cycleId = decision.cycleId || _currentCycleId(db);
+    // BUG-10: if no cycle is active, skip rather than inserting cycle_id=null (NOT NULL throw).
+    if (!cycleId) {
+      return { backend: 'sqlite', skipped: true, reason: 'no active cycle_id - call setPosition first' };
+    }
     _dualWrite(db, statePath, cycleId, () => {
       db.prepare(`
         INSERT INTO decisions
@@ -349,6 +354,17 @@ async function appendDecision(decision, opts = {}) {
         decision.rawLine || null,
         decision.createdAt || new Date().toISOString(),
       );
+      // BUG-05: populate decisions_fts so FTS5 queries return hits.
+      // FTS5 virtual tables do not support ON CONFLICT — use DELETE + INSERT pattern.
+      // Guard: if FTS5 tables are absent (no-fts5 build), skip without throwing.
+      try {
+        db.prepare(`DELETE FROM decisions_fts WHERE id = ?`).run(decision.id);
+        db.prepare(`INSERT INTO decisions_fts (id, body_md, tags) VALUES (?, ?, ?)`).run(
+          decision.id,
+          decision.bodyMd || '',
+          decision.tags ? JSON.stringify(decision.tags) : null,
+        );
+      } catch { /* FTS5 table absent in no-fts5 build - skip */ }
     }, sdk);
     return { backend: 'sqlite', id: decision.id };
   } finally {
@@ -373,16 +389,21 @@ function getDecisions(opts = {}) {
   if (BACKEND !== 'sqlite') {
     return [];
   }
-  const dbPath = _resolveDbPath(opts);
-  const db = openStateDb(dbPath, { readonly: true });
+  // BUG-06: wrap in try/catch — openStateDb(readonly) throws on a missing file.
   try {
-    const cycleId = opts.cycleId || _currentCycleId(db);
-    if (!cycleId) return [];
-    return db.prepare(
-      'SELECT * FROM decisions WHERE cycle_id = ? ORDER BY ordinal ASC'
-    ).all(cycleId);
-  } finally {
-    db.close();
+    const dbPath = _resolveDbPath(opts);
+    const db = openStateDb(dbPath, { readonly: true });
+    try {
+      const cycleId = opts.cycleId || _currentCycleId(db);
+      if (!cycleId) return [];
+      return db.prepare(
+        'SELECT * FROM decisions WHERE cycle_id = ? ORDER BY ordinal ASC'
+      ).all(cycleId);
+    } finally {
+      db.close();
+    }
+  } catch {
+    return [];
   }
 }
 
@@ -408,7 +429,7 @@ async function appendBlocker(blocker, opts = {}) {
   const statePath = _statePath(opts.projectRoot);
   const db = openStateDb(dbPath);
   try {
-    _applyFreshnessGuard(db, statePath);
+    await _applyFreshnessGuard(db, statePath);
     const cycleId = blocker.cycleId || _currentCycleId(db);
     let rowid = null;
     _dualWrite(db, statePath, cycleId, () => {
@@ -447,21 +468,26 @@ function getBlockers(opts = {}) {
   if (BACKEND !== 'sqlite') {
     return [];
   }
-  const dbPath = _resolveDbPath(opts);
-  const db = openStateDb(dbPath, { readonly: true });
+  // BUG-06: wrap in try/catch — openStateDb(readonly) throws on a missing file.
   try {
-    const cycleId = opts.cycleId || _currentCycleId(db);
-    if (!cycleId) return [];
-    if (opts.includeResolved) {
+    const dbPath = _resolveDbPath(opts);
+    const db = openStateDb(dbPath, { readonly: true });
+    try {
+      const cycleId = opts.cycleId || _currentCycleId(db);
+      if (!cycleId) return [];
+      if (opts.includeResolved) {
+        return db.prepare(
+          'SELECT * FROM blockers WHERE cycle_id = ? ORDER BY ordinal ASC'
+        ).all(cycleId);
+      }
       return db.prepare(
-        'SELECT * FROM blockers WHERE cycle_id = ? ORDER BY ordinal ASC'
+        'SELECT * FROM blockers WHERE cycle_id = ? AND resolved_at IS NULL ORDER BY ordinal ASC'
       ).all(cycleId);
+    } finally {
+      db.close();
     }
-    return db.prepare(
-      'SELECT * FROM blockers WHERE cycle_id = ? AND resolved_at IS NULL ORDER BY ordinal ASC'
-    ).all(cycleId);
-  } finally {
-    db.close();
+  } catch {
+    return [];
   }
 }
 
@@ -488,7 +514,7 @@ async function setPosition(position, opts = {}) {
   const statePath = _statePath(opts.projectRoot);
   const db = openStateDb(dbPath);
   try {
-    _applyFreshnessGuard(db, statePath);
+    await _applyFreshnessGuard(db, statePath);
     _dualWrite(db, statePath, position.cycleId, () => {
       db.prepare(`
         INSERT INTO state_position
@@ -535,17 +561,22 @@ function getPosition(opts = {}) {
   if (BACKEND !== 'sqlite') {
     return null;
   }
-  const dbPath = _resolveDbPath(opts);
-  const db = openStateDb(dbPath, { readonly: true });
+  // BUG-06: wrap in try/catch — openStateDb(readonly) throws on a missing file.
   try {
-    if (opts.cycleId) {
-      return db.prepare('SELECT * FROM state_position WHERE cycle_id = ?').get(opts.cycleId) || null;
+    const dbPath = _resolveDbPath(opts);
+    const db = openStateDb(dbPath, { readonly: true });
+    try {
+      if (opts.cycleId) {
+        return db.prepare('SELECT * FROM state_position WHERE cycle_id = ?').get(opts.cycleId) || null;
+      }
+      return db.prepare(
+        'SELECT * FROM state_position ORDER BY updated_at DESC LIMIT 1'
+      ).get() || null;
+    } finally {
+      db.close();
     }
-    return db.prepare(
-      'SELECT * FROM state_position ORDER BY updated_at DESC LIMIT 1'
-    ).get() || null;
-  } finally {
-    db.close();
+  } catch {
+    return null;
   }
 }
 

package/sdk/cli/index.js

@@ -4014,7 +4014,13 @@ function migrationActive(statePath) {
   const backend = _loadBackend();
   if (backend === null || backend.BACKEND !== "sqlite") return false;
   const sqliteSibling = (0, import_node_path4.join)((0, import_node_path4.dirname)(statePath), "state.sqlite");
-  return (0, import_node_fs5.existsSync)(sqliteSibling);
+  if (!(0, import_node_fs5.existsSync)(sqliteSibling)) return false;
+  try {
+    if ((0, import_node_fs5.statSync)(sqliteSibling).isDirectory()) return false;
+  } catch {
+    return false;
+  }
+  return true;
 }
 async function read(path) {
   const raw = (0, import_node_fs5.readFileSync)(path, "utf8");

package/sdk/dashboard/data/_pkg-root.cjs

@@ -6,8 +6,8 @@
  * resolve a cross-tree sibling via a fixed `__dirname`-relative `../../..`
  * jump, because that breaks the moment a file is copied/moved or the layout
  * shifts. Instead, walk UP from this file's directory until we find the GDD
- * package.json (identified by `name === 'get-design-done'`), and resolve all
- * in-repo siblings relative to that root.
+ * package.json (identified by `name === '@hegemonart/get-design-done'`), and
+ * resolve all in-repo siblings relative to that root.
  *
  * Even though these dashboard `.cjs` files are NOT esbuild-bundled (R8 — the
  * bin trampoline runs them directly so the Phase 53 __dirname-rewrite trap
@@ -23,7 +23,7 @@ let _cachedRoot = null;
 
 /**
  * Walk up from `startDir` looking for the GDD package root. The GDD root is
- * the first ancestor whose package.json declares `name: "get-design-done"`;
+ * the first ancestor whose package.json declares `name: "@hegemonart/get-design-done"`;
  * if no such marker is found (e.g. running from an unusual layout), fall back
  * to the FIRST ancestor that has any package.json, then to `startDir`.
  *
@@ -44,7 +44,7 @@ function findPackageRoot(startDir) {
     }
     if (pkg) {
       if (firstWithPkg === null) firstWithPkg = dir;
-      if (pkg.name === 'get-design-done') return dir;
+      if (pkg.name === '@hegemonart/get-design-done') return dir;
     }
     const parent = path.dirname(dir);
     if (parent === dir) break;

package/sdk/dashboard/data/risk-surface.cjs

@@ -33,15 +33,20 @@
  *   (absent / unknown)  -> default
  */
 
-/** Canonical action → color map (the only colors the Findings pane uses). */
+/**
+ * Canonical action -> color map. Keys are lowercase (matching the emitter's
+ * suggested_action values from events.schema.json: allow/review/
+ * require_confirmation/block). The display label is separate from the key so
+ * the map can do a single case-insensitive lookup.
+ */
 const ACTION_COLOR = Object.freeze({
-  Allow: 'green',
-  Review: 'yellow',
-  RequireConfirmation: 'orange',
-  Block: 'red',
+  allow: 'green',
+  review: 'yellow',
+  require_confirmation: 'orange',
+  block: 'red',
 });
 
-/** The set of recognized suggested-action values (Phase 56 vocabulary). */
+/** The set of recognized suggested-action values (Phase 56 vocabulary, lowercase). */
 const VALID_ACTIONS = Object.freeze(Object.keys(ACTION_COLOR));
 
 /** The blank placeholder row emitted pre-56 (or for malformed/absent input). */
@@ -66,34 +71,64 @@ function finiteOrNull(v) {
 }
 
 /**
- * Map a suggested_action to its display color. Unknown / absent -> 'default'.
+ * Canonicalize a suggested_action to its lowercase snake_case key for lookup.
+ * Handles the emitter's lowercase values (allow/review/require_confirmation/block)
+ * AND legacy CamelCase (Allow/Review/RequireConfirmation/Block) - the CamelCase
+ * 'RequireConfirmation' lowercases to 'requireconfirmation' with no separator, so
+ * map that explicitly to 'require_confirmation'. Returns null for non-strings.
+ * @param {*} action
+ * @returns {string|null}
+ */
+function canonAction(action) {
+  if (typeof action !== 'string') return null;
+  let s = action.trim().toLowerCase().replace(/[\s-]+/g, '_');
+  if (s === 'requireconfirmation') s = 'require_confirmation';
+  return s;
+}
+
+/**
+ * Map a suggested_action to its display color. Case-insensitive so both
+ * 'allow' (emitter) and 'Allow' (legacy) resolve correctly. Unknown / absent -> 'default'.
  * @param {*} action
  * @returns {'green'|'yellow'|'orange'|'red'|'default'}
  */
 function colorForAction(action) {
-  if (typeof action === 'string' && Object.prototype.hasOwnProperty.call(ACTION_COLOR, action)) {
-    return ACTION_COLOR[action];
+  const canon = canonAction(action);
+  if (canon !== null && Object.prototype.hasOwnProperty.call(ACTION_COLOR, canon)) {
+    return ACTION_COLOR[canon];
   }
   return 'default';
 }
 
 /**
- * Surface the risk fields on ONE event/finding. Reads `risk_score`,
- * `confidence`, `suggested_action` WHEN PRESENT; otherwise returns the blank
- * placeholder. PURE; NEVER throws.
+ * Surface the risk fields on ONE event/finding. Accepts either a raw
+ * risk_assessment envelope (with a `.payload` sub-object) OR a bare payload
+ * object. When `.payload` is present it is used as the source of risk fields;
+ * otherwise `item` itself is inspected (bare-payload / legacy path).
  *
- * @param {*} item an event or finding (may be missing the risk fields pre-56)
+ * Reads `risk_score`, `confidence`, `suggested_action` WHEN PRESENT; otherwise
+ * returns the blank placeholder. PURE; NEVER throws.
+ *
+ * @param {*} item an event envelope or bare payload (may be missing risk fields pre-56)
  * @returns {{risk_score:number|null, confidence:number|null,
  *            suggested_action:string|null, color:string}}
  */
 function surfaceRiskOne(item) {
   if (!item || typeof item !== 'object') return blankRow();
 
-  const risk_score = finiteOrNull(item.risk_score);
-  const confidence = finiteOrNull(item.confidence);
-  const rawAction = item.suggested_action;
-  const suggested_action =
-    typeof rawAction === 'string' && VALID_ACTIONS.includes(rawAction) ? rawAction : null;
+  // Normalize: if the caller passed a full event envelope (with .payload), use the payload.
+  const src = (item.payload && typeof item.payload === 'object') ? item.payload : item;
+
+  const risk_score = finiteOrNull(src.risk_score);
+  const confidence = finiteOrNull(src.confidence);
+  const rawAction = src.suggested_action;
+  const canon = canonAction(rawAction);
+  const recognized =
+    canon !== null && Object.prototype.hasOwnProperty.call(ACTION_COLOR, canon);
+  // Preserve the action VERBATIM when recognized: the emitter sends lowercase
+  // (allow/review/require_confirmation/block), legacy callers may send CamelCase,
+  // and either is echoed back unchanged. Unrecognized / absent -> null.
+  const suggested_action = recognized ? rawAction : null;
 
   // Pre-56: when NONE of the risk fields are present, emit the blank placeholder
   // verbatim (color 'default') so the column reads as "not yet scored".
@@ -105,7 +140,7 @@ function surfaceRiskOne(item) {
     risk_score,
     confidence,
     suggested_action,
-    color: colorForAction(suggested_action),
+    color: recognized ? ACTION_COLOR[canon] : 'default',
   };
 }
 

package/sdk/dashboard/tui/index.cjs

@@ -37,6 +37,21 @@ const readline = require('node:readline');
 
 const ansi = require('./ansi.cjs');
 
+// Lazily require the risk-surface helper (same dep-free constraint as the data plane).
+let _surfaceRisk = null;
+function getSurfaceRisk() {
+  if (_surfaceRisk === null) {
+    try {
+      ({ surfaceRisk: _surfaceRisk } = require('../data/risk-surface.cjs'));
+    } catch {
+      // If the module is unavailable for any reason, fall back to a no-op that returns
+      // blank placeholder rows so the column still renders cleanly.
+      _surfaceRisk = () => ({ risk_score: null, confidence: null, suggested_action: null, color: 'default' });
+    }
+  }
+  return _surfaceRisk;
+}
+
 // Lazily require the data plane so `renderFrame` (the pure path) can be imported + unit-tested
 // without paying for the data module's transitive requires. `run` resolves it on demand.
 let _loadDashboardModel = null;
@@ -351,11 +366,22 @@ function bodyFindings(model, inner, scroll) {
   if (tail.length === 0) {
     lines.push('  ' + ansi.color('no events', { dim: true }));
   } else {
+    const surfaceRisk = getSurfaceRisk();
     for (const ev of tail) {
       const name = (ev && (ev.event || ev.type || ev.kind)) || 'event';
-      // Pre-Phase-56: risk/confidence are blank placeholders (D8).
+      // Phase-56+: surface risk/confidence from risk_assessment events.
+      // For pre-56 events that lack risk fields, surfaceRiskOne returns the blank placeholder.
+      const surfaced = (ev && ev.type === 'risk_assessment')
+        ? surfaceRisk(ev)
+        : { risk_score: null, confidence: null, suggested_action: null, color: 'default' };
+      const riskText = surfaced.risk_score !== null
+        ? ansi.color(surfaced.risk_score.toFixed(2), { fg: surfaced.color !== 'default' ? surfaced.color : undefined })
+        : ansi.color('·', { dim: true });
+      const confText = surfaced.confidence !== null
+        ? String(surfaced.confidence.toFixed(2))
+        : ansi.color('·', { dim: true });
       lines.push(ansi.columns(
-        [String(name), ansi.color('·', { dim: true }), ansi.color('·', { dim: true })],
+        [String(name), riskText, confText],
         [Math.max(8, inner - 14), 5, 5],
       ));
     }

package/sdk/mcp/gdd-state/server.js

@@ -1776,7 +1776,13 @@ function migrationActive(statePath) {
   const backend = _loadBackend();
   if (backend === null || backend.BACKEND !== "sqlite") return false;
   const sqliteSibling = (0, import_node_path.join)((0, import_node_path.dirname)(statePath), "state.sqlite");
-  return (0, import_node_fs2.existsSync)(sqliteSibling);
+  if (!(0, import_node_fs2.existsSync)(sqliteSibling)) return false;
+  try {
+    if ((0, import_node_fs2.statSync)(sqliteSibling).isDirectory()) return false;
+  } catch {
+    return false;
+  }
+  return true;
 }
 async function read(path2) {
   const raw = (0, import_node_fs2.readFileSync)(path2, "utf8");

package/sdk/state/index.ts

@@ -33,6 +33,7 @@ import {
   renameSync,
   unlinkSync,
   existsSync,
+  statSync,
 } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -176,7 +177,16 @@ function migrationActive(statePath: string): boolean {
   const backend = _loadBackend();
   if (backend === null || backend.BACKEND !== 'sqlite') return false;
   const sqliteSibling = join(dirname(statePath), 'state.sqlite');
-  return existsSync(sqliteSibling);
+  if (!existsSync(sqliteSibling)) return false;
+  // BUG-07: a DIRECTORY named state.sqlite would cause existsSync to return true,
+  // and then every mutate() would throw when trying to open it as a database.
+  // Guard: if the path is a directory, treat migration as inactive.
+  try {
+    if (statSync(sqliteSibling).isDirectory()) return false;
+  } catch {
+    return false;
+  }
+  return true;
 }
 
 /**