@holmes-lab/holmes-kit 0.18.0 → 0.19.0

package/dist/holmes/cpg/cycle-detect.js

@@ -0,0 +1,251 @@
+"use strict";
+// @implements A-SPEC-574.1
+// The spec graph has been cycle-free by constitution (ART-2) since early on; the CODE graph never
+// was — the same repository enforcing acyclicity on one graph and not the other. Census 2026-09-08
+// on src/holmes: three cycles, whose edges are three different things. A rule that cannot tell them
+// apart is wrong on its first day: TypeScript ERASES a type-only import, so a "cycle" held up only
+// by those does not exist at runtime.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CYCLE_ADVISORY_NOTE = void 0;
+exports.classifyImportEdge = classifyImportEdge;
+exports.detectCycles = detectCycles;
+exports.classifyEdgeByTarget = classifyEdgeByTarget;
+exports.cycleAdvisory = cycleAdvisory;
+exports.cycleRatchetViolations = cycleRatchetViolations;
+exports.cycleKey = cycleKey;
+/**
+ * What survives compilation for one import edge.
+ *
+ * Deliberately conservative: a shape this cannot read is `eager-value`, never `type-erasable`.
+ * Reporting "this disappears at compile time" about something we did not understand is the one
+ * error that silently deletes a real cycle from the count.
+ */
+function classifyImportEdge(source, specifier) {
+    const quoted = specifier.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // A require() anywhere but the top level is the deliberate cycle-breaking idiom. Its PRESENCE is
+    // evidence the cycle was real enough that someone paid to work around it.
+    if (new RegExp(`require\\(\\s*['"]${quoted}['"]\\s*\\)`).test(source))
+        return 'lazy-require';
+    const decl = new RegExp(`^\\s*import\\s+(type\\s+)?([^;]*?)\\s+from\\s+['"]${quoted}['"]`, 'm').exec(source);
+    if (decl === null)
+        return 'eager-value';
+    if (decl[1] !== undefined)
+        return 'type-erasable'; // explicit `import type`
+    const clause = decl[2].trim();
+    // Namespace and default imports carry no per-binding information here — not readable, so eager.
+    const named = /^\{([^}]*)\}$/.exec(clause);
+    if (named === null)
+        return 'eager-value';
+    const bindings = named[1].split(',')
+        .map((b) => b.split(/\s+as\s+/).pop().trim())
+        .filter((b) => b !== '');
+    if (bindings.length === 0)
+        return 'eager-value';
+    // A binding used ONLY in type position is elided by TypeScript. "Type position" is approximated
+    // by the shapes a tree-sitter-free reader can see: after `:`, after `<`, in `extends`/`implements`,
+    // or as a type alias right-hand side. Anything else — a call, a `new`, a value reference — makes
+    // the whole edge eager, because one surviving binding keeps the import statement alive.
+    // Comments are stripped first. Measured on the real corpus: `scan-cache.ts` uses `ScannedFile`
+    // only in type positions, but a prose comment saying "the ScannedFile schema" made the whole edge
+    // read as a value use — the classifier was scoring English.
+    const body = stripComments(source.slice(decl.index + decl[0].length));
+    return bindings.every((b) => usedOnlyAsType(body, b)) ? 'type-erasable' : 'eager-value';
+}
+/** Line and block comments removed, so prose cannot look like code. String bodies are left alone. */
+function stripComments(source) {
+    return source.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/^[^\n]*?\/\/[^\n]*$/gm, (line) => {
+        const at = line.indexOf('//');
+        return at < 0 ? line : line.slice(0, at);
+    });
+}
+function usedOnlyAsType(body, binding) {
+    const name = binding.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const uses = [...body.matchAll(new RegExp(`\\b${name}\\b`, 'g'))];
+    if (uses.length === 0)
+        return true; // imported and never used: nothing survives
+    return uses.every((m) => {
+        const before = body.slice(Math.max(0, m.index - 40), m.index);
+        const after = body.slice(m.index + binding.length, m.index + binding.length + 2);
+        if (/[:<|&,(]\s*$/.test(before) && !/\(\s*$/.test(before))
+            return true; // annotation, generic arg, union
+        if (/\b(extends|implements|satisfies)\s+$/.test(before))
+            return true;
+        if (/\btype\s+\w+\s*=\s*$/.test(before))
+            return true;
+        if (/^\s*[<[]/.test(after) && /[:<|&]\s*$/.test(before))
+            return true;
+        return false;
+    });
+}
+/**
+ * Strongly connected components of size > 1 — Tarjan, iterative order-independent output.
+ *
+ * A self-edge is not a cycle: a file importing itself is a parse artefact, not a design defect.
+ */
+function detectCycles(edges) {
+    const out = new Map();
+    const nodes = new Set();
+    for (const e of edges) {
+        if (e.from === e.to)
+            continue;
+        nodes.add(e.from);
+        nodes.add(e.to);
+        (out.get(e.from) ?? out.set(e.from, []).get(e.from)).push(e.to);
+    }
+    // Sorted adjacency and sorted roots: the same edge set in any input order yields the same result.
+    for (const [, list] of out)
+        list.sort();
+    let counter = 0;
+    const index = new Map();
+    const low = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const components = [];
+    const strongconnect = (v) => {
+        index.set(v, counter);
+        low.set(v, counter);
+        counter++;
+        stack.push(v);
+        onStack.add(v);
+        for (const w of out.get(v) ?? []) {
+            if (!index.has(w)) {
+                strongconnect(w);
+                low.set(v, Math.min(low.get(v), low.get(w)));
+            }
+            else if (onStack.has(w))
+                low.set(v, Math.min(low.get(v), index.get(w)));
+        }
+        if (low.get(v) === index.get(v)) {
+            const comp = [];
+            let w;
+            do {
+                w = stack.pop();
+                onStack.delete(w);
+                comp.push(w);
+            } while (w !== v);
+            if (comp.length > 1)
+                components.push(comp.sort());
+        }
+    };
+    for (const v of [...nodes].sort())
+        if (!index.has(v))
+            strongconnect(v);
+    const cycles = components
+        .map((files) => {
+        const members = new Set(files);
+        // Sorted, not input order: `files` alone being sorted still let two runs of the same edge set
+        // differ, which the determinism case caught.
+        // Deduped: the scanner emits one edge per occurrence, so three `require('./y')` calls in one
+        // file said the same thing three times. Sorted, because `files` alone being sorted still let
+        // two runs of the same edge set differ.
+        const seen = new Set();
+        const held = edges
+            .filter((e) => e.from !== e.to && members.has(e.from) && members.has(e.to))
+            .filter((e) => {
+            const key = `${e.from}\u0000${e.to}\u0000${e.kind}`;
+            if (seen.has(key))
+                return false;
+            seen.add(key);
+            return true;
+        })
+            .sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to));
+        return {
+            files,
+            edges: held,
+            // One surviving edge is enough to keep the cycle at runtime; all-erasable means it is gone.
+            runtime: held.some((e) => e.kind !== 'type-erasable'),
+        };
+    })
+        .sort((a, b) => a.files[0].localeCompare(b.files[0]));
+    return { cycles, runtimeCycles: cycles.filter((c) => c.runtime).length };
+}
+/**
+ * @implements A-SPEC-574.2
+ * The wording that ships with the advisory. Fixed here, not composed at the call site, so the one
+ * thing this surface must never claim cannot drift: it reports cycles that ALREADY exist among the
+ * declared files. What a design is about to create is not visible until the code is written.
+ */
+exports.CYCLE_ADVISORY_NOTE = '선언한 파일이 이미 순환 안에 있습니다. 이것은 예측이 아닙니다 — '
+    + 'import 간선은 실제 소스에서 나오므로, 아직 쓰이지 않은 코드가 만들 순환은 여기서 보이지 않습니다.';
+/**
+ * @implements A-SPEC-574.2
+ * Classify the edge `fromFile -> toFile` by finding the import statement that actually resolves to
+ * that target.
+ *
+ * Picking the statement by the target's BASENAME would classify the wrong import whenever two files
+ * share a name in different directories — which is ordinary in any tree with `util.ts` or
+ * `index.ts`. The specifier is resolved instead, the way the module system does it.
+ *
+ * A target no specifier in this source resolves to is `eager-value`: not finding it is not evidence
+ * that it disappears at compile time.
+ */
+function classifyEdgeByTarget(source, fromFile, toFile) {
+    const dir = fromFile.includes('/') ? fromFile.slice(0, fromFile.lastIndexOf('/')) : '';
+    const target = toFile.replace(/(\/index)?\.[cm]?[jt]sx?$/, '');
+    for (const m of source.matchAll(/from\s+['"](\.[^'"]*)['"]|require\(\s*['"](\.[^'"]*)['"]\s*\)/g)) {
+        const spec = m[1] ?? m[2];
+        if (spec === undefined)
+            continue;
+        if (normalizeRelative(dir, spec) === target)
+            return classifyImportEdge(source, spec);
+    }
+    return 'eager-value';
+}
+/** POSIX-style join+normalize, without pulling in `path` — this module stays pure and portable. */
+function normalizeRelative(dir, spec) {
+    const parts = (dir === '' ? [] : dir.split('/')).concat(spec.split('/'));
+    const out = [];
+    for (const p of parts) {
+        if (p === '' || p === '.')
+            continue;
+        if (p === '..') {
+            out.pop();
+            continue;
+        }
+        out.push(p);
+    }
+    return out.join('/').replace(/(\/index)?\.[cm]?[jt]sx?$/, '');
+}
+/**
+ * @implements A-SPEC-574.2
+ * The cycles the DECLARED files are already in — read before the Files-to-Touch are frozen.
+ *
+ * This is not a prediction and must never be presented as one. Import edges come from scanning real
+ * source, so the cycle a design would CREATE does not exist to be seen at approval time; what can
+ * be seen is that a file the author is about to edit already sits in one. Selling the first as the
+ * second would be worse than silence.
+ *
+ * Calls `detectCycles` rather than computing its own: the advisory and the later verdict have to be
+ * the same function, or "what we warned" and "what we judge" drift apart (A-SPEC-572.1).
+ */
+function cycleAdvisory(fttFiles, edges) {
+    const declaredSet = new Set(fttFiles);
+    if (declaredSet.size === 0)
+        return [];
+    return detectCycles(edges).cycles
+        .map((c) => ({ ...c, declared: c.files.filter((f) => declaredSet.has(f)) }))
+        .filter((c) => c.declared.length > 0);
+}
+/**
+ * @implements A-SPEC-574.4
+ * The runtime cycles nobody allowed — a RATCHET, not an absolute zero.
+ *
+ * Absolute zero would keep every project with a legacy cycle from adopting the harness at all, and
+ * a rule that blocks adoption is a barrier rather than a rule. The escape is a NAME in the allow
+ * list, never a threshold: naming a cycle is a decision someone signed, while a threshold is a
+ * number anyone can move.
+ *
+ * Type-erasable-only cycles are not counted: TypeScript deletes those imports, so refusing them
+ * would refuse something that does not exist at runtime.
+ */
+function cycleRatchetViolations(current, allowed) {
+    const permitted = new Set(allowed);
+    return current
+        .filter((c) => c.runtime)
+        .map((c) => ({ key: cycleKey(c.files), files: c.files, detail: `import cycle: ${c.files.join(' -> ')} -> ${c.files[0]}` }))
+        .filter((v) => !permitted.has(v.key));
+}
+/** Order-independent identity for a cycle, so the allow list cannot be defeated by a reordering. */
+function cycleKey(files) {
+    return [...files].sort().join('|');
+}

package/dist/holmes/cpg/scan-cache.d.ts

@@ -1,4 +1,4 @@
-import { ScannedFile } from './cpg-scanner';
+import type { ScannedFile } from './scanned-file';
 export declare const SCAN_CACHE_VERSION = 3;
 export declare class ScanFileCache {
     private readonly dir;

package/dist/holmes/cpg/scanned-file.d.ts

@@ -0,0 +1,36 @@
+import { CodeSymbol, CodeEdge, DataFlowFacts } from './language-parser';
+export interface ScannedFile {
+    path: string;
+    /** Repo-root-relative POSIX path — provenance key used by RtmGraph.removeBySource. */
+    sourcePath: string;
+    symbols: CodeSymbol[];
+    /**
+     * Call/import relations recovered from this file, with `from` a qualified name defined HERE and
+     * `to` a bare callee name or module path. Resolution to graph node ids happens in rtm-builder,
+     * where the whole scan is visible; a single file cannot know where a callee lives.
+     *
+     * Optional so a cache entry written by an older scanner still loads — such an entry simply carries
+     * no edges, which degrades to the previous anchor-only behaviour rather than crashing.
+     */
+    edges?: CodeEdge[];
+    /**
+     * Def-use facts, present ONLY when the scanner was constructed with `{ dataflow: true }` AND the
+     * file's language has a data-flow walk.
+     *
+     * @implements A-SPEC-140.1
+     * Opt-in by measurement, not taste: the scan already parses each file twice (symbols, edges), and
+     * an unconditional third parse would regress the REQ-139 cold-scan baseline by ~50% to produce a
+     * signal only the taint pass reads. `undefined` therefore means "not extracted" — for the option
+     * being off, for a language with no walk, or for a cache entry from an older writer. It never
+     * means "extracted, found nothing"; that is `{defs:[],calls:[],params:[],returns:[]}`.
+     */
+    dataflow?: DataFlowFacts;
+    implementsSpecs: string[];
+    /**
+     * `@implements` tags shaped like a well-formed governed spec id (REQ/H-SPEC/
+     * C-SPEC/T-SPEC-NNN) instead of an A-SPEC anchor — a wrong-kind anchor that
+     * would otherwise be silently dropped (audit finding D). Populated
+     * alongside `implementsSpecs`, never overlapping with it.
+     */
+    unanchoredImplements: string[];
+}

package/dist/holmes/cpg/scanned-file.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/holmes/governance/constitution.d.ts

@@ -44,6 +44,26 @@ export interface ConstitutionContext {
         severity?: string;
         summary?: string;
     }[];
+    /**
+     * @implements A-SPEC-574.4
+     * Import cycles in the CODE graph, supplied by the hook — the constitution stays pure and does no
+     * I/O, exactly as ART-4's evidence and ART-6's findings are supplied.
+     *
+     * Absent means SILENT: a project whose hook could not scan is not a project without cycles, and
+     * inventing a clean verdict from missing data is the failure mode this repository names most
+     * often. `scope.unavailable` carries the languages whose imports could not be resolved, so the
+     * report can say what it did NOT judge instead of implying zero.
+     */
+    cycles?: {
+        current: import('../cpg/cycle-detect').Cycle[];
+        /** Cycle keys a C-SPEC named as accepted. The escape is a name, never a threshold. */
+        allowed: string[];
+        mode: 'strict' | 'track' | 'off';
+        scope: {
+            judged: string[];
+            unavailable: string[];
+        };
+    };
     /** A-SPEC id -> count of real test cases in anchored test files (H1 syntactic lower bound). */
     testCasesByAspec?: Record<string, number>;
     /**

package/dist/holmes/governance/constitution.js

@@ -6,6 +6,8 @@ exports.verifyConstitution = verifyConstitution;
 const basis_1 = require("../mcp/basis");
 const spec_types_1 = require("../spec/spec-types");
 const rtm_check_1 = require("../rtm/rtm-check");
+// @implements A-SPEC-574.4 — the same detector the design-time advisory calls.
+const cycle_detect_1 = require("../cpg/cycle-detect");
 const validator_1 = require("../spec/validator");
 /**
  * @implements A-SPEC-534.2
@@ -54,6 +56,21 @@ function verifyConstitution(ctx) {
     for (const issue of (0, rtm_check_1.rtmCheck)(governed)) {
         v.push({ article: 'ART-2', detail: `RTM ${issue.kind} [${issue.id}]: ${issue.detail}` });
     }
+    // @implements A-SPEC-574.4
+    // ART-2's sibling on the OTHER graph. The spec graph has been required to be acyclic since early
+    // on; the code graph never was, in the same repository. Shipped in `track` first — the posture
+    // that records without blocking — because a gate whose false-positive rate nobody has measured
+    // gets promoted by evidence, not by enthusiasm (the impactAdvisory / anchorDensity lifecycle).
+    // STRICT ONLY here, exactly like ART-8: `track` must record without blocking, and a violation
+    // emitted from this function IS a block. The hook computes the track list separately.
+    if (ctx.cycles !== undefined && ctx.cycles.mode === 'strict') {
+        const scope = ctx.cycles.scope.unavailable.length > 0
+            ? ` (judged: ${ctx.cycles.scope.judged.join(', ') || 'none'}; NOT judged: ${ctx.cycles.scope.unavailable.join(', ')})`
+            : '';
+        for (const found of (0, cycle_detect_1.cycleRatchetViolations)(ctx.cycles.current, ctx.cycles.allowed)) {
+            v.push({ article: 'ART-2', detail: `code ${found.detail}${scope}` });
+        }
+    }
     // ART-3: spec validity (type rules + 4-quadrant GWT via validateSpec)
     for (const s of governed) {
         const r = (0, validator_1.validateSpec)(s, resolve);

package/dist/holmes/governance/ledger-store.d.ts

@@ -112,3 +112,12 @@ export declare class MemoryLedgerStore implements LedgerStore {
     append(body: Omit<ProvenanceEvent, 'prevHash' | 'hash' | 'seq'>): ProvenanceEvent;
     isNonceConsumed(nonce: string): boolean;
 }
+/**
+ * The cross-replica nonce check, bound to one ledger file, ready to hand to
+ * `consumeNonceExclusively`.
+ *
+ * Lives HERE, on the store side, because that is the direction the dependency should point: the
+ * chain layer asks a question the caller answers, instead of reaching into the store through a lazy
+ * `require()` to dodge an import cycle. One helper rather than three copies at the call sites.
+ */
+export declare function nonceConsumedIn(ledgerFile: string): (nonce: string) => boolean;

package/dist/holmes/governance/ledger-store.js

@@ -1,9 +1,44 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MemoryLedgerStore = exports.FileLedgerStore = void 0;
+exports.nonceConsumedIn = nonceConsumedIn;
 // @implements A-SPEC-150
 const provenance_chain_1 = require("./provenance-chain");
 const provenance_ledger_1 = require("./provenance-ledger");
+const path = __importStar(require("node:path"));
 /**
  * Local adapter — DELEGATES to `ProvenanceLedger` rather than re-implementing it.
  *
@@ -104,3 +139,15 @@ class MemoryLedgerStore {
     }
 }
 exports.MemoryLedgerStore = MemoryLedgerStore;
+// @implements A-SPEC-574.3
+/**
+ * The cross-replica nonce check, bound to one ledger file, ready to hand to
+ * `consumeNonceExclusively`.
+ *
+ * Lives HERE, on the store side, because that is the direction the dependency should point: the
+ * chain layer asks a question the caller answers, instead of reaching into the store through a lazy
+ * `require()` to dodge an import cycle. One helper rather than three copies at the call sites.
+ */
+function nonceConsumedIn(ledgerFile) {
+    return (nonce) => new FileLedgerStore(path.dirname(ledgerFile)).isNonceConsumed(nonce);
+}

package/dist/holmes/governance/provenance-chain.d.ts

@@ -177,5 +177,20 @@ export declare const PROVENANCE_FILE: string;
  * decision, not this function's: an authorization gate must deny, while a record-keeping append must
  * not flip a decision that was already made.
  */
-export declare function consumeNonceExclusively(nonce: string, ledgerFile: string, body: Omit<ProvenanceBody, 'seq'>, opts?: LockOptions): boolean;
+export declare function consumeNonceExclusively(nonce: string, ledgerFile: string, body: Omit<ProvenanceBody, 'seq'>, opts: LockOptions & {
+    /**
+     * @implements A-SPEC-574.3
+     * Whether this nonce was already consumed, ACROSS every replica chain (A-SPEC-148's rule).
+     *
+     * Injected, because the chain layer has no business knowing about the store layer — it used to
+     * reach for `FileLedgerStore` through a lazy `require()`, and that workaround existed only to
+     * dodge the import cycle it created. The caller owns the store; the caller passes the question.
+     *
+     * REQUIRED, and that is the point. The first cut made it optional with a `?? false` default,
+     * and `ledger-race` went red immediately: the second consume of the same nonce SUCCEEDED. A
+     * default of "nothing is spent" turns REQ-141's whole reason for existing into an opt-in. A
+     * missing security check has to be a compile error, not a quiet pass.
+     */
+    isNonceConsumed: (nonce: string) => boolean;
+}): boolean;
 export {};

package/dist/holmes/governance/provenance-chain.js

@@ -427,8 +427,10 @@ function consumeNonceExclusively(nonce, ledgerFile, body, opts) {
         // across machines there is no shared filesystem to lock, so two machines racing the same nonce
         // can both pass and the duplicate is DETECTED afterwards in the merged ledger rather than
         // prevented. Preventing it needs a shared authority, which is out of this slice's scope.
-        const { FileLedgerStore } = require('./ledger-store');
-        const spent = new FileLedgerStore(path.dirname(ledgerFile)).isNonceConsumed(nonce);
+        // @implements A-SPEC-574.3 — the check comes from the caller. Absent, nothing is known to be
+        // spent: a caller that does not supply the store is asking for an append, not for exclusion,
+        // and inventing a false "already consumed" here would silently refuse a legitimate action.
+        const spent = opts.isNonceConsumed(nonce);
         if (spent)
             return false;
         chain.appendInsideLock(body);
@@ -436,5 +438,5 @@ function consumeNonceExclusively(nonce, ledgerFile, body, opts) {
         // Default the stale-break recorder to the chain's own: breaking a lock silently is forbidden
         // here for exactly the same reason it is in `append()`, and leaving it undefined made this
         // path — the SECURITY path — the one place a lock could be stolen without a trace.
-    }, { ...opts, onStaleBreak: opts?.onStaleBreak ?? chain.staleBreakRecorder() });
+    }, { ...opts, onStaleBreak: opts.onStaleBreak ?? chain.staleBreakRecorder() });
 }

package/dist/holmes/hooks/pre-tool-use.js

@@ -72,6 +72,8 @@ const governance_history_1 = require("../guardrail/governance-history");
 const rtm_check_1 = require("../rtm/rtm-check");
 const ledger_store_1 = require("../governance/ledger-store");
 const provenance_chain_1 = require("../governance/provenance-chain");
+// @implements A-SPEC-574.3 — the caller owns the store and hands the chain the question.
+const ledger_store_2 = require("../governance/ledger-store");
 const risk_gate_1 = require("../guardrail/risk-gate");
 const approval_queue_1 = require("../governance/approval-queue");
 const approval_grants_1 = require("../governance/approval-grants");
@@ -491,7 +493,7 @@ function evaluateHook(input, specsDir, opts) {
                         ts: nowTs, actor: acting.actor, kind: 'nonce-consumed',
                         summary: `consumed single-use approval for: ${(0, provenance_chain_1.redactTarget)('command', command)}`.slice(0, 200),
                         inputs: [(0, provenance_chain_1.nonceFingerprint)(acting.nonce)], rationale: acting.rationale, authorization: (0, provenance_chain_1.authorizationRef)(acting.actor, acting.token),
-                    });
+                    }, { isNonceConsumed: (0, ledger_store_2.nonceConsumedIn)(ledgerFile) });
                 }
                 catch (err) {
                     // FAIL CLOSED. A gate that cannot prove exclusivity must not grant — degrading to an

package/dist/holmes/hooks/stop.d.ts

@@ -95,6 +95,20 @@ export interface StopEvidence {
         ts: string;
     }>>;
     redFirstMode?: 'strict' | 'track' | 'off';
+    /**
+     * @implements A-SPEC-574.4
+     * Code-graph cycles, scanned by this hook. Absent = not scanned, which the constitution treats as
+     * silence rather than as "none" — a project whose scan failed has not been cleared.
+     */
+    cycles?: {
+        current: import('../cpg/cycle-detect').Cycle[];
+        allowed: string[];
+        mode: 'strict' | 'track' | 'off';
+        scope: {
+            judged: string[];
+            unavailable: string[];
+        };
+    };
 }
 /**
  * @implements A-SPEC-534.4

package/dist/holmes/hooks/stop.js

@@ -62,6 +62,8 @@ const node_child_process_1 = require("node:child_process");
 const path = __importStar(require("node:path"));
 const test_scope_1 = require("../rtm/test-scope");
 const constitution_1 = require("../governance/constitution");
+// @implements A-SPEC-574.4 — same detector as the design-time advisory and the strict article.
+const cycle_detect_1 = require("../cpg/cycle-detect");
 const provenance_chain_1 = require("../governance/provenance-chain");
 const test_evidence_1 = require("../review/test-evidence");
 const test_outcomes_1 = require("../review/test-outcomes");
@@ -439,6 +441,7 @@ function evaluateStop(specs, evidence) {
     const violations = (0, constitution_1.verifyConstitution)({
         specs, testCasesByAspec: evidence?.testCasesByAspec, executedByAspec: evidence?.executedByAspec, findings: evidence?.findings,
         redFirstMode: evidence?.redFirstMode, changedAspecs: evidence?.changedAspecs, outcomesByAspec: evidence?.outcomesByAspec,
+        cycles: evidence?.cycles,
     });
     // @implements A-SPEC-534.4 — `track` records ART-8 findings without blocking the turn. Computed
     // separately (the constitution stays silent on ART-8 outside strict) and returned in `tracked` for
@@ -449,6 +452,17 @@ function evaluateStop(specs, evidence) {
         if (t.length)
             tracked = t;
     }
+    // @implements A-SPEC-574.4 — the cycle ratchet's track posture: recorded, never blocking. Promotion
+    // to `strict` waits on the observation ledger answering the false-positive rate, which is the same
+    // path impactAdvisory and anchorDensity took.
+    if (evidence?.cycles !== undefined && evidence.cycles.mode === 'track') {
+        const scope = evidence.cycles.scope.unavailable.length > 0
+            ? ` (NOT judged: ${evidence.cycles.scope.unavailable.join(', ')})` : '';
+        const t = (0, cycle_detect_1.cycleRatchetViolations)(evidence.cycles.current, evidence.cycles.allowed)
+            .map((x) => ({ article: 'ART-2', detail: `code ${x.detail}${scope}` }));
+        if (t.length)
+            tracked = [...(tracked ?? []), ...t];
+    }
     const problems = violations.map((x) => `[${x.article}] ${x.detail}`);
     // @implements A-SPEC-247 — structured list so the caller can ask acknowledgeStop which of these
     // are waiting on an owner. Mirrors `problems` exactly, including the two synthesized below.
@@ -876,6 +890,65 @@ if (require.main === module) {
                 changedAspecs = undefined;
                 outcomesByAspec = undefined;
             }
+            // @implements A-SPEC-574.4 — the code graph's acyclicity, judged where the code exists. The
+            // scan is the same one every other layer uses; the classification reads only the files an
+            // import edge starts from. Fail-open in every direction: any error leaves the article silent,
+            // because "we could not look" must never be reported as "there is nothing there".
+            let cycles;
+            try {
+                const root = stopProjectRoot();
+                const { CpgScanner } = require('../cpg/cpg-scanner');
+                const scanned = new CpgScanner().scan(root, root);
+                const known = new Set(scanned.map((f) => f.sourcePath));
+                const edges = [];
+                const judged = new Set();
+                const sawImports = new Set();
+                for (const f of scanned) {
+                    const ext = f.sourcePath.slice(f.sourcePath.lastIndexOf('.'));
+                    let text = '';
+                    try {
+                        text = fs.readFileSync(path.join(root, f.sourcePath), 'utf8');
+                    }
+                    catch {
+                        continue;
+                    }
+                    let sawImport = false;
+                    for (const e of f.edges ?? []) {
+                        if (e.rel !== 'imports' || !e.to)
+                            continue;
+                        sawImport = true;
+                        if (!e.to.startsWith('.'))
+                            continue;
+                        const base = path.posix.normalize(path.posix.join(path.posix.dirname(f.sourcePath), e.to));
+                        const to = ['.ts', '.tsx', '.js', '/index.ts'].map((x) => base + x).find((c) => known.has(c))
+                            ?? (known.has(base) ? base : null);
+                        if (to === null || to === f.sourcePath)
+                            continue;
+                        edges.push({ from: f.sourcePath, to, kind: (0, cycle_detect_1.classifyEdgeByTarget)(text, f.sourcePath, to) });
+                        judged.add(ext);
+                    }
+                    // A file whose imports are all bare specifiers is not evidence that its LANGUAGE is
+                    // unresolvable — subtract the judged set at the end instead of marking per file, or one
+                    // such file makes the whole language read as unjudged (measured: `.ts` and `.js` landed in
+                    // both lists).
+                    if (sawImport)
+                        sawImports.add(ext);
+                }
+                cycles = {
+                    current: (0, cycle_detect_1.detectCycles)(edges).cycles,
+                    allowed: [],
+                    mode: 'track',
+                    // Unjudged = saw imports, resolved none, anywhere. Naming these is the difference between
+                    // "no cycles" and "no cycles in the languages we could follow".
+                    scope: {
+                        judged: [...judged].sort(),
+                        unavailable: [...sawImports].filter((e) => !judged.has(e)).sort(),
+                    },
+                };
+            }
+            catch {
+                cycles = undefined;
+            }
             // Provenance-chain verification (fail-open: a verify error skips the check, never crashes).
             let provenance;
             // @implements A-SPEC-148

package/dist/holmes/mcp/defuse-bound.d.ts

@@ -0,0 +1 @@
+export declare const DEFUSE_TOP_FILES = 10;

package/dist/holmes/mcp/defuse-bound.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFUSE_TOP_FILES = void 0;
+// @implements A-SPEC-573.4
+// One constant, imported by both consumers, so the product path and the benchmark cannot drift on
+// how much data flow they read. Ten is the emission tier a caller acts on; whole-repository
+// extraction was measured at +88.8% (2572ms -> 4857ms, 2026-09-08) and ten files at roughly 95ms.
+exports.DEFUSE_TOP_FILES = 10;

package/dist/holmes/mcp/handlers.d.ts

@@ -223,6 +223,11 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         graphPreview?: {
             impact?: import("../rtm/impact-advisory").ImpactAdvisory;
             density?: import("../rtm/anchor-density").AnchorDensityFinding[];
+            cycles?: {
+                findings: import("../cpg/cycle-detect").CycleFinding[];
+                note: string;
+            };
+            architecture?: import("../cpg/arch-observe").ArchObservation[];
             graphAsOf?: string;
         } | undefined;
         id: string;