@hegemonart/get-design-done 1.54.0 → 1.56.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.54.0"
+    "version": "1.56.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.54.0",
+      "version": "1.56.0",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.54.0",
+  "version": "1.56.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,98 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [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)
+
+GDD ships to 14 runtimes and users run multi-harness sessions in parallel; a control plane is the natural way to surface
+that. Phase 55 ships a READ-ONLY dashboard: a terminal TUI (`bin/gdd-dashboard`) and an opt-in browser graph view
+(`gdd dashboard --web`) that visualizes the Phase 52 DesignContext graph. **Built fully dep-free** (maintainer Rule-4
+decision): no Ink, no React / Vite / React Flow. The ROADMAP had named those stacks (~100 packages / ~84 MB + a CI build
+gate); a footprint study plus the read-only / single-machine / opt-in scale made a hand-rolled ANSI TUI + a
+self-contained-HTML graph (extending the Phase 35.5 `build-html.cjs` precedent) the better fit, and it keeps the
+zero-new-dependency streak intact. The web layer is kept swappable, so a React Flow migration later needs no data rewrite.
+Planned and executed via the GSD pipeline (3 + 3 parallel executors).
+
+### Breaking changes
+
+- **New `bin/gdd-dashboard` + `gdd dashboard [--web]`.** A new bin (the TUI) and a new SDK CLI subcommand. Read-only by
+  design: the dashboard never mutates state (the action surface is "open this file / copy this command / run the
+  slash-skill"). The `--web` server is an ephemeral LOCAL loopback (127.0.0.1, OS-assigned port) serving a single
+  self-contained HTML file to your own browser, then exits.
+- **`gsd-health` gains a 10th check** (`dashboard_reachable`); the health check count moves 9 -> 10.
+
+### Added
+
+- **Data plane** `sdk/dashboard/data/` - `source.cjs` (`loadDashboardModel` reads state / events / graph / health via the
+  shared libs in-process, with a `.design/*` file-scrape fallback; never throws), `cost-aggregator.cjs` (per-runtime +
+  cumulative + per-cycle), `discovery.cjs` (14-runtime detection, worktree enumeration via `git worktree list`,
+  best-effort session manifests).
+- **TUI** `bin/gdd-dashboard` + `sdk/dashboard/tui/` - a hand-rolled ANSI render core (`ansi.cjs`: box/column layout,
+  width-aware truncation incl. CJK, line-diff repaint) + 5 panes (Sessions / Cycle / Cost / Findings /
+  DesignContext-tree), keyboard navigation, alt-screen, event-tail live refresh. Plain `.cjs` (no bundle, no flags).
+- **Web graph** `scripts/lib/dashboard/graph-html.cjs` (`buildGraphHtml`) - one self-contained HTML doc (inline SVG +
+  vanilla JS): layered Atomic / Molecular / Organism / Template layout with barycenter crossing-reduction, viewBox
+  pan/zoom, click-to-inspect, type/tag filters, find-consumers highlight, unreachable outline, PNG export, minimap.
+  Deterministic (hermetic byte-equal test). Launched by `gdd dashboard --web` (`node:http` loopback + browser-open;
+  headless prints the URL; `--once` writes `.design/dashboard.html`).
+- **Risk surfacing** `sdk/dashboard/data/risk-surface.cjs` - reads `risk_score`/`confidence` when present (Phase 56),
+  color-routes Allow/Review/RequireConfirmation/Block; a blank placeholder pre-56.
+
+### Notes
+
+- 6-manifest lockstep at **v1.55.0** + `OFF_CADENCE_VERSIONS.add('1.55.0')` + 37 `manifests-version.txt` baselines.
+  No new skill (the dashboard is a bin + CLI subcommand) -> skill-list / build:skills / skills.json unchanged. No new
+  agent. The dashboard's local `node:http` server is allowlisted in `scripts/security/outbound-allowlist.json` (an
+  inbound loopback read-only server, not outbound egress). Tarball golden 969 -> 979. **No new runtime dependency.**
+
+---
+
 ## [1.54.0] - 2026-06-03
 
 ### Phase 54 - Composable Reference Addendums (Per-DS + Per-Framework + Per-Motion-Lib)

package/README.md

@@ -269,6 +269,10 @@ All 14 runtimes receive their native artifact layout (`skills/`, `command/`, `ag
 
 **Composable reference addendums (v1.54.0).** One general mapper prompt cannot know Tailwind's `@theme` tokens from shadcn's `cn()` from vanilla-extract's `style({})`. Phase 54 adds 18 stack-specific addendums (8 design systems, 6 frameworks, 4 motion libraries) under `reference/{systems,frameworks,motion}/`, each at most 50 lines with Conventions / File patterns / Gotchas / Example-output sections. `scripts/lib/detect/stack.cjs` detects the project stack from dependencies plus config files and import signatures; `scripts/lib/mapper-spawn.cjs` composes the matching addendums (capped at one DS + one framework + one motion) into each explore mapper's prompt at spawn time, additively, so a project on an unknown stack just keeps the base prompt and `gsd-health` reports the coverage gap. A `/gdd:new-addendum` scaffolder adds more. Maintainer-authored, vendor-cross-checked, no LLM-generated content. **No new runtime dependency.**
 
+**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.**
+
 Verify with:
 
 ```
@@ -843,6 +847,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,7 @@ 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 |
 
 ## 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/bin/gdd-dashboard

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// bin/gdd-dashboard — Phase 55 (GDD Dashboard, DEP-FREE), TUI-01 (executor D).
+//
+// CJS trampoline that launches the terminal dashboard
+// (sdk/dashboard/tui/index.cjs) under `node`, forwarding argv + the child's
+// exit code / signal. Windows-safe.
+//
+// SIMPLER than bin/gdd-sdk (R8): the TUI is plain `.cjs` (Node builtins only),
+// so there is NO esbuild bundle and NO `--experimental-strip-types` flag — we
+// just `node <entry>`. The only reason this is a spawning trampoline (rather
+// than a direct require) is the same one gdd-sdk documents: npm's
+// auto-generated Windows `.cmd` shim invokes `node bin/gdd-dashboard` and we
+// want a single, platform-uniform launch path that cleanly forwards the exit
+// code and re-raises a terminating signal (so Ctrl-C tears down correctly).
+//
+// Sibling resolution uses a PACKAGE-ROOT WALK-UP (the Phase 53/54 lesson, D7),
+// never a fixed `__dirname`-relative cross-tree jump: we climb from this file's
+// directory to the GDD package root (package.json with name
+// "get-design-done") and resolve `sdk/dashboard/tui/index.cjs` from there. This
+// keeps the bin correct even if it is copied/relocated within the tree.
+
+'use strict';
+
+const { spawn } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Walk up from `startDir` to the GDD package root: the first ancestor whose
+ * package.json declares `name === "get-design-done"`. Falls back to the first
+ * ancestor that has any package.json, then to `startDir`. Bounded climb.
+ * @param {string} startDir
+ * @returns {string} absolute package-root directory
+ */
+function findPackageRoot(startDir) {
+  let dir = path.resolve(startDir);
+  let firstWithPkg = null;
+  for (let i = 0; i < 12; i++) {
+    const pkgPath = path.join(dir, 'package.json');
+    let pkg = null;
+    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;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return firstWithPkg || path.resolve(startDir);
+}
+
+const root = findPackageRoot(__dirname);
+const entry = path.join(root, 'sdk', 'dashboard', 'tui', 'index.cjs');
+
+if (!fs.existsSync(entry)) {
+  // eslint-disable-next-line no-console
+  console.error(`gdd-dashboard: TUI entry not found at ${entry}`);
+  process.exit(3);
+}
+
+const child = spawn(process.execPath, [entry, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+  shell: false,
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    // Re-raise the signal so the parent shell sees the same termination mode
+    // (e.g. Ctrl+C propagates as SIGINT). Falls back to a non-zero exit if the
+    // self-signal cannot be delivered.
+    try {
+      process.kill(process.pid, signal);
+    } catch {
+      process.exit(1);
+    }
+    return;
+  }
+  process.exit(typeof code === 'number' ? code : 0);
+});
+
+child.on('error', (err) => {
+  // Failure to spawn node itself — extremely rare; surface to stderr.
+  // eslint-disable-next-line no-console
+  console.error('gdd-dashboard: failed to launch the TUI:', err.message);
+  process.exit(3);
+});

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/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,
 };