@holmes-lab/holmes-kit 0.19.0 → 0.19.3

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.

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

@@ -490,6 +490,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
             survivors: import("../spec/kills").Mutation[];
         };
     } | {
+        calibrationClosed?: string[] | undefined;
         baselineRecorded?: string | undefined;
         scopeFallback?: "full" | undefined;
         tier: import("../rtm/test-scope").RegressionTier;
@@ -518,6 +519,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         changedFiles?: string[];
     }): Promise<MaintenanceAnalysis & {
         persistedTo?: string;
+        bounded?: boolean;
     }>;
     maintenance_outcome(a: {
         root: string;

package/dist/holmes/mcp/handlers.js

@@ -2367,6 +2367,9 @@ function makeRawHandlers(store, opts) {
             // Record ONLY an actually-executed, GREEN run (review C4/C7): a red suite must not stand as
             // coverage evidence at the moment the code is broken, and a no-op run must not overwrite a real
             // record with a dishonest `passed: true` over an empty result.
+            // @implements A-SPEC-578.4 — read BEFORE the write below replaces it: the calibration window
+            // is "since the previous evidence run", and this line is the only moment that value exists.
+            const previousEvidenceTs = (0, test_evidence_1.readTestEvidence)(root)?.ts;
             const verified = (0, baseline_1.shouldRecordBaseline)(result);
             if (verified) {
                 (0, test_evidence_1.writeTestEvidence)(root, { ts: new Date().toISOString(), head, tier: testScope.tier, passed: true, executedByAspec });
@@ -2382,6 +2385,19 @@ function makeRawHandlers(store, opts) {
             // actually executed and passed. A red or skipped run must never become the reference point for
             // "since the last verified state" — that would silently narrow every later scope against a
             // state nobody verified.
+            // @implements A-SPEC-578.4 — close the calibration loop on real work.
+            // The window is the PREVIOUS evidence run's timestamp, read before this run overwrote it —
+            // an analysis older than that belonged to a previous slice, and attributing today's changes
+            // to it would be contamination rather than measurement. Its own try: an observation that
+            // could change `passed` would be a gate wearing another name.
+            let calibrationClosed;
+            try {
+                const closed = (0, maintenance_evidence_1.closeOpenArtifacts)(path.join(root, maintenance_evidence_1.EVIDENCE_DIR), { files: changedFiles }, new Date().toISOString(), previousEvidenceTs).closed;
+                if (closed.length > 0)
+                    calibrationClosed = closed;
+            }
+            catch { /* the loop is observation; it never touches the verdict */ }
+            // @implements A-SPEC-128
             let baseline;
             if (verified) {
                 baseline = a.mark ?? DEFAULT_BASELINE;
@@ -2393,7 +2409,8 @@ function makeRawHandlers(store, opts) {
                 ranFiles: result.ranFiles, executedByAspec, tail: result.tail,
                 // @implements A-SPEC-130 — the remediation rides in the answer: these are the files to anchor.
                 unresolvedFiles: testScope.unresolvedFiles,
-                changeSource, ...(scopeFallback ? { scopeFallback } : {}), ...(baseline ? { baselineRecorded: baseline } : {}) };
+                changeSource, ...(scopeFallback ? { scopeFallback } : {}), ...(baseline ? { baselineRecorded: baseline } : {}),
+                ...(calibrationClosed ? { calibrationClosed } : {}) };
         },
         async issue_localize(a) {
             assertSpecStoreReachable('issue_localize', store, a.root); // @implements A-SPEC-419
@@ -2643,9 +2660,19 @@ function makeRawHandlers(store, opts) {
                         if (digest)
                             fileDigests[file] = digest;
                     }
+                    // The artifact takes the WHOLE analysis, never the bounded one below: a file has no
+                    // context window, and the calibration that scores this prediction must score what the
+                    // product actually predicted.
                     result.persistedTo = (0, maintenance_evidence_1.writeArtifact)(path.join(root, maintenance_evidence_1.EVIDENCE_DIR), (0, maintenance_evidence_1.artifactFrom)(analysis, new Date().toISOString(), fileDigests));
                 }
-                return result;
+                // @implements A-SPEC-578.5 — the response, and only the response, is bounded. Measured
+                // 2026-09-09: the full shape is 187,174 characters (~47k tokens) and the harness refuses
+                // it, which is why AGENTS.md step 3 had never once been obeyed with `persist: true`.
+                // `persistedTo` rides along so the caller knows where the whole thing is.
+                const bounded = (0, maintenance_analyze_1.boundAnalysis)(result);
+                if (JSON.stringify(bounded).length !== JSON.stringify(result).length)
+                    bounded.bounded = true;
+                return bounded;
             }
             finally {
                 graph.close();

package/dist/holmes/mcp/maintenance-analyze.d.ts

@@ -444,3 +444,40 @@ export declare function unquoteGitPath(line: string): string;
  * reproduce and compare an analysis from the exact same captured inputs.
  */
 export declare function analyzeMaintenance(input: MaintenanceAnalysisInput): MaintenanceAnalysis;
+/**
+ * Items a response lists before it starts counting instead.
+ *
+ * TEN, because that is the unit this product is measured in: localization emits Top-10 and every
+ * recall figure in this repository is recall@10. Aligning the response cap with the emission unit
+ * is a reason; picking a number that happens to hit a size target is a knob. Measured on the real
+ * 187,174-character response: cap 20 gave 34,811 with `intent` alone at 11,037 (32%), cap 10 fits.
+ */
+export declare const ANALYZE_LIST_CAP = 10;
+/** Characters one listed item keeps. */
+export declare const ANALYZE_TEXT_CAP = 400;
+/**
+ * @implements A-SPEC-578.5
+ * The RESPONSE-EDGE projection. The artifact on disk keeps everything.
+ *
+ * Measured 2026-09-09: one `maintenance_analyze` call returns 187,174 characters (~47k tokens) and
+ * the harness refuses it outright. AGENTS.md step 3 instructs every agent to make that call before
+ * editing source — and across 2,779 spec approvals `persist:true` had never been used once. An
+ * instruction nobody can afford to follow is not an instruction.
+ *
+ * The cap is applied RECURSIVELY, which the first cut got wrong. Capping only the top level took
+ * the response from 187,174 to 142,701 and no further, because the weight is in NESTED DUPLICATES:
+ * `impacts.test` and `testScope.impactedTestFiles` carry the same 158 paths, and `impacts.contract`
+ * and `testScope.impactedSpecs` the same 160 spec ids. A cap that stops at depth one caps the
+ * cheapest arrays in the document.
+ *
+ * NEVER CALLED FROM `analyzeMaintenance`. The design-time advisory named the replay benchmark
+ * (`run-replay.ts`, `replay-corpus.ts`, `commit-text.ts`, `temporal-prior.ts`) as readers of this
+ * type, and among their anchors sits A-SPEC-402 — "the numbers reported are not what the product
+ * does". Bounding inside the analysis would make every pinned benchmark score a truncated
+ * pipeline, which is the most expensive instrument failure this repository has recorded. The
+ * benchmark keeps seeing exactly what it sees today; only the conversation gets the short form.
+ *
+ * What is dropped is COUNTED, at whatever depth it was dropped. A response that quietly shrank
+ * would be a worse lie than a long one.
+ */
+export declare function boundAnalysis(a: MaintenanceAnalysis): MaintenanceAnalysis;

package/dist/holmes/mcp/maintenance-analyze.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PRIMARY_TIER_WIDTH = exports.EVIDENCE_DIMENSIONS = exports.MAINTENANCE_ANALYSIS_EXTRACTOR = exports.MAINTENANCE_ANALYSIS_SCHEMA = void 0;
+exports.ANALYZE_TEXT_CAP = exports.ANALYZE_LIST_CAP = exports.PRIMARY_TIER_WIDTH = exports.EVIDENCE_DIMENSIONS = exports.MAINTENANCE_ANALYSIS_EXTRACTOR = exports.MAINTENANCE_ANALYSIS_SCHEMA = void 0;
 exports.unquoteGitPath = unquoteGitPath;
 exports.analyzeMaintenance = analyzeMaintenance;
+exports.boundAnalysis = boundAnalysis;
 // @implements A-SPEC-295
 // @implements A-SPEC-294
 // @implements A-SPEC-293
@@ -1048,3 +1049,74 @@ function buildAblation(a) {
     ], truth, a.primaryTier, a.impactedTier, a.importedByTier);
     return { graphOff, current, enhanced };
 }
+// @implements A-SPEC-578.5
+/**
+ * Items a response lists before it starts counting instead.
+ *
+ * TEN, because that is the unit this product is measured in: localization emits Top-10 and every
+ * recall figure in this repository is recall@10. Aligning the response cap with the emission unit
+ * is a reason; picking a number that happens to hit a size target is a knob. Measured on the real
+ * 187,174-character response: cap 20 gave 34,811 with `intent` alone at 11,037 (32%), cap 10 fits.
+ */
+exports.ANALYZE_LIST_CAP = 10;
+/** Characters one listed item keeps. */
+exports.ANALYZE_TEXT_CAP = 400;
+/** Dropped whole: another tool answers this question, and it is 41,619 characters of the answer. */
+const DROPPED_FIELDS = ['contextBundle'];
+/**
+ * @implements A-SPEC-578.5
+ * The RESPONSE-EDGE projection. The artifact on disk keeps everything.
+ *
+ * Measured 2026-09-09: one `maintenance_analyze` call returns 187,174 characters (~47k tokens) and
+ * the harness refuses it outright. AGENTS.md step 3 instructs every agent to make that call before
+ * editing source — and across 2,779 spec approvals `persist:true` had never been used once. An
+ * instruction nobody can afford to follow is not an instruction.
+ *
+ * The cap is applied RECURSIVELY, which the first cut got wrong. Capping only the top level took
+ * the response from 187,174 to 142,701 and no further, because the weight is in NESTED DUPLICATES:
+ * `impacts.test` and `testScope.impactedTestFiles` carry the same 158 paths, and `impacts.contract`
+ * and `testScope.impactedSpecs` the same 160 spec ids. A cap that stops at depth one caps the
+ * cheapest arrays in the document.
+ *
+ * NEVER CALLED FROM `analyzeMaintenance`. The design-time advisory named the replay benchmark
+ * (`run-replay.ts`, `replay-corpus.ts`, `commit-text.ts`, `temporal-prior.ts`) as readers of this
+ * type, and among their anchors sits A-SPEC-402 — "the numbers reported are not what the product
+ * does". Bounding inside the analysis would make every pinned benchmark score a truncated
+ * pipeline, which is the most expensive instrument failure this repository has recorded. The
+ * benchmark keeps seeing exactly what it sees today; only the conversation gets the short form.
+ *
+ * What is dropped is COUNTED, at whatever depth it was dropped. A response that quietly shrank
+ * would be a worse lie than a long one.
+ */
+function boundAnalysis(a) {
+    const src = a;
+    const out = boundValue(src, 0);
+    for (const field of DROPPED_FIELDS)
+        delete out[field];
+    return out;
+}
+/** Depth bound: deep enough for the shapes measured, shallow enough to terminate on any input. */
+const BOUND_MAX_DEPTH = 6;
+function boundValue(value, depth) {
+    if (depth > BOUND_MAX_DEPTH || value === null || typeof value !== 'object')
+        return trimItem(value);
+    if (Array.isArray(value)) {
+        return value.slice(0, exports.ANALYZE_LIST_CAP).map((v) => boundValue(v, depth + 1));
+    }
+    const src = value;
+    const out = {};
+    for (const [k, v] of Object.entries(src)) {
+        out[k] = boundValue(v, depth + 1);
+        // The counter sits BESIDE the array it describes, at the depth it was cut, so a nested trim is
+        // as visible as a top-level one.
+        if (Array.isArray(v) && v.length > exports.ANALYZE_LIST_CAP)
+            out[`${k}Omitted`] = v.length - exports.ANALYZE_LIST_CAP;
+    }
+    return out;
+}
+/** Trim one listed item. A long item is CUT, never discarded — the item's existence is information. */
+function trimItem(item) {
+    if (typeof item !== 'string' || item.length <= exports.ANALYZE_TEXT_CAP)
+        return item;
+    return `${item.slice(0, exports.ANALYZE_TEXT_CAP)}… [+${item.length - exports.ANALYZE_TEXT_CAP}]`;
+}

package/dist/holmes/mcp/maintenance-evidence.d.ts

@@ -100,8 +100,49 @@ export interface OutcomeInput {
 /**
  * Attach what actually happened to a prediction that was actually made. An unknown digest is
  * refused: inventing the prediction alongside the outcome would let the record score itself.
+ *
+ * @implements A-SPEC-578.6
+ * MERGES into any outcome already there. It used to REPLACE, and the defect was found by following
+ * this repository's own instruction: A-SPEC-578.4 made `test_run` attach the 12 files a slice
+ * actually changed, AGENTS.md then said "call maintenance_outcome yourself only to add a judged
+ * classification" — and that call left `actualFiles: []`. The documented workflow destroyed the
+ * data it existed to complete.
+ *
+ * Omission and erasure are DIFFERENT ACTS: a field left out keeps its value, a field given as an
+ * empty array is cleared. Without the second, a wrong record could never be corrected; without the
+ * first, completing a record destroys it.
  */
 export declare function recordOutcome(dir: string, digest: string, outcome: OutcomeInput, recordedAt: string): EvidenceArtifact;
+/**
+ * Predictions still waiting to be scored — the loop's missing second half.
+ *
+ * `since` bounds the window: an analysis recorded before the previous evidence run belonged to a
+ * previous slice, and attributing today's changes to it would be contamination rather than
+ * measurement. The boundary is EXCLUSIVE (`> since`) because the previous run already saw that
+ * instant.
+ */
+export declare function openArtifacts(dir: string, since?: string): EvidenceArtifact[];
+/**
+ * @implements A-SPEC-578.4
+ * Attach what a slice ACTUALLY touched to the predictions it made.
+ *
+ * Measured 2026-09-09: `maintenance_calibration` had reported `n:0, artifacts:0` since the loop was
+ * built, because `maintenance_analyze({persist:true})` is instructed (AGENTS.md step 3) while
+ * `maintenance_outcome` is instructed nowhere at all. The write path was healthy the whole time —
+ * one call produced an artifact immediately. What was missing was the call.
+ *
+ * TWO REFUSALS make this a measurement rather than a self-graded exam:
+ *  - `actualClassification` is never filled in. That is a judgement, and a loop that supplies its
+ *    own judgement scores itself; the bins stay `insufficient-data` and only the objective half —
+ *    file-level false positives and negatives — accrues.
+ *  - An empty change set closes nothing. Attributing "nothing changed" would turn every prediction
+ *    into a false positive: a measurement of nothing, recorded as a failure of everything.
+ */
+export declare function closeOpenArtifacts(dir: string, actual: {
+    files: string[];
+}, recordedAt: string, since?: string): {
+    closed: string[];
+};
 export interface CalibrationBin {
     lower: number;
     upper: number;