vigiles 4.0.2 → 5.0.0

package/dist/cli.js

@@ -21,9 +21,9 @@ const types_js_1 = require("./core/types.js");
 const test_coverage_js_1 = require("./test-coverage.js");
 const scan_js_1 = require("./scan.js");
 const adapter_registry_js_1 = require("./adapter-registry.js");
+const skill_harness_js_1 = require("./skill-harness.js");
 const leaderboard_js_1 = require("./leaderboard.js");
 const compile_js_1 = require("./core/compile.js");
-const dialect_js_1 = require("./adapters/claude-code/dialect.js");
 const proofs_js_1 = require("./core/proofs.js");
 const inline_js_1 = require("./core/inline.js");
 const frontmatter_js_1 = require("./core/frontmatter.js");
@@ -32,6 +32,7 @@ const compose_js_1 = require("./core/compose.js");
 const compile_generator_js_1 = require("./core/compile-generator.js");
 const action_gate_js_1 = require("./action-gate.js");
 const agent_runtime_js_1 = require("./adapters/claude-code/agent-runtime.js");
+const tool_intercept_js_1 = require("./tool-intercept.js");
 const refs_js_1 = require("./core/refs.js");
 const mcp_js_1 = require("./core/mcp.js");
 const skill_runtime_js_1 = require("./adapters/claude-code/skill-runtime.js");
@@ -140,12 +141,12 @@ function compileGeneratorSkillToFile(specPath, source) {
     return false;
 }
 /** Compile a ClaudeSpec → its primary + any additional targets. */
-function compileClaudeToFile(spec, specPath, config) {
+function compileClaudeToFile(spec, specPath, config, dialect) {
     const basePath = process.cwd();
     const { markdown, errors, linterResults, targets } = (0, compile_js_1.compileClaude)(spec, {
         basePath,
         specFile: specPath,
-        dialect: dialect_js_1.claudeCodeDialect,
+        dialect,
         maxRules: config.maxRules,
         maxTokens: config.maxTokens,
         maxSectionLines: config.maxSectionLines,
@@ -175,15 +176,54 @@ function compileClaudeToFile(spec, specPath, config) {
     console.log(`  ${String(Object.keys(spec.rules).length)} rules (${String(linterCount)} linter-verified)`);
     return true;
 }
+/**
+ * Branch 3 of the mirror story (research/multi-harness-compile.md): when a repo
+ * declares ≥2 harnesses and nothing else fans out the instruction file, write a
+ * byte-identical copy to each other harness's instruction file (e.g. CLAUDE.md →
+ * AGENTS.md). A copy — not a symlink — because it works everywhere and carries
+ * the source's embedded integrity hash by construction, so a hand-edit of the
+ * mirror trips the existing `integrity` check. Never fights a sync tool or
+ * clobbers a target that owns its own spec.
+ */
+function writeInstructionMirrors(primaryOutput, harnesses) {
+    if (harnesses.length < 2)
+        return;
+    const cwd = process.cwd();
+    // A sync tool (Ruler/rulesync) owns fan-out — don't fight it.
+    if ((0, compose_js_1.detectSyncTools)(cwd).length > 0)
+        return;
+    const primaryName = (0, node_path_1.basename)(primaryOutput);
+    const primaryAbs = (0, node_path_1.resolve)(cwd, primaryOutput);
+    if (!(0, node_fs_1.existsSync)(primaryAbs))
+        return;
+    const content = (0, node_fs_1.readFileSync)(primaryAbs, "utf-8");
+    for (const name of harnesses) {
+        const adapter = (0, adapter_registry_js_1.getAdapter)(name);
+        if (!adapter)
+            continue;
+        const target = adapter.layout.instructionFile;
+        if (target === primaryName)
+            continue; // the file we just compiled
+        // Never clobber a target that has its own spec (a genuinely separate file).
+        if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, `${target}.spec.ts`)))
+            continue;
+        const targetAbs = (0, node_path_1.resolve)(cwd, target);
+        if ((0, node_fs_1.existsSync)(targetAbs) && (0, node_fs_1.readFileSync)(targetAbs, "utf-8") === content) {
+            continue; // already byte-identical
+        }
+        (0, node_fs_1.writeFileSync)(targetAbs, content);
+        console.log(`  ↳ mirrored ${primaryName} → ${target} (byte-identical)`);
+    }
+}
 /** Compile a declarative SkillSpec → SKILL.md. */
-function compileSkillToFile(spec, specPath) {
+function compileSkillToFile(spec, specPath, dialect) {
     const outputPath = specPath.replace(/\.spec\.ts$/, "");
     const { markdown, errors } = (0, compile_js_1.compileSkill)(spec, {
         basePath: process.cwd(),
         specFile: specPath,
-        // Pick the SKILL.md frontmatter profile from the detected harness — a Codex
+        // The SKILL.md frontmatter profile comes from the resolved harness — a Codex
         // repo gets a minimal (name + description) SKILL.md; CC gets the full set.
-        dialect: (0, adapter_registry_js_1.detectAdapter)(process.cwd()).dialect,
+        dialect,
     });
     (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
     if (errors.length === 0) {
@@ -195,12 +235,12 @@ function compileSkillToFile(spec, specPath) {
     return false;
 }
 /** Compile a subagent spec → agents/<name>.md (with its result-contract section). */
-function compileAgentToFile(spec, specPath) {
+function compileAgentToFile(spec, specPath, dialect) {
     const outputPath = specPath.replace(/\.spec\.ts$/, "");
     const { markdown, errors } = (0, compile_js_1.compileAgent)(spec, {
         basePath: process.cwd(),
         specFile: specPath,
-        dialect: (0, adapter_registry_js_1.detectAdapter)(process.cwd()).dialect,
+        dialect,
     });
     (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
     if (errors.length === 0) {
@@ -241,8 +281,21 @@ async function collectAgentNames() {
     }
     return names;
 }
-async function compile(specPaths, config) {
+async function compile(specPaths, config, opts = {}) {
     let allValid = true;
+    // Parse the declared harness set ONCE (alias-normalized) and feed both the
+    // dialect pick and the mirror from it — no re-parsing, no cwd-sniffing in the
+    // helpers. A loud notice (never a silent guess) on a multi-harness or
+    // ambiguous-detection pick.
+    const declaredHarnesses = (0, adapter_registry_js_1.normalizeHarnessList)(config.harness);
+    const selection = (0, adapter_registry_js_1.resolveHarnessSelection)({
+        root: process.cwd(),
+        flag: opts.harnessFlag,
+        configHarness: declaredHarnesses,
+    });
+    if (selection.kind === "notice")
+        console.log(`⚠ ${selection.notice}`);
+    const dialect = selection.adapter.dialect;
     // Resolved lazily on the first railway spec — every delegate() target is
     // checked against the agents defined anywhere in the project.
     let knownAgents = null;
@@ -262,15 +315,36 @@ async function compile(specPaths, config) {
             continue;
         }
         if (spec._specType === "claude") {
-            if (!compileClaudeToFile(spec, specPath, config))
+            // Spec-target disambiguation: a CLAUDE.md.spec.ts is a claude-code file, an
+            // AGENTS.md.spec.ts a codex one — the strongest dialect signal for THIS
+            // spec. The flag still overrides; absent one, the spec's own target wins
+            // over config/detect. (Skill/agent targets don't name a harness, so they
+            // keep the run-level dialect.)
+            const targetFile = (0, node_path_1.basename)(specPath).replace(/\.spec\.ts$/, "");
+            const specDialect = opts.harnessFlag === undefined
+                ? ((0, adapter_registry_js_1.adapterForInstructionFile)(targetFile)?.dialect ?? dialect)
+                : dialect;
+            if (compileClaudeToFile(spec, specPath, config, specDialect)) {
+                writeInstructionMirrors(specPath.replace(/\.spec\.ts$/, ""), declaredHarnesses);
+            }
+            else {
                 allValid = false;
+            }
         }
         else if (spec._specType === "skill") {
-            if (!compileSkillToFile(spec, specPath))
+            // Cross-harness verify: flag CC-only frontmatter a declared minimal-profile
+            // harness (Codex/OpenCode) would silently drop.
+            const forHarnesses = declaredHarnesses.length > 0
+                ? declaredHarnesses
+                : [selection.adapter.name];
+            for (const w of (0, skill_harness_js_1.skillFrontmatterDropWarnings)(spec, forHarnesses)) {
+                console.log(`⚠ ${w}`);
+            }
+            if (!compileSkillToFile(spec, specPath, dialect))
                 allValid = false;
         }
         else if (spec._specType === "agent") {
-            if (!compileAgentToFile(spec, specPath))
+            if (!compileAgentToFile(spec, specPath, dialect))
                 allValid = false;
         }
         else if (spec._specType === "railway") {
@@ -836,8 +910,8 @@ async function runLint(restArgs, flags, config) {
         }
     }
     // 7b. Untested-surface check — skills/agents/hooks shipping without a test or
-    // eval. Warning by default (a nudge, exit 0); set rules.untested-surface to
-    // "error" to gate CI. See src/test-coverage.ts and docs/rules/untested-surface.md.
+    // eval. Warning by default (a nudge, exit 0); set rules.untested-{skill,agent,
+    // hook} to "error" to gate CI. See src/test-coverage.ts and docs/rules/.
     const untested = checkUntestedSurfaces(config, silent);
     // 8. Validate vigiles builder calls inside markdown code blocks. Default
     // is to validate every ref; illustrative blocks opt out via
@@ -851,6 +925,16 @@ async function runLint(restArgs, flags, config) {
             console.log(`  ${line}`);
         }
     }
+    // Per-line GitHub annotations for each broken doc ref — each carries file+line,
+    // so GitHub renders it INLINE on the PR diff (not just in the summary blob).
+    // Previously this check reported to stdout only; the inline/spec checks already
+    // annotate per-line, so this closes the gap that left doc-ref findings invisible
+    // on the PR. CI-only (isGitHubActions); skipped under --json/--summary.
+    if (isGitHubActions() && !silent) {
+        for (const e of docRefReport.errors) {
+            ghAnnotate("error", `${e.kind}("${e.value}") — ${e.message}`, e.file, e.line);
+        }
+    }
     // 9. Verify code-shaped symbol references live (see src/refs.ts).
     const symbolRefErrors = verifyMarkdownSymbols(files, silent);
     // 10. Verify `vigiles:mcp server#tool` marks against live MCP servers
@@ -1735,16 +1819,44 @@ async function setup(args) {
         console.log("\n  Non-markdown agent configs detected. Use a sync tool to convert:");
         console.log("    npm install -D rule-porter");
     }
-    // Strict config.
-    if (strict) {
-        const configPath = (0, node_path_1.resolve)(process.cwd(), ".vigilesrc.json");
-        if (!(0, node_fs_1.existsSync)(configPath)) {
-            (0, node_fs_1.writeFileSync)(configPath, JSON.stringify({ rules: { "require-spec": "error", "require-skill-spec": "error" } }, null, 2) + "\n");
-            console.log("✓ Created .vigilesrc.json with strict rules");
-            written.push(".vigilesrc.json");
+    // Project config — record the harness(es) so compile/lint select the dialect
+    // deterministically (no cwd sniffing), plus strict rule severities on --strict.
+    writeProjectConfig({ harnesses, strict, written });
+    printSetupSummary({ plan, strict, targets, needsMigration, written });
+}
+/** Canonical, de-duplicated harness list → a config value (string when one). */
+function harnessConfigValue(harnesses) {
+    const canon = [...new Set(harnesses.map(adapter_registry_js_1.normalizeHarnessName))];
+    return canon.length === 1 ? canon[0] : canon;
+}
+/**
+ * Merge the resolved harness(es) (and strict rule severities) into
+ * `.vigilesrc.json` without clobbering existing keys — an existing `harness`
+ * stays, a missing one is added, a malformed file is left untouched.
+ */
+function writeProjectConfig(opts) {
+    const configPath = (0, node_path_1.resolve)(process.cwd(), ".vigilesrc.json");
+    const existed = (0, node_fs_1.existsSync)(configPath);
+    let existing = {};
+    if (existed) {
+        try {
+            existing = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
+        }
+        catch {
+            return; // user-owned malformed config — never clobber it
         }
     }
-    printSetupSummary({ plan, strict, targets, needsMigration, written });
+    const merged = (0, setup_plan_js_1.mergeProjectConfig)(existing, {
+        harness: harnessConfigValue(opts.harnesses),
+        strict: opts.strict,
+    });
+    if (!merged)
+        return;
+    (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(merged, null, 2) + "\n");
+    console.log(`✓ ${existed ? "Updated" : "Created"} .vigilesrc.json`);
+    if (!opts.written.includes(".vigilesrc.json")) {
+        opts.written.push(".vigilesrc.json");
+    }
 }
 // ---------------------------------------------------------------------------
 // Strengthen: guidance() → enforce() suggestions
@@ -1776,29 +1888,47 @@ function checkIntegrityForFiles(files, severity, silent) {
     return severity === "error" ? errorCount : 0;
 }
 /**
- * Apply the `untested-surface` rule: find skills/agents/hooks with no test or
- * eval (see src/test-coverage.ts). Returns the raw untested count plus the
- * severity-gated error count — "warn" prints but never fails CI (errors=0),
- * "error" fails (exit 2), mirroring the integrity check.
+ * Apply the per-kind `untested-skill` / `untested-agent` / `untested-hook` rules:
+ * find skills/agents/hooks with no test or eval (see src/test-coverage.ts). Each
+ * kind is gated by its OWN rule severity — a kind set to `false` is not scanned;
+ * "warn" prints but never fails CI; "error" fails (exit 2). Returns the raw
+ * untested count plus the severity-gated error count.
  */
 function checkUntestedSurfaces(config, silent) {
-    const severity = (0, types_js_1.ruleSeverity)(config?.rules["untested-surface"]);
-    if (!severity)
+    const rules = config?.rules;
+    const skillSev = (0, types_js_1.ruleSeverity)(rules?.["untested-skill"]);
+    const agentSev = (0, types_js_1.ruleSeverity)(rules?.["untested-agent"]);
+    const hookSev = (0, types_js_1.ruleSeverity)(rules?.["untested-hook"]);
+    if (!skillSev && !agentSev && !hookSev)
         return { untested: 0, errors: 0 };
-    const opts = (0, types_js_1.ruleOptions)(config?.rules["untested-surface"]);
-    const report = (0, test_coverage_js_1.findUntestedSurfaces)({ basePath: process.cwd(), ...opts });
+    const sevFor = (kind) => kind === "skill" ? skillSev : kind === "agent" ? agentSev : hookSev;
+    // Test-discovery options (testGlobs/exclude) are shared; merge them from
+    // whichever of the three rules carries them.
+    const opts = {
+        ...(0, types_js_1.ruleOptions)(rules?.["untested-skill"]),
+        ...(0, types_js_1.ruleOptions)(rules?.["untested-agent"]),
+        ...(0, types_js_1.ruleOptions)(rules?.["untested-hook"]),
+    };
+    const report = (0, test_coverage_js_1.findUntestedSurfaces)({
+        basePath: process.cwd(),
+        skills: skillSev !== false,
+        agents: agentSev !== false,
+        hooks: hookSev !== false,
+        testGlobs: opts.testGlobs,
+        exclude: opts.exclude,
+    });
     if (!silent) {
         console.log("\nUntested surfaces:\n");
         for (const line of (0, test_coverage_js_1.formatUntestedReport)(report).split("\n")) {
             console.log(`  ${line}`);
         }
         for (const s of report.untested) {
-            ghAnnotate(severity === "error" ? "error" : "warning", `${s.kind} ${s.path} ships without a test or eval`, s.path);
+            ghAnnotate(sevFor(s.kind) === "error" ? "error" : "warning", `${s.kind} ${s.path} ships without a test or eval`, s.path);
         }
     }
     return {
         untested: report.untested.length,
-        errors: severity === "error" ? report.untested.length : 0,
+        errors: report.untested.filter((s) => sevFor(s.kind) === "error").length,
     };
 }
 /**
@@ -1980,6 +2110,18 @@ function handleRunScripts(kind, args, restArgs) {
     // Harness/eval scripts may be authored in JS or TS (see run-scripts.ts).
     const defaultGlob = (0, run_scripts_js_1.scriptGlob)(kind === "test" ? "harness" : "eval");
     const files = (0, run_scripts_js_1.discoverScripts)(restArgs, defaultGlob, cwd);
+    // `--min=N`: a CI gate asserts at least N scripts actually RAN — so a bad path,
+    // a renamed file, or a glob that matched nothing fails LOUD instead of passing
+    // green with zero evals executed. Default 0 (off) keeps local runs ergonomic.
+    const minFlag = args.find((a) => a.startsWith("--min="));
+    const minRequired = minFlag
+        ? Math.max(0, Number.parseInt(minFlag.split("=")[1] ?? "", 10) || 0)
+        : 0;
+    if (files.length < minRequired) {
+        console.error(`✗ vigiles ${kind}: --min=${String(minRequired)} but only ${String(files.length)} ${kind} file(s) matched — ` +
+            "evals never executed (check the paths/globs, or that the run was reached).");
+        process.exit(1);
+    }
     if (files.length === 0) {
         console.log(`No ${defaultGlob} files found.`);
         return;
@@ -1990,6 +2132,10 @@ function handleRunScripts(kind, args, restArgs) {
     if (kind === "test" && !(0, harness_test_js_1.claudeAvailable)()) {
         console.log("ℹ `claude` CLI not found — unit-tier tests run; tests that need it report SKIPPED.\n");
     }
+    // `--trials=N` (a run knob: cost/precision, doesn't change WHAT is measured) is
+    // forwarded to scripts via env. The MODEL is deliberately NOT a CLI/env knob —
+    // it's part of the measurement definition, so it belongs in the spec
+    // (`model` / `minModel`), version-controlled, not a hidden override.
     const trialsFlag = args.find((a) => a.startsWith("--trials="));
     const env = {};
     if (trialsFlag)
@@ -2016,7 +2162,7 @@ function printUsage(command) {
     console.log("  vigiles compile [files...]     Compile .spec.ts → .md");
     console.log("  vigiles lint [files...]        Verify references, find gaps in instruction files");
     console.log("  vigiles test [files...]        Run *.harness.mjs deterministic harness tests");
-    console.log("  vigiles eval [files...]        Run *.eval.mjs real-model harness evals (--trials=N)");
+    console.log("  vigiles eval [files...]        Run *.eval.mjs real-model harness evals (--trials=N, --min=N, --no-skip)");
     console.log("");
     console.log("Examples:");
     console.log("  vigiles init                 Auto-detect project, create specs, wire CI");
@@ -2130,7 +2276,7 @@ function skillStartCommand(target) {
  * PreToolUse-hook entrypoint: enforce the active subagent's allowed-tools
  * contract. Reads the tool event on stdin, parses the active agent's compiled
  * `.md` tool rail, and blocks (exit 2 + reason on stderr) any tool outside it —
- * the deterministic boundary `tools:` alone can't provide (Claude Code #54898).
+ * the deterministic boundary `tools:` alone can't provide (Claude Code #4740/#21460, SDK #172).
  */
 function agentHookCommand() {
     let raw = "";
@@ -2155,6 +2301,30 @@ function agentHookCommand() {
         process.exit(2);
     }
 }
+/**
+ * `vigiles intercept-tool-hook` — the PreToolUse interception hook for the
+ * tool-call spy. Reads the intercept list from `VIGILES_INTERCEPT_TOOLS`, decides
+ * whether the called tool should be intercepted, and if so denies the real
+ * execution (exit 2) with a block message — the call is intercepted (prevented),
+ * NOT executed. Allowing (return) lets the tool run for real. The model still
+ * emits the `tool_use`, so its arguments land in the Trace for `toolWith` /
+ * `notTool` to assert on. See src/tool-intercept.ts.
+ */
+function interceptToolHookCommand() {
+    let raw = "";
+    try {
+        raw = (0, node_fs_1.readFileSync)(0, "utf-8");
+    }
+    catch {
+        /* no stdin */
+    }
+    const intercepts = (0, tool_intercept_js_1.parseIntercepts)(process.env[tool_intercept_js_1.INTERCEPT_TOOLS_ENV] ?? "");
+    const decision = (0, tool_intercept_js_1.interceptHookDecision)(raw, intercepts);
+    if (decision.intercept) {
+        console.error(decision.denyReason);
+        process.exit(2);
+    }
+}
 /** Mark a subagent active so the PreToolUse hook enforces its tool contract. */
 function agentStartCommand(target) {
     if (!target) {
@@ -2188,6 +2358,9 @@ function handleSkillCommand(command, restArgs) {
         case "agent-hook":
             agentHookCommand();
             return true;
+        case "intercept-tool-hook":
+            interceptToolHookCommand();
+            return true;
         case "action-hook":
             actionHookCommand();
             return true;
@@ -2367,7 +2540,10 @@ async function main() {
                 console.log("Run `vigiles init` to create one.");
                 process.exit(0);
             }
-            const valid = await compile(specs, config);
+            const harnessFlag = args
+                .find((a) => a.startsWith("--harness="))
+                ?.slice("--harness=".length);
+            const valid = await compile(specs, config, { harnessFlag });
             console.log("");
             if (valid) {
                 console.log("Compilation complete.");

package/dist/core/types.d.ts

@@ -69,16 +69,13 @@ export interface OrphansConfig {
      */
     exclude?: readonly string[];
 }
-/** Options for the untested-surface check. */
+/**
+ * Shared options for the per-kind untested-* rules (`untested-skill` /
+ * `untested-agent` / `untested-hook`). Which kinds are scanned is controlled by
+ * each rule's severity (set a rule to `false` to skip that kind), so only the
+ * test-discovery knobs live here.
+ */
 export interface TestCoverageConfig {
-    /** Scan skills. Default true. */
-    skills?: boolean;
-    /** Scan subagents. Default true. */
-    agents?: boolean;
-    /** Scan hook scripts referenced from plugin.json / settings.json. Default true. */
-    hooks?: boolean;
-    /** Require a test for user-invoked (disable-model-invocation) skills. Default false. */
-    includeUserInvokedSkills?: boolean;
     /** Globs of test files that count as coverage. */
     testGlobs?: readonly string[];
     /** Extra ignore globs. */
@@ -87,14 +84,22 @@ export interface TestCoverageConfig {
 export interface RulesConfig {
     /** Require .spec.ts for CLAUDE.md / AGENTS.md. Default: "warn". */
     "require-spec"?: RuleSeverity;
-    /** Require .spec.ts for SKILL.md files. Default: false. */
+    /**
+     * @deprecated Skills are legitimately hand-written; use `untested-skill`
+     * ("every skill ships with a test/eval") instead. Default: false (off). The
+     * check still runs if you set this explicitly.
+     */
     "require-skill-spec"?: RuleSeverity;
     /** Detect hand-edits to compiled markdown via SHA-256 hash. Default: "warn". */
     integrity?: RuleSeverity;
     /** Enforce minimum spec coverage thresholds. Default: false. ESLint-style: ["warn", { scripts: 50 }]. */
     coverage?: RuleWithOptions<CoverageThresholds>;
-    /** Flag skills/agents/hooks with no test or eval. Default: "warn". */
-    "untested-surface"?: RuleWithOptions<TestCoverageConfig>;
+    /** Flag a skill (SKILL.md) that ships with no test or eval. Default: "warn". */
+    "untested-skill"?: RuleWithOptions<TestCoverageConfig>;
+    /** Flag a subagent (agents/*.md) that ships with no test or eval. Default: "warn". */
+    "untested-agent"?: RuleWithOptions<TestCoverageConfig>;
+    /** Flag a hook script that ships with no test or eval. Default: "warn". */
+    "untested-hook"?: RuleWithOptions<TestCoverageConfig>;
     /**
      * Nudge (or block) when an instruction file has code-shaped references that
      * aren't expressed as vigiles marks (so the lint can't verify them), or a
@@ -127,6 +132,16 @@ export interface VigilesConfig {
     }>;
     /** Orphan-docs check configuration. Include/exclude globs, tsconfig-style. */
     orphans?: OrphansConfig;
+    /**
+     * The harness(es) this repo targets — selects the compile dialect / skill
+     * frontmatter profile / instruction-file shape, instead of sniffing the cwd.
+     * A single name (`"codex"`) for the common single-harness repo, or an array
+     * (`["claude-code", "codex"]`) declaring the supported set. Written by
+     * `vigiles init`. Omitted → the CLI auto-detects (backwards-compatible).
+     * Canonical adapter names; `"claude"` is accepted as an alias for
+     * `"claude-code"`. See research/multi-harness-compile.md.
+     */
+    harness?: string | string[];
 }
 /** Valid marker types for rule detection. */
 export type MarkerType = "headings" | "checkboxes";

package/dist/core/validate.js

@@ -32,10 +32,19 @@ const INSTRUCTION_FILES = ["CLAUDE.md", "AGENTS.md"];
 const DEFAULT_FILES = [INSTRUCTION_FILES[0]];
 const DEFAULT_RULES = {
     "require-spec": "warn",
-    "require-skill-spec": "warn",
+    // DEPRECATED — default OFF. Skills are legitimately hand-written (Level 0/1),
+    // so requiring a .spec.ts per SKILL.md was the wrong constraint and only added
+    // noise (it also nagged about vendored/fixture/bench skills). Use the
+    // `untested-*` rules instead — "every skill/agent/hook ships with a test or
+    // eval" is the coverage that matters. The implementation is kept: setting
+    // `require-skill-spec` explicitly still works for anyone who wants it.
+    "require-skill-spec": false,
     integrity: "warn",
     coverage: false,
-    "untested-surface": "warn",
+    // Per-kind surface-coverage: a skill/agent/hook must ship with a test or eval.
+    "untested-skill": "warn",
+    "untested-agent": "warn",
+    "untested-hook": "warn",
     "unmarked-refs": "warn",
 };
 const DEFAULT_CONFIG = {
@@ -175,7 +184,9 @@ function validate(content, { ruleMarkers, rules: rulesConfig, filePath, dialect
                 }
             }
         }
-        // --- require-skill-spec (SKILL.md) ---
+        // --- require-skill-spec (SKILL.md) — DEPRECATED but still honored when a
+        // user sets it explicitly, so reading the deprecated key here is intentional.
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
         const skillSeverity = activeRules["require-skill-spec"];
         if (skillSeverity && isSkill && !disableComment.test(content)) {
             const specPath = filePath + ".spec.ts";

package/dist/eval-cache.d.ts

@@ -11,6 +11,29 @@ export interface CacheKeyInput {
     readonly files: Record<string, string>;
     /** The resolved `.claude/settings.json` for the arm (or undefined). */
     readonly settings: unknown;
+    /**
+     * Per-run env that affects model behaviour (e.g. `VIGILES_INTERCEPT_TOOLS`).
+     * Keyed because two intercept configs that share tool names — so produce
+     * identical merged `settings` — still differ in their `when`/`denyReason`, which
+     * lives only in the env. Omit when there's no model-affecting env.
+     */
+    readonly env?: Record<string, string>;
+    /**
+     * Content digest of a natively-installed plugin dir (`--plugin-dir`), or
+     * undefined when there is none. Folded in so editing a skill INSIDE the dir
+     * invalidates the entry — a path-only key would false-replay, since the dir's
+     * files are NOT in `files` (that holds only the materialized fixture / `plugin`
+     * arm, not a native install). See {@link hashDir}.
+     */
+    readonly pluginDirHash?: string;
+    /**
+     * The harness BINARY version (e.g. `claude --version`). The harness evolves
+     * fast — a CLI upgrade changes the system prompt + tool definitions, which steer
+     * behaviour as much as the model does — so a cached result must invalidate when
+     * the binary changes, or a replay silently serves a result from a different
+     * harness. Resolved once per run; omit when unknown (then it doesn't partition).
+     */
+    readonly harnessVersion?: string;
     /** Which trial this is — distinct trials are distinct samples, cached apart. */
     readonly trialIndex: number;
 }
@@ -20,9 +43,23 @@ export interface CacheRecord {
     /** Text files present in the cwd after the run (relative path → contents). */
     readonly files: Record<string, string>;
 }
+/**
+ * Cache record-format version, SALTED into every key (Jest `CACHE_VERSION` /
+ * webpack `cache.version` pattern). Bump when the `CacheRecord` shape — or how a
+ * record is produced in a way the key can't otherwise see — changes, so old
+ * entries become *unreachable* rather than deserializing into a stale shape (no
+ * brittle read-time version gate needed). A major bump means orphaned files on
+ * disk; reclaim them by deleting the cache dir.
+ */
+export declare const CACHE_FORMAT_VERSION = 2;
 /** Deterministic content hash of the key inputs (order-independent). */
 export declare function cacheKey(input: CacheKeyInput): SHA256Hash;
-/** Read a cached record by key, or null on miss / unreadable / malformed. */
+/**
+ * Read a cached record by key. A MISS (no file) returns `null` — normal, the run
+ * proceeds. A CORRUPT record (file present but not valid JSON) **throws** instead
+ * of silently degrading to a re-run: a broken cassette is a real failure the CI
+ * gate must surface, not mask. The message tells you how to recover.
+ */
 export declare function readCache(dir: string, key: SHA256Hash): CacheRecord | null;
 /** Write a cached record by key (creating the cache dir as needed). */
 export declare function writeCache(dir: string, key: SHA256Hash, record: CacheRecord): void;
@@ -30,4 +67,15 @@ export declare function writeCache(dir: string, key: SHA256Hash, record: CacheRe
 export declare function snapshotDir(cwd: string): Record<string, string>;
 /** Restore a snapshot into `cwd`, recreating directories as needed. */
 export declare function restoreDir(cwd: string, files: Record<string, string>): void;
+/**
+ * Content digest of a directory: a lexicographically-sorted list of
+ * `relativePath:contentHash` for every file, hashed to one value. Editing,
+ * adding, removing, or moving any file changes the digest. It hashes file
+ * CONTENT (not mtime — CI checkouts reset mtimes, the classic stale-cache
+ * anti-pattern) and includes the relative path (so a rename invalidates and two
+ * files can't swap contents undetected). A flat sorted list, NOT a Merkle tree —
+ * sufficient at plugin-dir scale; the tree's incremental-recompute payoff isn't
+ * worth the complexity here (cf. Bazel/Turborepo hash content per file).
+ */
+export declare function hashDir(dir: string): SHA256Hash;
 //# sourceMappingURL=eval-cache.d.ts.map