@holmes-lab/holmes-kit 0.1.7 → 0.1.8

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

@@ -0,0 +1,154 @@
+import { LockOptions } from './ledger-lock';
+/**
+ * N3 — Decision PROVENANCE chain (target-architecture §7-N N3): "누가·언제·왜"의 완전 인과 재구성.
+ *
+ * Upgrades the L4 ledgers from plain append-only JSONL to a TAMPER-EVIDENT HASH CHAIN: every event
+ * carries `prevHash` and `hash = sha256(prevHash | canonical(event))`, so any rewrite, deletion, or
+ * reordering of history breaks verification at the exact seam. Honest naming: this is tamper-EVIDENT
+ * (a forger cannot alter past events without detection), not a cryptographic SIGNATURE — there is no
+ * key infrastructure, so a forger who rewrites the ENTIRE chain from the tampered point forward would
+ * pass verification; the defense against that is the write-gate on `.ax/ledger` (HIGH-3 hardening)
+ * plus out-of-band copies. Full signing (HMAC/asymmetric) is a documented future step.
+ *
+ * Each event is a Decision Event node: consumed inputs (evidence refs), rationale, actor, timestamp,
+ * and the authorization that unlocked it — the GAIE "Decision Event" concept realized on the RTM side.
+ *
+ * Pure half: canonicalize / computeHash / chainNext / verifyChain (caller supplies ts; no clock).
+ * I/O half: ProvenanceChain over a JSONL file, ENOENT -> empty, other read errors THROW (silently
+ * returning [] would erase the audit trail this exists to guarantee — same policy as DecisionLedger).
+ */
+export interface ProvenanceEvent {
+    seq: number;
+    ts: string;
+    actor: string;
+    kind: string;
+    summary: string;
+    inputs?: string[];
+    rationale?: string;
+    authorization?: string;
+    prevHash: string;
+    hash: string;
+}
+type ProvenanceBody = Omit<ProvenanceEvent, 'prevHash' | 'hash'>;
+export declare const GENESIS = "GENESIS";
+/** Ordered-key serialization so identical bodies always produce identical bytes (hash stability). */
+export declare function canonicalize(b: ProvenanceBody): string;
+/**
+ * Event hash. WITHOUT a key: plain sha256 chain (tamper-EVIDENT — a full rewrite from point k still
+ * passes, the documented no-key limit). WITH an out-of-band key (HOLMES_LEDGER_KEY env, same channel
+ * discipline as HOLMES_APPROVAL): HMAC-SHA256 — a forger without the key cannot recompute ANY link,
+ * so even the full-rewrite attack fails verification. Key presence upgrades the guarantee from
+ * tamper-evident to tamper-PROOF-against-keyless-forgers; absence degrades gracefully to the chain.
+ */
+export declare function computeHash(prevHash: string, body: ProvenanceBody, key?: string): string;
+/** Build the next chained event from the current chain tail (pure). */
+export declare function chainNext(chain: ProvenanceEvent[], body: Omit<ProvenanceBody, 'seq'>, key?: string): ProvenanceEvent;
+/**
+ * Verify the whole chain: recomputed hashes, prevHash linkage, contiguous seq, AND no unknown fields.
+ * The unknown-field check closes the canonicalization-gap attack (adversarial review #2): canonicalize
+ * hashes only the known fields, so a tamperer could smuggle forged data in an EXTRA field that the
+ * hash ignores but a consumer might read — any field outside the schema now fails verification.
+ * Returns the FIRST broken seam so remediation is addressable. An empty chain is trivially valid.
+ */
+export declare function verifyChain(chain: ProvenanceEvent[], key?: string): {
+    ok: boolean;
+    brokenAt?: number;
+    detail?: string;
+};
+/**
+ * Reference an approval credential WITHOUT persisting it: a short sha256 fingerprint identifies which
+ * token authorized an action while the ledger never stores the replayable secret (adversarial review
+ * #1 — the raw token in an audit file meant any local reader could harvest live gate-unlock
+ * credentials).
+ */
+export declare function authorizationRef(actor: string, token: string): string;
+/**
+ * Redact a tool's target before it enters the audit trail.
+ *
+ * The chain used to store the raw command text. Audited on this repository's own ledger: 29 records,
+ * 15 carrying absolute home paths and 6 matching secret-ish patterns. The hazard is structural, not
+ * incidental — the gate DENIES commands like `echo $HOLMES_APPROVAL` and `HOLMES_LEDGER_KEY=…`, and
+ * a denial is exactly what gets recorded, so the ledger is the one place guaranteed to collect the
+ * secrets the gate exists to protect. Committing it would publish them irreversibly.
+ *
+ * Same principle `authorizationRef` already applies to tokens: fingerprint, never store.
+ *
+ * - A FILE PATH is kept, because "which file was touched" is the audit question, but normalised to
+ *   repo-relative; anything outside the repository becomes a placeholder rather than a host path.
+ * - A COMMAND is never kept. Its digest is recorded instead, so identical attempts remain
+ *   correlatable across records without the text being recoverable. Nothing is lost for audit: the
+ *   event's `summary` already carries the human-readable classification ("hard-hitl risk: git push
+ *   --force rewrites remote history"), which is what a reader actually needs.
+ */
+export declare function redactTarget(kind: 'path' | 'command', value: string, repoRoot?: string): string;
+export declare function blankNonce(nonce: unknown): boolean;
+/** Declared at all — the operand for "does this grant claim single use?" (falsy values included). */
+export declare function nonceDeclared(nonce: unknown): boolean;
+export declare function nonceFingerprint(nonce: string): string;
+export declare function approvalMarkers(approval: {
+    scope?: {
+        kind: string;
+        pattern: string;
+    }[];
+    expires?: string;
+    nonce?: string;
+} | undefined): string;
+export declare class ProvenanceChain {
+    private readonly file;
+    constructor(file: string);
+    /** Load all events. ENOENT -> []; any other error throws (audit trail must not silently vanish). */
+    load(): ProvenanceEvent[];
+    /** Append a new event chained onto the CURRENT on-disk tail. Returns the appended event.
+     *  The signing key comes from HOLMES_LEDGER_KEY (out-of-band env, never tool-settable in-session).
+     *
+     *  @implements A-SPEC-141
+     *  The read-and-write span runs under exclusion. Measured without it: two processes read the same
+     *  tail, both wrote events claiming the same `seq`, and `verify()` then reported `ok:false` —
+     *  tampering that never happened, 17 times out of 20. */
+    append(body: Omit<ProvenanceBody, 'seq'>): ProvenanceEvent;
+    /**
+     * Append assuming exclusion is ALREADY held. Only for callers running inside `withLedgerLock` on
+     * this same file — `consumeNonceExclusively` needs the read and the write in one hold, and calling
+     * `append()` from there would deadlock against its own budget.
+     */
+    appendInsideLock(body: Omit<ProvenanceBody, 'seq'>): ProvenanceEvent;
+    /** The append itself, assuming exclusion is already held. Only callers INSIDE a hold may use it. */
+    private appendUnlocked;
+    /**
+     * Records a broken stale hold into the chain itself. Bound so it can be handed to the lock layer,
+     * which must not import this module (the lock is the lower layer).
+     *
+     * Written WITHOUT re-entering the lock: this fires from inside the acquire loop, where the hold has
+     * just been released and not yet re-taken, so calling `append()` here would deadlock against the
+     * budget. The event may therefore race a concurrent writer, which is acceptable for a diagnostic —
+     * a missing note is better than a wedged harness, and `verify()` still reports any resulting seam.
+     */
+    staleBreakRecorder(): NonNullable<LockOptions['onStaleBreak']>;
+    private recordStaleBreak;
+    verify(): {
+        ok: boolean;
+        brokenAt?: number;
+        detail?: string;
+    };
+}
+/** Default chain location, beside the other L4 ledgers (protected surface). */
+export declare const PROVENANCE_FILE: string;
+/**
+ * Spend a single-use approval, atomically. Returns `true` iff THIS caller spent it.
+ *
+ * @implements A-SPEC-141
+ * THIS is the operation REQ-141 exists for. The gate used to ask `isNonceConsumed(...)` and only
+ * afterwards append the consumption record, so two agents both observed "not consumed" and both
+ * proceeded: measured, a single-use approval for a destructive command was honoured TWICE in 20 of
+ * 20 barrier-synchronized trials. Locking the append alone would not have helped — the unguarded
+ * span is the READ followed by the WRITE, so both must live inside one hold.
+ *
+ * A loser writes NOTHING. Recording a consumption the caller was refused would put a second
+ * `nonce-consumed` event in the audit trail for an action that never happened.
+ *
+ * Throws `LedgerLockError` when exclusion cannot be obtained. The direction to fail is the CALLER's
+ * decision, not this function's: an authorization gate must deny, while a record-keeping append must
+ * not flip a decision that was already made.
+ */
+export declare function consumeNonceExclusively(nonce: string, ledgerFile: string, body: Omit<ProvenanceBody, 'seq'>, opts?: LockOptions): boolean;
+export {};

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

@@ -0,0 +1,102 @@
+import { ProvenanceChain, ProvenanceEvent } from './provenance-chain';
+/**
+ * The ledger as a SET of per-replica chains, read together and written one at a time.
+ *
+ * WHY, measured: ADR-012 made `provenance.jsonl` a shared SSOT tracked in git, explicitly so a
+ * colleague who clones can answer "who decided this, when, and why". That decision opens a use case
+ * the format cannot survive — two machines appending to one chain and merging produces
+ * `{"ok":false,"detail":"seq gap: expected 2, found 1"}`. Tamper detection fires when nobody
+ * tampered, and because `isBaselineTrusted` requires an intact chain, baseline trust collapses with
+ * it. REQ-141 solved the same shape WITHIN one machine with a lock; across machines there is no
+ * shared filesystem to lock.
+ *
+ * The primitive is deliberately untouched. `ProvenanceChain` remains "one file, one chain", so the
+ * legacy `provenance.jsonl` keeps loading and verifying with no migration at all — this change obeys
+ * the ADR-013 tier-① rule it was written under — and REQ-141's per-file lock keeps working unchanged.
+ *
+ * WHAT IS LOST: the globally monotonic `seq`, and with it a total order proven by hashes. After the
+ * split that proof holds only within a replica.
+ *
+ * WHAT REPLACES IT: git. These files are tracked (ADR-012), any deletion or rewrite shows up in
+ * history, and a git commit is itself a hash chain. The cross-replica anchor does not disappear; it
+ * moves one layer up. That is why splitting is not the same as giving up detection.
+ */
+export interface LedgerEvent extends ProvenanceEvent {
+    /** Which chain this came from; `null` for the pre-split legacy file. */
+    replicaId: string | null;
+}
+export interface LedgerVerifyResult {
+    ok: boolean;
+    /** Per-chain failures, naming the replica so a report is actionable rather than merely alarming. */
+    broken: {
+        replicaId: string | null;
+        file: string;
+        detail?: string;
+        brokenAt?: number;
+    }[];
+}
+export declare class ProvenanceLedger {
+    private readonly dir;
+    /**
+     * Resolved LAZILY. Constructing a reader must not write anything, and `resolveReplicaId`
+     * persists `.ax/state/replica-id` on first use — doing that from `at()` made every read create
+     * a `.ax/state/` directory, which changed what `resolveProjectRoot` found in test fixtures and
+     * broke ten unrelated tests. A read that leaves a footprint is a defect regardless of what it
+     * happens to break.
+     */
+    private readonly replicaIdFn;
+    private indexCache?;
+    private constructor();
+    private cachedId;
+    private get replicaId();
+    /**
+     * `replicaId` is normally resolved from the machine; tests and CI pass it explicitly. The project
+     * root is taken to be the ledger directory's grandparent (`<root>/.ax/ledger`), which is where
+     * `.ax/state/replica-id` lives.
+     */
+    static at(dir: string, replicaId?: string): ProvenanceLedger;
+    /**
+     * This writer's replica id WITHOUT persisting it.
+     *
+     * @implements A-SPEC-150
+     * Asking "who am I" is a read, and the ledger port's conformance requires a read to leave no
+     * trace. `resolveReplicaId` persists by default because the value has to be stable for a WRITER;
+     * a reader gets the same answer with `persist: false`. Merely calling this used to create
+     * `.ax/state/`, which is the REQ-148 footprint defect returning through a new door.
+     */
+    replicaIdOf(): string;
+    /** Every chain file present, legacy first. `replicaId` is null for the legacy chain. */
+    chains(): {
+        replicaId: string | null;
+        file: string;
+    }[];
+    /** The file this machine appends to. Never the legacy chain — see `append`. */
+    currentFile(): string;
+    private computeMtimeKey;
+    private cloneEvents;
+    /**
+     * Every event across every chain, ordered by `(ts, replicaId, seq)`.
+     *
+     * Deterministic, and deliberately NOT a total causal order: two events on different replicas have
+     * no causal relation, and their timestamps differ by whatever the machines' clocks differ by. The
+     * ordering exists so output is stable and readable, not so it can be read as "this happened first".
+     */
+    loadAll(): LedgerEvent[];
+    /** Each chain verified on its own; one bad chain fails the whole ledger, and is named. */
+    verifyAll(): LedgerVerifyResult;
+    /**
+     * Append to THIS replica's chain.
+     *
+     * Never to the legacy file: continuing to write there would put two machines back on one chain,
+     * which is the defect this class exists to remove.
+     */
+    append(body: Parameters<ProvenanceChain['append']>[0]): ProvenanceEvent;
+    /**
+     * Has this nonce been spent on ANY replica?
+     *
+     * The trap the split creates: judging from one chain alone lets a single-use approval be spent once
+     * per replica, which would resurrect REQ-141's double-spend along a new axis. The question is only
+     * meaningful across the whole set.
+     */
+    isNonceConsumed(nonce: string): boolean;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * The provenance ledger's schema version, read from the FILE NAME rather than from the records.
+ *
+ * WHY the filename and not a field, measured rather than chosen: adding `v` to a record fails
+ * verification with `unknown field(s) outside the hashed schema: v (smuggled data)` — the
+ * anti-smuggling check an earlier adversarial review added, working exactly as intended. The two
+ * ways around it are both worse than the problem. Allowing an exempt field creates one field a
+ * forger can write freely, inside the artefact whose whole purpose is tamper evidence. Adding the
+ * field to `canonicalize` changes the canonical form of every record, so all 1804 existing entries
+ * stop matching their own hashes — a compatibility rule that destroys the tier-① artefact it was
+ * written to protect.
+ *
+ * That leaves the name. It is not a workaround: the replica split is about to rename these files
+ * anyway, so the name is already the thing that changes when the schema changes, and reading it
+ * costs nothing.
+ *
+ * - `provenance.jsonl`                → 1 (single global chain, contiguous seq)
+ * - `provenance.<replicaId>.jsonl`    → 2 (per-replica chain, seq local to the replica)
+ */
+export type ProvenanceSchema = 1 | 2;
+export declare function provenanceSchemaOf(fileName: string): ProvenanceSchema;

package/dist/holmes/governance/replica-id.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Reduce a raw name to something safe to embed in `provenance.<id>.jsonl`.
+ *
+ * DOTS ARE THE POINT. macOS hostnames end in `.local`, and the schema rule reads
+ * `provenance.<segment>.jsonl` with `<segment>` containing no dot — an unsanitised
+ * `SungNamui-MacStudio.local` would produce `provenance.SungNamui-MacStudio.local.jsonl`, which the
+ * schema check would not recognise as a replica chain at all. Two rules disagreeing about the same
+ * file is worse than either rule being wrong.
+ */
+export declare function sanitizeReplicaId(raw: string): string;
+/**
+ * Resolve this machine's replica id: explicit env, then the stored value, then the hostname.
+ *
+ * The env override exists for CI and for tests, where the hostname is neither stable nor meaningful.
+ * Writing the generated value down is what makes the identity stable — an id derived fresh each run
+ * would scatter one machine's history across several chains.
+ */
+export declare function resolveReplicaId(root: string, env?: NodeJS.ProcessEnv, opts?: {
+    persist?: boolean;
+}): string;

package/dist/holmes/governance/role-policy.d.ts

@@ -0,0 +1,52 @@
+import { Identity } from './identity';
+/**
+ * What each role may do, as project-owned governance config.
+ *
+ * The allow-list entries are the action names `classifyAction` already produces (`WRITE_CODE`,
+ * `WRITE_TEST`, …). Inventing a separate vocabulary would let what the gate decides and what a role
+ * claims drift apart, and the drift would be invisible until someone was wrongly allowed.
+ *
+ * OPT-IN. A project with no `.ax/roles/` has no policy and the gate behaves exactly as before —
+ * making roles mandatory would deny every existing project at once, which is the bricking REQ-146
+ * measured when it tried to make a spec field required.
+ *
+ * The definition lives under a PROTECTED path. Blocking role claims while leaving the policy
+ * writable would be one lock on a door with two entrances: an agent that cannot change its role
+ * would simply change what that role is allowed to do.
+ */
+export interface RolePolicy {
+    roles: Record<string, {
+        allow: string[];
+    }>;
+    /**
+     * Which role an UNSPECIFIED agent is treated as. Declared by the project, never assumed by code.
+     *
+     * That distinction is the whole security argument. If the code defaulted to a full-capability role
+     * whenever `HOLMES_ROLE` was absent, every restriction would be bypassable by unsetting one
+     * environment variable — the rule that binds a Reviewer would become "don't set it". Because this
+     * lives in `.ax/roles/`, which is a PROTECTED path, an agent cannot write it either.
+     *
+     * Omitting it keeps the fail-closed behaviour: unspecified is refused.
+     */
+    default?: string;
+}
+/** `null` when the project has not opted in. A PRESENT-but-broken policy is never null — see below. */
+export declare function loadRolePolicy(root: string): RolePolicy | null;
+/** What `doctor` reports. Three states, because "no policy" and "guidance present but off" differ. */
+export interface RolePolicyStatus {
+    state: 'absent' | 'inactive' | 'active';
+    roles: string[];
+    default?: string;
+}
+/**
+ * Describes the project's role configuration WITHOUT judging it. Not having roles on is not a
+ * defect; reporting it as one would teach operators to ignore doctor, which costs more than it saves.
+ */
+export declare function rolePolicyStatus(root: string): RolePolicyStatus;
+/**
+ * Whether this identity may perform this action. Returns the refusal reason, or `null` to allow.
+ *
+ * Fail-closed once a policy exists: an absent role, an unregistered role, and a role without the
+ * action are all refusals. Before a policy exists there is no opinion at all.
+ */
+export declare function roleCheck(action: string, identity: Identity, policy: RolePolicy | null): string | null;

package/dist/holmes/governance/trust-score.d.ts

@@ -0,0 +1,32 @@
+/**
+ * L5 — quantitative TRUST SCORE → automation level (target-architecture §7 L5).
+ *
+ * bkit's trust-score pattern, deterministic: recent governed-work metrics fold into a 0..1 score and
+ * a discrete automation LEVEL that callers (risk gate, orchestrators) can use to graduate autonomy —
+ * high sustained trust earns wider auto-approval; faults/regressions/critical findings walk it back.
+ *
+ *   L0 observe   — read/analyze only
+ *   L1 propose   — may draft changes, human applies
+ *   L2 gated     — may apply changes behind every gate (default posture)
+ *   L3 trusted   — routine (auto-level) actions skip confirm-level friction
+ *   L4 autonomous— may batch routine work; hard-hitl still ALWAYS gates (never waived — ART-5)
+ *
+ * Pure and clock-free: the caller aggregates the window (e.g. from the L4 ledgers) into TrustMetrics.
+ * Conservative by construction: zero history -> L2 default-gated, never trusted; any fault or
+ * regression caps the level regardless of volume (a burst of green cannot buy back a fresh fault).
+ */
+export interface TrustMetrics {
+    slicesCompleted: number;
+    suiteGreenRate: number;
+    guardrailDenials: number;
+    faults: number;
+    regressions: number;
+    criticalFindings: number;
+}
+export type AutomationLevel = 'L0' | 'L1' | 'L2' | 'L3' | 'L4';
+export interface TrustAssessment {
+    score: number;
+    level: AutomationLevel;
+    rationale: string;
+}
+export declare function computeTrustScore(m: TrustMetrics): TrustAssessment;

package/dist/holmes/guardrail/anchors.d.ts

@@ -0,0 +1,8 @@
+export declare function claimedAnchors(content: string): string[];
+/**
+ * The anchors this write ADDS, relative to what the file already had.
+ *
+ * Only the additions are judged. Re-judging anchors already in the file would block every edit to a
+ * file whose spec later moved back to draft — including the edits needed to fix exactly that.
+ */
+export declare function newlyClaimed(content: string, previous: string | undefined): string[];

package/dist/holmes/guardrail/blind-spots.d.ts

@@ -0,0 +1,32 @@
+/**
+ * What the guardrail CANNOT see, declared in code rather than prose.
+ *
+ * The guardrail inspects the command STRING. Anything whose behaviour lives elsewhere — a script
+ * file, a variable, stdin — is opaque to it, and no amount of pattern work changes that: what
+ * `node ./x.js` does is not statically decidable. Measured 2026-08-08: every entry below reached
+ * `allow`.
+ *
+ * Declared here, not in a document, because a test can read this and assert that each example really
+ * is allowed. A limit written in prose drifts silently from the code; twice this session a claim in
+ * a comment turned out to be false when measured. Keeping the claim next to an executable check
+ * means whoever later closes one of these has to come here and rewrite it.
+ *
+ * REQ-167 already closed the half that mattered most: WRITING a script now needs an approved spec,
+ * so `x.sh` followed by `bash ./x.sh` no longer completes on its own. What remains is running a
+ * script that was ALREADY in the repository — code a human committed.
+ */
+export interface BlindSpot {
+    /** A command the gate allows, verbatim, so a test can check the claim. */
+    example: string;
+    /** Why it is opaque. */
+    why: string;
+}
+export declare const GATE_BLIND_SPOTS: readonly BlindSpot[];
+/**
+ * One line for `doctor`.
+ *
+ * Deliberately neither "the gate stops everything" nor "the gate stops nothing". The first gets
+ * someone hurt; the second makes a reader distrust the parts that do work — and after REQ-167 those
+ * parts include creating the script in the first place.
+ */
+export declare function blindSpotSummary(): string;

package/dist/holmes/guardrail/decision-ledger.d.ts

@@ -0,0 +1,29 @@
+import { RiskAction, RiskLevel } from './risk-types';
+export interface DecisionEvent {
+    ts: string;
+    actor: string;
+    action: RiskAction;
+    level: RiskLevel;
+    decision: 'auto' | 'approved' | 'proceeded-unconfirmed' | 'blocked' | 'rejected';
+    rationale: string;
+    reasons: string[];
+}
+/**
+ * Append-only, provenance audit trail for riskGate decisions. Each call to
+ * `record` appends one JSON line per event to a `.jsonl` file -- never
+ * truncated, never rewritten -- so the file itself is the durable evidence
+ * trail.
+ *
+ * Timestamps and ids are caller-supplied: this ledger has no clock, so
+ * recording is fully deterministic given its inputs. Ledger I/O is
+ * deliberately separate from riskGate's decision -- a write failure here
+ * must never change a gate verdict that was already computed.
+ */
+export declare class DecisionLedger {
+    private readonly path;
+    constructor(path: string);
+    record(events: DecisionEvent[]): void;
+    list(): DecisionEvent[];
+    /** Ordered-object serialization so identical events always produce identical bytes. */
+    private static serialize;
+}

package/dist/holmes/guardrail/executable-artifact.d.ts

@@ -0,0 +1 @@
+export declare function isExecutableArtifact(relPath: string, content?: string): boolean;

package/dist/holmes/guardrail/governance-history.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The two ways out, and why the project is being judged governed at all.
+ *
+ * Shared by both hooks so they cannot describe the same situation differently. Naming only the
+ * restore path would be no guidance to a user whose actual intent is to stop being governed — they
+ * would keep deleting things until it stopped.
+ */
+export declare const GOVERNANCE_LOST_HINT: string;
+/**
+ * True if any provenance replica records a spec approval.
+ *
+ * Fails toward `true` on anything unreadable: if "cannot read" meant "never governed", corrupting a
+ * ledger file would be a way to switch the gate off — worse than the hole this closes.
+ */
+export declare function hasGovernanceHistory(root: string): boolean;

package/dist/holmes/guardrail/phase.d.ts

@@ -0,0 +1,27 @@
+import { Spec } from '../spec/spec-parser';
+export declare const ACTIONS: readonly ["AUTHOR_REQ", "AUTHOR_HSPEC", "AUTHOR_ASPEC", "AUTHOR_CSPEC", "AUTHOR_TSPEC", "WRITE_TEST", "WRITE_CODE"];
+export type Action = (typeof ACTIONS)[number];
+export interface CheckResult {
+    decision: 'allow' | 'deny';
+    phase?: string;
+    missing?: string[];
+    remediation?: {
+        message: string;
+        next_action: string;
+        discipline: string;
+    };
+}
+/**
+ * Classify a write target. `p` must be PROJECT-RELATIVE (POSIX or Windows separators both fine).
+ *
+ * Relative matters for the test rules: several of them key on a directory segment, so an absolute
+ * path would let a project checked out under `/…/test/` classify its production code as tests —
+ * DOWNGRADING the gate, since WRITE_TEST does not require an approved T-SPEC. Callers that hold an
+ * absolute path make it relative first (see evaluateHook).
+ */
+export declare function classifyAction(p: string, content?: string): Action | null;
+export declare function phaseCheck(action: Action, ctx: {
+    specs: Spec[];
+    targetParentReqId?: string;
+    targetAspecId?: string;
+}): CheckResult;

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

@@ -0,0 +1,52 @@
+import { AxisVerdict, RiskAction, RiskAssessment, RiskThresholds } from './risk-types';
+export declare function rmCommandTargets(cmd: string): string[];
+/**
+ * Neutralise `.ax` paths that belong to ANOTHER project before the protected-path rules run.
+ *
+ * `.ax/specs` is this project's governance directory, and deleting it must stay non-bypassable. But
+ * the rules match the substring anywhere in a command, so `rm /other/project/.ax/cpg_cache/x.json`
+ * was gated too — found by dogfooding while cleaning up a scan cache left in a DIFFERENT repository,
+ * which is exactly what a user juggling several projects does every day. The governance claim only
+ * extends to this project's own `.ax`.
+ *
+ * Only ABSOLUTE paths outside the project root are masked. A relative `.ax/...` resolves against the
+ * project and stays protected, so nothing is weakened for the case the rule exists to cover. With no
+ * projectRoot supplied the command is returned unchanged — unknown scope stays conservative.
+ */
+export declare function scopeAxToProject(cmd: string, projectRoot?: string): string;
+/**
+ * Normalize a command string for protected-path matching: collapse `//` runs and `./` segments so
+ * `./.ax//ledger/x` matches the same rules as `.ax/ledger/x` (adversarial probe: those forms slipped
+ * every protected-path regex). Also flattens a leading `cd <dir> &&` so a cd-relative write
+ * (`cd .ax/ledger && cat > provenance.jsonl`) is seen against its real directory.
+ */
+export declare function normalizeCommandPaths(cmd: string): string;
+/**
+ * @implements A-SPEC-125.1
+ * Reversibility axis: can the action's effect be undone? Conservative default —
+ * unknown kinds and ambiguous (tracked===undefined) states never resolve to 'auto'.
+ */
+export declare function classifyReversibility(action: RiskAction): AxisVerdict;
+/**
+ * @implements A-SPEC-125.1
+ * Architecture axis: does this action reverse a previously accepted architectural decision?
+ */
+export declare function classifyArchitectureReversal(action: RiskAction): AxisVerdict;
+/**
+ * @implements A-SPEC-125.1
+ * Secret axis: does the staged content contain a credential-shaped string?
+ */
+export declare function classifySecret(action: RiskAction): AxisVerdict;
+/**
+ * @implements A-SPEC-125.3
+ * Blast-radius axis: how far does this change's impact ripple through the spec graph?
+ * The graph impact signal (`action.blastRadius`) is INJECTED by the caller — this function
+ * remains pure, performing no graph traversal or I/O of its own.
+ */
+export declare function classifyBlastRadius(action: RiskAction, cfg?: RiskThresholds): AxisVerdict;
+/**
+ * @implements A-SPEC-125.1
+ * Runs all four axes and folds them into a single overall risk assessment.
+ * Pure function: no I/O, no clocks, no randomness — same input always yields the same output.
+ */
+export declare function assessRisk(action: RiskAction, cfg?: RiskThresholds): RiskAssessment;

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

@@ -0,0 +1,77 @@
+import { RiskAssessment, RiskLevel } from './risk-types';
+export type Enforcement = 'block' | 'warn' | 'off';
+export interface Approval {
+    actor: string;
+    token: string;
+    rationale: string;
+    /** If present, the approval authorizes ONLY actions matching some entry (deny-by-default within). */
+    scope?: {
+        kind: string;
+        pattern: string;
+    }[];
+    /** ISO 8601. If present, the approval is dead once the action timestamp passes it. */
+    expires?: string;
+    /** If present, a hard-hitl grant is single-use: consumed on the ledger, a replay is denied. */
+    nonce?: string;
+}
+export interface GateResult {
+    blocked: boolean;
+    level: RiskLevel;
+    requiresApproval: boolean;
+    reasons: string[];
+}
+/** All of actor/token/rationale must be present and non-empty (whitespace-only counts as empty). */
+export declare function isValidApproval(a?: Approval): boolean;
+/**
+ * @implements A-SPEC-133
+ * Does this well-formed approval AUTHORIZE this specific action, right now? This is the seam P2
+ * adds beside isValidApproval: the gates ask "covers?" instead of "well-formed?", so one token
+ * stops being a master key. Pure — `now` is passed in (the action timestamp), never read from the
+ * clock, so the predicate stays deterministic and testable.
+ *
+ * - malformed → false (isValidApproval's meaning is preserved).
+ * - expired (epoch comparison, both operands must parse; unreadable expires OR now → false). Absent expires → no expiry.
+ * - scope present → true iff some entry FULL-matches (kind exact or `*`; the pattern is anchored
+ *   at both ends, `*` a wildcard run, trailing `/` a directory prefix). No entry matches → false: an existing-but-empty scope denies
+ *   everything, which is the safe reading of "scoped but matches nothing".
+ * - scope absent → true: the documented UNSCOPED master-key path (the operator's session token).
+ */
+export declare function approvalCovers(a: Approval | undefined, action: {
+    kind: string;
+    target: string;
+}, now: string): boolean;
+/**
+ * @implements A-SPEC-133
+ * Has this single-use nonce already been spent? Sync-reads the append-only provenance chain for a
+ * `nonce-consumed` entry carrying the nonce. A missing/unreadable ledger means nothing was consumed
+ * yet — false, never a throw (the gate must not crash on a fresh project).
+ */
+export declare function isNonceConsumed(nonce: string, ledgerFile: string): boolean;
+/**
+ * Graduated response for a bare risk level, with no notion of approval.
+ * Pure: no I/O, no clock, no randomness.
+ *
+ * `enforcement: 'off'` softens `confirm` to a clean pass, but MUST NOT soften
+ * `hard-hitl` -- that is the non-bypassable minimum this gate exists to guarantee.
+ */
+export declare function gradedResponse(level: RiskLevel, enforcement: Enforcement): GateResult;
+/**
+ * @implements A-SPEC-125.2
+ * Pure decision function: given a risk assessment, an optional out-of-band
+ * approval, and an enforcement mode, decides whether the action is blocked.
+ *
+ * No I/O and no ledger writes happen here -- recording a DecisionEvent is a
+ * separate caller step (see decision-ledger.ts), so a ledger write failure
+ * can never change the gate verdict.
+ *
+ * hard-hitl is non-bypassable: only a valid Approval (actor+token+rationale,
+ * all non-empty) unblocks it. enforcement:'off' softens confirm to a pass,
+ * but never softens hard-hitl.
+ */
+export declare function riskGate(assessment: RiskAssessment, approval?: Approval, enforcement?: Enforcement, cover?: {
+    action: {
+        kind: string;
+        target: string;
+    };
+    now: string;
+}): GateResult;