@holmes-lab/holmes-kit 0.1.0

package/dist/holmes/guardrail/risk-classifier.js

@@ -0,0 +1,450 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rmCommandTargets = rmCommandTargets;
+exports.scopeAxToProject = scopeAxToProject;
+exports.normalizeCommandPaths = normalizeCommandPaths;
+exports.classifyReversibility = classifyReversibility;
+exports.classifyArchitectureReversal = classifyArchitectureReversal;
+exports.classifySecret = classifySecret;
+exports.classifyBlastRadius = classifyBlastRadius;
+exports.assessRisk = assessRisk;
+// @implements A-SPEC-125.1
+const risk_types_1 = require("./risk-types");
+const AWS_KEY_RE = /AKIA[0-9A-Z]{16}/;
+const PEM_KEY_RE = /-----BEGIN [A-Z ]*PRIVATE KEY-----/;
+const SECRET_KV_RE = /(password|passwd|secret|token|api[_-]?key)\s*[:=]\s*\S{6,}/i;
+// A long token-shaped run — NOT a true entropy measure (it matches SHAs/UUIDs/base64/
+// long identifiers too). Used only as a conservative FALLBACK when the specific
+// AWS/PEM/kv patterns miss; false-positive-heavy by design (false-positive > false-negative).
+const LONG_TOKEN_RE = /[A-Za-z0-9+/_-]{20,}/;
+// Token-based (not adjacency-based) matches so global flags between subcommands
+// (`git --no-pager push --force`) and case variations (`GIT PUSH --FORCE`) are still caught.
+const GIT_TOKEN_RE = /\bgit\b/i;
+const PUSH_TOKEN_RE = /\bpush\b/i;
+const RESET_TOKEN_RE = /\breset\b/i;
+const HARD_FLAG_RE = /--hard\b/i;
+// A bare `--force` (not merely the prefix of `--force-with-lease`). Scans the whole command,
+// so `--force-with-lease --force` still matches on the second, standalone occurrence.
+const FORCE_RE = /--force(?![-\w])|--force=/i;
+// The SHORT force flag for `git push` (`-f`, incl. clusters `-fu`/`-uf`), scoped to AFTER the
+// `push` subcommand within its segment (up to a shell separator). Scoping avoids mis-attributing an
+// unrelated later `-f` (e.g. `git push origin main && rm -f tmp`) as a force push, and the
+// single-dash start means `--force-with-lease` never matches it. (Corpus finding: `git push -f`
+// slipped the `--force`-only rule.)
+const PUSH_FORCE_SHORT_RE = /\bpush\b[^;&|\n]*\s-[a-z]*f[a-z]*(?:\s|$)/i;
+// Recursive+force `rm`, scoped to each `rm` invocation up to a shell separator so an
+// unrelated later subcommand's flag (e.g. `rm x && terraform apply --force`) is not
+// misattributed, and so an unrelated long option on the rm line (`rm x --format json`)
+// does not spuriously match. Catches combined clusters (`-rf`, `-fr`, `-rfv`) AND
+// separated short flags (`-r -f`) AND long options (`--recursive --force`).
+const RM_SEGMENT_RE = /\brm\b[^;&|\n]*/gi;
+const RM_RECURSIVE_RE = /(?:^|\s)-[a-z]*r[a-z]*(?:\s|$)|(?:^|\s)--recursive(?:\s|$)/i;
+const RM_FORCE_RE = /(?:^|\s)-[a-z]*f[a-z]*(?:\s|$)|(?:^|\s)--force(?:\s|$)/i;
+// A recursive-force `rm` is whole-tree destruction ONLY when its target isn't a manifestly-safe,
+// regenerable build/dependency/cache dir. Cleaning `build/`, `dist/`, `node_modules/`, `target/`,
+// etc. is a routine non-destructive dev command — blanket-blocking it as hard-hitl broke real
+// C++/JS/Rust rebuild workflows (empirical benchmark finding). The allowlist is deliberately narrow
+// (well-known output dirs, relative, no root/home/glob/parent-traversal), so genuinely dangerous
+// deletes (`rm -rf /`, `~`, `.`, `*`, `src/…`, `.ax/…`) stay hard-hitl.
+const SAFE_RM_DIRS = new Set([
+    'build', 'dist', 'node_modules', 'target', 'out', 'coverage', '.cache',
+    '.next', '.nuxt', '.gradle', '__pycache__', '.pytest_cache', '.turbo', '.parcel-cache',
+    'cmake-build-debug', 'cmake-build-release',
+    // CMake regenerable reconfigure-clean artifacts — `rm -rf CMakeCache.txt CMakeFiles` is the
+    // standard "wipe the cache and re-run cmake" step (empirical benchmark finding: blocking it
+    // broke C++ rebuild workflows). All are cmake-generated + trivially regenerated by re-running cmake.
+    'CMakeCache.txt', 'CMakeFiles', 'cmake_install.cmake', 'CTestTestfile.cmake',
+]);
+function isSafeScopedRmTarget(raw) {
+    const unq = raw.replace(/^["']/, '').replace(/["']$/, ''); // strip one surrounding quote pair
+    const t = unq.replace(/\/+$/, '').replace(/^(?:\.\/)+/, ''); // strip trailing / and leading ./
+    if (!t || t === '.' || t === '..')
+        return false;
+    // Only a CLEAN simple path may be safe. Any shell metacharacter means we cannot statically know
+    // the real target, so we must treat it as dangerous — e.g. brace expansion `build/{y,../src}`
+    // expands to delete `../src` (a bypass that a bare `..`-segment check misses), and `$()`,
+    // backticks, globs, quotes, `~` similarly hide the true target. Whitelist charset only.
+    if (!/^[A-Za-z0-9._/-]+$/.test(t))
+        return false;
+    if (t.split('/').some((s) => s === '..'))
+        return false; // any parent traversal
+    const segs = t.split('/').filter(Boolean);
+    if (t.startsWith('/')) {
+        // ABSOLUTE: allow ONLY when the FINAL segment is itself a known regenerable build dir AND there
+        // is at least one parent segment — i.e. a scoped absolute build clean like
+        // `/path/to/work/build` (agents clean build dirs by absolute path too). A bare top-level
+        // `/build` (segs.length 1) or a system path (`/usr/lib`, `/etc`) is never waved through.
+        // ABSOLUTE: safe-scoped ONLY under a known ephemeral/scratch root (/tmp, /var/folders, /private/*).
+        // The old "final segment is a build-dir name" rule (review G-F2) waved through ANY absolute path
+        // with a build-ish basename regardless of location — e.g. rm -rf /home/victim/target, /root/.cache.
+        // A legitimate in-project absolute build clean is instead vouched for by the hook's git inProject
+        // signal; without that signal a non-ephemeral absolute path cannot be statically proven safe.
+        return EPHEMERAL_ABS_ROOT_RE.test(t);
+    }
+    return SAFE_RM_DIRS.has(segs[0]); // relative: first segment is a known build dir
+}
+function rmTargets(segment) {
+    return segment.replace(/^\s*rm\b/i, '').split(/\s+/).filter((tok) => tok && !tok.startsWith('-'));
+}
+// The rm target tokens the classifier will look up in `rmTargetSignals`, across every RECURSIVE rm
+// segment of a command. Exported so the hook resolves git facts for EXACTLY these tokens (the signal
+// map keys must match what rmDangerReason reads). Pure (no I/O) — the hook does the git resolution.
+function rmCommandTargets(cmd) {
+    const segments = cmd.match(RM_SEGMENT_RE);
+    if (!segments)
+        return [];
+    const out = [];
+    for (const seg of segments) {
+        if (RM_RECURSIVE_RE.test(seg))
+            out.push(...rmTargets(seg));
+    }
+    return out;
+}
+// Clean-charset literal targets that make a RECURSIVE `rm` whole-tree destruction even WITHOUT
+// `-f` and would otherwise slip past the metachar/absolute checks below (they contain no shell
+// metacharacter and are not absolute). Root `/`, `$HOME`, globs, braces, `$()`, and non-ephemeral
+// absolute/system paths are handled structurally in isDangerousUnforcedRmTarget, not here.
+const CATASTROPHIC_RM_TARGET_RES = [
+    /^\.\/?$/, // the current working directory (`.` or `./`)
+];
+// Absolute roots under which a recursive delete of a NESTED path is routine (OS/build temp).
+// A recursive rm of an absolute path OUTSIDE these is treated as catastrophic on the no-force
+// path — so system paths (`/usr/lib`, `/System/Library`, `/etc/ssh`, `/etc/*`) can never be
+// waved through just because `-f` is absent (adversarial-review findings #1/#2).
+const EPHEMERAL_ABS_ROOT_RE = /^\/(private\/)?(tmp|var\/tmp|var\/folders)(\/|$)/;
+// The NON-git-overridable floor: targets that are NEVER safe to recursively delete, no matter what
+// git says — filesystem root, any home-relative path (tilde), the cwd, parent-traversal, and any
+// opaque shell-expansion (metachar) whose real target can't be known statically. `git check-ignore`
+// can't make `/` or `~/.ssh` safe, so these short-circuit before any signal is consulted.
+function isCatastrophicRmFloor(raw) {
+    const unquoted = raw.replace(/^["']/, '').replace(/["']$/, '');
+    const t = unquoted === '/' ? '/' : unquoted.replace(/\/+$/, '');
+    if (!t)
+        return false;
+    if (t === '/')
+        return true; // filesystem root
+    if (t === '..' || t.split('/').some((s) => s === '..'))
+        return true; // any parent-traversal segment
+    if (t.startsWith('~'))
+        return true; // any home-relative path (~, ~/x, ~user)
+    if (/[^A-Za-z0-9._/~-]/.test(t))
+        return true; // opaque/metachar (can expand to /)
+    if (CATASTROPHIC_RM_TARGET_RES.some((re) => re.test(t)))
+        return true; // cwd literal
+    return false;
+}
+// Per-target verdict for a RECURSIVE delete, git-aware:
+//   'safe'      — a regenerable build artifact or manifestly-scoped path; no gate, even with -f
+//   'dangerous' — catastrophic, version-controlled source, or out-of-project; must hard-hitl
+//   'unknown'   — cannot prove either way here; the caller applies the -f / no-f latitude rule
+// Layer order: catastrophic FLOOR (git-independent) → GIT signal (authoritative when the hook
+// resolved it) → static NAME allowlist fallback (relative build dirs, absolute build paths, CMake).
+function rmTargetSafety(raw, sig) {
+    if (isCatastrophicRmFloor(raw))
+        return 'dangerous';
+    if (sig) {
+        if (sig.tracked)
+            return 'dangerous'; // git-tracked source under VCS
+        if (sig.inProject === false)
+            return 'dangerous'; // resolves outside the project tree
+        if (sig.gitIgnored && sig.inProject)
+            return 'safe'; // regenerable build artifact (ANY name)
+        // in-project, untracked, not-ignored → inconclusive; fall through to the static checks
+    }
+    if (isSafeScopedRmTarget(raw))
+        return 'safe'; // name allowlist: build/, /path/build, CMake…
+    const t = raw.replace(/^["']/, '').replace(/["']$/, '').replace(/\/+$/, '');
+    if (t.startsWith('/') && !EPHEMERAL_ABS_ROOT_RE.test(t))
+        return 'dangerous'; // system-area absolute
+    return 'unknown';
+}
+// Returns the hard-hitl reason for a destructive `rm`, or null. Per recursive `rm` segment:
+//   • any target 'dangerous'      → hard-hitl (catastrophic / VCS-tracked / out-of-project / system)
+//   • all targets 'safe'          → allowed even with -f (proven regenerable/scoped)
+//   • some 'unknown' + `-f`        → hard-hitl (unattended batch delete of an unproven target)
+//   • some 'unknown', no `-f`      → allowed (ordinary `rm -r dir` latitude)
+// `signals` (per-target git/fs facts resolved by the hook) sharpen the verdict; absent, the static
+// name-based logic applies unchanged (full backward compatibility — no signals == prior behavior).
+// A NON-recursive `rm` still mass-deletes when its target is a whole-scope glob or the root/home
+// itself — `rm *` / `rm -f *` wipes the entire cwd, `rm /*` / `rm ~/*` / `rm ~/.ssh/*` wipe root/home
+// (review G-F1: these are unclassified because the floor was only consulted for recursive rm). A
+// FILTERED relative glob (`*.log`, `build/*.o`) is left alone — only whole-scope / absolute / home
+// globs and bare root/home count.
+function isMassRmTarget(raw) {
+    const t = raw.replace(/^["']/, '').replace(/["']$/, '');
+    if (/^\*$/.test(t))
+        return true; // bare glob = every entry in cwd
+    if (/^[/~]/.test(t) && t.includes('*'))
+        return true; // absolute or home glob (/*, ~/*, ~/.ssh/*, /etc/*)
+    if (/^(\/|~\/?|\$\{?HOME\}?\/?)$/.test(t))
+        return true; // the whole filesystem root or home dir
+    return false;
+}
+function rmDangerReason(cmd, signals) {
+    const segments = cmd.match(RM_SEGMENT_RE);
+    if (!segments)
+        return null;
+    for (const seg of segments) {
+        // Mass-delete check applies to EVERY rm (recursive or not) — a non-recursive glob/root wipe is
+        // just as destructive. Runs before the recursion gate below.
+        if (rmTargets(seg).some(isMassRmTarget)) {
+            return 'rm of a whole-scope glob or root/home target — mass file destruction';
+        }
+        if (!RM_RECURSIVE_RE.test(seg))
+            continue; // remaining checks are recursive whole-tree risk
+        const targets = rmTargets(seg);
+        const safeties = targets.map((t) => rmTargetSafety(t, signals?.[t]));
+        if (safeties.some((s) => s === 'dangerous')) {
+            return 'recursive rm of a catastrophic / version-controlled / out-of-project / system target — whole-tree destruction';
+        }
+        if (targets.length > 0 && safeties.every((s) => s === 'safe'))
+            continue; // all proven regenerable
+        if (RM_FORCE_RE.test(seg)) {
+            return 'rm -rf of an unverified target (not a proven regenerable/scoped path) — whole-tree destruction';
+        }
+    }
+    return null;
+}
+const DROP_TABLE_OR_DB_RE = /\bDROP\s+(TABLE|DATABASE)\b/i;
+// Additional unambiguously destructive / irreversible / RCE shell patterns. This set is
+// deliberately conservative (each is clearly high-risk) and NON-EXHAUSTIVE — command-space
+// coverage is a calibration concern deferred per REQ-125; false-negatives on unlisted
+// destructive commands are possible and must not be over-trusted (other layers + human
+// oversight remain). Each is scanned across the whole command string, case-insensitively.
+const DESTRUCTIVE_CMD_CHECKS = [
+    { re: /\bdd\b[^;&|\n]*\bof=\/dev\//i, reason: 'dd writing to a raw device (irreversible disk overwrite)' },
+    { re: /\bmkfs(\.\w+)?\b/i, reason: 'mkfs formats a filesystem (irreversible)' },
+    { re: /\bshred\b/i, reason: 'shred irreversibly destroys file contents' },
+    // Raw-device redirect — widened past sd/disk/nvme/hd to rdisk (macOS), device-mapper, loop, md, vd (review F5).
+    { re: />\s*\/dev\/(r?disk|sd|nvme|hd|vd|md|loop|mapper)/i, reason: 'redirect overwrites a raw device' },
+    // Pipe-to-shell RCE — `[^;&\n]*` now CROSSES intermediate `|` stages (curl|tee|sh, curl|grep|sh) and
+    // covers more interpreters (python/perl/ruby/node/php/ksh), which the old single-pipe list missed (F5).
+    { re: /\b(curl|wget|fetch)\b[^;&\n]*\|[^;&\n]*\b(sudo\s+)?(sh|bash|zsh|dash|ksh|python[0-9.]*|perl|ruby|node|php)\b/i, reason: 'pipe-to-shell executes remote code (RCE)' },
+    { re: /\bgit\s+clean\b[^;&|\n]*-[a-z]*f/i, reason: 'git clean -f irreversibly removes untracked files' },
+    { re: /\bfind\b[^;&|\n]*\s-delete\b/i, reason: 'find -delete irreversibly removes matched files' },
+    // Discard ALL uncommitted work — same harm as `git reset --hard`, previously unchecked (review F3).
+    { re: /\bgit\s+(restore|checkout)\b[^;&|\n]*(?:\s--)?\s\.(?:\s|$)/i, reason: 'git restore/checkout . discards all uncommitted work irreversibly' },
+    { re: /\bgit\s+branch\b[^;&|\n]*\s-D\b/i, reason: 'git branch -D force-deletes a branch' },
+    // Recursive chmod on a catastrophic target bricks permissions; truncate -s 0 zeroes a file (F3).
+    { re: /\bchmod\b\s+-[a-z]*R[a-z]*\b[^;&|\n]*\s(\/|~|\.)(\s|$)/i, reason: 'recursive chmod on root/home/cwd bricks permissions' },
+    { re: /\btruncate\b[^;&|\n]*-s\s*0\b/i, reason: 'truncate -s 0 irreversibly zeroes a file' },
+    // @implements A-SPEC-196 (Windows Native CMD / PowerShell destructive command classification)
+    { re: /\b(?:Remove-Item|ri)\b[^;&|\n]*-(?:Recurse|Force|r|f)\b/i, reason: 'PowerShell Remove-Item -Recurse/-Force deletes file trees (irreversible)' },
+    { re: /\bdel\b[^;&|\n]*\/(s|f|q)\b/i, reason: 'Windows CMD del /s deletes file trees (irreversible)' },
+    { re: /\b(rmdir|rd)\b[^;&|\n]*\/s\b/i, reason: 'Windows CMD rmdir /s deletes directory trees (irreversible)' },
+];
+// Protected .ax governance paths, matched as a path SEGMENT so absolute (`/proj/.ax/specs/x`)
+// and `./`-relative (`./.ax/decisions/x`) forms are caught, not just a literal string prefix.
+/**
+ * Neutralise `.ax` paths that belong to ANOTHER project before the protected-path rules run.
+ *
+ * `.ax/specs` is this project's governance directory, and deleting it must stay non-bypassable. But
+ * the rules match the substring anywhere in a command, so `rm /other/project/.ax/cpg_cache/x.json`
+ * was gated too — found by dogfooding while cleaning up a scan cache left in a DIFFERENT repository,
+ * which is exactly what a user juggling several projects does every day. The governance claim only
+ * extends to this project's own `.ax`.
+ *
+ * Only ABSOLUTE paths outside the project root are masked. A relative `.ax/...` resolves against the
+ * project and stays protected, so nothing is weakened for the case the rule exists to cover. With no
+ * projectRoot supplied the command is returned unchanged — unknown scope stays conservative.
+ */
+function scopeAxToProject(cmd, projectRoot) {
+    if (!projectRoot)
+        return cmd;
+    const root = projectRoot.replace(/\\/g, '/').replace(/\/+$/, '');
+    return cmd.replace(/(^|[\s'"=(:])(\/[^\s'"()]*\/\.ax\/[^\s'"()]*)/g, (m, pre, abs) => (abs === root || abs.startsWith(`${root}/`) ? m : `${pre}<other-project-path>`));
+}
+// `state` joined the protected set with P3 (REQ-134): it holds the constitution-debt and the
+// last-green baseline, so a single-file `rm` there would bypass the WRITE_CODE debt gate — measured
+// in the campaign completeness critique. Deleting governance state is now hard-hitl like every other.
+const PROTECTED_AX_PATH_RE = /(^|\/)\.ax\/(specs|decisions|ledger|cpg_cache|state|roles)(\/|$)/;
+// A removal verb + a protected .ax path anywhere in a shell command — the command form of
+// the governance-path delete, which the structured `kind:'delete'` branch alone would miss.
+// Not just removal: RELOCATING or CLOBBERING a protected .ax path is equally destructive to it, so
+// mv/cp/git-mv and a `>` truncation count too (review F4 — `mv .ax/specs /tmp` evaded the rm-only rule).
+const REMOVAL_VERB_RE = /\b(rm|rmdir|unlink|git\s+rm|git\s+mv|mv|cp)\b/i;
+const CLOBBER_AX_RE = />\s*['"]?[^\s;&|]*\.ax\/(specs|decisions|ledger|cpg_cache|state|roles)\b/i;
+const CMD_PROTECTED_AX_RE = /(^|[\s'"=(/])\.ax\/(specs|decisions|ledger|cpg_cache|state|roles)(\/|\b)/;
+/**
+ * Normalize a command string for protected-path matching: collapse `//` runs and `./` segments so
+ * `./.ax//ledger/x` matches the same rules as `.ax/ledger/x` (adversarial probe: those forms slipped
+ * every protected-path regex). Also flattens a leading `cd <dir> &&` so a cd-relative write
+ * (`cd .ax/ledger && cat > provenance.jsonl`) is seen against its real directory.
+ */
+function normalizeCommandPaths(cmd) {
+    let out = cmd.replace(/(?<![:\w])\.\//g, '').replace(/([^:])\/{2,}/g, '$1/');
+    const cdChain = /(^|[;&|]\s*)cd\s+(['"]?)([^\s;&|'"]+)\2\s*(?:&&|;)\s*/;
+    for (let m = cdChain.exec(out); m; m = cdChain.exec(out)) {
+        const dir = m[3].replace(/\/+$/, '');
+        const rest = out.slice(m.index + m[0].length);
+        // Prefix bare relative paths in the remainder with the cd target so path rules see the real path.
+        const rewritten = rest.replace(/(^|[\s>|])(?![-/~'"])([\w@.][\w@./-]*)/g, (full, pre, p) => /^[A-Za-z0-9_.@-]+$/.test(p) || p.includes('/') ? `${pre}${dir}/${p}` : full);
+        out = out.slice(0, m.index + (m[1] ? m[1].length : 0)) + rewritten;
+    }
+    return out;
+}
+// File-mutating shell verbs beyond redirect/removal: these WRITE a target path, so a protected path
+// as their argument is the same governance breach as `>` or `rm` (probe: tee/cp/install slipped).
+const WRITE_VERB_AX_RE = /\b(?:tee|cp|install|dd|ln|mv|rsync)\b[^;&|\n]*\.ax\/(?:specs|decisions|ledger|cpg_cache|state|roles)\b/i;
+// An interpreter one-liner naming a protected path: `node -e "...appendFileSync('.ax/ledger/...')"`,
+// `python3 -c "open('.ax/ledger/...','a')"`. Read-only one-liners are not distinguishable from writes
+// here, so this is deliberately conservative on the .ax governance surface only.
+const INTERPRETER_AX_RE = /\b(?:node|python3?|ruby|perl|deno|bun)\b[^;&|\n]*-(?:e|c|-eval)\b[^\n]*\.ax\/(?:specs|decisions|ledger|cpg_cache|state|roles)\b/i;
+/**
+ * @implements A-SPEC-125.1
+ * Reversibility axis: can the action's effect be undone? Conservative default —
+ * unknown kinds and ambiguous (tracked===undefined) states never resolve to 'auto'.
+ */
+function classifyReversibility(action) {
+    const axis = 'reversibility';
+    const cmd = action.command ?? '';
+    // Command-based hard-hitl checks run regardless of `kind` — a dangerous shell command
+    // can be carried by any action (e.g. an `edit` action with an embedded `command`), so
+    // gating this scan on `kind==='shell'` would let it slip through under a different kind.
+    if (GIT_TOKEN_RE.test(cmd) && PUSH_TOKEN_RE.test(cmd) && (FORCE_RE.test(cmd) || PUSH_FORCE_SHORT_RE.test(cmd))) {
+        return { axis, level: 'hard-hitl', reasons: ['git push --force/-f rewrites remote history irreversibly'] };
+    }
+    if (GIT_TOKEN_RE.test(cmd) && RESET_TOKEN_RE.test(cmd) && HARD_FLAG_RE.test(cmd)) {
+        return { axis, level: 'hard-hitl', reasons: ['git reset --hard discards uncommitted work irreversibly'] };
+    }
+    // Removal targeting a protected .ax governance path is UNCONDITIONALLY hard-hitl —
+    // `.ax/specs`/`.ax/decisions` deletion is non-bypassable per H-SPEC-125, independent
+    // of `tracked` (the shell form of the delete-kind protected-path rule).
+    // Protected-path checks run on the NORMALIZED command so `//`, `./`, and `cd <dir> &&` forms cannot
+    // dodge the rules, and cover every mutation channel: removal verbs, redirect clobber, file-writing
+    // verbs (tee/cp/install/…), and interpreter one-liners naming a governance path.
+    const ncmd = scopeAxToProject(normalizeCommandPaths(cmd), action.projectRoot);
+    if ((REMOVAL_VERB_RE.test(ncmd) && CMD_PROTECTED_AX_RE.test(ncmd)) || CLOBBER_AX_RE.test(ncmd)
+        || WRITE_VERB_AX_RE.test(ncmd) || INTERPRETER_AX_RE.test(ncmd)) {
+        return { axis, level: 'hard-hitl', reasons: ['removal command targets a protected .ax governance path'] };
+    }
+    // A destructive recursive `rm` — either `-rf` on a non-safe target, or a recursive delete of
+    // a catastrophic root (/, ~, $HOME, ., .., glob) even WITHOUT `-f` — is whole-tree destruction,
+    // unconditionally hard-hitl regardless of `tracked`. The single-file `tracked===true` auto
+    // exception lives only in the structured delete-kind branch below; a recursive delete never qualifies.
+    const rmReason = rmDangerReason(cmd, action.rmTargetSignals);
+    if (rmReason) {
+        return { axis, level: 'hard-hitl', reasons: [rmReason] };
+    }
+    if (DROP_TABLE_OR_DB_RE.test(cmd)) {
+        return { axis, level: 'hard-hitl', reasons: ['destructive DDL (DROP TABLE/DATABASE)'] };
+    }
+    for (const check of DESTRUCTIVE_CMD_CHECKS) {
+        if (check.re.test(cmd))
+            return { axis, level: 'hard-hitl', reasons: [check.reason] };
+    }
+    if (action.kind === 'delete') {
+        const normalizedTarget = action.target.replace(/\\/g, '/');
+        // A trailing slash is an additional POSITIVE directory signal; its absence must NOT
+        // imply "not a directory" — that inference is exactly what let directory deletes slip
+        // to 'auto'. Only an explicit isDirectory===false (alongside tracked===true) is 'auto'.
+        const looksLikeDirectory = normalizedTarget.endsWith('/') || action.isDirectory === true;
+        if (PROTECTED_AX_PATH_RE.test(normalizedTarget)) {
+            return { axis, level: 'hard-hitl', reasons: ['delete under protected .ax governance path'] };
+        }
+        if (looksLikeDirectory) {
+            return { axis, level: 'hard-hitl', reasons: ['delete targets a directory'] };
+        }
+        if (action.tracked === false) {
+            return { axis, level: 'hard-hitl', reasons: ['delete of an untracked path'] };
+        }
+        if (action.tracked === true && action.isDirectory === false) {
+            return { axis, level: 'auto', reasons: [] };
+        }
+        // Ambiguous: tracked and/or directory status not conclusively known. Never auto.
+        return { axis, level: 'confirm', reasons: ['ambiguous: tracked/directory status not conclusively known for delete target'] };
+    }
+    if (action.kind === 'edit') {
+        return { axis, level: 'auto', reasons: [] };
+    }
+    // Unknown/unhandled kind: conservative default, never auto.
+    return { axis, level: 'confirm', reasons: [`ambiguous: unhandled action kind '${action.kind}'`] };
+}
+/**
+ * @implements A-SPEC-125.1
+ * Architecture axis: does this action reverse a previously accepted architectural decision?
+ */
+function classifyArchitectureReversal(action) {
+    const axis = 'architecture';
+    const supersedes = action.adrSupersedes ?? [];
+    const supersedesAdr = supersedes.length > 0;
+    const changesConstraints = action.cspecConstraintChange === true;
+    if (supersedesAdr || changesConstraints) {
+        const reasons = [];
+        if (supersedesAdr)
+            reasons.push(`supersedes accepted ADR(s): ${supersedes.join(', ')}`);
+        if (changesConstraints)
+            reasons.push('C-SPEC Forbidden Edges / Layer Rules changed');
+        return { axis, level: 'hard-hitl', reasons };
+    }
+    return { axis, level: 'auto', reasons: [] };
+}
+/**
+ * @implements A-SPEC-125.1
+ * Secret axis: does the staged content contain a credential-shaped string?
+ */
+function classifySecret(action) {
+    const axis = 'secret';
+    const content = action.stagedContent ?? '';
+    const reasons = [];
+    if (AWS_KEY_RE.test(content))
+        reasons.push('AWS access key pattern detected');
+    if (PEM_KEY_RE.test(content))
+        reasons.push('PEM private key block detected');
+    if (SECRET_KV_RE.test(content))
+        reasons.push('password/token/api_key assignment detected');
+    if (reasons.length === 0 && LONG_TOKEN_RE.test(content))
+        reasons.push('long token-shaped string detected (conservative fallback)');
+    if (reasons.length > 0)
+        return { axis, level: 'hard-hitl', reasons };
+    return { axis, level: 'auto', reasons: [] };
+}
+const DEFAULT_BLAST_CONFIRM = 8;
+const DEFAULT_BLAST_HARD_HITL = 20;
+/**
+ * @implements A-SPEC-125.3
+ * Blast-radius axis: how far does this change's impact ripple through the spec graph?
+ * The graph impact signal (`action.blastRadius`) is INJECTED by the caller — this function
+ * remains pure, performing no graph traversal or I/O of its own.
+ */
+function classifyBlastRadius(action, cfg) {
+    const axis = 'blast-radius';
+    const br = action.blastRadius;
+    if (!br)
+        return { axis, level: 'auto', reasons: [] };
+    // A blastRadius signal was supplied but its count is unreadable — NaN, or a non-number
+    // from a malformed injected/deserialized signal. Fail SAFE, not to 'auto': a
+    // present-but-unreadable impact signal escalates to confirm, matching this module's
+    // conservative-default philosophy (unknown never silently resolves to the least-protective
+    // outcome). NaN>=T is always false, which would otherwise fall through to 'auto'.
+    // Infinity is intentionally NOT caught here — it is a readable "unbounded blast" and
+    // correctly resolves to hard-hitl via the `>= hardT` comparison below.
+    if (typeof br.impactedSpecCount !== 'number' || Number.isNaN(br.impactedSpecCount)) {
+        return { axis, level: 'confirm', reasons: ['blast-radius signal present but impactedSpecCount is not a readable number'] };
+    }
+    const hardT = cfg?.blastRadiusHardHitl ?? DEFAULT_BLAST_HARD_HITL;
+    const confirmT = cfg?.blastRadiusConfirm ?? DEFAULT_BLAST_CONFIRM;
+    if (br.impactedSpecCount >= hardT)
+        return { axis, level: 'hard-hitl', reasons: [`impacts ${br.impactedSpecCount} specs (>= ${hardT})`] };
+    if (br.hitsFoundational)
+        return { axis, level: 'confirm', reasons: ['change ripples to a foundational REQ node'] };
+    if (br.impactedSpecCount >= confirmT)
+        return { axis, level: 'confirm', reasons: [`impacts ${br.impactedSpecCount} specs (>= ${confirmT})`] };
+    return { axis, level: 'auto', reasons: [] };
+}
+/**
+ * @implements A-SPEC-125.1
+ * Runs all four axes and folds them into a single overall risk assessment.
+ * Pure function: no I/O, no clocks, no randomness — same input always yields the same output.
+ */
+function assessRisk(action, cfg) {
+    const verdicts = [
+        classifyReversibility(action),
+        classifyArchitectureReversal(action),
+        classifySecret(action),
+        classifyBlastRadius(action, cfg),
+    ];
+    const level = verdicts.reduce((acc, v) => (0, risk_types_1.maxLevel)(acc, v.level), 'auto');
+    const reasons = verdicts.filter((v) => v.level !== 'auto').flatMap((v) => v.reasons);
+    return { level, verdicts, reasons };
+}

package/dist/holmes/guardrail/risk-gate.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidApproval = isValidApproval;
+exports.approvalCovers = approvalCovers;
+exports.isNonceConsumed = isNonceConsumed;
+exports.gradedResponse = gradedResponse;
+exports.riskGate = riskGate;
+/** All of actor/token/rationale must be present and non-empty (whitespace-only counts as empty). */
+function isValidApproval(a) {
+    if (a == null)
+        return false;
+    // A malformed/deserialized Approval (missing keys, null/non-string fields) must
+    // return false, NEVER throw — the gate is handed unvalidated external JSON (MCP
+    // call / CLI flag / config), and a crash here would be a DoS on the safety
+    // mechanism (or a fail-open if a caller wraps it in try/catch). Guard the type.
+    return [a.actor, a.token, a.rationale].every((s) => typeof s === 'string' && s.trim().length > 0);
+}
+/**
+ * @implements A-SPEC-133
+ * Does this well-formed approval AUTHORIZE this specific action, right now? This is the seam P2
+ * adds beside isValidApproval: the gates ask "covers?" instead of "well-formed?", so one token
+ * stops being a master key. Pure — `now` is passed in (the action timestamp), never read from the
+ * clock, so the predicate stays deterministic and testable.
+ *
+ * - malformed → false (isValidApproval's meaning is preserved).
+ * - expired (epoch comparison, both operands must parse; unreadable expires OR now → false). Absent expires → no expiry.
+ * - scope present → true iff some entry FULL-matches (kind exact or `*`; the pattern is anchored
+ *   at both ends, `*` a wildcard run, trailing `/` a directory prefix). No entry matches → false: an existing-but-empty scope denies
+ *   everything, which is the safe reading of "scoped but matches nothing".
+ * - scope absent → true: the documented UNSCOPED master-key path (the operator's session token).
+ */
+function approvalCovers(a, action, now) {
+    if (!isValidApproval(a))
+        return false;
+    const appr = a;
+    if (appr.expires !== undefined) {
+        // A PRESENT deadline judges — including ''/'   ' (round-5: the trim-gate routed blank strings
+        // around the whole branch, and A-SPEC-133 says an unreadable deadline is a passed one).
+        // Epoch comparison, not lexicographic: `now` is always a Z-form ISO string, so a legitimate
+        // local-offset expires (+09:00) that was INSTANT-expired still sorted "after" it and lifted the
+        // gate (round-3 HIGH, fail-open). An unparseable expires is fail-closed — a deadline we cannot
+        // read is a deadline we must assume passed.
+        const exp = Date.parse(String(appr.expires));
+        const nowMs = Date.parse(now);
+        // BOTH operands fail closed (round-4: guarding only `expires` left `now` — which risk_check
+        // takes from the CALLER's ts — able to resurrect an expired approval via NaN comparison).
+        if (!Number.isFinite(exp) || !Number.isFinite(nowMs) || nowMs > exp)
+            return false;
+    }
+    if (appr.scope === undefined)
+        return true; // unscoped master key
+    if (!Array.isArray(appr.scope))
+        return false;
+    return appr.scope.some((s) => {
+        if (!s || typeof s.kind !== 'string' || typeof s.pattern !== 'string')
+            return false;
+        if (s.kind !== '*' && s.kind !== action.kind)
+            return false;
+        return patternMatches(s.pattern, action.target);
+    });
+}
+/**
+ * FULL match with `*` as a wildcard run — anchored at BOTH ends. `git push*` matches
+ * `git push --force`; `rm *` matches `rm -rf x` but NOT `confirm x`. Every documented pattern ends
+ * its open tail with an explicit `*`; the old start-only anchor made a bare pattern a PREFIX, so a
+ * scope narrowed to finding id `C1` also lifted `C10` and `C1-regression` (round-3 HIGH) and no
+ * exact-id scope was expressible ('$' is escaped as a literal). A pattern without `*` now means
+ * exactly what it says.
+ */
+function patternMatches(pattern, target) {
+    // '' is NOT a wildcard (round-6): an empty pattern covered every target — the same degenerate
+    // fail-open the blank-expires fix closed. Full-match semantics give '' only the empty target.
+    if (pattern === '*')
+        return true;
+    // A trailing '/' is an unambiguous directory-prefix intent — `src/` covers `src/feature.ts`
+    // (the style A-SPEC-149's gate-isolation TEST sanctions for code-write scopes — the doc itself carries no pattern prose). Everything else matches in full.
+    const p = pattern.endsWith('/') ? `${pattern}*` : pattern;
+    const re = new RegExp('^' + p.split('*').map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*') + '$');
+    return re.test(target);
+}
+/**
+ * @implements A-SPEC-133
+ * Has this single-use nonce already been spent? Sync-reads the append-only provenance chain for a
+ * `nonce-consumed` entry carrying the nonce. A missing/unreadable ledger means nothing was consumed
+ * yet — false, never a throw (the gate must not crash on a fresh project).
+ */
+function isNonceConsumed(nonce, ledgerFile) {
+    if (!nonce)
+        return false;
+    let text;
+    try {
+        // Local require to keep this module free of a load-time fs dependency for its pure consumers.
+        const fs = require('node:fs');
+        if (!fs.existsSync(ledgerFile))
+            return false;
+        text = fs.readFileSync(ledgerFile, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    for (const line of text.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const evt = JSON.parse(line);
+            if (evt.kind === 'nonce-consumed' && Array.isArray(evt.inputs) && evt.inputs.includes(nonce))
+                return true;
+        }
+        catch { /* skip unparseable line */ }
+    }
+    return false;
+}
+/**
+ * Graduated response for a bare risk level, with no notion of approval.
+ * Pure: no I/O, no clock, no randomness.
+ *
+ * `enforcement: 'off'` softens `confirm` to a clean pass, but MUST NOT soften
+ * `hard-hitl` -- that is the non-bypassable minimum this gate exists to guarantee.
+ */
+function gradedResponse(level, enforcement) {
+    if (level === 'auto' || level === 'notify') {
+        return { blocked: false, level, requiresApproval: false, reasons: [] };
+    }
+    if (level === 'confirm') {
+        if (enforcement === 'off') {
+            return { blocked: false, level, requiresApproval: false, reasons: [] };
+        }
+        return { blocked: false, level, requiresApproval: true, reasons: [] };
+    }
+    // level === 'hard-hitl': non-bypassable, regardless of enforcement.
+    return { blocked: true, level, requiresApproval: true, reasons: [] };
+}
+/**
+ * @implements A-SPEC-125.2
+ * Pure decision function: given a risk assessment, an optional out-of-band
+ * approval, and an enforcement mode, decides whether the action is blocked.
+ *
+ * No I/O and no ledger writes happen here -- recording a DecisionEvent is a
+ * separate caller step (see decision-ledger.ts), so a ledger write failure
+ * can never change the gate verdict.
+ *
+ * hard-hitl is non-bypassable: only a valid Approval (actor+token+rationale,
+ * all non-empty) unblocks it. enforcement:'off' softens confirm to a pass,
+ * but never softens hard-hitl.
+ */
+function riskGate(assessment, approval, enforcement = 'block', 
+// @implements A-SPEC-133 — when the caller supplies the action + timestamp, coverage is checked
+// with approvalCovers (scope + expiry), so an out-of-scope or expired token no longer unblocks.
+// Omitted → falls back to well-formedness (backward compatible for existing callers/tests).
+cover) {
+    const { level, reasons } = assessment;
+    const authorized = cover ? approvalCovers(approval, cover.action, cover.now) : isValidApproval(approval);
+    if (authorized) {
+        if (level === 'confirm' || level === 'hard-hitl') {
+            return { blocked: false, level, requiresApproval: false, reasons };
+        }
+    }
+    const graded = gradedResponse(level, enforcement);
+    return { ...graded, reasons };
+}

package/dist/holmes/guardrail/risk-types.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RISK_ORDER = void 0;
+exports.maxLevel = maxLevel;
+exports.RISK_ORDER = ['auto', 'notify', 'confirm', 'hard-hitl'];
+function maxLevel(a, b) { return exports.RISK_ORDER.indexOf(a) >= exports.RISK_ORDER.indexOf(b) ? a : b; }