@holmes-lab/holmes-kit 0.19.0 → 0.19.2

package/dist/holmes/cli/native-deps.d.ts

@@ -0,0 +1,65 @@
+import type { Coverage } from '../project/install-scripts-policy';
+/**
+ * @implements A-SPEC-580
+ * Why better-sqlite3 has no binary — judged from EVIDENCE, not from the load error's wording.
+ *
+ * Measured 2026-09-09 (Windows, npm 12.0.1, Node 24.19.0): doctor said "ABI-locked … reinstall"
+ * when the real cause was npm 12 skipping the install script for lack of an `allowScripts` entry.
+ * A reinstall reproduces the same state. At least five causes hide behind one FAIL and each has a
+ * different remedy, so this module collects what is observable and refuses to assert what is not:
+ * a prebuilt-download failure leaves no trace doctor can read, and is named as a possibility only.
+ *
+ * Pure. The caller (doctor) gathers the evidence; every process it spawns for that is optional,
+ * and "not observed" is carried as `undefined`, never as `false`.
+ */
+export type InstallKind = 'repo' | 'local' | 'global' | 'npx' | 'unknown';
+export type NativeCause = 'ok' | 'scripts-blocked' | 'abi-mismatch' | 'build-failed' | 'unknown';
+export type Level = 'PASS' | 'WARN' | 'FAIL';
+export interface NativeEvidence {
+    platform: string;
+    packageName: string;
+    packageVersion: string;
+    /** `build/Release/<name>.node` exists under the package. */
+    bindingPresent: boolean;
+    /** The first line of the `require` failure, when it failed. */
+    loadError?: string;
+    /** `npm --version` major; undefined when npm could not be consulted. */
+    npmMajor?: number;
+    /** How the ROOT package.json that governs this install covers the package (A-SPEC-579). */
+    coverage: Coverage;
+    installKind: InstallKind;
+    /** win32 only: whether a source build could even start. */
+    toolchain?: {
+        python: boolean;
+        msvc: boolean;
+    };
+    /** node-gyp is known to trip over spaces in the install path. */
+    pathHasSpace: boolean;
+    /** win32 only: `Get-ExecutionPolicy`, when observed. */
+    psPolicy?: string;
+}
+/** Where this package lives — the layout decides which package.json (if any) holds the policy. */
+export declare function installKind(packageRoot: string, globalDir?: string): InstallKind;
+/**
+ * The narrowest commands that repair each layout. `--allow-scripts=<pkg>` is a per-invocation flag
+ * scoped to ONE package — never `--dangerously-allow-all-scripts`, never a change to npm config.
+ *
+ * Global targets the DEPENDENCY, not the holmes-kit package: measured 2026-09-09 (npm 12.0.1,
+ * Windows), `npm rebuild -g @holmes-lab/holmes-kit` re-links the bin and dies EEXIST on the
+ * existing `holmes-kit` shim before any script runs, while `npm rebuild -g better-sqlite3
+ * --allow-scripts=better-sqlite3` runs `prebuild-install` in place. (It then needs the global
+ * prefix to be writable — a protected prefix fails EPERM there, which is the `global prefix`
+ * check's territory, not this one's.)
+ */
+export declare function recoveryCommands(ev: Pick<NativeEvidence, 'platform' | 'installKind' | 'packageName' | 'packageVersion'>): string[];
+/**
+ * What a PowerShell execution policy means for the emitted commands. Only the two policies that
+ * refuse every unsigned local script block the `npm.ps1`/`npx.ps1` shims; the rest add nothing.
+ */
+export declare function powershellPolicyNote(policy: string | undefined): string;
+export declare function nativeVerdict(ev: NativeEvidence): {
+    cause: NativeCause;
+    level: Level;
+    detail: string;
+    fix?: string;
+};

package/dist/holmes/cli/native-deps.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installKind = installKind;
+exports.recoveryCommands = recoveryCommands;
+exports.powershellPolicyNote = powershellPolicyNote;
+exports.nativeVerdict = nativeVerdict;
+// @implements A-SPEC-580
+// @implements A-SPEC-580.1
+const npx_bin_1 = require("../project/npx-bin");
+const install_scripts_policy_1 = require("../project/install-scripts-policy");
+const HOLMES_PKG = '@holmes-lab/holmes-kit';
+/** Where this package lives — the layout decides which package.json (if any) holds the policy. */
+function installKind(packageRoot, globalDir) {
+    const norm = packageRoot.replace(/\\/g, '/').replace(/\/+$/, '');
+    if (norm.split('/').includes('_npx'))
+        return 'npx';
+    if (globalDir) {
+        const g = globalDir.replace(/\\/g, '/').replace(/\/+$/, '');
+        if (norm.toLowerCase().startsWith(`${g.toLowerCase()}/`))
+            return 'global';
+    }
+    if (/\/node_modules\/@holmes-lab\/holmes-kit$/.test(norm))
+        return 'local';
+    return 'repo';
+}
+/**
+ * The narrowest commands that repair each layout. `--allow-scripts=<pkg>` is a per-invocation flag
+ * scoped to ONE package — never `--dangerously-allow-all-scripts`, never a change to npm config.
+ *
+ * Global targets the DEPENDENCY, not the holmes-kit package: measured 2026-09-09 (npm 12.0.1,
+ * Windows), `npm rebuild -g @holmes-lab/holmes-kit` re-links the bin and dies EEXIST on the
+ * existing `holmes-kit` shim before any script runs, while `npm rebuild -g better-sqlite3
+ * --allow-scripts=better-sqlite3` runs `prebuild-install` in place. (It then needs the global
+ * prefix to be writable — a protected prefix fails EPERM there, which is the `global prefix`
+ * check's territory, not this one's.)
+ */
+function recoveryCommands(ev) {
+    const npm = (0, npx_bin_1.npmBin)(ev.platform);
+    const project = [
+        (0, install_scripts_policy_1.approveCommand)(ev.packageName, ev.packageVersion, npm),
+        `${npm} rebuild ${ev.packageName} --foreground-scripts`,
+    ];
+    switch (ev.installKind) {
+        case 'global': return [`${npm} rebuild -g ${ev.packageName} --foreground-scripts --allow-scripts=${ev.packageName}`];
+        case 'npx': return [`${npm} install --save-dev ${HOLMES_PKG}`, ...project];
+        default: return project;
+    }
+}
+/** A rebuild alone (the script is approved or the policy is not the problem). */
+function rebuildCommand(ev) {
+    const npm = (0, npx_bin_1.npmBin)(ev.platform);
+    return ev.installKind === 'global'
+        ? `${npm} rebuild -g ${ev.packageName} --foreground-scripts --allow-scripts=${ev.packageName}`
+        : `${npm} rebuild ${ev.packageName} --foreground-scripts`;
+}
+/**
+ * What a PowerShell execution policy means for the emitted commands. Only the two policies that
+ * refuse every unsigned local script block the `npm.ps1`/`npx.ps1` shims; the rest add nothing.
+ */
+function powershellPolicyNote(policy) {
+    if (policy === 'Restricted' || policy === 'AllSigned') {
+        return `PowerShell execution policy ${policy} blocks the npm.ps1/npx.ps1 shims — use npm.cmd/npx.cmd (the commands above already do).`;
+    }
+    return '';
+}
+const ABI_RE = /NODE_MODULE_VERSION|compiled against a different Node\.js version/;
+function nativeVerdict(ev) {
+    const pkg = `${ev.packageName}@${ev.packageVersion}`;
+    const isWin = ev.platform === 'win32';
+    const psNote = isWin ? powershellPolicyNote(ev.psPolicy) : '';
+    const withPs = (detail) => (psNote ? `${detail} ${psNote}` : detail);
+    const approved = ev.coverage === 'approved-pinned' || ev.coverage === 'approved-unpinned';
+    const policyHome = ev.installKind === 'repo' || ev.installKind === 'local'
+        ? 'the project package.json (allowScripts)'
+        : `no package.json can carry the approval for a ${ev.installKind} install — approve per command instead`;
+    // 1. Loads → nothing to diagnose. The wording is read by other suites; keep it byte-identical.
+    if (ev.bindingPresent && !ev.loadError) {
+        return { cause: 'ok', level: 'PASS', detail: 'loads and executes against :memory:' };
+    }
+    // 2. The binary exists but was built for another Node ABI — the ONE case the old wording fit.
+    if (ev.loadError && ABI_RE.test(ev.loadError)) {
+        return {
+            cause: 'abi-mismatch', level: 'FAIL',
+            detail: withPs(`${pkg} was built for a different Node ABI (running ${process.version}): ${ev.loadError}`),
+            fix: `Rebuild against this Node: ${rebuildCommand(ev)}`,
+        };
+    }
+    if (!ev.bindingPresent && !approved) {
+        // 3. npm ≥ 12 skips the script without an approval. That the approval is missing IS observed;
+        //    an unobserved npm version does not change the remedy, so it is said and the same commands go out.
+        if (ev.npmMajor === undefined || ev.npmMajor >= 12) {
+            const npmSaid = ev.npmMajor === undefined ? 'npm (npm version not observed)' : `npm ${ev.npmMajor}`;
+            const denied = ev.coverage === 'denied' ? ` (allowScripts explicitly denied ${ev.packageName})` : '';
+            return {
+                cause: 'scripts-blocked', level: 'FAIL',
+                detail: withPs(`no binary — ${npmSaid} blocks dependency install scripts unless allowScripts covers ${pkg}${denied}; policy home: ${policyHome}.`),
+                fix: `Approve the one script that must run, then rebuild: ${recoveryCommands(ev).join(' && ')}`,
+            };
+        }
+        // 6b. Early npm 11 did not block scripts, so a missing approval proves nothing about why the
+        //     script left no binary — say so instead of inventing a cause.
+        return {
+            cause: 'unknown', level: 'FAIL',
+            detail: withPs(`no binary — npm ${ev.npmMajor} may or may not have run the install script; rerun with --foreground-scripts to see what happened.`),
+            fix: `${rebuildCommand(ev)} — then run doctor again.`,
+        };
+    }
+    // 4. Approved, yet no binary: the script ran and produced nothing. What it could not do is
+    //    partly observable (toolchain, path); a failed prebuild download is not.
+    if (!ev.bindingPresent) {
+        const missing = [];
+        if (ev.toolchain?.python === false)
+            missing.push('Python is not on PATH (node-gyp needs it)');
+        if (ev.toolchain?.msvc === false)
+            missing.push('Visual Studio C++ Build Tools (MSVC) were not found');
+        if (ev.pathHasSpace)
+            missing.push('the install path contains a space, which node-gyp is known to mishandle');
+        const because = missing.length ? ` Observed obstacles to a source build: ${missing.join('; ')}.` : '';
+        return {
+            cause: 'build-failed', level: 'FAIL',
+            detail: withPs(`the install script for ${pkg} is approved but produced no binary — a prebuilt download failure is not observable here.${because} Rerun with --foreground-scripts to see the script's own output.`),
+            fix: `${rebuildCommand(ev)} — install the missing toolchain (or use a Node version with a prebuilt binary) if the output shows a compile step.`,
+        };
+    }
+    // 6a. Present but failing to load for a reason we do not recognise — quote it, do not classify it.
+    return {
+        cause: 'unknown', level: 'FAIL',
+        detail: withPs(`${pkg} is present but failed to load: ${ev.loadError ?? '(no error text)'}`),
+        fix: `${rebuildCommand(ev)} — then run doctor again.`,
+    };
+}

package/dist/holmes/cpg/cycle-observation.d.ts

@@ -0,0 +1,65 @@
+import { type Cycle } from './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.
+ */
+export declare const CYCLE_LIST_CAP = 50;
+/**
+ * One turn's observation — paths, integers and enums only.
+ *
+ * ADR-012's redaction rule is what lets this file be git-tracked at all: no prose, no command
+ * strings, no file content. `files` are the scanner's project-relative paths, which the impact and
+ * density ledgers already carry.
+ */
+export interface CycleObservationRecord {
+    ts: string;
+    mode: 'strict' | 'track' | 'off';
+    cycles: Array<{
+        key: string;
+        files: string[];
+        runtime: boolean;
+        edges: number;
+    }>;
+    /** Cycles beyond CYCLE_LIST_CAP: counted, so a truncation is never mistaken for a clean tree. */
+    cyclesOmitted: number;
+    /** Keys of the runtime cycles nobody allowed — the ratchet's verdict at this moment. */
+    violations: string[];
+    allowed: number;
+    scope: {
+        judged: string[];
+        unavailable: string[];
+    };
+    replica?: string;
+}
+/** The cycle evidence the Stop hook computes, in the shape it already holds it. */
+export interface CycleEvidence {
+    current: Cycle[];
+    allowed: string[];
+    mode: 'strict' | 'track' | 'off';
+    scope: {
+        judged: string[];
+        unavailable: string[];
+    };
+}
+/**
+ * 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.
+ */
+export declare function buildCycleObservation(ev: CycleEvidence, ts: string): CycleObservationRecord;
+/**
+ * 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.
+ */
+export declare function appendCycleObservation(root: string, rec: CycleObservationRecord): boolean;
+/** Every replica's records, merged. A corrupt line is skipped, never fatal. */
+export declare function readCycleObservations(root: string): CycleObservationRecord[];

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/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/hooks/stop.d.ts

@@ -174,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;

package/dist/holmes/hooks/stop.js

@@ -42,6 +42,7 @@ exports.escalateReappraisals = escalateReappraisals;
 exports.unrecordedApprovals = unrecordedApprovals;
 exports.rolledBackLedgers = rolledBackLedgers;
 exports.governanceLostPreflight = governanceLostPreflight;
+exports.trackedLines = trackedLines;
 exports.evaluateStop = evaluateStop;
 exports.stopDebtAction = stopDebtAction;
 exports.acknowledgeStop = acknowledgeStop;
@@ -432,6 +433,36 @@ function governanceLostPreflight(specsDir, projectRoot) {
     const root = projectRoot ?? path.resolve(specsDir, '..', '..');
     return (0, governance_history_1.hasGovernanceHistory)(root) ? governance_history_1.GOVERNANCE_LOST_HINT : null;
 }
+// @implements A-SPEC-578.1
+/** What each article's track observations are called on the operator's screen. */
+const TRACK_LABELS = {
+    'ART-8': 'RED-first',
+    'ART-2': 'code-graph cycles',
+};
+/**
+ * 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.
+ */
+function trackedLines(tracked) {
+    if (!tracked || tracked.length === 0)
+        return [];
+    const byArticle = new Map();
+    for (const t of tracked) {
+        const key = String(t?.article ?? '');
+        byArticle.set(key, [...(byArticle.get(key) ?? []), String(t?.detail ?? '')]);
+    }
+    return [...byArticle.entries()].map(([article, details]) => {
+        const label = TRACK_LABELS[article];
+        return `[Holmes-Kit] ${article}${label ? ` ${label}` : ''} (track): ${details.join(' | ')}`;
+    });
+}
 function evaluateStop(specs, evidence) {
     // L1: the Stop gate IS the constitution's re-verification point — every turn boundary re-runs the
     // inviolable articles (ART-2 RTM, ART-3 validity incl. 4-quadrant GWT, ART-4 coverage evidence).
@@ -945,6 +976,18 @@ if (require.main === module) {
                         unavailable: [...sawImports].filter((e) => !judged.has(e)).sort(),
                     },
                 };
+                // @implements A-SPEC-578.1 — record the observation the promotion criterion waits on.
+                // EVERY run, including a clean one: a false-positive rate is violations over chances, and a
+                // ledger that only speaks when something is wrong keeps the numerator and drops the
+                // denominator. Append failure is swallowed by the outer catch below — an observation that
+                // could change a verdict would be a gate wearing another name.
+                // Its OWN try: sharing the outer one would let a fault in the observation discard the
+                // article's evidence, which is the coupling this comment exists to deny.
+                try {
+                    const { appendCycleObservation, buildCycleObservation } = require('../cpg/cycle-observation');
+                    appendCycleObservation(root, buildCycleObservation(cycles, new Date().toISOString()));
+                }
+                catch { /* an observation never touches the verdict */ }
             }
             catch {
                 cycles = undefined;
@@ -1046,9 +1089,9 @@ if (require.main === module) {
                 }
             }
             catch { /* the reappraisal signal is advisory; a failure never affects the stop verdict */ }
-            if (out.tracked && out.tracked.length > 0) {
-                process.stderr.write(`[Holmes-Kit] ART-8 RED-first (track): ${out.tracked.map((t) => t.detail).join(' | ')}\n`);
-            }
+            // @implements A-SPEC-578.1 — one line per article, each under its own name.
+            for (const line of trackedLines(out.tracked))
+                process.stderr.write(`${line}\n`);
             // @implements A-SPEC-247 — before deciding to re-block, ask whether every unresolved debt is
             // already queued for the owner. If so, tell the user ONCE and let the turn finish; a single
             // non-waiting violation and we block exactly as before.