@holmes-lab/holmes-kit 0.18.0 → 0.19.2

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

@@ -0,0 +1,146 @@
+"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.CYCLE_LIST_CAP = void 0;
+exports.buildCycleObservation = buildCycleObservation;
+exports.appendCycleObservation = appendCycleObservation;
+exports.readCycleObservations = readCycleObservations;
+// @implements A-SPEC-578.1
+// The observation ledger the cycle ratchet's promotion criterion was already waiting on.
+//
+// `stop.ts` says promotion to `strict` "waits on the observation ledger answering the false-positive
+// rate, which is the same path impactAdvisory and anchorDensity took". Measured 2026-09-09: those two
+// siblings had been appending to `<name>.<replica>.jsonl` all along, and this one wrote a single line
+// to stderr and nothing to disk — 0 records against their 12 and 7. A criterion waiting on data
+// nobody collects never fires. This is the missing half, and it is deliberately the SIBLINGS' shape
+// rather than a better one: a second convention for the same job is the next drift point.
+//
+// `cycle-detect.ts` stays pure (zero imports) — the same split `rtm/anchor-density.ts` uses against
+// the rule it observes.
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const replica_id_1 = require("../governance/replica-id");
+const cycle_detect_1 = require("./cycle-detect");
+/**
+ * How many cycles one record lists before it starts counting instead.
+ *
+ * A record must not grow with the tree: a repository with a thousand cycles would otherwise write a
+ * thousand-entry line every turn, and the ledger this exists to make readable would be the thing
+ * that makes it unreadable. What is dropped is COUNTED, never silently cut.
+ */
+exports.CYCLE_LIST_CAP = 50;
+/**
+ * Build the record. PURE — the clock is an argument, so a test can pin it and two callers cannot
+ * disagree about what "now" was.
+ *
+ * A CLEAN run produces a record too. That is the whole design: a false-positive RATE is violations
+ * over chances, and a ledger that only speaks when something is wrong records the numerator and
+ * throws the denominator away.
+ */
+function buildCycleObservation(ev, ts) {
+    const listed = ev.current.slice(0, exports.CYCLE_LIST_CAP);
+    // The ratchet's own predicate decides what counts as a violation — reimplementing the filter here
+    // would be a second rule for one question, which is how the two quietly disagree.
+    const violations = (0, cycle_detect_1.cycleRatchetViolations)(listed, ev.allowed).map((v) => v.key);
+    return {
+        ts,
+        mode: ev.mode,
+        cycles: listed.map((c) => ({ key: (0, cycle_detect_1.cycleKey)(c.files), files: [...c.files].sort(), runtime: c.runtime, edges: c.edges.length })),
+        cyclesOmitted: Math.max(0, ev.current.length - listed.length),
+        violations,
+        allowed: ev.allowed.length,
+        scope: { judged: [...ev.scope.judged], unavailable: [...ev.scope.unavailable] },
+    };
+}
+const OBSERVATION_FILE_RE = /^cycle-observations\.([^.]+)\.jsonl$/;
+/**
+ * Append one record. Never throws, and never creates `.ax` where governance was not opted into
+ * (A-SPEC-191 §25 — the same refusal the approval queue makes).
+ *
+ * A failure returns `false` and changes nothing else: this is an OBSERVATION, and an observation
+ * that could alter a verdict would be a gate wearing a different name.
+ */
+function appendCycleObservation(root, rec) {
+    try {
+        if (!fs.existsSync(path.join(root, '.ax')))
+            return false;
+        let replica = 'local';
+        try {
+            replica = (0, replica_id_1.resolveReplicaId)(root) || 'local';
+        }
+        catch { /* keep the fallback */ }
+        const file = path.join(root, '.ax', 'ledger', `cycle-observations.${replica}.jsonl`);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.appendFileSync(file, `${JSON.stringify({ ...rec, replica })}\n`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Every replica's records, merged. A corrupt line is skipped, never fatal. */
+function readCycleObservations(root) {
+    const dir = path.join(root, '.ax', 'ledger');
+    let names;
+    try {
+        names = fs.readdirSync(dir).filter((n) => OBSERVATION_FILE_RE.test(n)).sort();
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        let text;
+        try {
+            text = fs.readFileSync(path.join(dir, name), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split('\n')) {
+            const s = line.trim();
+            if (!s)
+                continue;
+            try {
+                const r = JSON.parse(s);
+                if (r && typeof r === 'object' && typeof r.ts === 'string' && Array.isArray(r.cycles) && Array.isArray(r.violations)) {
+                    out.push(r);
+                }
+            }
+            catch { /* a corrupt line never breaks the read */ }
+        }
+    }
+    return out;
+}

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/approval-queue.d.ts

@@ -109,8 +109,9 @@ export declare function approvalRequestId(kind: string, target: string): string;
  * waiting.
  */
 export declare function foldQueue(lines: string[], opts?: {
-    now: number;
-    ttlMs: number;
+    now?: number;
+    ttlMs?: number;
+    includeAllKinds?: boolean;
 }): QueueState;
 /**
  * Append a request event. Fire-and-forget.
@@ -126,10 +127,28 @@ export declare function enqueueApprovalRequest(root: string, req: {
     why: string;
     reasonBytes?: number;
 }): boolean;
+/**
+ * The same act, told in full: what happened and why.
+ *
+ * @implements A-SPEC-576.1
+ * Nine modules read this one, and all of them want the boolean — so the boolean stays and this is
+ * the shape underneath it, rather than a breaking change rippling through nine call sites for the
+ * benefit of the one caller that wants to distinguish a duplicate from a refusal.
+ */
+export declare function enqueueApprovalRequestDetailed(root: string, req: {
+    kind: string;
+    target: string;
+    why: string;
+    reasonBytes?: number;
+}): {
+    written: boolean;
+    reason: 'written' | 'duplicate' | 'no-project' | 'unwritable';
+};
 /** Read and fold the queue on disk. A missing file is an empty queue, not an error. */
 export declare function readQueue(root: string, opts?: {
-    now: number;
-    ttlMs: number;
+    now?: number;
+    ttlMs?: number;
+    includeAllKinds?: boolean;
 }): QueueState;
 /**
  * The refusal-message suffix pointing the operator at the review CLI.

package/dist/holmes/governance/approval-queue.js

@@ -40,6 +40,7 @@ exports.readRefusals = readRefusals;
 exports.approvalRequestId = approvalRequestId;
 exports.foldQueue = foldQueue;
 exports.enqueueApprovalRequest = enqueueApprovalRequest;
+exports.enqueueApprovalRequestDetailed = enqueueApprovalRequestDetailed;
 exports.readQueue = readQueue;
 exports.queueHint = queueHint;
 // @implements A-SPEC-244
@@ -169,6 +170,16 @@ function foldQueue(lines, opts) {
                     malformedLines++;
                     break;
                 }
+                // @implements A-SPEC-576.1 — the READER applies the writer's predicate.
+                // REQ-563 routed gate refusals away from the inbox and deliberately did NOT rewrite the
+                // 2,192 lines already written; append-only is the rule this ledger is worth something for.
+                // The two decisions together left the inbox permanently 99.93% noise (measured here:
+                // 1,418 `shell` entries around a single real decision) because only the writer changed.
+                // The same constant does both jobs, so there is no second list to drift.
+                // `decisions` and `holds` are built from the OTHER events and stay complete — the hold
+                // question and the denial reason a refused `shell` request needs still reach `queueHint`.
+                if (!opts?.includeAllKinds && !exports.DECISION_KINDS.has(String(e.kind ?? '')))
+                    break;
                 const prev = pending.get(id);
                 const ts = typeof e.ts === 'string' ? e.ts : '';
                 if (prev) {
@@ -223,7 +234,9 @@ function foldQueue(lines, opts) {
         }
     }
     const all = [...pending.values()];
-    if (!opts)
+    const ttl = typeof opts?.ttlMs === 'number' && typeof opts?.now === 'number'
+        ? { ttlMs: opts.ttlMs, now: opts.now } : null;
+    if (ttl === null)
         return { pending: all, expired: [], malformedLines, decisions, holds };
     // @implements A-SPEC-507.1 — strict excess only, and an unparseable lastTs stays ACTIVE: a
     // clockless entry must never be silently hidden by a clock it does not carry.
@@ -231,7 +244,7 @@ function foldQueue(lines, opts) {
     const active = [];
     for (const p of all) {
         const last = Date.parse(p.lastTs);
-        (Number.isFinite(last) && last + opts.ttlMs < opts.now ? expired : active).push(p);
+        (Number.isFinite(last) && last + ttl.ttlMs < ttl.now ? expired : active).push(p);
     }
     return { pending: active, expired, malformedLines, decisions, holds };
 }
@@ -244,6 +257,18 @@ function foldQueue(lines, opts) {
  * caller uses the boolean only to decide whether to print the review hint.
  */
 function enqueueApprovalRequest(root, req) {
+    return enqueueApprovalRequestDetailed(root, req).written;
+}
+/**
+ * The same act, told in full: what happened and why.
+ *
+ * @implements A-SPEC-576.1
+ * Nine modules read this one, and all of them want the boolean — so the boolean stays and this is
+ * the shape underneath it, rather than a breaking change rippling through nine call sites for the
+ * benefit of the one caller that wants to distinguish a duplicate from a refusal.
+ */
+function enqueueApprovalRequestDetailed(root, req) {
+    let reason = 'unwritable';
     try {
         // @implements A-SPEC-244
         // Only under an EXISTING .ax. The constitution suite (§25a) caught the first cut creating
@@ -251,7 +276,7 @@ function enqueueApprovalRequest(root, req) {
         // marker where governance was never opted into, the exact defect A-SPEC-191 §25 exists to stop.
         // An ungoverned directory gets no queue and no hint; it is not part of the system.
         if (!fs.existsSync(path.join(root, '.ax')))
-            return false;
+            return { written: false, reason: 'no-project' };
         // @implements A-SPEC-563.1 — kind routing: only decision-seeking kinds enter the tracked inbox;
         // a gate refusal (shell, or any future kind — fail-safe toward a clean inbox) goes to this
         // machine's LOCAL refusal log, raw target and all, where the approve fallback can still find it.
@@ -301,12 +326,25 @@ function enqueueApprovalRequest(root, req) {
         // not a regular file, so a link — dangling or not — is refused. A path that truly does not exist
         // throws ENOENT and is created, which is the ordinary first-write case.
         if (!isPlainFile(file))
-            return false;
+            return { written: false, reason: 'unwritable' };
+        // @implements A-SPEC-576.1 — idempotency, on the INBOX only.
+        // Measured on this ledger: 2,203 `requested` lines carry 1,427 distinct ids, and 774 of the 776
+        // duplicates are one id — a `rm -rf /` test fixture re-filed 774 times across nine days. An
+        // outstanding question does not become more answerable by being asked again.
+        // The refusal log is deliberately left alone: it is a LOG, where each refusal is its own event
+        // and A-SPEC-564.2 counts them. Deduplicating a log erases the measurement it exists for.
+        // "Already asked" means still pending — a request re-filed AFTER a decision is a new question,
+        // and folding already drops decided ids from `pending`.
+        if (exports.DECISION_KINDS.has(req.kind)
+            && readQueue(root, { includeAllKinds: true }).pending.some((p) => p.id === event.id)) {
+            return { written: false, reason: 'duplicate' };
+        }
         fs.appendFileSync(file, JSON.stringify(event) + '\n');
-        return true;
+        reason = 'written';
+        return { written: true, reason };
     }
     catch {
-        return false;
+        return { written: false, reason };
     }
 }
 /**

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
@@ -160,6 +174,21 @@ export declare function rolledBackLedgers(root: string): string[] | undefined;
  * Returns the reason to block with, or null when there is nothing to report.
  */
 export declare function governanceLostPreflight(specsDir: string, projectRoot?: string): string | null;
+/**
+ * One line per ARTICLE, each under its own name.
+ *
+ * This used to be a single line reading `ART-8 RED-first (track)` for everything in `tracked` —
+ * and the cycle ratchet pushes ART-2 findings into that same array, so an import cycle was
+ * reported to the operator as a RED-first violation. Two observers sharing one sentence means the
+ * sentence is wrong for at least one of them.
+ *
+ * An article with no label still speaks, under its bare name: a new observer that says nothing is
+ * worse than one that says something plain.
+ */
+export declare function trackedLines(tracked?: {
+    article: string;
+    detail: string;
+}[]): string[];
 export declare function evaluateStop(specs: Spec[], evidence?: StopEvidence): {
     block: boolean;
     reason?: string;