vigiles 10.0.0 → 12.0.0

package/dist/core/skill-resources.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.skillResourceIssues = skillResourceIssues;
+/**
+ * vigiles — SKILL bundled-resource resolution (the cross-reference moat applied
+ * to a SKILL.md body).
+ *
+ * A SKILL.md body is freeform markdown that routinely points the agent at LOCAL
+ * BUNDLED files shipped beside it — `scripts/foo.sh`, `references/api.md`,
+ * `[setup](./scripts/run.py)`, an inline `run \`scripts/setup.sh\``. When a
+ * referenced file doesn't exist on disk under the skill directory, the agent
+ * reads the instruction, gets nothing, and silently continues (a documented top
+ * skill pain — one practitioner found 59 broken refs across 192 files). vigiles
+ * already verifies file/script refs inside typed specs (core/refs.ts,
+ * core/doc-refs.ts) and intra-plugin script refs in the loader
+ * (plugin-loader.ts `danglingRefs`); this extends that to the SKILL.md body.
+ *
+ * HIGH-PRECISION / FP-SAFE, by the same don't-cry-wolf discipline the rest of
+ * vigiles holds (see `danglingRefs`/`isPluginRooted`): we flag ONLY references
+ * that are UNAMBIGUOUSLY a local bundled resource — a markdown link to a
+ * relative path with a file extension, or an explicit `scripts/`/`references/`/
+ * `assets/`-prefixed path (the Agent-Skills standard bundle dirs) with an
+ * extension. Everything else is skipped: URLs, absolute paths, `${VAR}`/`$VAR`
+ * tokens, `../` escapes, bare words with no extension or known prefix. Prefer
+ * MISSING a real ref over emitting a false positive — a noisy resource check
+ * would teach users to ignore it.
+ *
+ * Pure: the only IO is an injectable `existsSync` (default node:fs), mirroring
+ * core/refs.ts and the loader so the detector is testable with a fake.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+// ---------------------------------------------------------------------------
+// Shapes we match vs deliberately skip (FP-safety)
+// ---------------------------------------------------------------------------
+const FENCE = /^\s*(?:`{3,}|~{3,})/;
+// The Agent-Skills standard bundle subdirectories. A path PREFIXED by one of
+// these is unambiguously a local bundled resource, even without a `./`.
+const BUNDLE_DIRS = ["scripts", "references", "assets"];
+const BUNDLE_PREFIX = new RegExp(`^(?:${BUNDLE_DIRS.join("|")})/`);
+// A markdown inline link `[text](target)` — we read its target.
+const MD_LINK = /\[[^\]]*\]\(([^)\s]+)\)/g;
+// An inline-code path mention: a backtick span whose whole content is a single
+// path token. We only treat it as a ref when it is a bundle-dir-prefixed path
+// with an extension (the high-confidence shape); a bare `scripts` or a generic
+// `foo.ts` mention is NOT flagged.
+const INLINE_SPAN = /`([^`\n]+)`/g;
+// A path must carry a file extension to be a resource reference. A bare word or
+// a directory name (`scripts/lib`) is undecidable prose — skipped.
+const HAS_EXT = /\.[A-Za-z0-9]+$/;
+/**
+ * A reference target is a LOCAL BUNDLED RESOURCE worth resolving iff it is a
+ * relative path with a file extension AND is not one of the skip shapes. This is
+ * the single gate; both the link path and the inline-path path run through it.
+ */
+function localResourceTarget(rawTarget) {
+    // Strip a markdown link title / fragment / query if present, and trim.
+    const target = rawTarget.trim();
+    if (target.length === 0)
+        return null;
+    // SKIP: URLs (http://, https://, mailto:, any scheme://) — external.
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(target) || /^mailto:/i.test(target)) {
+        return null;
+    }
+    // SKIP: a pure anchor / fragment-only link (`#section`).
+    if (target.startsWith("#"))
+        return null;
+    // SKIP: absolute paths (`/etc/x`, Windows `C:\`) — not bundled-relative.
+    if (target.startsWith("/") || /^[A-Za-z]:[\\/]/.test(target))
+        return null;
+    // SKIP: variable tokens (`${CLAUDE_PLUGIN_ROOT}/x`, `$VAR/x`) — uncheckable,
+    // and almost always a plugin-root or runtime path, not a bundled file.
+    if (target.includes("$"))
+        return null;
+    // Drop a URL fragment / query suffix so `references/api.md#auth` resolves to
+    // the file. (Only after the scheme check above, so we never mangle a URL.)
+    const path = target.replace(/[?#].*$/, "");
+    if (path.length === 0)
+        return null;
+    // SKIP: a `../` escape OUT of the skill dir — undecidable / not a bundled
+    // resource (it points at a sibling skill or the repo). A leading `./` is fine.
+    const normalized = path.replace(/^\.\//, "");
+    if (normalized.startsWith("../") || normalized.includes("/../"))
+        return null;
+    // Must look like a file (have an extension), else it's a dir/prose mention.
+    if (!HAS_EXT.test(normalized))
+        return null;
+    return normalized;
+}
+/**
+ * Whether an inline-code path token is high-confidence enough to flag on its
+ * own (no surrounding `[..](..)` link syntax). We require a BUNDLE-DIR PREFIX
+ * (`scripts/`, `references/`, `assets/`) so a generic `` `config.json` `` or a
+ * `` `src/foo.ts` `` API mention in prose is never flagged — only the standard
+ * bundle layout, which is unambiguously a shipped resource.
+ */
+function isInlineBundlePath(token) {
+    const t = token.trim();
+    // A single token only — a span with spaces is a command/prose, not a path.
+    if (/\s/.test(t))
+        return false;
+    const normalized = t.replace(/^\.\//, "");
+    return BUNDLE_PREFIX.test(normalized) && HAS_EXT.test(normalized);
+}
+/** Collect candidate bundled-resource refs from one body line, skipping fences. */
+function candidatesInLine(line, lineNo) {
+    const out = [];
+    // Markdown links: any relative path target that passes the local-resource gate.
+    for (const m of line.matchAll(MD_LINK)) {
+        const resolved = localResourceTarget(m[1]);
+        if (resolved !== null) {
+            out.push({ ref: m[1].trim(), resolved, kind: "link", line: lineNo });
+        }
+    }
+    // Inline-code path mentions: only the high-confidence bundle-dir-prefixed form.
+    for (const m of line.matchAll(INLINE_SPAN)) {
+        const token = m[1].trim();
+        if (!isInlineBundlePath(token))
+            continue;
+        const resolved = localResourceTarget(token);
+        if (resolved !== null) {
+            out.push({ ref: token, resolved, kind: "path", line: lineNo });
+        }
+    }
+    return out;
+}
+/**
+ * The bundled-resource references in a SKILL.md body that don't resolve on disk
+ * under `skillDir`. Pure + FP-safe (see the module header). `skillDir` is the
+ * directory the SKILL.md itself lives in (resources are bundled beside it).
+ *
+ * The shared detector behind both `vigiles lint` (the `skill-resource-resolves`
+ * rule) and `vigiles audit` (the read-only report) — one detector, no drift.
+ */
+function skillResourceIssues(skillBody, skillDir, opts = {}) {
+    const exists = opts.existsSync ?? node_fs_1.existsSync;
+    const findings = [];
+    const seen = new Set();
+    const lines = skillBody.split("\n");
+    let inFence = false;
+    for (let i = 0; i < lines.length; i++) {
+        if (FENCE.test(lines[i])) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        for (const c of candidatesInLine(lines[i], i + 1)) {
+            const full = (0, node_path_1.resolve)(skillDir, c.resolved);
+            if (exists(full))
+                continue;
+            // De-dupe the same missing file referenced several times in the body.
+            const key = `${c.kind}:${c.resolved}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            findings.push({
+                ref: c.ref,
+                resolved: c.resolved,
+                kind: c.kind,
+                line: c.line,
+            });
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=skill-resources.js.map

package/dist/core/types.d.ts

@@ -220,6 +220,77 @@ export interface RulesConfig {
      * as `scan` (mcpHookIssues).
      */
     "mcp-hook-target-resolves"?: RuleSeverity;
+    /**
+     * Flag a unit (subagent / model-invocable skill) whose declared tools hold all
+     * THREE legs of Simon Willison's "lethal trifecta" — read private data, ingest
+     * untrusted content, AND exfiltrate — a prompt-injection exfil path with no
+     * exploit code (Meta's Rule of Two: allow at most two). A capability SET-
+     * intersection over the declared contract, NOT a text scan; high-precision (only
+     * well-known tools map to a leg). An EXPLICIT all-three contract is a "hard"
+     * finding; an inherits-all unit (no contract → every leg) is "advisory". Default
+     * "warn" (don't-cry-wolf rollout); raise to "error" to gate CI. Same detector as
+     * `scan` (lethalTrifectaIssues). See docs/rules/lethal-trifecta.md.
+     */
+    "lethal-trifecta"?: RuleSeverity;
+    /**
+     * Flag a SKILL.md body referencing a bundled file (`scripts/`/`references/`/
+     * `assets/`, or a relative markdown link with an extension) that doesn't exist
+     * on disk under the skill dir — the agent reads the instruction, gets nothing,
+     * and silently continues. The cross-reference moat applied to the SKILL.md body.
+     * High-precision / FP-safe (skips URLs, `$VAR` tokens, `../` escapes, extension-
+     * less mentions). Default "warn"; raise to "error" to gate CI. Same detector as
+     * `scan` (skillResourceIssues). See docs/rules/skill-resource-resolves.md.
+     */
+    "skill-resource-resolves"?: RuleSeverity;
+    /**
+     * Flag a SKILL.md that opens with frontmatter-looking keys (`name:`,
+     * `description:`, …) but has NO opening `---` fence — the harness loads the
+     * whole file as body, so the skill has no name/description/trigger and is
+     * invisible (never fires). High-precision (a fixed key whitelist; markdown /
+     * prose lines never match). Default "warn"; raise to "error" to gate CI. Same
+     * detector as `scan` (skillFenceIssues). See docs/rules/skill-missing-fence.md.
+     */
+    "skill-missing-fence"?: RuleSeverity;
+    /**
+     * Flag a functional surface directory (skills/agents/commands) nested INSIDE
+     * the `.claude-plugin/` manifest dir, where only `plugin.json` belongs — the
+     * harness can't see it, so the surface is invisible (the #1 plugin-author
+     * mistake). Pure filesystem check, FP-safe. Default "warn"; raise to "error"
+     * to gate CI. Same detector as `scan` (pluginLayoutIssues). See
+     * docs/rules/plugin-dir-layout.md.
+     */
+    "plugin-dir-layout"?: RuleSeverity;
+    /**
+     * Flag a lethal trifecta that EMERGES across a delegation edge — a subagent
+     * whose effective (own ∪ delegated-to) capability holds all three legs though
+     * no single unit does (the combined blast radius). The capability-diff across
+     * the delegation tree; skips units the per-unit `lethal-trifecta` already
+     * flags (no double-report), FP-safe (explicit edges, wildcard-guarded). Default
+     * "warn"; raise to "error" to gate CI. Same detector as `scan`
+     * (delegationTrifecta). See docs/rules/delegation-trifecta.md.
+     */
+    "delegation-trifecta"?: RuleSeverity;
+    /**
+     * Flag a hook that LOOKS like it blocks but silently doesn't — a block decision
+     * (`exit 2` / `decision` / `permissionDecision`) on an event that can't veto, or
+     * the legacy top-level `decision` field on a permission-gated event where only
+     * `hookSpecificOutput.permissionDecision` works (#19009, the #1 verified hook
+     * pain). FP-safe (conservative literal patterns; the blocking-event sets are
+     * read from the dialect, so it runs only where they're declared). Default "warn";
+     * raise to "error" to gate CI. Same detector as `scan` (hookBlockFindings). See
+     * docs/rules/hook-block-ineffective.md.
+     */
+    "hook-block-ineffective"?: RuleSeverity;
+    /**
+     * Flag a hook `matcher` string that silently never fires — a close typo of a
+     * built-in tool (`bash`→`Bash`), or a malformed/undeclared MCP form
+     * (`mcp_memory_*` instead of `mcp__memory__.*`, or a server the plugin doesn't
+     * declare). High-precision (close-typo only; MCP gated on a declared set,
+     * built-ins allowlisted; wildcards/regex skipped). Default "warn"; raise to
+     * "error" to gate CI. Same detector as `scan` (hookMatcherFindings). See
+     * docs/rules/hook-matcher.md.
+     */
+    "hook-matcher"?: RuleSeverity;
 }
 /** Extract severity from a rule value (handles both simple and tuple forms). */
 export declare function ruleSeverity<T>(rule: RuleWithOptions<T> | undefined): RuleSeverity;
@@ -275,6 +346,18 @@ export interface VigilesConfig {
     audit?: {
         measure?: boolean;
     };
+    /**
+     * `vigiles eval` preferences. `apiVersion` is the hand-bumped **behavior epoch**
+     * folded into the eval LOCK's input hash (`src/eval-lock.ts`): bump it when a
+     * harness-side change YOU made (a CLAUDE.md edit, a global hook) would shift
+     * eval outputs but isn't otherwise visible to the lock — so `vigiles eval
+     * --check` reports the committed eval results STALE and forces a local re-run.
+     * Default 1. Distinct from the (auto-resolved) `claude` CLI version, which is
+     * recorded as provenance but deliberately NOT hashed.
+     */
+    eval?: {
+        apiVersion?: number;
+    };
 }
 /** Valid marker types for rule detection. */
 export type MarkerType = "headings" | "checkboxes";

package/dist/core/validate.d.ts

@@ -1,5 +1,6 @@
 import type { ParsedRule, ValidationError, ValidationResult, ReadResult, FileResult, ValidatePathsResult, RulesConfig, VigilesConfig, MarkerType, ParseOptions, ValidateOptions, ValidatePathsOptions, ReadOptions } from "./types.js";
 export type { ParsedRule, ValidationError, ValidationResult, ReadResult, FileResult, ValidatePathsResult, RulesConfig, VigilesConfig, MarkerType, ParseOptions, ValidateOptions, ValidatePathsOptions, ReadOptions, };
+export declare const DEFAULT_RULES: Required<RulesConfig>;
 export declare function findInstructionFiles(cwd?: string, configFiles?: string[]): string[];
 export declare function loadConfig(): VigilesConfig;
 export declare function parseRules(content: string, { ruleMarkers }?: ParseOptions): ParsedRule[];

package/dist/core/validate.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RULES = void 0;
 exports.findInstructionFiles = findInstructionFiles;
 exports.loadConfig = loadConfig;
 exports.parseRules = parseRules;
@@ -28,7 +29,7 @@ const VALID_MARKERS = ["headings", "checkboxes"];
 const INSTRUCTION_FILES = ["CLAUDE.md", "AGENTS.md"];
 // The default instruction file to validate when no config names one.
 const DEFAULT_FILES = [INSTRUCTION_FILES[0]];
-const DEFAULT_RULES = {
+exports.DEFAULT_RULES = {
     "require-instructions-spec": "warn",
     // Default OFF — the consistent `require-<surface>-spec` parallel. Skills are
     // legitimately hand-written, so requiring a .spec.ts per SKILL.md is the wrong
@@ -70,10 +71,31 @@ const DEFAULT_RULES = {
     "frontmatter-valid": "warn",
     // A mcp_tool hook incomplete / targeting an undeclared server — on by default at warn.
     "mcp-hook-target-resolves": "warn",
+    // Lethal-trifecta capability set-intersection (read-private + ingest-untrusted +
+    // exfiltrate in one unit) — WARN by default (don't-cry-wolf rollout); raise to error.
+    "lethal-trifecta": "warn",
+    // A SKILL.md body referencing a missing bundled resource — WARN by default
+    // (don't-cry-wolf rollout, FP-safe); raise to error to gate CI.
+    "skill-resource-resolves": "warn",
+    // A SKILL.md missing its opening `---` fence (invisible skill) — WARN by
+    // default (FP-safe key whitelist); raise to error to gate CI.
+    "skill-missing-fence": "warn",
+    // Functional dirs nested inside `.claude-plugin/` (invisible surfaces) — WARN
+    // by default; raise to error to gate CI.
+    "plugin-dir-layout": "warn",
+    // A lethal trifecta emerging across a delegation edge (combined blast radius) —
+    // WARN by default (don't-cry-wolf rollout); raise to error to gate CI.
+    "delegation-trifecta": "warn",
+    // A hook that looks like it blocks but silently doesn't (#19009) — WARN by
+    // default (FP-safe literal patterns); raise to error to gate CI.
+    "hook-block-ineffective": "warn",
+    // A hook matcher that never fires (tool typo / wrong MCP form) — WARN by
+    // default (high-precision); raise to error to gate CI.
+    "hook-matcher": "warn",
 };
 const DEFAULT_CONFIG = {
     ruleMarkers: ["headings", "checkboxes"],
-    rules: DEFAULT_RULES,
+    rules: exports.DEFAULT_RULES,
     files: DEFAULT_FILES,
 };
 // ---------------------------------------------------------------------------
@@ -99,7 +121,7 @@ function loadConfig() {
         const config = {
             ...DEFAULT_CONFIG,
             ...userConfig,
-            rules: { ...DEFAULT_RULES, ...userConfig.rules },
+            rules: { ...exports.DEFAULT_RULES, ...userConfig.rules },
             files: Array.isArray(userConfig.files) ? userConfig.files : DEFAULT_FILES,
         };
         if (!Array.isArray(config.ruleMarkers) ||
@@ -170,7 +192,7 @@ function parseRules(content, { ruleMarkers } = {}) {
 // Core validation
 // ---------------------------------------------------------------------------
 function validate(content, { ruleMarkers, rules: rulesConfig, filePath, dialect } = {}) {
-    const activeRules = rulesConfig ?? DEFAULT_RULES;
+    const activeRules = rulesConfig ?? exports.DEFAULT_RULES;
     const parsedRules = parseRules(content, { ruleMarkers });
     const enforced = parsedRules.filter((r) => r.enforcement === "enforced").length;
     const guidanceOnly = parsedRules.filter((r) => r.enforcement === "guidance").length;

package/dist/eval-cache.d.ts

@@ -43,6 +43,12 @@ export interface CacheRecord {
     /** Text files present in the cwd after the run (relative path → contents). */
     readonly files: Record<string, string>;
 }
+/**
+ * Canonicalize a value so the key is stable regardless of object key order —
+ * recursively sorts object keys. Arrays keep order (it's significant for tools).
+ * Exported so the eval LOCK ({@link ./eval-lock}) hashes its inputs the same way.
+ */
+export declare function canonical(value: unknown): unknown;
 /**
  * Cache record-format version, SALTED into every key (Jest `CACHE_VERSION` /
  * webpack `cache.version` pattern). Bump when the `CacheRecord` shape — or how a

package/dist/eval-cache.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CACHE_FORMAT_VERSION = void 0;
+exports.canonical = canonical;
 exports.cacheKey = cacheKey;
 exports.readCache = readCache;
 exports.writeCache = writeCache;
@@ -32,6 +33,7 @@ const SKIP_DIRS = new Set(["node_modules", ".git"]);
 /**
  * Canonicalize a value so the key is stable regardless of object key order —
  * recursively sorts object keys. Arrays keep order (it's significant for tools).
+ * Exported so the eval LOCK ({@link ./eval-lock}) hashes its inputs the same way.
  */
 function canonical(value) {
     if (Array.isArray(value))

package/dist/eval-lock.d.ts

@@ -0,0 +1,192 @@
+import { type SHA256Hash } from "./core/hash.js";
+/** Lock mode: never touch the lock / verify-only (CI) / record-and-write (local). */
+export type LockMode = "off" | "check" | "update";
+/**
+ * Per-spec lock overrides (additive on `EvalSpec`/`TriggerRateSpec`). Normally the
+ * mode comes from the CLI (`eval --check`/`--update` → `VIGILES_EVAL_LOCK`) and
+ * the dir/epoch from defaults/config; set these to drive the lock programmatically
+ * (or to point a test at a throwaway dir). Each field falls back to its env/default.
+ */
+export interface EvalLockOptions {
+    /** Override the lock mode (else `VIGILES_EVAL_LOCK`, else `off`). */
+    readonly mode?: LockMode;
+    /** Override the lock directory (else `<cwd>/.vigiles/eval-locks`). */
+    readonly dir?: string;
+    /** Override the behavior epoch (else `VIGILES_EVAL_API_VERSION`, else 1). */
+    readonly evalApiVersion?: number;
+}
+/**
+ * On-disk lock-format version, salted into nothing (the lock is keyed by name,
+ * not by hash) but VALIDATED on read so an incompatible shape fails loud rather
+ * than deserializing into a stale structure. Bump on a breaking shape change.
+ */
+export declare const LOCK_VERSION = 1;
+/** Default directory for committed eval locks (tracked, NOT gitignored). */
+export declare const DEFAULT_LOCK_DIR = ".vigiles/eval-locks";
+/**
+ * The model-affecting inputs hashed into a lock's `inputsHash`. Everything here
+ * is something that, if it changes, means the recorded model behavior is stale
+ * and you MUST re-drive the model (→ subscription → local). Deliberately EXCLUDED:
+ * the scoring `measure`/assertions (re-run live against the replayed report), the
+ * trial count (a sample-size knob, not a behavior input), and per-run env noise.
+ */
+export interface EvalLockInputs {
+    /** Model id used (folded in; a floating alias can't detect weight drift — warned). */
+    readonly model: string;
+    /**
+     * A hand-bumped behavior epoch the project owns (`.vigilesrc.json`
+     * `eval.apiVersion`), bumped when a harness-side change YOU made (a CLAUDE.md
+     * edit, a global hook) would shift eval outputs but isn't otherwise in the
+     * inputs. The escape hatch for "force a re-eval."
+     */
+    readonly evalApiVersion: number;
+    /**
+     * The seam-specific canonical input object — the tasks/prompts/files/settings/
+     * sorted-tools/pluginDirHash/serialized-checks that steer the model. Assembled
+     * by each entry point (it knows its own shape) and hashed opaquely here.
+     */
+    readonly inputs: unknown;
+}
+/**
+ * Why the harness binary version is **NOT** hashed (only recorded as provenance):
+ * `--check` runs in CI where `claude` is PINNED to a fixed version, while a dev's
+ * local `claude` is whatever they have — folding the version into the hash would
+ * false-trip `--check` on every PR where those differ. It is also the lock's
+ * honest scope: the gate verifies your committed results match your current
+ * *author-controlled inputs*, not current model/harness behavior (there is no
+ * automated live run). Harness/model drift is caught when YOU re-run `--update`
+ * locally and review the moved numbers in the git diff. Keeping the version out
+ * of the hash is what lets `--check` stay binary-free + deterministic in CI.
+ * (The eval CACHE still keys on it — that's local replay soundness, a different
+ * axis.) See research/cache-invalidation.md.
+ */
+/** Deterministic content hash of a lock's model-affecting inputs. */
+export declare function evalInputsHash(input: EvalLockInputs): SHA256Hash;
+/** A committed eval lock: the integrity stamp + the replayable recorded report. */
+export interface EvalLock {
+    readonly version: number;
+    /** The eval's report name (human-facing; also the lock filename slug source). */
+    readonly name: string;
+    /** Hash of the model-affecting inputs ({@link evalInputsHash}). */
+    readonly inputsHash: string;
+    /** The model id the report was produced against (for the drift warning). */
+    readonly model: string;
+    /** The harness version token at record time (provenance; already in the hash). */
+    readonly harnessVersionKey: string;
+    /** The behavior epoch at record time (provenance; already in the hash). */
+    readonly evalApiVersion: number;
+    /** ISO-8601 timestamp the lock was recorded (provenance; NOT in the hash). */
+    readonly builtAt: string;
+    /**
+     * The entry point's recorded report — the model's observed behavior, REPLAYED
+     * verbatim on `--check` so the script's own assertions judge it. Stored as the
+     * exact return type of the entry point (`EvalReport` / `TriggerRateReport` /
+     * `CheckReport`) so replay is transparent to the caller.
+     */
+    readonly report: unknown;
+}
+/** Filesystem-safe slug for a report name (the lock filename). */
+export declare function lockSlug(name: string): string;
+/** Path to a named eval's lock file under `dir`. */
+export declare function lockPath(dir: string, name: string): string;
+/**
+ * Read a named eval's lock. A MISS (no file) returns `null`. A CORRUPT or
+ * wrong-version file **throws** — a broken lock is a real failure the CI gate
+ * must surface, not silently treat as "no lock" (which would let a stale eval
+ * pass). The message says how to recover.
+ */
+export declare function readLock(dir: string, name: string): EvalLock | null;
+/**
+ * Whether ANY lock has been committed under `dir`. The CI staleness gate
+ * (`eval --check`) uses this to stay a NO-OP until the feature is in use: a repo
+ * that has never run `eval --update` has no locks, so there is nothing to verify
+ * and CI passes green. Once the first lock is committed, every named eval is held
+ * to having a fresh one (a new unlocked eval then reads as stale). The graduated,
+ * opt-in-by-committing behavior that keeps a fresh `init` from going red.
+ */
+export declare function anyLocksCommitted(dir: string): boolean;
+/**
+ * Does an edited path plausibly change an eval's INPUTS — so a committed lock may
+ * now be stale? Two surfaces feed the hash: a skill's trigger surface (`SKILL.md`)
+ * and the eval script that holds the prompts/spec (`*.eval.{mjs,cjs,js,mts,cts,ts}`).
+ * Pure (string-only) so the nudge hook stays cheap and never runs an eval script.
+ */
+export declare function isEvalInputFile(path: string): boolean;
+/**
+ * The NON-BLOCKING nudge to emit after an eval-input edit when committed locks
+ * exist, or `null` for no nudge. Self-gating: it stays silent until you've opted
+ * into the lock (committed one), so it can't annoy a repo that doesn't use evals.
+ * It deliberately does NOT recompute staleness (that needs the eval script + is
+ * the job of `eval --check`) — a reminder, not a gate. The honest harness-neutral
+ * reminder; how it reaches the agent (both CC and Codex inject `additionalContext`
+ * on `PostToolUse`) is the caller's concern. See docs/harness-testing-*.md.
+ */
+export declare function evalLockNudge(filePath: string, lockDir: string): string | null;
+/** Write a named eval's lock (pretty JSON for a reviewable git diff). */
+export declare function writeLock(dir: string, lock: EvalLock): void;
+/**
+ * Build a fresh lock envelope from a just-recorded report (the `--update` write).
+ * `builtAt` is passed in (never read from the clock here) so the module stays
+ * pure + deterministically testable; the CLI stamps the real timestamp.
+ */
+export declare function buildLock(args: {
+    readonly name: string;
+    readonly inputsHash: string;
+    readonly model: string;
+    readonly harnessVersionKey: string;
+    readonly evalApiVersion: number;
+    readonly builtAt: string;
+    readonly report: unknown;
+}): EvalLock;
+/** What the lock layer decides an entry point should do for this run. */
+export type LockDecision = 
+/** Drive the model normally (mode `off`, or `update`, or `check` with no lock-skip). */
+{
+    readonly kind: "run";
+}
+/** `check` + a matching fresh lock → return the recorded report, NO model call. */
+ | {
+    readonly kind: "replay";
+    readonly report: unknown;
+}
+/** `check` + a missing/stale lock → fail; the caller throws `reason`. */
+ | {
+    readonly kind: "stale";
+    readonly reason: string;
+};
+/**
+ * Decide what `check` mode should do given the current input hash and the
+ * committed lock. `off`/`update` always `run` (update records afterwards). `check`
+ * replays a matching lock (no model) and is `stale` on a missing lock or a hash
+ * mismatch — the deterministic CI gate.
+ */
+export declare function decideLock(mode: LockMode, name: string, currentHash: string, existing: EvalLock | null): LockDecision;
+/** A single numeric leaf that moved between the prior lock and a fresh `--update`. */
+export interface NumberDelta {
+    readonly path: string;
+    readonly before: number;
+    readonly after: number;
+}
+/**
+ * Collect the numeric leaves that changed between two recorded reports — the
+ * human-facing delta printed at `--update` time (e.g. `rate: 0.900 → 0.650`).
+ * Generic over any report shape (walks numbers by dotted path), so it works for
+ * `EvalReport`, `TriggerRateReport`, and `CheckReport` without per-type code. The
+ * committed git diff is the primary review surface; this is the at-a-glance echo.
+ */
+export declare function diffReportNumbers(before: unknown, after: unknown): NumberDelta[];
+/** Render the `--update` result for a human: NEW lock, or the per-number deltas. */
+export declare function formatLockUpdate(name: string, deltas: readonly NumberDelta[], isNew: boolean): string;
+/**
+ * Read the lock mode from the environment (`VIGILES_EVAL_LOCK`), set by the CLI's
+ * `eval --check` / `--update` flags. A run knob (like `VIGILES_TRIALS`): the CLI
+ * is the only place that should set it. Anything unrecognized → `off`.
+ */
+export declare function lockModeFromEnv(env?: NodeJS.ProcessEnv): LockMode;
+/**
+ * The behavior epoch (`evalApiVersion`) for this run, read from the env the CLI
+ * populates from `.vigilesrc.json` `eval.apiVersion`. Default 1. A malformed
+ * value falls back to 1 (never throws) — the lock stays usable.
+ */
+export declare function evalApiVersionFromEnv(env?: NodeJS.ProcessEnv): number;
+//# sourceMappingURL=eval-lock.d.ts.map