@holmes-lab/holmes-kit 0.1.7 → 0.1.8

package/dist/holmes/guardrail/risk-types.d.ts

@@ -0,0 +1,48 @@
+export type RiskLevel = 'auto' | 'notify' | 'confirm' | 'hard-hitl';
+export declare const RISK_ORDER: RiskLevel[];
+export type RiskAxis = 'reversibility' | 'architecture' | 'secret' | 'blast-radius';
+export interface AxisVerdict {
+    axis: RiskAxis;
+    level: RiskLevel;
+    reasons: string[];
+}
+export interface RmSignal {
+    gitIgnored?: boolean;
+    tracked?: boolean;
+    inProject?: boolean;
+}
+export interface RiskAction {
+    kind: string;
+    target: string;
+    command?: string;
+    tracked?: boolean;
+    isDirectory?: boolean;
+    adrSupersedes?: string[];
+    cspecConstraintChange?: boolean;
+    stagedContent?: string;
+    blastRadius?: {
+        impactedSpecCount: number;
+        hitsFoundational: boolean;
+    };
+    rmTargetSignals?: Record<string, RmSignal>;
+    /**
+     * Absolute path of the project this command runs against, supplied by the hook (the classifier
+     * itself stays pure and does no I/O).
+     *
+     * Used to scope the protected-`.ax` rules to THIS project's governance directory. Without it the
+     * substring match gated `.ax` paths belonging to any other repository on the machine — real
+     * friction for anyone working across projects. Absent means unknown scope, which stays
+     * conservative: every `.ax` path is treated as protected.
+     */
+    projectRoot?: string;
+}
+export interface RiskThresholds {
+    blastRadiusConfirm?: number;
+    blastRadiusHardHitl?: number;
+}
+export interface RiskAssessment {
+    level: RiskLevel;
+    verdicts: AxisVerdict[];
+    reasons: string[];
+}
+export declare function maxLevel(a: RiskLevel, b: RiskLevel): RiskLevel;

package/dist/holmes/guardrail/tspec-state.d.ts

@@ -0,0 +1,71 @@
+import { Spec } from '../spec/spec-parser';
+/**
+ * The T-SPEC situation for one A-SPEC, kept as a state rather than the boolean the gate used to
+ * compute.
+ *
+ * The defect this exists for, measured 2026-08-13: four different situations produced the identical
+ * sentence `A-SPEC A-SPEC-129의 approved T-SPEC이 없습니다(테스트 먼저).` while needing different
+ * actions. The harness already knew — `promote-slice`'s 「침묵의 실패 모드」 section said outright
+ * that the refusal offered no way to tell them apart. A document was compensating for what the gate
+ * could have said.
+ *
+ * THE PARTITION LOOKS ONLY AT THE TARGET. An earlier draft split on whether the PROJECT had any
+ * T-SPEC at all, which made "none written yet" unreachable in any repo past its first slice —
+ * measured: 0 of this repository's 73 A-SPECs could reach it, and a new A-SPEC was instead handed
+ * three unrelated documents with "add depends_on to one of them". That was worse than the sentence
+ * it replaced, which at least said 테스트 먼저.
+ *
+ * So there are two deny states. "Not written yet" and "written but the edge is missing" are NOT
+ * distinguishable by the gate — only the author knows which — so they are one state whose message
+ * offers both moves. Guessing between them (e.g. from the `T-SPEC-<number>` naming convention,
+ * which measures 71/73 here) would be the gate judging rather than reporting.
+ */
+export type TspecState = {
+    kind: 'approved';
+    spec: Spec;
+} | {
+    kind: 'linked-not-approved';
+    specs: Spec[];
+} | {
+    kind: 'unlinked';
+    orphans: Spec[];
+};
+/**
+ * Classify the T-SPEC situation for `aspecId`. Array lookups only — the gate calls this from a
+ * PreToolUse hook on every tool call, so it never touches the filesystem.
+ */
+export declare function tspecStateFor(aspecId: string, specs: Spec[]): TspecState;
+export declare const ID_BUDGET = 200;
+export declare const REASON_BUDGET = 1200;
+export declare const ID_MAX = 80;
+/**
+ * `a, b 외 N개` — or, when nothing fits, `N개` (rule 2). The count always agrees with what is shown.
+ */
+export declare const listOrCount: (items: string[], budget: number, unit: string, cap?: number) => string;
+/**
+ * What the author should read, and what they should do, for a state that denies.
+ *
+ * `null` for `approved` — there is nothing to say when nothing is wrong.
+ */
+export declare function tspecRemediation(rawAspecId: string, state: TspecState, why: (spec: Spec) => string[]): {
+    message: string;
+    next_action: string;
+} | null;
+/**
+ * @implements A-SPEC-192 §10R (round 10, 4th)
+ * ONE spec's clause, budgeted — the shared discipline both refusal surfaces now use.
+ *
+ * The twin in `phase.ts` compared the whole joined summary (framing + id + every blocker) against
+ * REASON_BUDGET and dropped it ALL when it did not fit. Two harms followed, both measured. A 93-char
+ * parent blocker — the one action the author could take right now — vanished because a sibling
+ * blocker happened to be 1,154 characters. And because the id sits inside what was being measured,
+ * the effective budget slid with the id's LENGTH: growing an id by one character past ID_MAX made
+ * the §7R scrub fold it, freed 63 characters, and turned a 236-char refusal that named nothing into
+ * a 1,209-char refusal that named everything. Worse input, better answer, decided by something the
+ * author cannot control.
+ *
+ * Here the framing is priced first and every judgement about a blocker is made against what remains
+ * for bodies; blockers are dropped one at a time and counted, and the label distinguishes "no reason
+ * fits at all" from "the budget was spent elsewhere" — the same words the sibling uses.
+ */
+export declare function budgetedClause(labelId: string, fallbackLabel: string, blockers: string[], spentElsewhere?: boolean): string;

package/dist/holmes/guardrail/write-target.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Tools known to only READ. Everything else that carries a path is treated as a write.
+ *
+ * The list is inverted on purpose. The gate used to ask `['Write','Edit'].includes(name)`, and
+ * measured 2026-08-08 that meant `MultiEdit`, `NotebookEdit`, and a lower-case `write` reached the
+ * same protected files `Write` was denied — No-Spec-No-Code, the role gate, the ledger ban and the
+ * approval-config ban all bypassed by a different name. Adding those three names would postpone the
+ * problem to the fourth tool; inverting it means an unrecognised tool fails CLOSED.
+ */
+export declare const READ_ONLY_TOOLS: readonly ["read", "grep", "glob", "ls", "notebookread", "webfetch", "websearch", "todowrite", "task", "bashoutput", "killshell"];
+/**
+ * Payload keys that name a file. Shared with normalization so the two cannot drift: a field the
+ * gate does not know about is a path the gate cannot see, which is how `notebook_path` slipped
+ * through.
+ */
+export declare const PATH_FIELDS: readonly ["file_path", "notebook_path"];
+/**
+ * Whether this tool call writes a file.
+ *
+ * A missing or non-string name counts as a write. `normalizeHookInput` turns both into `''`, and the
+ * old membership test read that as "not a write tool" — REQ-144 closed exactly this direction for
+ * the path field while leaving the name field open.
+ */
+export declare function writesFiles(toolName: string | undefined, input: unknown): boolean;
+/**
+ * The file a raw path actually names.
+ *
+ * `path.resolve` folds `//`, `.` and `..`. Then the longest EXISTING ancestor is realpath'd and the
+ * remainder rejoined lexically — a whole-path `realpath` throws on a file that does not exist yet,
+ * which is precisely when the gate has to answer.
+ */
+export declare function resolveTarget(root: string, raw: string, depth?: number): string;
+/**
+ * Whether a write lands inside a governance directory.
+ *
+ * Comparison folds case because that is what the filesystem does: measured 2026-08-08 on macOS,
+ * writing `.AX/roles/policy.yaml` changed the very file the gate protects. On a case-sensitive
+ * filesystem folding over-protects, which is the safe direction and only collides for a project
+ * that deliberately keeps both `.ax` and `.AX`.
+ *
+ * The separator suffix matters: without it `.axolotl/` would inherit `.ax/`'s protection by prefix.
+ */
+export declare function isProtectedTarget(root: string, raw: string): boolean;
+/**
+ * Which governance directory a write lands in, or `null`.
+ *
+ * Callers that phrase a refusal need to name the right thing — REQ-155 measured how much a message
+ * that points at the wrong file costs — so the matched directory is returned rather than a bare
+ * boolean re-derived from a second regex.
+ */
+/**
+ * The spec FILE a write lands on, resolved — or `null` when the target is not a spec.
+ *
+ * @implements A-SPEC-191 §23 (round 12) — §22 moved `.mcp.json`, `.env`, `.ax/roles` and
+ * `.ax/ledger` onto identity and left the spec store itself on a case-sensitive regex over the
+ * caller's string. Measured on one fixture: `.AX/specs/…`, `.Ax/specs/…`, `.ax/SPECS/…`,
+ * `.ax//specs/…`, `.ax/./specs/…`, a link named `alias.md` and a link named `specslink` ALL
+ * reached the same files with the pattern looking elsewhere — so a session could self-approve an
+ * A-SPEC and a T-SPEC and then write the code they authorise, and could rewrite the body of an
+ * already-approved spec. The two rules the spec chain rests on (no self-approval, no seal-breaking
+ * edit) were both spelling-deep. The RESOLVED path is returned so callers read the disk at the
+ * same file they judged — asking `existsSync` about the caller's spelling was its own bypass.
+ */
+export declare function specTargetOf(root: string, specsDir: string, raw: string): string | null;
+/**
+ * Which governance FILE a write lands on, or `null`.
+ *
+ * @implements A-SPEC-191 §22 (round 11) — `.ax/*` and `.claude` were judged by identity here while
+ * `.mcp.json` and `.env` were judged by a regex over the caller's string, one function away. So the
+ * same sentence that A-SPEC-163 wrote ("identity, not spelling") was true of half its subject:
+ * a link inside the project under any other name reached `.mcp.json` with the pattern looking at a
+ * different string, and on a case-insensitive volume `.MCP.json` was the same file too. The
+ * resolution is `resolveTarget`'s — it follows links, including dangling ones, because a write
+ * through a dangling link creates exactly the file it names.
+ */
+export declare function protectedFileKindOf(root: string, raw: string): string | null;
+export declare function protectedKindOf(root: string, raw: string): string | null;

package/dist/holmes/hooks/adapters/antigravity.d.ts

@@ -0,0 +1,42 @@
+export interface AgyPreDecision {
+    decision: 'allow' | 'deny';
+    reason?: string;
+}
+export interface AgyStopDecision {
+    decision?: 'continue';
+    reason?: string;
+}
+/**
+ * 실측한 도구만 등재한다.
+ *
+ * 이름과 인자 키는 이 기계에 설치된 Antigravity CLI 의 실제 대화 기록에서 뽑았다
+ * (run_command{CommandLine,Cwd} 101건, view_file{AbsolutePath} 99건,
+ * replace_file_content{TargetFile,ReplacementContent,TargetContent} 46건, grep_search, list_dir).
+ * **추측으로 이름을 더하지 않는다** — 읽기로 잘못 등재하면 쓰기가 게이트를 지나가고, 쓰기로
+ * 잘못 등재하면 읽기가 막힌다. 등재되지 않은 이름은 그대로 게이트에 넘겨 fail-closed 로 받는다
+ * (A-SPEC-163: 읽기 전용이라고 알려지지 않은 도구가 경로를 들고 오면 그것은 쓰기다).
+ */
+export declare const TOOL_MAP: Record<string, {
+    as: string;
+    pathArg?: string;
+    contentArg?: string;
+    commandArg?: string;
+}>;
+/** 훅을 실행해 그 표준 출력을 돌려준다. 실행 자체가 실패하면 `null`(호출자가 닫는 쪽으로 받는다). */
+export type HookRunner = (hookPath: string, payload: string, cwd: string) => Record<string, unknown> | null;
+/**
+ * PreToolUse: Antigravity 의 말 → 게이트 → Antigravity 의 말.
+ *
+ * 번역할 수 없는 입력은 **닫는 쪽**으로 답한다. 어댑터가 조용히 `allow` 를 돌려주면 게이트가
+ * 없는 것과 같고, 그 사실은 아무 데도 나타나지 않는다 — REQ-144 가 같은 방향으로 세운 규율이다.
+ */
+export declare function adaptPreToolUse(stdin: string, cwd?: string, run?: HookRunner): AgyPreDecision;
+/**
+ * Stop: 게이트가 "막아라"라고 하면, 이 하네스에서 막는 말은 `continue` 다.
+ *
+ * 이름이 반대라서 헷갈리기 쉽다 — Claude Code 의 `block` 은 "정지를 막아라"이고 Antigravity 의
+ * `continue` 도 "정지하지 말고 계속하라"이다. 같은 뜻, 다른 낱말이다.
+ *
+ * 여기서는 실행 실패를 **열어 준다**. Stop 훅은 이미 fail-open 계약이다(턴을 죽이지 않는다).
+ */
+export declare function adaptStop(stdin: string, cwd?: string, run?: HookRunner): AgyStopDecision;

package/dist/holmes/hooks/pre-tool-use.d.ts

@@ -0,0 +1,144 @@
+import { Spec } from '../spec/spec-parser';
+import { Approval } from '../guardrail/risk-gate';
+import { RiskAction, RiskAssessment, RmSignal } from '../guardrail/risk-types';
+export declare function resolveRmSignals(command: string, cwd: string): Record<string, RmSignal> | undefined;
+/**
+ * @implements A-SPEC-149
+ * The out-of-band approval channel, read at the ENTRY only. `evaluateHook` no longer calls this on
+ * its own — an exported HOLMES_APPROVAL used to reach the decision directly and turn a denial into
+ * permission with nothing recording that it had. Exported so the entry's contract (parse, and treat
+ * malformed input as absent) is testable at the layer that owns it.
+ */
+export declare function readApprovalFromEnv(): Approval | undefined;
+/**
+ * True when `env`/`printenv` runs as an actual COMMAND (an environment dump) rather than appearing as
+ * a mere word — `grep -rn env src/` and `git commit -m "set the env"` must stay allowed, while
+ * `env`, `/usr/bin/env`, `X=1 env`, `command env`, `(env)`, `sh -c 'env'` must not. Each segment is
+ * stripped of leading assignments/wrappers and, for a nested shell, its `-c` body is re-examined.
+ * `env FOO=1 cmd` is a RUNNER (assignment then command), not a dump.
+ */
+export declare function dumpsEnvInCommandPosition(command: string, depth?: number): boolean;
+/**
+ * Coerce a hook envelope into known shapes so a type surprise cannot become an exception.
+ *
+ * @implements A-SPEC-144
+ * Measured against a real installed package, in a governed project where the control payload was
+ * correctly DENIED: `file_path: ["src/x.ts"]` and `file_path: {"a":1}` both threw
+ * `p.replace is not a function`, and an absent `tool_input` threw on property access — and the
+ * entry point's catch turned each of those into `allow`. No-Spec-No-Code was bypassed by a wrong type.
+ *
+ * A non-string target is DROPPED rather than coerced. `String(['a'])` is `'a'` and `String({})` is
+ * `'[object Object]'`; either would hand the classifier a path that does not exist and let it decide
+ * confidently about nothing. An absent target is honest, and the gate already knows how to treat one.
+ */
+export interface HookInput {
+    tool_name: string;
+    tool_input: {
+        file_path?: string;
+        notebook_path?: string;
+        content?: string;
+        new_string?: string;
+        command?: string;
+    };
+    /**
+     * @implements A-SPEC-163
+     * The raw payload carried a path field that was NOT a string, or `tool_input` was not an object.
+     *
+     * REQ-144's guarantee — a malformed payload denies rather than slips through — used to hold only
+     * by accident: `Write` happened to be in the hard-coded write list, so a dropped `file_path` fell
+     * into the write branch and failed there. Inverting the tool predicate removed that accident and
+     * three of its tests went red, which is what a guarantee resting on a coincidence looks like.
+     * Recording the fact makes it independent of which tool asked.
+     */
+    malformed?: boolean;
+}
+export declare function normalizeHookInput(raw: unknown): HookInput;
+/**
+ * Which way to fail when the gate itself throws.
+ *
+ * @implements A-SPEC-144
+ * The entry point used to answer `allow` unconditionally, with the comment "to avoid blocking the
+ * workflow". The tension is real — an unrelated bug that denies every tool call bricks a session —
+ * but resolving it toward a silent grant makes every future bug in the gate a bypass instead of a
+ * visible failure, which is the opposite of the posture the rest of this codebase takes.
+ *
+ * So: a governed project DENIES, because a gate that cannot evaluate must not grant (the same rule
+ * REQ-141 applied to the ledger). An ungoverned project ALLOWS, because there was no policy to apply
+ * and inventing a denial there is its own failure mode. And an operator — never the session — can
+ * escape via `HOLMES_GATE_BYPASS`.
+ */
+export declare function decideOnGateError(opts: {
+    governed: boolean;
+    bypass: boolean;
+    message: string;
+}): {
+    permissionDecision: 'allow' | 'deny';
+    permissionDecisionReason?: string;
+};
+/**
+ * Is this project governed? Computed on the ERROR path, so it must not re-run the logic that just
+ * failed: presence of a configured spec root or a non-empty spec directory, nothing more. Any
+ * problem reading it means NOT governed — the conservative direction here is the one that keeps an
+ * unrelated failure from bricking a project that never asked for gating.
+ */
+export declare function isGovernedProject(specsDir: string, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * The whole error-path decision, assembled from an environment.
+ *
+ * @implements A-SPEC-144
+ * Exported and env-injected so the WIRING is tested rather than trusted. Mutation testing found the
+ * gap: hardcoding `bypass: true` and inverting the governance check both left every test green,
+ * because the tests exercised the pure helpers directly and nothing exercised the code that reads
+ * the environment. An untested wire is where a fix quietly stops applying.
+ */
+export declare function gateErrorDecision(message: string, env?: NodeJS.ProcessEnv, argv?: readonly string[], projectRoot?: string): {
+    permissionDecision: 'allow' | 'deny';
+    permissionDecisionReason?: string;
+};
+/**
+ * @implements A-SPEC-190 (round 8)
+ * Which spec directory this hook enforces against. The wiring writes it on the hook's own command
+ * line because the hook entry in settings carries no environment: `init --specs-dir docs/specs`
+ * reached the MCP server (HOLMES_SPECS in .mcp.json) and NOT the gate, so a project could be wired
+ * `governed` while the gate read an empty `.ax/specs` and refused nothing. Precedence is
+ * argv > env > default: the wiring is more specific than an ambient variable.
+ */
+export declare function wiredSpecsDir(argv: readonly string[], env: NodeJS.ProcessEnv): string;
+/** Default spec root. Used to tell "never governed" apart from an explicitly configured HOLMES_SPECS. */
+export declare const DEFAULT_SPECS_DIR = ".ax/specs";
+export declare function evaluateHook(input: {
+    tool_name: string;
+    tool_input: {
+        file_path?: string;
+        notebook_path?: string;
+        content?: string;
+        new_string?: string;
+        command?: string;
+    };
+}, specsDir: string, opts: {
+    assess?: (a: RiskAction) => RiskAssessment;
+    /**
+     * @implements A-SPEC-149
+     * REQUIRED, `undefined` allowed explicitly. The old `?? readApprovalFromEnv()` fallback let an
+     * exported HOLMES_APPROVAL reach the decision: measured, a root with planted debt produced NO
+     * denial because `codeWriteCovered` became true, while the same call under `env -u` denied. That
+     * failure mode is worse than the cwd one — it makes tests PASS. The out-of-band channel stays;
+     * only the entry point reads it.
+     */
+    approval: Approval | undefined;
+    resolveRmSignals?: (command: string) => Record<string, RmSignal> | undefined;
+    /**
+     * @implements A-SPEC-149
+     * REQUIRED. The implicit `process.cwd()` fallback is gone: it made the gate read whichever
+     * project the process happened to sit in, so a unit test's verdict depended on the repository's
+     * own `.ax/state`. Measured — thirteen tests failed deterministically while constitution debt was
+     * recorded here, and the code was correct. A missing root is now a compile error, which is the
+     * only way the coupling stops being re-introduced by the next caller.
+     */
+    projectRoot: string;
+    now?: string;
+}): {
+    permissionDecision: 'allow' | 'deny';
+    permissionDecisionReason?: string;
+};
+export declare function readSpecsSync(root: string): Spec[];

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

@@ -0,0 +1,91 @@
+import { Spec } from '../spec/spec-parser';
+/**
+ * @implements A-SPEC-100.2
+ * Stop-hook governance gate (Phase-2 #1: push, not pull).
+ *
+ * RTM integrity (rtm_check) and spec correctness (spec_validate) were only reachable as MCP tools
+ * the model had to VOLUNTARILY invoke — and across a full benchmark it invoked them 0/143 times. A
+ * "deterministic control plane" cannot depend on the LLM choosing to call its own governance. This
+ * hook runs those checks at every turn boundary (PUSH): if the governed spec set has unresolved RTM
+ * or validation errors, it BLOCKS the stop and feeds the findings back so the model must fix them
+ * before finishing. No model cooperation required — the governance fires whether or not it is asked.
+ *
+ * HARDENING H1 (GWT-실테스트 bridge): declared 4-quadrant coverage previously verified only the
+ * T-SPEC DOCUMENT. Now, for every approved T-SPEC, its parent A-SPEC must have at least one anchored
+ * TEST FILE containing REAL test cases (`it(`/`test(`) — declared coverage over an empty/absent test
+ * suite blocks the stop. Evidence is supplied by the CLI (I/O half); evaluateStop stays pure.
+ *
+ * Pure and testable: evaluateStop takes the loaded spec set (+ optional evidence); the CLI does I/O.
+ */
+export interface StopEvidence {
+    /** A-SPEC id -> number of real test cases (`it(`/`test(`) found in test files anchored to it. */
+    testCasesByAspec?: Record<string, number>;
+    /** Provenance-chain verification result (CLI-supplied). A broken chain blocks the stop. */
+    provenance?: {
+        ok: boolean;
+        brokenAt?: number;
+        detail?: string;
+    };
+    /** A-SPEC -> cases that ACTUALLY EXECUTED in a fresh run; authoritative over the syntactic count. */
+    executedByAspec?: Record<string, number>;
+    /** @implements A-SPEC-160 — recorded findings, for ART-6. @implements A-SPEC-191 — severity rides along for ART-7. */
+    findings?: {
+        id: string;
+        status: 'open' | 'resolved';
+        basis?: string;
+        severity?: string;
+        summary?: string;
+    }[];
+    /**
+     * @implements A-SPEC-191 (§4a)
+     * The findings ledger EXISTS but could not be read (any list() throw — ENOENT is absorbed as an
+     * empty list upstream). Measured: swallowing this into `undefined` let an open critical pass AND
+     * cleared standing ART-7 debt — an unreadable ledger laundering the very state it records.
+     */
+    findingsUnreadable?: boolean;
+}
+/**
+ * @implements A-SPEC-175
+ * The turn-boundary answer to "this project is governed but its specs are gone".
+ *
+ * Extracted so it is reachable by a test: the runtime block below only runs under
+ * `require.main === module`, and a check that lives only there is a check nothing can mutate against.
+ * Returns the reason to block with, or null when there is nothing to report.
+ */
+export declare function governanceLostPreflight(specsDir: string, projectRoot?: string): string | null;
+export declare function evaluateStop(specs: Spec[], evidence?: StopEvidence): {
+    block: boolean;
+    reason?: string;
+    articles?: string[];
+};
+/**
+ * @implements A-SPEC-134
+ * Pure decision for the constitution-debt state at a turn boundary. Replaces the Stop gate's silent
+ * cap-yield: a clean turn clears any standing debt; a cap-yield (the gate giving up its block after
+ * MAX_CONSECUTIVE_BLOCKS) RECORDS the unresolved articles as debt so new code is blocked until the
+ * constitution is clean again; a normal block (still within the cap) touches nothing.
+ */
+export declare function stopDebtAction(evaluation: {
+    block: boolean;
+    articles?: string[];
+}, guard: {
+    block: boolean;
+    capped: boolean;
+}): {
+    action: 'write' | 'clear' | 'none';
+    articles: string[];
+};
+export declare const MAX_CONSECUTIVE_BLOCKS = 3;
+export declare function decideStopGuard(wantsBlock: boolean, priorConsecutiveBlocks: number, cap?: number): {
+    block: boolean;
+    nextCount: number;
+    capped: boolean;
+};
+/** Test seam for the same reason as the two exports below — the CLI sets this on a real run. */
+export declare function __setWiredSpecsForTest(v: string | undefined): void;
+export declare function readGuardCount(sessionId: string): number;
+/**
+ * Exported for the §19 race discriminator: the persistence layer was the untested half (round-11),
+ * and a test that can only reach it through a spawned hook cannot pin what the lock does.
+ */
+export declare function writeGuardCount(sessionId: string, n: number): boolean;

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

@@ -0,0 +1,100 @@
+/**
+ * What a computation was based on.
+ *
+ * Measured 2026-08-08: the live MCP server answered `impactedSpecs: []` for a commit that touched 39
+ * specs, while the same handler in a fresh process answered correctly. The server had been running
+ * since 8/5 against a 8/8 build. Nothing in the response said which build, which scan generation, or
+ * which graph produced it — so a reviewer had no way to distrust it, and `doctor` reported
+ * "handshake ok".
+ *
+ * The fix is not staleness detection. That catches one cause; the next divergence (a graph
+ * generation, a spec corpus) slips through the same way. Carrying the basis makes divergence a FACT
+ * the caller reads rather than a verdict the server renders.
+ */
+export interface Basis {
+    /** The build this process loaded, read once at start-up. `unknown` when unstamped. */
+    loadedBuild: string;
+    /** What is on disk NOW. Present only in the detail — see `collectBasis`. */
+    diskBuild?: string;
+    /**
+     * Fingerprint of the scan artefact. `undefined` when the axis could not be measured.
+     *
+     * A fingerprint, not a file count: measured 2026-08-08, `cachedScan` costs 69ms on this repo, and
+     * charging that to every one of the tools on every call would break this module's own constant-I/O
+     * requirement. A stat over the scan cache costs nothing and changes whenever the scan does, which
+     * is all divergence detection needs.
+     */
+    scanFp?: number;
+    specs?: number;
+}
+/**
+ * There is deliberately NO graph axis. `RtmGraph` is in-memory only (ADR-011 — a derived index,
+ * rebuilt every time), so the graph is a FUNCTION of specs and scan and cannot diverge from them
+ * independently. Including it would mean either an always-`?` field or a rebuild per call: token
+ * cost with no information in the first case, a constant-I/O violation in the second.
+ */
+/**
+ * Cap on the digest. A basis rides on every one of the tools, so its size multiplies across a
+ * session — this bound is what keeps "carry the basis" compatible with REQ-122's requirement that
+ * the harness be net-token-positive, rather than opposed to it.
+ */
+export declare const MAX_DIGEST_LEN = 64;
+/**
+ * Cap on the build id alone. Truncating the whole digest at the end would eat the trailing axes, so
+ * a long build id could make `x:` disappear entirely and the digest would read as if that axis had
+ * never existed — the exact silent-omission failure `?` exists to prevent. Bounding the variable
+ * part instead keeps the structure intact whatever the stamp looks like.
+ */
+export declare const MAX_BUILD_LEN = 32;
+/**
+ * @implements A-SPEC-160
+ * Appended when the loaded and on-disk builds are BOTH known and differ.
+ *
+ * This is an observation, not a verdict, and the distinction matters: REQ-156 deliberately refused to
+ * let the server decide whether it was stale, because that logic would be running inside the stale
+ * build. Reporting that two measured values disagree is a fact; what to do about it is ART-6's call.
+ *
+ * An unknown disk build never carries the marker. Reading absence as divergence would fire on every
+ * tool but `review_record` — none of the others read disk — and an article that fires constantly is
+ * one people route around within a day.
+ */
+export declare const BASIS_DIVERGED = "/!";
+/** Reads the marker back out of a sealed digest. */
+export declare function basisDiverged(digest: string | undefined): boolean;
+/**
+ * The build identity of the code that is RUNNING. Read once at start-up by the server, never per
+ * call: hashing `dist` on every request buys I/O for no new information, and mtime changes on a
+ * checkout or a copy, which would manufacture divergence that is not there.
+ *
+ * An unstamped build is reported as `unknown` rather than guessed. Absence is a fact too, and a
+ * fabricated id would be worse than none — it would look like agreement.
+ */
+export declare function loadedBuildId(root: string): string;
+export interface BasisContext {
+    scanFp?: () => number;
+    specs?: () => number;
+    /** Project root, for reading the on-disk build id. Omit to skip that axis. */
+    root?: string;
+    /** The build this process loaded. Injected so the server reads it exactly once. */
+    loadedBuild?: string;
+}
+export declare function collectBasis(ctx: BasisContext): Basis;
+/**
+ * `b:<build>/s:<scanFp>/x:<specs>`
+ *
+ * Short by design: a caller compares the value against another and learns that something diverged
+ * without needing to interpret any field. An unmeasured axis renders as `?` rather than being
+ * dropped — omitting it would let a reader take "these two matched" for agreement when the third
+ * was never measured at all.
+ */
+export declare function basisDigest(b: Basis): string;
+/**
+ * Attaches a basis to a handler's result.
+ *
+ * Exported and pure so the contract is testable without a handler that exercises each branch. The
+ * array guard in particular has no live caller today — every tool returns an object — and an
+ * untested guard is one a later change deletes for free. Spreading an array into an object yields
+ * `{0:…, 1:…, basis}`, silently reshaping a response into something no caller can read, so the
+ * branch has to survive on its own merits rather than on nobody having tried it yet.
+ */
+export declare function withBasis<A>(fn: (a: A) => Promise<unknown>, basisOf: (a: A) => Basis): (a: A) => Promise<unknown>;