@holmes-lab/holmes-kit 0.1.8 → 0.1.10

package/dist/holmes/cpg/language-parser-walk.js

@@ -593,24 +593,90 @@ function extractEdgesFromTree(tree, lang = 'typescript') {
         }
         return parts.length ? parts.join('.') : '<module>';
     };
-    const visit = (node) => {
+    // @implements A-SPEC-231
+    // A dependency wears more than one spelling, and until 2026-08-22 the graph saw exactly one of
+    // them. Measured: `await import('../x')`, `require('../x')`, `export {y} from '../x'` and
+    // `export * from '../x'` all produced NO imports edge, so a Forbidden Edges ban could be walked
+    // past four ways. A rule that sees one spelling bans the spelling, not the dependency.
+    //
+    // RELATIVE specifiers only, string literals only. `require('js-yaml')` is an external dependency
+    // and a different subject; `require(base + '/x')` cannot be read statically and stays a stated
+    // blind spot rather than a guess.
+    const relativeLiteral = (n) => {
+        if (!n)
+            return null;
+        // A template literal WITHOUT substitutions is a string literal wearing different quotes —
+        // \`require(\`../x\`)\` walked past the first cut of this check (adversarial pass 2, 2026-08-22).
+        // One with substitutions is computed and stays unreadable, which is the stated blind spot.
+        const isTemplate = n.type === 'template_string';
+        if (n.type !== 'string' && !isTemplate)
+            return null;
+        if (isTemplate && n.namedChildren && n.namedChildren.some((c) => c.type === 'template_substitution'))
+            return null;
+        const text = n.text.replace(/^['"`]|['"`]$/g, '');
+        return text.startsWith('.') ? text : null;
+    };
+    const firstArgSpecifier = (node) => {
+        const args = node.childForFieldName('arguments');
+        if (!args || !args.namedChildren || args.namedChildren.length === 0)
+            return null;
+        return relativeLiteral(args.namedChildren[0]);
+    };
+    // @implements A-SPEC-231
+    // The enclosing name is carried DOWN the descent instead of re-walked UP from every call site.
+    // Same answer, different cost: the upward walk is O(nodes x depth), invisible in a batch scan
+    // and intolerable in a hook. Measured 2026-08-22 before this change — a 2KB file nested 800 deep
+    // took 10,558ms and 500 deep took 2,663ms, while a FLAT 1MB file took 1,031ms. The cost followed
+    // depth, not size, so no size cap could have bounded it. The quadratic predates this work;
+    // A-SPEC-230 is what moved it onto the write path.
+    const namedScopeOf = (node) => {
+        if (node.type !== 'function_declaration' && node.type !== 'method_definition' && node.type !== 'class_declaration')
+            return null;
+        const nm = node.childForFieldName('name');
+        return nm ? nm.text : null;
+    };
+    const visit = (node, scope) => {
         if (node.type === 'import_statement') {
             const src = node.childForFieldName('source') ?? (node.namedChildren && node.namedChildren.find((c) => c.type === 'string'));
             if (src)
                 out.push({ from: '<module>', to: src.text.replace(/['"]/g, ''), rel: 'imports' });
         }
+        else if (node.type === 'export_statement') {
+            // `export { x } from '…'` and `export * from '…'` — a re-export names no local binding but is
+            // every bit a module dependency.
+            const src = node.childForFieldName('source');
+            const spec = relativeLiteral(src);
+            if (spec)
+                out.push({ from: '<module>', to: spec, rel: 'imports' });
+        }
         else if (node.type === 'call_expression') {
             const fn = node.childForFieldName('function');
+            // Dynamic `import('…')`: the callee is neither an identifier nor a member expression, so the
+            // branch below never saw it at all.
+            if (fn && fn.type === 'import') {
+                const spec = firstArgSpecifier(node);
+                if (spec)
+                    out.push({ from: '<module>', to: spec, rel: 'imports' });
+            }
             if (fn && (fn.type === 'identifier' || fn.type === 'member_expression')) {
                 const property = fn.childForFieldName && fn.childForFieldName('property');
                 const callee = fn.type === 'identifier' ? fn.text : (property ? property.text : fn.text);
-                out.push({ from: enclosingFn(node), to: callee, rel: 'calls' });
+                out.push({ from: scope.length ? scope.join('.') : '<module>', to: callee, rel: 'calls' });
+                // The calls edge above is KEPT. Adding the imports edge alongside makes this an extension;
+                // replacing it would leave no single run able to say which it had been.
+                if (callee === 'require') {
+                    const spec = firstArgSpecifier(node);
+                    if (spec)
+                        out.push({ from: '<module>', to: spec, rel: 'imports' });
+                }
             }
         }
+        const named = namedScopeOf(node);
+        const childScope = named ? scope.concat(named) : scope;
         for (let i = 0; i < node.childCount; i++)
-            visit(node.child(i));
+            visit(node.child(i), childScope);
     };
-    visit(tree.rootNode);
+    visit(tree.rootNode, []);
     return out;
 }
 /**

package/dist/holmes/cpg/proposed-content.d.ts

@@ -0,0 +1,51 @@
+import { CodeEdge } from './language-parser';
+import { ForbiddenEdgeRule } from './forbidden-edges';
+import { RequiredCallRule } from './required-calls';
+/** What the gate could actually see. `none` means no verdict was formed, not that nothing was wrong. */
+export type JudgedAs = 'full' | 'fragment' | 'none';
+export interface ProposedContentCheck {
+    forbidden: ForbiddenEdgeRule[];
+    required: RequiredCallRule[];
+    sourcePath: string;
+    content: string;
+    /** `full` for a whole-file write; `fragment` for an edit's replacement text. */
+    mode: 'full' | 'fragment';
+    parser: {
+        extractEdges(code: string, lang: 'typescript'): CodeEdge[];
+    };
+}
+/**
+ * Judge ONE proposed file against structural constraints, without scanning the repository.
+ *
+ * @implements A-SPEC-230
+ * Both engines already judge file by file — a rule's `sourcePrefix` selects the path and only that
+ * file's edges are read — so the gate needs one parse, not a scan. Measured 2026-08-22: 2ms for a
+ * typical file, 18ms for the 109KB outlier, against 3.3s + 1.5s for the two full scans.
+ *
+ * FRAGMENTS ARE JUDGED DIFFERENTLY, and the asymmetry is the point:
+ *
+ *  - A BAN is sound on a fragment. If the added text contains a forbidden edge, that edge is really
+ *    being added. Not seeing the rest of the file can make this MISS something; it cannot make it
+ *    WRONG.
+ *  - An OBLIGATION is not. The companion call may already sit elsewhere in the file, so concluding
+ *    "absent" from a fragment manufactures a false positive — and false positives are precisely what
+ *    make a rule distrusted and then removed.
+ *
+ * A parse failure yields no verdict rather than a denial. This repository usually fails closed and
+ * that judgement has been right, but the asymmetry matters: the seal gate blocks forgery of evidence
+ * that cannot be recovered, while this one blocks a design-discipline violation that the suite
+ * catches again before the commit. Blocking every unparseable work-in-progress buys nothing the
+ * suite does not already provide.
+ */
+export declare function checkProposedContent(opts: ProposedContentCheck): {
+    violations: string[];
+    judged: JudgedAs;
+};
+/**
+ * What this check does NOT promise, carried in the refusal itself.
+ *
+ * @implements A-SPEC-230
+ * A gate's silence reads as "safe". Stating the approximations where the reader already is — rather
+ * than in a document they will not open — is what keeps a pass from becoming false confidence.
+ */
+export declare const CSPEC_GATE_LIMITS: string;

package/dist/holmes/cpg/proposed-content.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CSPEC_GATE_LIMITS = void 0;
+exports.checkProposedContent = checkProposedContent;
+const forbidden_edges_1 = require("./forbidden-edges");
+const required_calls_1 = require("./required-calls");
+/** Extensions the TypeScript grammar can actually read. @implements A-SPEC-231 */
+const TS_FAMILY_RE = /\.(ts|tsx|mts|cts|js|mjs|cjs|jsx)$/i;
+/**
+ * Judge ONE proposed file against structural constraints, without scanning the repository.
+ *
+ * @implements A-SPEC-230
+ * Both engines already judge file by file — a rule's `sourcePrefix` selects the path and only that
+ * file's edges are read — so the gate needs one parse, not a scan. Measured 2026-08-22: 2ms for a
+ * typical file, 18ms for the 109KB outlier, against 3.3s + 1.5s for the two full scans.
+ *
+ * FRAGMENTS ARE JUDGED DIFFERENTLY, and the asymmetry is the point:
+ *
+ *  - A BAN is sound on a fragment. If the added text contains a forbidden edge, that edge is really
+ *    being added. Not seeing the rest of the file can make this MISS something; it cannot make it
+ *    WRONG.
+ *  - An OBLIGATION is not. The companion call may already sit elsewhere in the file, so concluding
+ *    "absent" from a fragment manufactures a false positive — and false positives are precisely what
+ *    make a rule distrusted and then removed.
+ *
+ * A parse failure yields no verdict rather than a denial. This repository usually fails closed and
+ * that judgement has been right, but the asymmetry matters: the seal gate blocks forgery of evidence
+ * that cannot be recovered, while this one blocks a design-discipline violation that the suite
+ * catches again before the commit. Blocking every unparseable work-in-progress buys nothing the
+ * suite does not already provide.
+ */
+function checkProposedContent(opts) {
+    const { forbidden, required, sourcePath, content, mode, parser } = opts;
+    const rulesPresent = (forbidden?.length ?? 0) > 0 || (required?.length ?? 0) > 0;
+    if (!rulesPresent || typeof content !== 'string' || content.trim().length === 0) {
+        return { violations: [], judged: 'none' };
+    }
+    // @implements A-SPEC-231 — the parser is asked for TypeScript, so only TypeScript-family files may
+    // be handed to it. Measured 2026-08-22: a Python file's `list()` parsed as TypeScript became a
+    // calls edge and a false positive against an obligation rule, and false positives are what get a
+    // rule switched off. Not judging is reported as `none`, never as a pass.
+    if (!TS_FAMILY_RE.test(sourcePath))
+        return { violations: [], judged: 'none' };
+    let edges;
+    try {
+        edges = parser.extractEdges(content, 'typescript');
+    }
+    catch {
+        return { violations: [], judged: 'none' };
+    }
+    const asScanned = [{ path: sourcePath, sourcePath, symbols: [], edges, implementsSpecs: [] }];
+    const violations = [];
+    for (const v of (0, forbidden_edges_1.findForbiddenEdgeViolations)(asScanned, forbidden ?? [])) {
+        violations.push(`${v.sourcePath}: ${v.rule}  (${v.kind} → ${v.to})`);
+    }
+    // Obligations only where the whole file is visible — see the asymmetry above.
+    if (mode === 'full') {
+        for (const v of (0, required_calls_1.findRequiredCallViolations)(asScanned, required ?? [])) {
+            violations.push(`${v.sourcePath} :: ${v.fn}: ${v.rule}  (calls ${v.trigger}, none of the required)`);
+        }
+    }
+    return { violations, judged: mode };
+}
+/**
+ * What this check does NOT promise, carried in the refusal itself.
+ *
+ * @implements A-SPEC-230
+ * A gate's silence reads as "safe". Stating the approximations where the reader already is — rather
+ * than in a document they will not open — is what keeps a pass from becoming false confidence.
+ */
+exports.CSPEC_GATE_LIMITS = '이 검사가 보장하지 않는 것: 제어 흐름을 보지 않으므로 분기에 따라 규칙을 비껴가는 코드는 통과합니다;'
+    + ' 모듈 최상위 호출은 파일 단위로 귀속됩니다; 판정 대상은 이 파일 하나이며 저장소 전체가 아닙니다.';

package/dist/holmes/cpg/required-calls.d.ts

@@ -0,0 +1,62 @@
+import { ScannedFile } from './cpg-scanner';
+import { RuleCorpus } from './forbidden-edges';
+/**
+ * An obligation: within a scope, calling one thing requires calling another.
+ *
+ * @implements A-SPEC-228
+ * `Forbidden Edges` says "do not call B". It cannot say "if you call B, also call C", and that is
+ * the rule this session paid for three times — "anything reading the active graph must go through
+ * `filterGoverned`" lived only in prose, so its bypasses were found one at a time.
+ *
+ * `Allowed Dependencies` read as a whitelist does not express it either: a whitelist is the
+ * complement of a ban, not an implication.
+ */
+export interface RequiredCallRule {
+    /** Which corpus this rule judges. @implements A-SPEC-229 */
+    corpus: RuleCorpus;
+    /** Repo-relative prefix of the files this obligation applies to. */
+    sourcePrefix: string;
+    /** The call that triggers the obligation. */
+    trigger: string;
+    /** Any ONE of these satisfies it. */
+    required: string[];
+    /** The rule's own text, so a violation can quote what it broke. */
+    text: string;
+}
+export interface RequiredCallViolation {
+    rule: string;
+    sourcePath: string;
+    /** The enclosing definition that called the trigger without a companion. */
+    fn: string;
+    trigger: string;
+}
+/**
+ * Read the obligations out of a `## Layer Rules` section.
+ *
+ * @implements A-SPEC-228
+ * `-needs->` pairs with `Forbidden Edges`' `-x->` so a reader can tell a ban from an obligation at a
+ * glance. A malformed list item is RETURNED rather than dropped: a typo that parses to nothing reads
+ * as "the rule passed", which is the failure shape this whole line of work exists to remove.
+ */
+export declare function parseRequiredCalls(section: string): {
+    rules: RequiredCallRule[];
+    malformed: string[];
+};
+/**
+ * Judge a scan against a set of obligations.
+ *
+ * @implements A-SPEC-228
+ * The unit is the FUNCTION, taken from `CodeEdge.from`. File granularity would pass a file that
+ * calls the trigger in one function and the companion in another, and that relaxation defeats the
+ * rule's purpose.
+ *
+ * Deliberately incomplete, and the direction is stated rather than discovered: static co-occurrence
+ * does not read control flow, so a function that skips the companion on one branch still passes.
+ * Measured evidence that it is worth having anyway — run against the pre-71cd807 dashboard, it flags
+ * `startDashboardServer`, the real defect that shipped three bypassed endpoints.
+ *
+ * Test files are outside the scan entirely (`CpgScanner` excludes them so test symbols cannot
+ * corrupt the production graph), so the `tspec-mirror.test.ts` bypass of the same rule remains
+ * invisible here. Catching one incident of three is not "solved".
+ */
+export declare function findRequiredCallViolations(files: ScannedFile[], rules: RequiredCallRule[]): RequiredCallViolation[];

package/dist/holmes/cpg/required-calls.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRequiredCalls = parseRequiredCalls;
+exports.findRequiredCallViolations = findRequiredCallViolations;
+const test_files_1 = require("./test-files");
+const forbidden_edges_1 = require("./forbidden-edges");
+const RULE = /^call\s+(\S+)\s+(\S+)\s+-needs->\s+(.+)$/;
+/**
+ * Read the obligations out of a `## Layer Rules` section.
+ *
+ * @implements A-SPEC-228
+ * `-needs->` pairs with `Forbidden Edges`' `-x->` so a reader can tell a ban from an obligation at a
+ * glance. A malformed list item is RETURNED rather than dropped: a typo that parses to nothing reads
+ * as "the rule passed", which is the failure shape this whole line of work exists to remove.
+ */
+function parseRequiredCalls(section) {
+    const rules = [];
+    const malformed = [];
+    for (const raw of String(section ?? '').split('\n')) {
+        const line = raw.trim();
+        if (!line.startsWith('- '))
+            continue; // prose, blank, or not a list item
+        const body = line.slice(2).replace(/\s+#.*$/, '').replace(/`/g, '').trim().replace(/\s+/g, ' ');
+        if (!/-needs->/.test(body) && !/^call\b/.test(body))
+            continue; // not an obligation at all
+        const m = RULE.exec(body);
+        if (!m) {
+            malformed.push(raw.trim());
+            continue;
+        }
+        const required = m[3].split('|').map((s) => s.trim()).filter(Boolean);
+        if (required.length === 0) {
+            malformed.push(raw.trim());
+            continue;
+        }
+        const { corpus, sourcePrefix } = (0, forbidden_edges_1.splitCorpus)(m[1]);
+        rules.push({ corpus, sourcePrefix, trigger: m[2], required, text: body });
+    }
+    return { rules, malformed };
+}
+/**
+ * Judge a scan against a set of obligations.
+ *
+ * @implements A-SPEC-228
+ * The unit is the FUNCTION, taken from `CodeEdge.from`. File granularity would pass a file that
+ * calls the trigger in one function and the companion in another, and that relaxation defeats the
+ * rule's purpose.
+ *
+ * Deliberately incomplete, and the direction is stated rather than discovered: static co-occurrence
+ * does not read control flow, so a function that skips the companion on one branch still passes.
+ * Measured evidence that it is worth having anyway — run against the pre-71cd807 dashboard, it flags
+ * `startDashboardServer`, the real defect that shipped three bypassed endpoints.
+ *
+ * Test files are outside the scan entirely (`CpgScanner` excludes them so test symbols cannot
+ * corrupt the production graph), so the `tspec-mirror.test.ts` bypass of the same rule remains
+ * invisible here. Catching one incident of three is not "solved".
+ */
+function findRequiredCallViolations(files, rules) {
+    const out = [];
+    if (!Array.isArray(files) || !Array.isArray(rules) || rules.length === 0)
+        return out;
+    for (const f of files) {
+        const sourcePath = f?.sourcePath;
+        if (typeof sourcePath !== 'string')
+            continue;
+        // @implements A-SPEC-229 — see forbidden-edges.ts for why `isTestFile` decides this.
+        const corpus = (0, test_files_1.isTestFile)(sourcePath) ? 'tests' : 'production';
+        const applicable = rules.filter((r) => r.corpus === corpus && sourcePath.startsWith(r.sourcePrefix));
+        if (applicable.length === 0)
+            continue;
+        const callsByFunction = new Map();
+        for (const e of f.edges ?? []) {
+            if (e.rel !== 'calls' || !e.from)
+                continue;
+            let set = callsByFunction.get(e.from);
+            if (!set) {
+                set = new Set();
+                callsByFunction.set(e.from, set);
+            }
+            set.add(e.to);
+        }
+        for (const [fn, calls] of callsByFunction) {
+            for (const r of applicable) {
+                if (!calls.has(r.trigger))
+                    continue;
+                if (r.required.some((req) => calls.has(req)))
+                    continue;
+                out.push({ rule: r.text, sourcePath, fn, trigger: r.trigger });
+            }
+        }
+    }
+    return out;
+}

package/dist/holmes/guardrail/cspec-change.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The C-SPEC a risk action is about, or `null` when it is about something else.
+ *
+ * @implements A-SPEC-225
+ * Both spellings resolve to the same id, because the same edit reaches the same document whether the
+ * caller named `C-SPEC-224` or `.ax/specs/04_cpg/C-SPEC-224.md`. A verdict that depends on how the
+ * caller spelled the target is a verdict the caller chooses — the identity-not-spelling rule
+ * A-SPEC-163 set for paths, applied to this field.
+ */
+export declare function cspecTargetId(target: string): string | null;
+/**
+ * Did the proposal change what this C-SPEC forbids?
+ *
+ * @implements A-SPEC-225
+ * Pure — text in, boolean out — so the verdict can be exercised without a store, and the I/O stays
+ * in the handler exactly as `risk-classifier`'s existing split requires.
+ *
+ * An unreadable side answers `true`. Concluding "unchanged" from content one cannot see is the
+ * failure this repository has now paid for three times: A-SPEC-191 §17 and §29 both began as "the
+ * gate did not refuse to govern — it concluded there was nothing to govern", and A-SPEC-222.2 was
+ * the same shape again. Not seeing is not sameness.
+ */
+export declare function cspecConstraintChanged(current: string | null, proposed: string | null): boolean;

package/dist/holmes/guardrail/cspec-change.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cspecTargetId = cspecTargetId;
+exports.cspecConstraintChanged = cspecConstraintChanged;
+// @implements A-SPEC-225
+const spec_parser_1 = require("../spec/spec-parser");
+const forbidden_edges_1 = require("../cpg/forbidden-edges");
+/**
+ * The C-SPEC a risk action is about, or `null` when it is about something else.
+ *
+ * @implements A-SPEC-225
+ * Both spellings resolve to the same id, because the same edit reaches the same document whether the
+ * caller named `C-SPEC-224` or `.ax/specs/04_cpg/C-SPEC-224.md`. A verdict that depends on how the
+ * caller spelled the target is a verdict the caller chooses — the identity-not-spelling rule
+ * A-SPEC-163 set for paths, applied to this field.
+ */
+function cspecTargetId(target) {
+    if (typeof target !== 'string')
+        return null;
+    const m = /\bC-SPEC-\d{3,}(?:\.\d+)?\b/.exec(target);
+    return m ? m[0] : null;
+}
+/** The constraint content of one document, in a form two documents can be compared by. */
+function constraintFingerprint(text) {
+    let spec;
+    try {
+        spec = (0, spec_parser_1.parseSpec)(text);
+    }
+    catch {
+        return null;
+    }
+    const sections = spec.sections ?? {};
+    const forbidden = sections['Forbidden Edges'];
+    const layerRules = sections['Layer Rules'];
+    if (forbidden === undefined && layerRules === undefined)
+        return null;
+    const { rules, malformed } = (0, forbidden_edges_1.parseForbiddenEdges)(forbidden ?? '');
+    // Sorted sets, not raw text: whitespace, backticks and trailing comments are not constraints, and
+    // calling a human for those would make the rule itself distrusted.
+    const ruleKeys = rules.map((r) => `${r.kind}|${r.sourcePrefix}|${r.target}`).sort();
+    // Malformed lines count. A rule broken by a typo is a rule that no longer binds anything, which is
+    // indistinguishable in effect from deleting it.
+    const brokenKeys = malformed.map((l) => l.replace(/\s+/g, ' ').trim()).sort();
+    // Layer Rules is compared as normalised prose. Nothing judges that section yet (A-SPEC-224 leaves
+    // it out), but DETECTION IS NOT JUDGEMENT — and the field this feeds names both sections. Missing
+    // it would honour "a constraint change needs a human" for only half of what it promises.
+    const layerKey = (layerRules ?? '').replace(/\s+/g, ' ').trim();
+    return JSON.stringify({ ruleKeys, brokenKeys, layerKey });
+}
+/**
+ * Did the proposal change what this C-SPEC forbids?
+ *
+ * @implements A-SPEC-225
+ * Pure — text in, boolean out — so the verdict can be exercised without a store, and the I/O stays
+ * in the handler exactly as `risk-classifier`'s existing split requires.
+ *
+ * An unreadable side answers `true`. Concluding "unchanged" from content one cannot see is the
+ * failure this repository has now paid for three times: A-SPEC-191 §17 and §29 both began as "the
+ * gate did not refuse to govern — it concluded there was nothing to govern", and A-SPEC-222.2 was
+ * the same shape again. Not seeing is not sameness.
+ */
+function cspecConstraintChanged(current, proposed) {
+    if (!current || !proposed)
+        return true;
+    const a = constraintFingerprint(current);
+    const b = constraintFingerprint(proposed);
+    if (a === null || b === null)
+        return true;
+    return a !== b;
+}

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

@@ -290,6 +290,117 @@ const WRITE_VERB_AX_RE = /\b(?:tee|cp|install|dd|ln|mv|rsync)\b[^;&|\n]*\.ax\/(?
 // `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;
+/**
+ * Commands that only read. Everything else over a governance path is a write.
+ *
+ * @implements A-SPEC-226
+ * The list is inverted, exactly as `write-target.ts` inverted tool recognition and for the same
+ * measured reason. Shell writes were judged by ENUMERATING write shapes — removal verbs, `>`
+ * clobbers, write verbs, interpreter one-liners — under a comment claiming those "cover every
+ * mutation channel". Measured 2026-08-22 against an approved spec: `sed -i`, `perl -i -pe` and
+ * `ex -sc` all returned allow, while the SAME edit through the Write tool was denied as seal
+ * forgery. A fifth variant would have been found the same way.
+ *
+ * Scoped to the governance surface on purpose. Inverting the whole shell would spread friction
+ * across the project; here the cost is bounded and the thing being protected is the seal.
+ */
+const READ_ONLY_SHELL = new Set([
+    'cat', 'grep', 'rg', 'ls', 'find', 'head', 'tail', 'wc', 'diff', 'awk', 'sort', 'uniq',
+    'less', 'more', 'file', 'stat', 'du', 'cut', 'tr', 'column', 'jq', 'basename', 'dirname',
+    'realpath', 'echo', 'printf', 'true', 'test',
+]);
+/** `git` subcommands that only read. `commit`/`checkout`/`add` are not among them. */
+const READ_ONLY_GIT = new Set([
+    'show', 'log', 'status', 'diff', 'ls-tree', 'ls-files', 'blame', 'cat-file', 'rev-parse',
+    'merge-base', 'describe',
+]);
+/** An in-place edit flag, including bundled forms: `-i`, `--in-place`, `-pi`, `-ipe`. */
+const IN_PLACE_FLAG_RE = /^--in-place\b|^-[A-Za-z]*i[A-Za-z]*$/;
+/**
+ * Split a command into the clauses that run separately.
+ *
+ * @implements A-SPEC-226
+ * One clause being a write makes the whole command a write: judging only the first word lets a write
+ * hide behind a pipe (`cat SPEC | tee OTHER`).
+ */
+function splitShellClauses(cmd) {
+    return cmd
+        .split(/\|\||&&|;|\||\n/)
+        .map((c) => c.replace(/^[\s(]+/, '').trim())
+        .filter((c) => c.length > 0);
+}
+/**
+ * Is this single clause known to only read?
+ *
+ * @implements A-SPEC-226
+ * The verdict needs the flags, not just the name: `sed -n` reads and `sed -i` writes. A name-only
+ * allowlist leaves exactly the hole this slice closes.
+ *
+ * Interpreters are never read-only — a one-liner's intent is not statically visible, and the
+ * existing INTERPRETER_AX_RE already took that position. Compound forms (`for`, `while`, `if`)
+ * are not either: their body cannot be read by enumeration, and calling something unreadable a read
+ * is how a gate switches itself off.
+ */
+function isReadOnlyShellClause(clause) {
+    const tokens = clause.split(/\s+/).filter(Boolean);
+    if (tokens.length === 0)
+        return false;
+    const name = tokens[0].replace(/^.*\//, ''); // /usr/bin/grep -> grep
+    if (name === 'git')
+        return tokens.length > 1 && READ_ONLY_GIT.has(tokens[1]);
+    if (name === 'sed' || name === 'perl') {
+        return !tokens.slice(1).some((t) => IN_PLACE_FLAG_RE.test(t));
+    }
+    return READ_ONLY_SHELL.has(name);
+}
+/** Append-only evidence: restoring it deletes records rather than undoing an edit. */
+const LEDGER_PATH_RE = /(^|[\s'"=(/])\.ax\/ledger(\/|\b)/;
+/**
+ * A restore that moves the working tree TOWARD the committed state.
+ *
+ * @implements A-SPEC-227
+ * Direction is what matters, and syntax can read it. Without a ref, `git checkout --` and
+ * `git restore` copy from the index — if an approved spec had been tampered with in the working
+ * tree, this UNDOES that and repairs the seal. With a ref, the content is replaced by another
+ * revision while `approved_digest` stays put, which is the drift the gate exists to catch.
+ *
+ * Only the explicit `--` form counts. `git checkout .ax/specs/` cannot be resolved by syntax —
+ * branch names carry slashes and revisions carry dots — so it is treated as a ref. The side effect
+ * is useful: it pushes callers toward the unambiguous spelling, which is the recommended one anyway.
+ *
+ * Deliberately NOT folded into `isReadOnlyShellClause`. A restore is not a read; it is a write that
+ * is not a governance risk, and merging the two would blur what "read-only" means.
+ */
+function isIndexRestoreClause(clause) {
+    const tokens = clause.split(/\s+/).filter(Boolean);
+    if (tokens.length < 2)
+        return false;
+    if (tokens[0].replace(/^.*\//, '') !== 'git')
+        return false;
+    if (tokens[1] === 'checkout') {
+        const sep = tokens.indexOf('--');
+        if (sep === -1)
+            return false; // no separator: the token could be a ref
+        return tokens.slice(2, sep).every((t) => t.startsWith('-')); // flags are not refs
+    }
+    if (tokens[1] === 'restore') {
+        return !tokens.slice(2).some((t) => t === '-s' || t === '--source' || t.startsWith('--source='));
+    }
+    return false;
+}
+/**
+ * A shell command that touches a protected governance path and is not recognisably read-only.
+ *
+ * @implements A-SPEC-226
+ */
+function shellWritesProtectedAx(ncmd) {
+    if (!CMD_PROTECTED_AX_RE.test(ncmd))
+        return false;
+    // @implements A-SPEC-227 — the ledger exemption is cancelled here, not inside the restore check,
+    // because it is a property of the TARGET rather than of the command shape.
+    const restoreAllowed = !LEDGER_PATH_RE.test(ncmd);
+    return !splitShellClauses(ncmd).every((c) => isReadOnlyShellClause(c) || (restoreAllowed && isIndexRestoreClause(c)));
+}
 /**
  * @implements A-SPEC-125.1
  * Reversibility axis: can the action's effect be undone? Conservative default —
@@ -318,6 +429,17 @@ function classifyReversibility(action) {
         || 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'] };
     }
+    // @implements A-SPEC-226 — the four enumerations above are kept, not replaced. Keeping them makes
+    // this addition purely monotonic: what was blocked stays blocked, and only previously-missed
+    // shapes become blocked. Replacing them would make it impossible to tell in one step whether this
+    // change loosened or tightened the gate.
+    if (shellWritesProtectedAx(ncmd)) {
+        return {
+            axis,
+            level: 'hard-hitl',
+            reasons: ['shell command over a protected .ax governance path is not recognisably read-only'],
+        };
+    }
     // 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