@hegemonart/get-design-done 1.54.0 → 1.56.0

package/scripts/lib/risk/compute-risk.cjs

@@ -0,0 +1,229 @@
+'use strict';
+/**
+ * scripts/lib/risk/compute-risk.cjs — PURE, deterministic action-risk scorer
+ * for the Phase 56 risk gate.
+ *
+ * NO I/O. NO Date.now / Math.random. Given the same (tool_name, input,
+ * thresholds) it always returns the same result. Frozen static tables live in
+ * ./tables.cjs; config overrides are merged by the HOOK (which reads
+ * .design/config.json and passes the merged thresholds/tables in) — this
+ * module stays side-effect-free so the routing matrix is unit-testable.
+ *
+ * Contract:
+ *   computeRisk(tool_name, input, thresholds = THRESHOLDS, tables = defaults)
+ *     -> { score:0..1, reasons:string[], suggested_action, breakdown }
+ *
+ *   score = clamp01( base * fileMult + fileAdd + sum(inputAdds) )
+ *   suggested_action in 'allow' | 'review' | 'require_confirmation' | 'block'
+ *
+ * loadRiskConfig(cwd) is provided (mirrors blast-radius.loadConfig) so the hook
+ * can read `.design/config.json#risk.{thresholds, base_tool_extra,
+ * file_sensitivity_extra, input_pattern_extra}` and EXTEND the defaults
+ * (extend-only — protected-paths discipline). computeRisk itself never calls it.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const TABLES = require('./tables.cjs');
+const { BASE_TOOL_RISK, FILE_SENSITIVITY, INPUT_PATTERN_RISK, THRESHOLDS } = TABLES;
+
+function clamp01(n) {
+  if (typeof n !== 'number' || Number.isNaN(n)) return 0;
+  if (n < 0) return 0;
+  if (n > 1) return 1;
+  return n;
+}
+
+function normPath(p) {
+  return String(p == null ? '' : p).replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+/**
+ * pathsFor(tool, input) — the file paths a tool action touches.
+ *   Edit/Write/NotebookEdit -> file_path / notebook_path
+ *   MultiEdit               -> the shared file_path (edits[] all target it)
+ *   Bash                    -> best-effort path-ish tokens extracted from the command
+ */
+function pathsFor(tool, input) {
+  const out = [];
+  if (!input || typeof input !== 'object') return out;
+  if (typeof input.file_path === 'string') out.push(normPath(input.file_path));
+  if (typeof input.notebook_path === 'string') out.push(normPath(input.notebook_path));
+  if (typeof input.path === 'string') out.push(normPath(input.path));
+  if (tool === 'Bash' && typeof input.command === 'string') {
+    for (const t of extractBashPaths(input.command)) out.push(normPath(t));
+  }
+  // de-dup, drop empties
+  return Array.from(new Set(out.filter(Boolean)));
+}
+
+// Small, linear extractor: pull whitespace-delimited tokens that look like
+// file paths (contain a slash or a dot-extension, no shell metachars). Linear
+// scan — no backtracking-prone regex.
+function extractBashPaths(command) {
+  const tokens = String(command).split(/\s+/);
+  const paths = [];
+  for (const raw of tokens) {
+    const t = raw.replace(/^['"]|['"]$/g, '');
+    if (!t || t.startsWith('-')) continue;
+    if (/[|;&$`(){}<>*?!]/.test(t)) continue; // skip shell-operator/glob tokens
+    if (t.includes('/') || /\.[A-Za-z0-9]{1,8}$/.test(t)) paths.push(t);
+  }
+  return paths;
+}
+
+/**
+ * pickMaxFileSensitivity(paths, table) — the single highest-WEIGHT matching
+ * entry across all touched paths. "Weight" = mult + add so a clearly higher-mult
+ * entry wins over a low de-risking one even when both match (e.g. a file under
+ * both `tests/` and `hooks/` resolves to the hook entry). Returns
+ * { mult:1, add:0, label:null } when nothing matches.
+ */
+function pickMaxFileSensitivity(paths, table) {
+  let best = null;
+  let bestWeight = -Infinity;
+  for (const entry of table) {
+    for (const p of paths) {
+      if (entry.test.test(p)) {
+        const w = (typeof entry.mult === 'number' ? entry.mult : 1) + (typeof entry.add === 'number' ? entry.add : 0);
+        if (w > bestWeight) {
+          bestWeight = w;
+          best = entry;
+        }
+        break; // this entry already matched; move to the next entry
+      }
+    }
+  }
+  if (!best) return { mult: 1, add: 0, label: null };
+  return { mult: typeof best.mult === 'number' ? best.mult : 1, add: typeof best.add === 'number' ? best.add : 0, label: best.label };
+}
+
+function actionFor(score, thresholds) {
+  const t = thresholds || THRESHOLDS;
+  if (score >= t.block) return 'block';
+  if (score >= t.require_confirmation) return 'require_confirmation';
+  if (score >= t.review) return 'review';
+  return 'allow';
+}
+
+/**
+ * computeRisk — the pure scorer.
+ * @param {string} tool_name
+ * @param {object} input            tool_input (Edit/Write/MultiEdit/Bash/...)
+ * @param {object} [thresholds]     defaults to TABLES.THRESHOLDS
+ * @param {object} [tables]         { BASE_TOOL_RISK, FILE_SENSITIVITY, INPUT_PATTERN_RISK } — defaults to the frozen tables
+ * @returns {{score:number, reasons:string[], suggested_action:string, breakdown:object}}
+ */
+function computeRisk(tool_name, input, thresholds = THRESHOLDS, tables) {
+  const baseTbl = (tables && tables.BASE_TOOL_RISK) || BASE_TOOL_RISK;
+  const fileTbl = (tables && tables.FILE_SENSITIVITY) || FILE_SENSITIVITY;
+  const inputTbl = (tables && tables.INPUT_PATTERN_RISK) || INPUT_PATTERN_RISK;
+
+  const reasons = [];
+
+  // 1. Base tool risk.
+  const base = typeof baseTbl[tool_name] === 'number' ? baseTbl[tool_name] : baseTbl.__default;
+  reasons.push(`base:${tool_name}=${round(base)}`);
+
+  // 2. File sensitivity (highest-weight match across touched paths).
+  const paths = pathsFor(tool_name, input);
+  const fs_ = pickMaxFileSensitivity(paths, fileTbl);
+  if (fs_.label) {
+    reasons.push(`file:${fs_.label}(x${fs_.mult}+${fs_.add})`);
+  }
+
+  // 3. Input-pattern addends (fixed table order).
+  const inputAdds = [];
+  let inputAddSum = 0;
+  for (const entry of inputTbl) {
+    let hit;
+    try {
+      hit = entry.when(tool_name, input);
+    } catch {
+      hit = false;
+    }
+    if (!hit) continue;
+    const add = typeof entry.add === 'function' ? entry.add(hit, tool_name, input) : entry.add;
+    const a = typeof add === 'number' && Number.isFinite(add) ? add : 0;
+    if (a === 0) continue;
+    inputAdds.push({ label: entry.label, add: a });
+    inputAddSum += a;
+    reasons.push(`input:${entry.label}=+${round(a)}`);
+  }
+
+  // 4. Combine + clamp.
+  const rawScore = base * fs_.mult + fs_.add + inputAddSum;
+  const score = clamp01(rawScore);
+
+  const suggested_action = actionFor(score, thresholds);
+
+  return {
+    score,
+    reasons,
+    suggested_action,
+    breakdown: {
+      base,
+      tool: tool_name,
+      paths,
+      file: { mult: fs_.mult, add: fs_.add, label: fs_.label },
+      inputAdds,
+      inputAddSum: round3(inputAddSum),
+      raw: round3(rawScore),
+      thresholds,
+    },
+  };
+}
+
+function round(n) {
+  return Math.round(n * 100) / 100;
+}
+function round3(n) {
+  return Math.round(n * 1000) / 1000;
+}
+
+// ── Config loader (used by the HOOK, not by computeRisk) ────────────────────
+// Mirrors blast-radius.loadConfig. Reads .design/config.json#risk and returns
+// merged thresholds + EXTEND-only table extras. Defaults are returned when the
+// file/keys are absent or malformed. This is the ONLY function here that does
+// I/O; computeRisk stays pure.
+function loadRiskConfig(cwd) {
+  const configPath = path.join(cwd || process.cwd(), '.design', 'config.json');
+  let cfg = {};
+  try { cfg = JSON.parse(fs.readFileSync(configPath, 'utf8')); } catch { cfg = {}; }
+  const risk = (cfg && typeof cfg === 'object' && cfg.risk) || {};
+  const t = (risk && typeof risk.thresholds === 'object' && risk.thresholds) || {};
+  return {
+    thresholds: {
+      review: numOrInRange(t.review, THRESHOLDS.review),
+      require_confirmation: numOrInRange(t.require_confirmation, THRESHOLDS.require_confirmation),
+      block: numOrInRange(t.block, THRESHOLDS.block),
+    },
+    // Extend-only table extras (the hook merges these onto the frozen defaults).
+    base_tool_extra: (risk && typeof risk.base_tool_extra === 'object' && risk.base_tool_extra) || {},
+    file_sensitivity_extra: Array.isArray(risk.file_sensitivity_extra) ? risk.file_sensitivity_extra : [],
+    input_pattern_extra: Array.isArray(risk.input_pattern_extra) ? risk.input_pattern_extra : [],
+  };
+}
+
+function numOrInRange(v, fallback) {
+  if (typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 1) return v;
+  return fallback;
+}
+
+module.exports = {
+  computeRisk,
+  // helpers exported for the hook + tests
+  pathsFor,
+  pickMaxFileSensitivity,
+  actionFor,
+  clamp01,
+  loadRiskConfig,
+  _extractBashPaths: extractBashPaths,
+  // re-export the tables so consumers (B/C/D) can `require('./compute-risk')`
+  // and get THRESHOLDS without a second import.
+  THRESHOLDS,
+  BASE_TOOL_RISK,
+  FILE_SENSITIVITY,
+  INPUT_PATTERN_RISK,
+};

package/scripts/lib/risk/consumers.cjs

@@ -0,0 +1,211 @@
+'use strict';
+/**
+ * scripts/lib/risk/consumers.cjs — Phase 56 importer/consumer resolver for the
+ * fact-forcing gate (hooks/gdd-fact-force.js).
+ *
+ * Wraps the Phase 52 typed DesignContext graph query (design-context-query.cjs
+ * `load` + `consumersOf`) with a BEST-EFFORT file→node mapping and a
+ * SOFTEN-IF-ABSENT contract: when `.design/context-graph.json` is missing,
+ * unbuilt, or malformed, this returns `{ available:false, importers:[] }` and
+ * NEVER throws — so the gate degrades to a warning on greenfield projects
+ * rather than over-blocking (CONTEXT.md R3 / D3).
+ *
+ * Why a wrapper and not a direct consumersOf call: the graph indexes NODES
+ * (ids like `component:Button`, `token:color/primary/500`), not file paths. A
+ * writer action mutates a FILE (`src/components/Button.tsx`). We map the file
+ * to its node id by lowercased basename/slug match against the node set, then
+ * ask the Phase 52 query for that node's consumers, and finally surface the
+ * consumer NAMES so the gate can check whether their files were Read.
+ *
+ * Dependency-free. The only I/O is the graph file read (delegated to the
+ * Phase 52 `load`), and it is fully guarded.
+ *
+ * Public API:
+ *   consumersOfFile(filePath, { root?, graph? })
+ *     -> { available:boolean, importers:string[], targets:string[], nodeId?:string }
+ *
+ *   `available`  — true only when a graph loaded AND the file mapped to a node.
+ *   `importers`  — consumer node names/slugs (lowercased), best-effort file
+ *                  identifiers the gate matches against state.reads.
+ *   `targets`    — the consumer node ids (raw, for diagnostics).
+ *   `nodeId`     — the resolved node id for `filePath`, when one matched.
+ */
+
+const path = require('path');
+
+// Phase 52 query — sibling under scripts/lib/. Resolved by package-root walk-up
+// (Phase 53/54 lesson) so the require survives regardless of this module's
+// install location. Loaded lazily + guarded so an absent sibling SOFTENS.
+let _query = null;
+let _queryResolved = false;
+
+/**
+ * Walk up from a start dir to the package root (the dir whose package.json
+ * `name` is this package), returning that root or null. Used to resolve the
+ * Phase 52 sibling robustly even when cwd differs from the install dir.
+ */
+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;
+}
+
+function getQuery() {
+  if (_queryResolved) return _query;
+  _queryResolved = true;
+  // 1. Adjacent sibling (this file lives in scripts/lib/risk/, query in scripts/lib/).
+  const candidates = [path.join(__dirname, '..', 'design-context-query.cjs')];
+  // 2. Package-root walk-up fallback (robust to relocated installs).
+  const root = findPackageRoot(__dirname);
+  if (root) candidates.push(path.join(root, 'scripts', 'lib', 'design-context-query.cjs'));
+  for (const c of candidates) {
+    try {
+      _query = require(c);
+      if (_query && typeof _query.consumersOf === 'function' && typeof _query.load === 'function') {
+        return _query;
+      }
+    } catch { /* try next candidate */ }
+  }
+  _query = null;
+  return _query;
+}
+
+/**
+ * Lowercase + tokenize a file basename or a node id/name into comparable slug
+ * tokens. Splits on path separators, hyphens, underscores, dots, and colons
+ * (node ids are `<type>:<name>` with `/`-segmented names). Drops the file
+ * extension and short no-signal tokens.
+ */
+function slugTokens(s) {
+  if (!s) return [];
+  const lc = String(s).toLowerCase();
+  // Drop a trailing file extension (`.tsx`, `.css.ts` -> keep `css`+`ts` out).
+  const noExt = lc.replace(/\.[a-z0-9]+$/i, '');
+  return noExt
+    .split(/[\\/\-_.:]+/)
+    .map((t) => t.trim())
+    .filter((t) => t.length > 1);
+}
+
+/** The most specific basename slug for a file (its basename, sans extension). */
+function fileSlug(filePath) {
+  const base = path.basename(String(filePath || ''));
+  return base.replace(/\.[a-z0-9.]+$/i, '').toLowerCase();
+}
+
+/**
+ * Best-effort: map a file path to a graph node id by matching the file's
+ * basename slug against each node's id/name tokens. Prefers an exact basename
+ * == node-name(slug) match; falls back to any shared token. Returns the matched
+ * node id, or null when nothing matches.
+ */
+function fileToNodeId(filePath, graph) {
+  const nodes = Array.isArray(graph && graph.nodes) ? graph.nodes : [];
+  if (!nodes.length) return null;
+  const fSlug = fileSlug(filePath);
+  const fTokens = new Set(slugTokens(path.basename(String(filePath || ''))));
+  if (!fSlug && fTokens.size === 0) return null;
+
+  let exact = null;
+  let partial = null;
+  for (const n of nodes) {
+    if (!n || typeof n.id !== 'string') continue;
+    const nameTokens = slugTokens(n.name != null ? n.name : '');
+    const idTokens = slugTokens(n.id);
+    // The node's "leaf" identifier: last segment of name, else last of id.
+    const nameLeaf = nameTokens.length ? nameTokens[nameTokens.length - 1] : '';
+    const idLeaf = idTokens.length ? idTokens[idTokens.length - 1] : '';
+    if (fSlug && (fSlug === nameLeaf || fSlug === idLeaf)) {
+      exact = n.id;
+      break;
+    }
+    if (!partial) {
+      for (const t of fTokens) {
+        if (nameTokens.includes(t) || idTokens.includes(t)) { partial = n.id; break; }
+      }
+    }
+  }
+  return exact || partial;
+}
+
+/**
+ * Resolve the consumer/importer identifiers for a file via the Phase 52 graph.
+ *
+ * @param {string} filePath               the file being mutated
+ * @param {{root?:string, graph?:object}} [opts]
+ *        root  — project root holding `.design/context-graph.json`
+ *        graph — pre-loaded graph object (test injection; bypasses disk read)
+ * @returns {{available:boolean, importers:string[], targets:string[], nodeId?:string}}
+ */
+function consumersOfFile(filePath, opts = {}) {
+  const SOFT = { available: false, importers: [], targets: [] };
+  try {
+    const q = getQuery();
+    if (!q) return SOFT;
+
+    // Obtain the graph: injected (tests) or loaded from disk (guarded).
+    let graph = opts && opts.graph;
+    if (!graph) {
+      const root = (opts && opts.root) || process.cwd();
+      const graphPath = path.join(root, '.design', 'context-graph.json');
+      try {
+        graph = q.load(graphPath);
+      } catch {
+        // Absent / unbuilt / malformed -> SOFTEN to a warning, never throw.
+        return SOFT;
+      }
+    }
+    if (!graph || !Array.isArray(graph.nodes)) return SOFT;
+
+    const nodeId = fileToNodeId(filePath, graph);
+    if (!nodeId) {
+      // Graph exists but this file maps to no node — treat as "no known
+      // consumers" but mark available so the gate doesn't soften purely on a
+      // mapping miss (an unmapped file genuinely has no importer prerequisite).
+      return { available: true, importers: [], targets: [], nodeId: undefined };
+    }
+
+    const consumerNodes = q.consumersOf(graph, nodeId) || [];
+    const targets = consumerNodes
+      .map((n) => (n && typeof n.id === 'string' ? n.id : null))
+      .filter(Boolean);
+    // Importer identifiers the gate matches against state.reads: the consumer
+    // node's leaf name (lowercased), which is the strongest signal for the
+    // consumer's source-file basename.
+    const importers = [];
+    for (const n of consumerNodes) {
+      if (!n) continue;
+      const nameTokens = slugTokens(n.name != null ? n.name : '');
+      const idTokens = slugTokens(n.id);
+      const leaf = nameTokens.length ? nameTokens[nameTokens.length - 1]
+        : (idTokens.length ? idTokens[idTokens.length - 1] : null);
+      if (leaf) importers.push(leaf);
+    }
+    return {
+      available: true,
+      importers: Array.from(new Set(importers)),
+      targets,
+      nodeId,
+    };
+  } catch {
+    // Any unexpected failure SOFTENS — the gate must never hard-fail on graph I/O.
+    return SOFT;
+  }
+}
+
+module.exports = {
+  consumersOfFile,
+  // exported for tests / reuse
+  fileToNodeId,
+  fileSlug,
+  slugTokens,
+  findPackageRoot,
+};

package/scripts/lib/risk/override.cjs

@@ -0,0 +1,87 @@
+'use strict';
+/**
+ * scripts/lib/risk/override.cjs — PURE helpers for the `/gdd:override` skill
+ * (Phase 56). Mirrors the unlock-decision precedent (Phase 40): override is the
+ * deliberately heavyweight escape hatch from a risk-blocked action or a
+ * fact-force gate, and every use is audited.
+ *
+ * NO I/O, NO Date.now / Math.random. The SKILL.md (and C's fact-force hook) do
+ * the actual atomic file write; these functions only shape the data so the
+ * routing/override matrix stays unit-testable in isolation.
+ *
+ * Two modes, one per exported builder:
+ *
+ *   1. overrideDecisionEntry(findingId, { approver, reason })
+ *        -> { text, status, tag } for `mcp__gdd_state__add_decision`.
+ *      The audit invariant: a recorded approver is mandatory. The `override`
+ *      tag is embedded in `text` (the Decision shape is { id, text, status } —
+ *      it has no dedicated tags field), so the entry is greppable and the
+ *      D-XX it becomes carries the override marker in STATE.md <decisions>.
+ *
+ *   2. setFactForceChecked(state, path)
+ *        -> a NEW session-state object with checked[path] = true.
+ *      The fact-force gate (hooks/gdd-fact-force.js) reads this map at
+ *      `<cwd>/.design/locks/factforce-<session_id>.json`; once a path is
+ *      checked it stops blocking the first mutation of that path.
+ *
+ * Dependency-free.
+ */
+
+const OVERRIDE_TAG = 'override';
+
+/**
+ * Build the audited decision entry for a risk-blocked finding override.
+ * @param {string} findingId  e.g. "G-12" or a risk finding id
+ * @param {object} opts
+ * @param {string} opts.approver  REQUIRED non-empty approver name (audit invariant)
+ * @param {string} [opts.reason]  optional rationale, recorded verbatim
+ * @returns {{ text:string, status:'locked', tag:'override' }}
+ * @throws {Error} when approver is missing/empty (override is never silent)
+ */
+function overrideDecisionEntry(findingId, opts = {}) {
+  const id = typeof findingId === 'string' ? findingId.trim() : '';
+  const approver = typeof opts.approver === 'string' ? opts.approver.trim() : '';
+  const reason = typeof opts.reason === 'string' ? opts.reason.trim() : '';
+  if (!id) throw new Error('override: a finding id is required');
+  if (!approver) throw new Error('override: --approver is required (audit invariant)');
+  // The tag prefix keeps the entry greppable; reason is recorded when present.
+  const base = `[${OVERRIDE_TAG}] ${id} risk-blocked action approved by ${approver}`;
+  const text = reason ? `${base}. Reason: ${reason}` : base;
+  return { text, status: 'locked', tag: OVERRIDE_TAG };
+}
+
+/**
+ * Mark a path as fact-force-checked in a session-state object. Pure: returns a
+ * new object, never mutates the input. A non-object/absent state seeds a fresh
+ * one ({ reads:{}, checked:{} }) so the first override on a greenfield session
+ * still produces a valid file for the hook to read.
+ * @param {object} state  the parsed factforce session state (or null/undefined)
+ * @param {string} p      the path to unblock
+ * @returns {{ reads:object, checked:object }}
+ */
+function setFactForceChecked(state, p) {
+  const key = typeof p === 'string' ? p.replace(/\\/g, '/').replace(/^\.\//, '') : '';
+  if (!key) throw new Error('override: a path is required for factforce mode');
+  const src = state && typeof state === 'object' ? state : {};
+  const reads = src.reads && typeof src.reads === 'object' ? { ...src.reads } : {};
+  const checked = src.checked && typeof src.checked === 'object' ? { ...src.checked } : {};
+  checked[key] = true;
+  return { ...src, reads, checked };
+}
+
+/**
+ * isFactForceChecked(state, path) — read-side predicate the gate uses to decide
+ * whether a path was overridden. Pure.
+ */
+function isFactForceChecked(state, p) {
+  const key = typeof p === 'string' ? p.replace(/\\/g, '/').replace(/^\.\//, '') : '';
+  if (!key || !state || typeof state !== 'object' || !state.checked) return false;
+  return state.checked[key] === true;
+}
+
+module.exports = {
+  overrideDecisionEntry,
+  setFactForceChecked,
+  isFactForceChecked,
+  OVERRIDE_TAG,
+};

package/scripts/lib/risk/route.cjs

@@ -0,0 +1,59 @@
+'use strict';
+/**
+ * scripts/lib/risk/route.cjs — pure confidence×risk router for the Phase 56
+ * gate (the risk sibling of scripts/lib/confidence-route.cjs from Phase 49).
+ *
+ * Decides what a writer agent (design-fixer Step 2.5) should DO with an action,
+ * given (a) the agent's CONFIDENCE in the change [0..1] and (b) the risk
+ * scorer's suggested_action ('allow'|'review'|'require_confirmation'|'block').
+ *
+ * Canonical rule (mirrors the Phase 56 shared contract):
+ *   1. action === 'block'                       -> 'override'   (always; block short-circuits)
+ *   2. confidence < 0.5                          -> 'skip'       (low-confidence floor; non-block)
+ *   3. confidence >= 0.8 && action in {allow,review}        -> 'auto'
+ *   4. confidence >= 0.8 && action === 'require_confirmation'-> 'confirm'
+ *   5. else (0.5 <= confidence < 0.8, non-block) -> 'confirm'
+ *
+ * Note the ordering: BLOCK is checked before the low-confidence floor, so a
+ * block with low confidence still routes to 'override' (you cannot silently
+ * skip a blocked action — it must be explicitly overridden). A non-block action
+ * with confidence < 0.5 is skipped.
+ *
+ * Returns: 'auto' | 'confirm' | 'skip' | 'override'. Dependency-free, no I/O.
+ */
+
+const AUTO_FLOOR = 0.8;     // at/above this, low-risk actions auto-apply
+const SKIP_FLOOR = 0.5;     // below this, non-block actions are skipped
+
+const AUTO_OK_ACTIONS = new Set(['allow', 'review']);
+
+/**
+ * @param {number} confidence  agent confidence in the change, 0.0-1.0
+ * @param {string} action      risk suggested_action: allow|review|require_confirmation|block
+ * @returns {'auto'|'confirm'|'skip'|'override'}
+ */
+function route(confidence, action) {
+  const a = typeof action === 'string' ? action.trim().toLowerCase() : '';
+  // A missing/non-numeric confidence is treated as the lowest tier (0).
+  const c = typeof confidence === 'number' && Number.isFinite(confidence) ? confidence : 0;
+
+  // 1. Block short-circuits everything: it must be explicitly overridden,
+  //    regardless of confidence.
+  if (a === 'block') return 'override';
+
+  // 2. Low-confidence floor (non-block): not worth surfacing — skip.
+  if (c < SKIP_FLOOR) return 'skip';
+
+  // 3-4. High confidence: auto-apply low-risk, confirm if confirmation asked.
+  if (c >= AUTO_FLOOR) {
+    if (AUTO_OK_ACTIONS.has(a)) return 'auto';
+    if (a === 'require_confirmation') return 'confirm';
+    // Any other (unknown) non-block action at high confidence: be conservative.
+    return 'confirm';
+  }
+
+  // 5. Mid confidence [0.5, 0.8), non-block: surface for confirmation.
+  return 'confirm';
+}
+
+module.exports = { route, AUTO_FLOOR, SKIP_FLOOR, AUTO_OK_ACTIONS };