@hegemonart/get-design-done 1.55.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.55.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.55.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.55.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,96 @@ 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)
+
+Every writer action now carries a quantified risk score instead of a binary allow/deny. Phase 56 adds a pure,
+deterministic risk scorer (no I/O, frozen tables) that grades each Write / Edit / MultiEdit / Bash by tool, file
+sensitivity, and input shape, then routes it through two PreToolUse hooks: a risk gate that emits a `risk_assessment`
+event and blocks only genuinely dangerous actions, and a fact-force gate that holds the FIRST write to a file until its
+graph consumers and recorded decisions have actually been read. Both are **dep-free** (a maintainer Rule-4 decision: a
+pure scorer plus static tables, no ML, no new dependency). The gate softens to a warning whenever the Phase 52
+DesignContext graph is absent, so greenfield projects are never over-blocked. A new `/gdd:override` escalation skill
+clears a block or a fact-force hold with an approver and reason (audit-trailed as a `D-XX` override decision), and
+`design-fixer` gains a confidence-times-risk routing step. Planned and executed via the GSD pipeline (3 + 2 parallel
+executors).
+
+### Breaking changes
+
+- **Writer actions are now risk-gated.** A new PreToolUse hook (`hooks/gdd-risk-gate.js`, matcher
+  `Write|Edit|MultiEdit|Bash`) scores every writer action and blocks the few that score at or above 0.85 (destructive
+  bash, high-sensitivity-file rewrites). Blocking uses the house-style `{continue:false, stopReason}` contract; `allow`
+  is silent, `review` and `require_confirmation` attach advisory context for the agent to surface. Read-only agents are
+  allowlisted through.
+- **The first write to a file is fact-forced.** A second PreToolUse hook (`hooks/gdd-fact-force.js`, matcher
+  `Edit|Write|MultiEdit`) holds the first mutation of a file until its DesignContext consumers and any recorded
+  decisions or blockers for it have been Read this session. The hold is soft (a `stopReason` listing the missing facts)
+  and softens to a warning when no graph exists; clear it deliberately with `/gdd:override factforce <path>`.
+
+### Added
+
+- **Risk scorer** `scripts/lib/risk/` - `compute-risk.cjs` (`computeRisk(tool, input) -> {score, reasons, suggested_action, breakdown}`,
+  pure and deterministic), `tables.cjs` (frozen BASE_TOOL_RISK / FILE_SENSITIVITY / INPUT_PATTERN_RISK / THRESHOLDS,
+  config-overridable extend-only), `route.cjs` (`route(confidence, action) -> auto|confirm|skip|override`),
+  `consumers.cjs` (best-effort file-to-node consumers lookup, soften-if-absent), `calibration.cjs` (rolling-50 per-agent
+  calibration plus drift detection feeding the bandit reward), `override.cjs`.
+- **`/gdd:override`** - escalation surface for a risk-gate block or a fact-force hold; writes a `D-XX` override-tagged
+  decision (audit trail) or clears the `checked[path]` lock, always with an approver and reason.
+- **`risk_assessment` event type** in `reference/schemas/events.schema.json` (score, suggested_action, reasons),
+  surfaced by the Phase 55 dashboard risk pane.
+- **`design-fixer` Step 2.5** - a confidence-times-risk routing filter (auto-apply / confirm-with-diff / skip / escalate).
+
+### Changed
+
+- **`hooks/gdd-decision-injector.js`** now records per-file reads so the fact-force gate can tell which files you have
+  legitimately reviewed this session.
+
 ## [1.55.0] - 2026-06-03
 
 ### Phase 55 - GDD Dashboard (Multi-Harness Control Plane + Graph Visualization + Session Surface)

package/README.md

@@ -271,6 +271,10 @@ All 14 runtimes receive their native artifact layout (`skills/`, `command/`, `ag
 
 **GDD dashboard (v1.55.0).** A read-only multi-harness control plane. `gdd-dashboard` opens a terminal TUI with five panes (sessions per runtime, current cycle, cost telemetry, findings, a DesignContext tree); `gdd dashboard --web` opens an interactive browser view of the Phase 52 graph (layered Atomic/Molecular/Organism/Template layout, pan/zoom, click-to-inspect, type/tag filters, find-consumers highlight, PNG export, minimap). It is **built fully dep-free** (a maintainer decision over the roadmap's Ink + React Flow + Vite stack, which would have added ~100 packages): the TUI is a hand-rolled ANSI renderer, the graph view is a self-contained HTML file (inline SVG + vanilla JS, extending the export builder), and the data plane reads GDD state through the existing shared libraries in-process. Read-only by design (the action surface is open-file / copy-command / run-skill); the `--web` server is a local loopback that serves to your own browser and exits. **No new runtime dependency.**
 
+**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:
 
 ```
@@ -845,6 +849,8 @@ GDD ships defense-in-depth security since Phase 14.5:
 
 - **`hooks/gdd-bash-guard.js`** - PreToolUse:Bash blocks ~50 dangerous patterns (`rm -rf /`, `chmod 777`, `curl | sh`, `git reset --hard`, fork bombs) after Unicode NFKC + ANSI normalization.
 - **`hooks/gdd-protected-paths.js`** - PreToolUse:Edit/Write/Bash enforces `protected_paths` glob list (defaults: `reference/**`, `.design/archive/**`, `skills/**`, `commands/**`, `hooks/**`, `.design/config.json`, `.design/telemetry/**`).
+- **`hooks/gdd-risk-gate.js`** - PreToolUse:Write/Edit/MultiEdit/Bash scores each writer action via the pure `scripts/lib/risk/compute-risk.cjs` (tool x file-sensitivity x input shape), emits a `risk_assessment` event, and blocks only actions at or above 0.85; `allow` is silent, `review` / `require_confirmation` attach advisory context. Clear a block with `/gdd:override`.
+- **`hooks/gdd-fact-force.js`** - PreToolUse:Edit/Write/MultiEdit holds the first write to a file until its DesignContext consumers and recorded decisions have been Read this session; soft block, softens to a warning when the graph is absent, cleared with `/gdd:override factforce <path>`.
 - **`hooks/gdd-read-injection-scanner.ts`** - scans inbound Read content for invisible-Unicode (zero-width, word-joiner, BOM, bidi overrides) + HTML-comment + secret-exfil patterns.
 - **`scripts/lib/blast-radius.cjs`** - `design-executor` preflight refuses tasks above `max_files_per_task: 10` / `max_lines_per_task: 400`.
 - **`hooks/gdd-mcp-circuit-breaker.js`** - breaks consecutive-timeout loops on `use_figma` / `use_paper` / `use_pencil`.

package/SKILL.md

@@ -116,6 +116,8 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `locale [<code>]` | `get-design-done:gdd-locale` | Phase 40.5 - inspect or set the GDD CLI locale (en/ru/uk/de/fr/zh/ja) for `--help`, errors, and skill prompt headers; missing keys fall back to English. No arg reports the resolved locale + coverage |
 | `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/agents/design-fixer.md

@@ -125,6 +125,22 @@ f. **Record status.** Note `G-NN: fixed` in your running tracker.
 - **Rule 3 - Blocking issue:** If something prevents applying this specific fix (missing import, wrong file structure), resolve the blocking issue first, then apply the fix → continue.
 - **Rule 4 - Architectural change required:** If resolving the gap requires a new DB table, major schema change, switching libraries, or breaking API changes → DO NOT force a fix. Classify as unresolvable and proceed to Step 3 for this gap.
 
+### Step 2.5 - Confidence x risk routing (Phase 56)
+
+Step 1's confidence filter (`scripts/lib/confidence-route.cjs`) already dropped tentative and low-confidence gaps. Step 2.5 adds the action-risk dimension: a fix that is correct can still be dangerous to APPLY (touching STATE.md, a schema, a hook, a large diff). Score the write, then combine score and confidence into one routing decision per gap.
+
+For each in-scope gap, before applying its edit:
+
+1. **Score the write.** `risk = computeRisk('Edit', { file_path, new_string })` from `scripts/lib/risk/compute-risk.cjs` (use `MultiEdit` with `edits[]` for multi-hunk fixes, `Write` for full rewrites). `risk.suggested_action` is one of `allow | review | require_confirmation | block`.
+2. **Route.** `decision = route(gap.confidence, risk.suggested_action)` from `scripts/lib/risk/route.cjs`:
+   - `auto` (high confidence, low risk): apply the fix via the Step 2 sequence and commit.
+   - `confirm` (medium confidence, or `require_confirmation` risk): propose the fix with its diff via `AskUserQuestion` before writing. Apply only on approval; otherwise treat it as `skip`. This agent is the only place the confirmation prompt happens (the writer hooks just score and flag).
+   - `skip` (confidence below 0.5, non-block): leave the gap as a deferred finding; do not write. Note it in the tracker.
+   - `override` (risk `block`, at any confidence): do NOT auto-apply a block-risk write. Route the user to `{{command_prefix}}override <G-NN> --approver <who> --reason <text>`; apply only after the audited override is recorded.
+3. **Record.** Note each gap as `G-NN: auto | confirm | skip | override` in your running tracker, then carry the `auto` and approved-`confirm` gaps into the Step 2 fix sequence.
+
+`route` and `computeRisk` are pure and dependency-free, so this filter is deterministic. A gap whose confidence field is missing is treated as the lowest tier (skip, unless the action is `block`, which routes to override).
+
 ### Step 3 - Handle unresolvable gaps
 
 A gap is unresolvable if:

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

@@ -0,0 +1,86 @@
+---
+name: gdd-override
+description: "Escalation surface for a risk-blocked action or a fact-force gate. Use when the Phase 56 risk gate blocked a writer action (suggested_action=block) and a reviewer has signed off, or when the first-write fact-force gate is holding a file you have legitimately reviewed. Activates for requests involving overriding a blocked edit, approving a high-risk change, or clearing a fact-force hold on a path."
+argument-hint: "<finding-id | factforce <path>> [--approver <who>] [--reason <text>]"
+user-invocable: true
+tools: Read, Write, Bash, Grep, Glob
+---
+
+# /gdd:override
+
+A risk-blocked action is hard: the Phase 56 risk gate routes `suggested_action=block`
+to `override` (see `scripts/lib/risk/route.cjs`), and the fact-force gate holds the
+first write to a file until its facts are read. This skill is the audited way past
+either hold. It mirrors `/gdd:unlock-decision`: a named approver plus a
+reason, recorded before anything is let through. Override is never silent.
+
+## Invocation
+
+| Command | Behavior |
+|---|---|
+| `/gdd:override <finding-id> --approver <who> --reason <text>` | Record a `D-XX` `override`-tagged decision in STATE.md `<decisions>` and let the risk-blocked action through. |
+| `/gdd:override factforce <path> --approver <who> --reason <text>` | Set `checked[path]` in the session fact-force state so the fact-force gate stops holding that path. |
+
+Both modes ask for a rationale: the audit trail is the reason override exists.
+
+## Steps
+
+1. **Parse args.** Mode is `factforce` when the first token is the literal `factforce`
+   (the next token is the `<path>`); otherwise the first token is a `<finding-id>`.
+   `--approver` is required (a non-empty name). Missing `--approver` prints the usage
+   and changes nothing. If `--reason` is absent, ASK for one (AskUserQuestion or a
+   prompt) before continuing: an override with no rationale is rejected.
+
+2. **Preview.** Show what will be written and stop for confirmation:
+   - finding mode: the decision entry from `overrideDecisionEntry(<id>, {approver, reason})`
+     (its `text`, `status: locked`, and `override` tag) plus the action it unblocks.
+   - factforce mode: the `<path>` that will gain `checked[path] = true` and the
+     session-state file it lands in.
+
+3. **Apply (finding mode).** Record the audited decision via the STATE writer
+   `mcp__gdd_state__add_decision` (it auto-assigns the next `D-N`). Pass the `text`
+   from the pure builder so the `override` tag is embedded and greppable:
+
+   ```bash
+   node -e '
+     const o = require("./scripts/lib/risk/override.cjs");
+     const [id, who, reason] = process.argv.slice(1);
+     const entry = o.overrideDecisionEntry(id, { approver: who, reason });
+     console.log(JSON.stringify(entry));
+   ' "<finding-id>" "<who>" "<reason>"
+   ```
+
+   Then call `mcp__gdd_state__add_decision` with `{ text: <entry.text>, status: "locked" }`.
+   The blocked action is now approved on the audit record; proceed with it.
+
+4. **Apply (factforce mode).** Set `checked[path]` in the session state file at
+   `<cwd>/.design/locks/factforce-<session_id>.json` (atomic tmp then rename), using
+   the pure helper so the shape matches what the fact-force gate reads:
+
+   ```bash
+   node -e '
+     const fs = require("fs"); const path = require("path");
+     const o = require("./scripts/lib/risk/override.cjs");
+     const [file, p] = process.argv.slice(1);
+     let state = {}; try { state = JSON.parse(fs.readFileSync(file, "utf8")); } catch {}
+     const next = o.setFactForceChecked(state, p);
+     fs.mkdirSync(path.dirname(file), { recursive: true });
+     const tmp = file + ".tmp";
+     fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + "\n");
+     fs.renameSync(tmp, file);
+     console.log(JSON.stringify(next.checked));
+   ' "<cwd>/.design/locks/factforce-<session_id>.json" "<path>"
+   ```
+
+   The fact-force gate stops holding `<path>` for the rest of the session.
+
+5. **Report** the recorded approver, the reason, and either the new `D-XX` id (finding
+   mode) or the unblocked path (factforce mode).
+
+## Do Not
+
+- Do not skip the rationale: every override is audited.
+- Do not override a finding that the risk gate did not actually block.
+- Do not edit `scripts/lib/risk/route.cjs` or `compute-risk.cjs`: this skill consumes them.
+
+## OVERRIDE COMPLETE

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-decision-injector.js

@@ -524,6 +524,58 @@ function buildRecallBlock(matches, basename, backendLabel) {
   return lines.join('\n');
 }
 
+/**
+ * Phase 56 (fact-force) read-tracking — ADDITIVE, best-effort, non-blocking.
+ *
+ * On every Read, record `reads[<normalizedRelPath>] = <ISO>` into the SAME
+ * session-state file the fact-forcing gate consults
+ * (`<cwd>/.design/locks/factforce-<sanitized session_id>.json`). This is how the
+ * gate knows which importer files an agent has already opened before its first
+ * mutation. Fully swallowed on any error so it can NEVER change this Read hook's
+ * existing decision-injection behavior or its `{ continue: true }` contract.
+ *
+ * Self-contained (no new import): mirrors the gate's session_id derivation
+ * (`payload.session_id ?? GDD_SESSION_ID ?? 'hook'`), path normalization, and
+ * atomic tmp+rename write so the two hooks agree byte-for-byte on the file.
+ */
+function recordReadForFactForce(payload) {
+  try {
+    const fp = payload && payload.tool_input && payload.tool_input.file_path;
+    if (!fp) return;
+    const cwd = (payload && payload.cwd) || process.cwd();
+
+    let rel = String(fp);
+    if (rel.startsWith('/') || /^[A-Za-z]:[\\/]/.test(rel)) {
+      try { rel = path.relative(cwd, rel); } catch { /* keep rel */ }
+    }
+    rel = rel.replace(/\\/g, '/').replace(/^\.\//, '');
+    if (!rel) return;
+
+    const rawSid = (payload && (payload.session_id || payload.sessionId))
+      || process.env.GDD_SESSION_ID
+      || 'hook';
+    const sid = String(rawSid).replace(/[^A-Za-z0-9_-]+/g, '-').slice(0, 120) || 'hook';
+    const stateFile = path.join(cwd, '.design', 'locks', `factforce-${sid}.json`);
+
+    let state = { reads: {}, first_mutation_seen: {}, checked: {} };
+    try {
+      const parsed = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+      if (parsed && typeof parsed === 'object') {
+        state.reads = (typeof parsed.reads === 'object' && parsed.reads) || {};
+        state.first_mutation_seen = (typeof parsed.first_mutation_seen === 'object' && parsed.first_mutation_seen) || {};
+        state.checked = (typeof parsed.checked === 'object' && parsed.checked) || {};
+      }
+    } catch { /* missing/corrupt -> start fresh */ }
+
+    state.reads[rel] = new Date().toISOString();
+
+    fs.mkdirSync(path.dirname(stateFile), { recursive: true });
+    const tmp = `${stateFile}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(state, null, 2));
+    fs.renameSync(tmp, stateFile);
+  } catch { /* best-effort: never let read-tracking affect the Read hook */ }
+}
+
 async function main() {
   let buf = '';
   for await (const chunk of process.stdin) buf += chunk;
@@ -539,6 +591,11 @@ async function main() {
     return;
   }
 
+  // Phase 56: record this Read into the fact-force session state for EVERY
+  // Read (not just recall-matching .md files), before the recall matcher gate.
+  // Best-effort + fully swallowed — does not alter the behavior below.
+  recordReadForFactForce(payload);
+
   const fp = payload?.tool_input?.file_path || '';
   if (!MATCHER_RE.test(fp)) {
     process.stdout.write(JSON.stringify({ continue: true }));
@@ -651,5 +708,6 @@ module.exports = {
   buildInstinctsBlock,
   instinctTokens,
   queryInstinctsBlock,
+  recordReadForFactForce,
   main,
 };