@hegemonart/get-design-done 1.55.0 → 1.56.0

package/hooks/gdd-risk-gate.js

@@ -0,0 +1,406 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * hooks/gdd-risk-gate.js — PreToolUse:Write|Edit|MultiEdit|Bash risk gate (Phase 56, RISK-02).
+ *
+ * Quantifies the confidence/risk of a writer action with the PURE scorer
+ * `scripts/lib/risk/compute-risk.cjs` (executor A), emits a `risk_assessment`
+ * telemetry event, and routes by the scorer's `suggested_action`:
+ *
+ *   allow                -> { continue: true }                                  (silent)
+ *   review               -> { continue: true, hookSpecificOutput: { … } }       (advisory, non-blocking)
+ *   require_confirmation -> { continue: true, hookSpecificOutput: { … } }       (advisory; the AGENT — design-fixer —
+ *                                                                                 does the AskUserQuestion, NOT the hook; R2)
+ *   block                -> { continue: false, stopReason: '…' }                (the block: continue:false at EXIT 0)
+ *
+ * Contract (the repo house-style — gdd-bash-guard / gdd-protected-paths, R1):
+ *   Input  (stdin JSON): { tool_name, tool_input, cwd, session_id? }
+ *   Output (stdout JSON):
+ *     - allow/review/confirm -> { continue: true [, hookSpecificOutput] }
+ *     - block                -> { continue: false, stopReason }
+ *   Exit: ALWAYS 0. `continue:false` is the block — never `process.exit(2)`.
+ *
+ * Resilience: best-effort. ANY error (bad stdin, unresolvable sibling, scorer
+ * throw, telemetry failure) fails OPEN -> { continue: true } and a logged note.
+ * A risk scorer can never be the reason a tool call is hard-blocked by accident.
+ *
+ * Sibling resolution: package-root WALK-UP (Phase 53/54 lesson — hooks run from
+ * varied cwds and installed-plugin layouts; a fixed `__dirname/..` is fragile).
+ * We walk up from this file to the directory that actually contains
+ * `scripts/lib/risk/compute-risk.cjs` and require it from there.
+ *
+ * Writer-agent gate: best-effort. If the repo signals the active agent
+ * (`payload.agent` / GDD_AGENT) AND it is a known READ-ONLY agent, we skip
+ * scoring (a read-only agent should not see write-risk advisories). When the
+ * agent is unknowable — the common case for a PreToolUse hook — we score ALL
+ * matched calls: advisory output is non-blocking and the score for low-risk
+ * work stays in the allow band, so scoring-all is safe (per the plan).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ── Package-root walk-up: locate scripts/lib/risk/compute-risk.cjs ──────────
+// Start at this file's dir and climb until we find the risk module (or a
+// package.json that owns it). Cwd-independent; survives installed-plugin
+// layouts where __dirname is not simply <pkg>/hooks.
+const RISK_REL = path.join('scripts', 'lib', 'risk', 'compute-risk.cjs');
+
+function findRiskModule(startDir) {
+  let dir = startDir;
+  // Bound the climb to the filesystem root.
+  for (let i = 0; i < 64; i++) {
+    const candidate = path.join(dir, RISK_REL);
+    try {
+      if (fs.existsSync(candidate)) return candidate;
+    } catch { /* stat error — keep climbing */ }
+    const parent = path.dirname(dir);
+    if (parent === dir) break; // reached the root
+    dir = parent;
+  }
+  return null;
+}
+
+// Resolve once at module load. If it cannot be found, `compute` stays null and
+// the hook fails open on every call (logged note).
+let _risk = null;
+let _riskLoadError = null;
+(function loadRisk() {
+  try {
+    const modPath = findRiskModule(__dirname);
+    if (!modPath) {
+      _riskLoadError = `compute-risk.cjs not found above ${__dirname}`;
+      return;
+    }
+    // eslint-disable-next-line global-require, import/no-dynamic-require
+    _risk = require(modPath);
+  } catch (err) {
+    _riskLoadError = err && err.message ? err.message : String(err);
+  }
+})();
+
+// ── Best-effort `risk_assessment` event emit ────────────────────────────────
+// The firehose (`appendEvent`, sdk/event-stream) is the sink the wire-in tests
+// read via GDD_EVENTS_PATH. `type` is free-form on the envelope, so emitting
+// `risk_assessment` is valid today; executor E adds it to KNOWN_EVENT_TYPES +
+// the schema. Lazily resolved + fully swallowed — telemetry never throws into
+// the hot path (mirrors hooks/_hook-emit.js's lazy .ts require).
+let _appendEvent = null;
+let _appendResolved = false;
+
+function getAppendEvent() {
+  if (_appendResolved) return _appendEvent || (() => {});
+  _appendResolved = true;
+  // Resolve the event-stream sibling via the same package-root walk-up so we
+  // do not depend on a fixed `hooks/..` layout.
+  const candidates = [
+    path.join('sdk', 'event-stream', 'index.ts'),
+    path.join('scripts', 'lib', 'event-stream', 'index.ts'),
+  ];
+  let dir = __dirname;
+  for (let i = 0; i < 64; i++) {
+    for (const rel of candidates) {
+      const p = path.join(dir, rel);
+      try {
+        if (fs.existsSync(p)) {
+          // eslint-disable-next-line global-require, import/no-dynamic-require
+          _appendEvent = require(p).appendEvent;
+          return _appendEvent || (() => {});
+        }
+      } catch { /* not loadable in this runtime (plain node + .ts) → keep trying */ }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  _appendEvent = null;
+  return () => {};
+}
+
+function emitRiskAssessment(payload, sessionId) {
+  try {
+    const appendEvent = getAppendEvent();
+    appendEvent({
+      type: 'risk_assessment',
+      timestamp: new Date().toISOString(),
+      sessionId: sessionId || process.env.GDD_SESSION_ID || 'hook',
+      payload,
+    });
+  } catch {
+    /* telemetry must never throw into the gate */
+  }
+}
+
+// Also emit the canonical `hook.fired` row (same as gdd-bash-guard) so the
+// Phase 22 wire-in baselines stay uniform. Best-effort.
+function emitHookFired(decision, extras) {
+  try {
+    // _hook-emit.js lives beside this hook; resolve it relatively but
+    // defensively (it is part of the same hooks/ dir in every layout).
+    // eslint-disable-next-line global-require
+    require('./_hook-emit.js').emitHookFired('gdd-risk-gate', decision, extras);
+  } catch {
+    /* swallow */
+  }
+}
+
+// ── Writer-agent gate (best-effort, inclusive) ──────────────────────────────
+// Known read-only agent ids that should NOT receive write-risk advisories.
+// Conservative + small: only agents whose whole job is reading/analysis. When
+// the agent is unknown we score anyway (advisory is safe; the plan: "if
+// unknowable, score all matched calls").
+const READ_ONLY_AGENTS = new Set([
+  'design-context-checker',
+  'design-context-reviewer',
+  'design-plan-checker',
+  'design-verifier-gate',
+  'design-integration-checker',
+  'brief-auditor',
+  'copy-auditor',
+  'design-auditor',
+]);
+
+function agentFrom(payload) {
+  const a = (payload && typeof payload.agent === 'string' && payload.agent)
+    || process.env.GDD_AGENT
+    || '';
+  return String(a).trim();
+}
+
+function isReadOnlyAgent(agent) {
+  if (!agent) return false; // unknown -> not read-only -> score it
+  return READ_ONLY_AGENTS.has(agent);
+}
+
+const MATCHED_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'Bash']);
+
+// ── Extend-only table merge (D7 / protected-paths discipline) ───────────────
+// loadRiskConfig returns numeric `base_tool_extra`, plus `file_sensitivity_extra`
+// / `input_pattern_extra` arrays sourced from JSON. We EXTEND the frozen
+// defaults (never shrink). JSON-sourced file-sensitivity entries carry a STRING
+// `test`; compile it to a linear RegExp defensively (malformed entries are
+// dropped, never thrown). input_pattern_extra needs a callable `when` (cannot
+// come from JSON) so it is passed through only when already callable.
+function compileFileSensitivityExtra(extra) {
+  const out = [];
+  if (!Array.isArray(extra)) return out;
+  for (const e of extra) {
+    if (!e || typeof e !== 'object') continue;
+    let test = e.test;
+    if (typeof test === 'string') {
+      try { test = new RegExp(test, 'i'); } catch { continue; }
+    }
+    if (!(test instanceof RegExp)) continue;
+    out.push({
+      test,
+      mult: typeof e.mult === 'number' && Number.isFinite(e.mult) ? e.mult : 1,
+      add: typeof e.add === 'number' && Number.isFinite(e.add) ? e.add : 0,
+      label: typeof e.label === 'string' ? e.label : 'config',
+    });
+  }
+  return out;
+}
+
+function buildMergedTables(cfg) {
+  // Frozen defaults are re-exported from compute-risk for exactly this.
+  const baseDefault = _risk.BASE_TOOL_RISK || {};
+  const fileDefault = _risk.FILE_SENSITIVITY || [];
+  const inputDefault = _risk.INPUT_PATTERN_RISK || [];
+
+  const baseExtra = (cfg && cfg.base_tool_extra && typeof cfg.base_tool_extra === 'object') ? cfg.base_tool_extra : {};
+  const fileExtra = compileFileSensitivityExtra(cfg && cfg.file_sensitivity_extra);
+  const inputExtra = Array.isArray(cfg && cfg.input_pattern_extra)
+    ? cfg.input_pattern_extra.filter((e) => e && typeof e.when === 'function')
+    : [];
+
+  // Only allocate new tables when there is something to extend; otherwise reuse
+  // the frozen defaults so the common path stays allocation-free + identical to
+  // the pure unit tests.
+  const haveBaseExtra = Object.keys(baseExtra).length > 0;
+  if (!haveBaseExtra && fileExtra.length === 0 && inputExtra.length === 0) {
+    return undefined; // computeRisk defaults to the frozen tables
+  }
+  return {
+    BASE_TOOL_RISK: haveBaseExtra ? { ...baseDefault, ...sanitizeNumeric(baseExtra) } : baseDefault,
+    // Config entries are appended AFTER defaults; pickMaxFileSensitivity takes
+    // the highest-weight match across the union, so order is immaterial.
+    FILE_SENSITIVITY: fileExtra.length ? [...fileDefault, ...fileExtra] : fileDefault,
+    INPUT_PATTERN_RISK: inputExtra.length ? [...inputDefault, ...inputExtra] : inputDefault,
+  };
+}
+
+function sanitizeNumeric(obj) {
+  const out = {};
+  for (const k of Object.keys(obj)) {
+    if (typeof obj[k] === 'number' && Number.isFinite(obj[k])) out[k] = obj[k];
+  }
+  return out;
+}
+
+// ── Rationale / advisory rendering ──────────────────────────────────────────
+function rationaleLine(tool, assessment) {
+  const score = typeof assessment.score === 'number' ? assessment.score.toFixed(2) : '?';
+  const reasons = Array.isArray(assessment.reasons) ? assessment.reasons.join(', ') : '';
+  return `gdd-risk-gate: ${tool} risk=${score} (${assessment.suggested_action}) — ${reasons}`;
+}
+
+function buildAdvisory(tool, assessment, extraNote) {
+  const head = rationaleLine(tool, assessment);
+  const body = extraNote ? `${head}\n${extraNote}` : head;
+  return {
+    continue: true,
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      additionalContext: body,
+    },
+  };
+}
+
+function buildBlock(tool, assessment) {
+  return {
+    continue: false,
+    stopReason: `${rationaleLine(tool, assessment)} — run /gdd:override to escalate`,
+  };
+}
+
+const ALLOW = { continue: true };
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+async function main() {
+  let buf = '';
+  for await (const chunk of process.stdin) buf += chunk;
+
+  let payload;
+  try {
+    payload = JSON.parse(buf || '{}');
+  } catch {
+    // Malformed stdin -> fail open.
+    emitHookFired('allow', { reason: 'parse-error' });
+    process.stdout.write(JSON.stringify(ALLOW));
+    return;
+  }
+
+  const tool = payload && typeof payload.tool_name === 'string' ? payload.tool_name : '';
+  if (!MATCHED_TOOLS.has(tool)) {
+    // Not a writer action we gate (the matcher should already exclude these,
+    // but be defensive).
+    emitHookFired('allow', { reason: 'unmatched-tool', tool });
+    process.stdout.write(JSON.stringify(ALLOW));
+    return;
+  }
+
+  const agent = agentFrom(payload);
+  if (isReadOnlyAgent(agent)) {
+    emitHookFired('allow', { reason: 'read-only-agent', agent });
+    process.stdout.write(JSON.stringify(ALLOW));
+    return;
+  }
+
+  // If the scorer could not be located/loaded, fail open with a logged note.
+  if (!_risk || typeof _risk.computeRisk !== 'function') {
+    try {
+      process.stderr.write(
+        `[gdd-risk-gate] risk scorer unavailable (${_riskLoadError || 'unknown'}) — failing open\n`,
+      );
+    } catch { /* swallow */ }
+    emitHookFired('allow', { reason: 'scorer-unavailable' });
+    process.stdout.write(JSON.stringify(ALLOW));
+    return;
+  }
+
+  const cwd = (payload && typeof payload.cwd === 'string' && payload.cwd) || process.cwd();
+  const input = (payload && payload.tool_input && typeof payload.tool_input === 'object') ? payload.tool_input : {};
+  const sessionId = (payload && typeof payload.session_id === 'string' && payload.session_id) || undefined;
+
+  let assessment;
+  try {
+    const cfg = _risk.loadRiskConfig(cwd);
+    const mergedTables = buildMergedTables(cfg);
+    assessment = _risk.computeRisk(tool, input, cfg.thresholds, mergedTables);
+  } catch (err) {
+    // Any scorer failure -> fail open with a logged note.
+    try {
+      process.stderr.write(
+        `[gdd-risk-gate] computeRisk threw (${err && err.message ? err.message : String(err)}) — failing open\n`,
+      );
+    } catch { /* swallow */ }
+    emitHookFired('allow', { reason: 'scorer-error' });
+    emitRiskAssessment({ tool, agent: agent || undefined, error: 'scorer-error', suggested_action: 'allow' }, sessionId);
+    process.stdout.write(JSON.stringify(ALLOW));
+    return;
+  }
+
+  const action = assessment && assessment.suggested_action;
+
+  // Emit the typed risk_assessment event for EVERY scored call (allow→block),
+  // so the dashboard (risk-surface, Phase 55) + calibration (E) see the full
+  // distribution. Best-effort.
+  emitRiskAssessment(
+    {
+      tool,
+      agent: agent || undefined,
+      score: assessment.score,
+      suggested_action: action,
+      reasons: assessment.reasons,
+      breakdown: assessment.breakdown,
+      paths: assessment.breakdown && assessment.breakdown.paths,
+    },
+    sessionId,
+  );
+
+  // Mirror the decision onto the hook.fired row (allow|review|confirm|block).
+  const firedDecision = action === 'block' ? 'block' : 'allow';
+  emitHookFired(firedDecision, { suggested_action: action, score: assessment.score });
+
+  switch (action) {
+    case 'block':
+      process.stdout.write(JSON.stringify(buildBlock(tool, assessment)));
+      return;
+    case 'require_confirmation':
+      // Advisory + flag. The hook does NOT prompt (R2) — design-fixer's
+      // confidence×risk routing will surface the AskUserQuestion with the diff.
+      process.stdout.write(JSON.stringify(buildAdvisory(
+        tool,
+        assessment,
+        'High-risk action — design-fixer will confirm with you (AskUserQuestion) before applying; or run /gdd:override to escalate.',
+      )));
+      return;
+    case 'review':
+      // Advisory, non-blocking: surface the rationale so the agent can weigh it.
+      process.stdout.write(JSON.stringify(buildAdvisory(tool, assessment, null)));
+      return;
+    case 'allow':
+    default:
+      process.stdout.write(JSON.stringify(ALLOW));
+      return;
+  }
+}
+
+// Auto-run only when invoked directly (hooks.json runs `node hooks/gdd-risk-gate.js`,
+// where require.main === module). Guarding the auto-run lets tests require() the
+// module in-process to unit-test the pure helpers without a stdin read.
+if (require.main === module) {
+  main().catch((err) => {
+    // Last-resort fail-open. Never throw out of the hook.
+    try {
+      process.stderr.write(
+        `[gdd-risk-gate] unexpected error (${err && err.message ? err.message : String(err)}) — failing open\n`,
+      );
+    } catch { /* swallow */ }
+    process.stdout.write(JSON.stringify({ continue: true }));
+  });
+}
+
+// Exported for tests — pure helpers + the resolver. main() owns the I/O + contract.
+module.exports = {
+  findRiskModule,
+  buildMergedTables,
+  compileFileSensitivityExtra,
+  isReadOnlyAgent,
+  agentFrom,
+  rationaleLine,
+  buildAdvisory,
+  buildBlock,
+  READ_ONLY_AGENTS,
+  main,
+};

package/hooks/hooks.json

@@ -71,6 +71,24 @@
           }
         ]
       },
+      {
+        "matcher": "Write|Edit|MultiEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gdd-risk-gate.js\""
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gdd-fact-force.js\""
+          }
+        ]
+      },
       {
         "matcher": "Read",
         "hooks": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.55.0",
+  "version": "1.56.0",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",

package/reference/schemas/events.schema.json

@@ -10,7 +10,7 @@
     "type": {
       "type": "string",
       "minLength": 1,
-      "description": "Free-form event type identifier. Pre-registered seeds: state.mutation, state.transition, stage.entered, stage.exited, hook.fired, error, capability_gap, kfm-candidate, router_pick, verify_outcome, rollout_started, rollout_advanced, rollout_stuck, budget_forecast, project_cap_warning, project_cap_halt, live_session_start, live_pick, live_generate, live_accept, live_discard, live_session_end, instinct_emitted, instinct_promoted, instinct_decayed."
+      "description": "Free-form event type identifier. Pre-registered seeds: state.mutation, state.transition, stage.entered, stage.exited, hook.fired, error, capability_gap, kfm-candidate, router_pick, verify_outcome, rollout_started, rollout_advanced, rollout_stuck, budget_forecast, project_cap_warning, project_cap_halt, live_session_start, live_pick, live_generate, live_accept, live_discard, live_session_end, instinct_emitted, instinct_promoted, instinct_decayed, risk_assessment."
     },
     "timestamp": {
       "type": "string",
@@ -232,6 +232,55 @@
         }
       },
       "description": "Phase 32-08 D-02 router_pick payload — 7 fields, additionalProperties: false, NO PII (context_hash only). Records which skill the router auto-picked per intent — the instrument that surfaces under-reached skills. Validated when the envelope's type === 'router_pick' via the allOf[2] conditional."
+    },
+    "RiskAssessmentPayload": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "event_id",
+        "tool_name",
+        "risk_score",
+        "suggested_action",
+        "reasons"
+      ],
+      "properties": {
+        "event_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Stable identifier for this risk_assessment event. Used by Phase 56 calibration to de-dupe re-emissions and to pair an assessment with its post-apply outcome (accept / reject / undo)."
+        },
+        "tool_name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The tool the risk gate scored — Write | Edit | MultiEdit | Bash | NotebookEdit (or any writer tool). Mirrors the PreToolUse tool_name the gdd-risk-gate hook received."
+        },
+        "risk_score": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "The clamped 0..1 score from scripts/lib/risk/compute-risk.cjs computeRisk(). 0 = no risk, 1 = maximal. Drives suggested_action via the THRESHOLDS table."
+        },
+        "suggested_action": {
+          "type": "string",
+          "enum": ["allow", "review", "require_confirmation", "block"],
+          "description": "The action the risk scorer recommends for this score. allow < review < require_confirmation < block (ascending threshold bands). The gdd-risk-gate hook silences 'allow', advises on 'review'/'require_confirmation', and blocks on 'block'."
+        },
+        "reasons": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Ordered, human-readable contributing factors from computeRisk().reasons (e.g. 'base:Bash=0.55', 'file:STATE.md(x2+0)', 'input:destructive-bash=+0.3'). May be empty for a zero-risk assessment."
+        },
+        "agent": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional — the writer agent whose action was scored (e.g. 'design-fixer'). Used by Phase 56 calibration to maintain per-agent rolling statistics. Absent when the gate fired outside an agent context."
+        },
+        "decision_context": {
+          "type": "string",
+          "description": "Optional — a short, PII-free context tag the agent layer attaches when routing the assessment (e.g. a finding id or routing verdict). Free-form; never the raw prompt."
+        }
+      },
+      "description": "Phase 56 (R8) risk_assessment payload — 5 required fields + 2 optional (agent, decision_context), additionalProperties: false. Emitted by the gdd-risk-gate PreToolUse hook for every scored writer action; read by sdk/dashboard/data/risk-surface.cjs ({risk_score, suggested_action}) and gdd-events --type risk_assessment. Validated when the envelope's type === 'risk_assessment' via the allOf[3] conditional."
     }
   },
   "allOf": [
@@ -267,6 +316,17 @@
           "payload": { "$ref": "#/definitions/RouterPickPayload" }
         }
       }
+    },
+    {
+      "if": {
+        "properties": { "type": { "const": "risk_assessment" } },
+        "required": ["type"]
+      },
+      "then": {
+        "properties": {
+          "payload": { "$ref": "#/definitions/RiskAssessmentPayload" }
+        }
+      }
     }
   ]
 }

package/reference/skill-graph.md

@@ -9,7 +9,7 @@ is a `composes_with` edge (the source calls the target as sub-orchestration); a
 a `next_skills` edge (a pipeline hint for what runs next). Stage grouping is best-effort and
 inferred from the skill name; skills with no stage keyword fall under Utility.
 
-Skills: 92. Composition edges: 0 composes_with, 6 next_skills.
+Skills: 93. Composition edges: 0 composes_with, 6 next_skills.
 
 ```mermaid
 flowchart TD
@@ -90,6 +90,7 @@ flowchart TD
     n_next["next"]
     n_note["note"]
     n_openrouter_status["openrouter-status"]
+    n_override["override"]
     n_pause["pause"]
     n_peer_cli_add["peer-cli-add"]
     n_peer_cli_customize["peer-cli-customize"]

package/scripts/lib/manifest/skills.json

@@ -319,6 +319,14 @@
       "user_invocable": true,
       "tools": "Read, Bash, Grep, Write"
     },
+    {
+      "name": "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",
+      "registered_in_phase": "56"
+    },
     {
       "name": "pause",
       "description": "Write a numbered checkpoint so work can resume in a new session without re-running completed stages.",