@hegemonart/get-design-done 1.55.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.55.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.55.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.55.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,51 @@ 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)

package/README.md

@@ -271,6 +271,8 @@ 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.**
+
 Verify with:
 
 ```
@@ -845,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/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,
 };

package/hooks/gdd-fact-force.js

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * hooks/gdd-fact-force.js — PreToolUse:Edit|Write|MultiEdit fact-forcing gate.
+ *
+ * Forces an agent to establish the FACTS before the FIRST mutation of a file in
+ * a session: the file's importers/consumers (from the Phase 52 DesignContext
+ * graph) must have been Read, and any decisions/blockers tagged with the file
+ * must have been surfaced. Until those prerequisites are met, the first write
+ * is SOFT-blocked (`{continue:false, stopReason}` listing the missing facts);
+ * the agent can satisfy them (Read the importers) or escape via
+ * `/gdd:override factforce <path>` which sets `checked[path]`.
+ *
+ * Tiering (CONTEXT.md shared contract):
+ *   - prerequisites met OR checked[path] set      -> { continue:true }
+ *   - prerequisites UNMET, computeRisk != block    -> SOFT block (continue:false)
+ *   - prerequisites UNMET, computeRisk == block     -> HARD block (continue:false);
+ *       only escape is /gdd:override (same JSON shape, stronger stopReason)
+ *   - graph ABSENT/unbuilt                          -> importer prereq SOFTENS to a
+ *       warning, never a hard block (do not over-block greenfield)
+ *
+ * Session-state (worktree-safe, CONTEXT.md R5):
+ *   <cwd>/.design/locks/factforce-<sanitized session_id>.json
+ *   { reads: { <normPath>: <ISO> }, first_mutation_seen: { <normPath>: <ISO> },
+ *     checked: { <normPath>: true } }
+ *   Atomic tmp+rename. session_id from payload.session_id ?? GDD_SESSION_ID ?? 'hook'.
+ *
+ * Contract (PreToolUse): stdin { tool_name, tool_input:{file_path}, cwd, session_id? }
+ *   stdout: { continue:true } | { continue:false, stopReason }
+ *   exit  : always 0. NEVER throws (fail-open { continue:true }).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const GATED_TOOLS = new Set(['Edit', 'Write', 'MultiEdit']);
+
+// ---------------------------------------------------------------------------
+// Package-root walk-up (Phase 53/54 lesson) for robust sibling resolution.
+// ---------------------------------------------------------------------------
+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;
+}
+
+/**
+ * Lazily resolve a sibling lib module by name, trying the adjacent path first
+ * then the package-root walk-up. Returns null when unresolvable (the gate then
+ * SOFTENS rather than crashing).
+ */
+function requireSibling(relFromLib, validate) {
+  const candidates = [path.join(__dirname, '..', 'scripts', 'lib', relFromLib)];
+  const root = findPackageRoot(__dirname);
+  if (root) candidates.push(path.join(root, 'scripts', 'lib', relFromLib));
+  for (const c of candidates) {
+    try {
+      const m = require(c);
+      if (!validate || validate(m)) return m;
+    } catch { /* try next */ }
+  }
+  return null;
+}
+
+const _risk = requireSibling('risk/compute-risk.cjs', (m) => m && typeof m.computeRisk === 'function');
+const _consumers = requireSibling('risk/consumers.cjs', (m) => m && typeof m.consumersOfFile === 'function');
+
+// ---------------------------------------------------------------------------
+// Path normalization
+// ---------------------------------------------------------------------------
+function normPath(p, cwd) {
+  if (!p) return '';
+  let s = String(p);
+  // Make absolute paths relative to cwd so reads[] keys match across the
+  // (absolute file_path the agent passes) and (relative paths we derive).
+  if (s.startsWith('/') || /^[A-Za-z]:[\\/]/.test(s)) {
+    try { s = path.relative(cwd || process.cwd(), s); } catch { /* keep s */ }
+  }
+  return s.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function leafSlug(p) {
+  const base = path.basename(String(p || ''));
+  return base.replace(/\.[a-z0-9.]+$/i, '').toLowerCase();
+}
+
+// ---------------------------------------------------------------------------
+// Session-state (atomic tmp+rename; mirrors bandit-router's write pattern)
+// ---------------------------------------------------------------------------
+function sessionIdFrom(payload) {
+  const raw = (payload && (payload.session_id || payload.sessionId))
+    || process.env.GDD_SESSION_ID
+    || 'hook';
+  // Sanitize for a filename: keep alnum/dash/underscore, collapse the rest.
+  return String(raw).replace(/[^A-Za-z0-9_-]+/g, '-').slice(0, 120) || 'hook';
+}
+
+function stateFileFor(cwd, sessionId) {
+  return path.join(cwd || process.cwd(), '.design', 'locks', `factforce-${sessionId}.json`);
+}
+
+function loadState(stateFile) {
+  const empty = { reads: {}, first_mutation_seen: {}, checked: {} };
+  try {
+    const parsed = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+    return {
+      reads: (parsed && typeof parsed.reads === 'object' && parsed.reads) || {},
+      first_mutation_seen: (parsed && typeof parsed.first_mutation_seen === 'object' && parsed.first_mutation_seen) || {},
+      checked: (parsed && typeof parsed.checked === 'object' && parsed.checked) || {},
+    };
+  } catch {
+    return empty;
+  }
+}
+
+function saveState(stateFile, state) {
+  try {
+    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: a state-write failure must not break the gate */ }
+}
+
+// ---------------------------------------------------------------------------
+// Decisions/blockers grep (reuses the decision-injector idiom: scan the small
+// canonical design docs for lines mentioning the file's basename/relPath).
+// ---------------------------------------------------------------------------
+function decisionSources(cwd) {
+  const roots = [];
+  for (const rel of [
+    ['.design', 'STATE.md'],
+    ['.design', 'CYCLES.md'],
+    ['.design', 'learnings', 'LEARNINGS.md'],
+  ]) {
+    const p = path.join(cwd, ...rel);
+    try { if (fs.statSync(p).isFile()) roots.push(p); } catch { /* skip */ }
+  }
+  return roots;
+}
+
+/**
+ * Does any decision/blocker line mention this file? Best-effort substring grep
+ * over the canonical docs for the file's basename or relPath (the same terms
+ * the decision-injector greps on). Returns { found:boolean, where:string|null }.
+ */
+function decisionMentions(cwd, relPath) {
+  const basename = path.basename(relPath);
+  const terms = Array.from(new Set([basename, relPath].filter(Boolean)));
+  for (const src of decisionSources(cwd)) {
+    let content;
+    try { content = fs.readFileSync(src, 'utf8'); } catch { continue; }
+    for (const t of terms) {
+      if (t && content.includes(t)) return { found: true, where: path.basename(src) };
+    }
+  }
+  return { found: false, where: null };
+}
+
+// ---------------------------------------------------------------------------
+// Importer prerequisite: were the file's consumers Read this session?
+// SOFTENS when the graph is absent (available:false).
+// ---------------------------------------------------------------------------
+function readSlugs(state, cwd) {
+  // Index the session reads by their leaf slug for token matching against
+  // consumer node names.
+  const slugs = new Set();
+  for (const k of Object.keys(state.reads || {})) {
+    const s = leafSlug(k);
+    if (s) slugs.add(s);
+  }
+  return slugs;
+}
+
+/**
+ * @returns {{ softened:boolean, unread:string[] }}
+ *   softened — true when the graph is unavailable (importer check downgraded
+ *              to a non-blocking warning).
+ *   unread   — importer slugs that were NOT found in this session's reads.
+ */
+function importerPrereq(filePath, cwd, state) {
+  if (!_consumers) return { softened: true, unread: [] };
+  let res;
+  try {
+    res = _consumers.consumersOfFile(filePath, { root: cwd });
+  } catch {
+    return { softened: true, unread: [] };
+  }
+  if (!res || res.available !== true) {
+    // Graph absent / unbuilt / file unmapped-with-no-graph -> SOFTEN.
+    return { softened: true, unread: [] };
+  }
+  const importers = Array.isArray(res.importers) ? res.importers : [];
+  if (importers.length === 0) return { softened: false, unread: [] };
+  const reads = readSlugs(state, cwd);
+  const unread = importers.filter((imp) => !reads.has(String(imp).toLowerCase()));
+  return { softened: false, unread };
+}
+
+// ---------------------------------------------------------------------------
+// Risk tier (imports A's compute-risk; SOFTENS to non-block when unavailable)
+// ---------------------------------------------------------------------------
+function riskIsBlock(tool, input, cwd) {
+  if (!_risk) return false;
+  try {
+    const cfg = typeof _risk.loadRiskConfig === 'function' ? _risk.loadRiskConfig(cwd) : null;
+    const thresholds = cfg && cfg.thresholds ? cfg.thresholds : undefined;
+    const r = _risk.computeRisk(tool, input, thresholds);
+    return !!(r && r.suggested_action === 'block');
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+  let buf = '';
+  for await (const chunk of process.stdin) buf += chunk;
+
+  let payload;
+  try { payload = JSON.parse(buf || '{}'); } catch {
+    process.stdout.write(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  const tool = (payload && payload.tool_name) || '';
+  if (!GATED_TOOLS.has(tool)) {
+    process.stdout.write(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  const cwd = (payload && payload.cwd) || process.cwd();
+  const rawPath = payload && payload.tool_input && payload.tool_input.file_path;
+  if (!rawPath) {
+    process.stdout.write(JSON.stringify({ continue: true }));
+    return;
+  }
+  const relPath = normPath(rawPath, cwd);
+
+  const sessionId = sessionIdFrom(payload);
+  const stateFile = stateFileFor(cwd, sessionId);
+  const state = loadState(stateFile);
+
+  // (1) Already overridden for this path -> always pass (and record the seen).
+  if (state.checked && state.checked[relPath]) {
+    if (!state.first_mutation_seen[relPath]) {
+      state.first_mutation_seen[relPath] = new Date().toISOString();
+      saveState(stateFile, state);
+    }
+    emit('allow', { reason: 'checked', path: relPath });
+    process.stdout.write(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  // (2) Not the FIRST mutation of this file this session -> not re-gated.
+  if (state.first_mutation_seen && state.first_mutation_seen[relPath]) {
+    emit('allow', { reason: 'already-mutated', path: relPath });
+    process.stdout.write(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  // (3) First mutation: evaluate prerequisites.
+  const missing = [];
+
+  const imp = importerPrereq(rawPath, cwd, state);
+  if (!imp.softened && imp.unread.length > 0) {
+    missing.push(`unread importers: ${imp.unread.join(', ')} (Read the file(s) that consume '${relPath}')`);
+  }
+
+  const dec = decisionMentions(cwd, relPath);
+  // A decision/blocker is "tagged with X" when a canonical doc mentions the
+  // file. If one exists, it must have been surfaced (Read) this session — we
+  // approximate "surfaced" by the doc itself being in reads[], else flag it.
+  if (dec.found) {
+    const docReadKnown = Object.keys(state.reads || {}).some((k) => {
+      const b = path.basename(k);
+      return b === dec.where || b === 'STATE.md' || b === 'CYCLES.md' || b === 'LEARNINGS.md';
+    });
+    if (!docReadKnown) {
+      missing.push(`unreviewed decisions/blockers tagged '${path.basename(relPath)}' in ${dec.where} (Read it first)`);
+    }
+  }
+
+  // Record that we have now SEEN the first mutation attempt for this file (so a
+  // subsequent retry after the agent satisfies prereqs flows through gate (2)
+  // only AFTER a pass; we set the marker on the allow path below to avoid
+  // permanently disarming on a blocked attempt).
+  if (missing.length === 0) {
+    state.first_mutation_seen[relPath] = new Date().toISOString();
+    saveState(stateFile, state);
+    emit('allow', { reason: 'prereqs-met', path: relPath, softened: imp.softened });
+    process.stdout.write(JSON.stringify({ continue: true }));
+    return;
+  }
+
+  // Prerequisites unmet -> block. SOFT unless risk == block (then HARD).
+  const hard = riskIsBlock(tool, payload.tool_input, cwd);
+  const factsList = missing.join('; ');
+  const stopReason = hard
+    ? `gdd-fact-force (HARD — risk=block): cannot mutate '${relPath}' until facts are established — ${factsList}. The only escape is \`/gdd:override factforce ${relPath} --approver <who>\`.`
+    : `gdd-fact-force: establish the facts before the first edit to '${relPath}' — ${factsList}. Read them, or run \`/gdd:override factforce ${relPath}\` to mark checked.`;
+
+  emit(hard ? 'block-hard' : 'block-soft', { path: relPath, missing: missing.length });
+  process.stdout.write(JSON.stringify({ continue: false, stopReason }));
+}
+
+// Best-effort telemetry — never throws, swallowed if the emitter is absent.
+function emit(decision, detail) {
+  try {
+    require('./_hook-emit.js').emitHookFired('gdd-fact-force', decision, detail || {});
+  } catch { /* swallow */ }
+}
+
+// Auto-run when invoked directly (hooks.json runs `node hooks/gdd-fact-force.js`).
+// Guarded so tests can require() the module to unit-test the pure helpers.
+if (require.main === module) {
+  main().catch(() => {
+    process.stdout.write(JSON.stringify({ continue: true }));
+  });
+}
+
+module.exports = {
+  // pure-ish helpers exported for tests; main() owns the I/O + contract.
+  normPath,
+  leafSlug,
+  sessionIdFrom,
+  stateFileFor,
+  loadState,
+  saveState,
+  decisionMentions,
+  importerPrereq,
+  riskIsBlock,
+  findPackageRoot,
+  main,
+};