vigiles 27.1.7 → 27.3.0

package/dist/hook-install.js

@@ -149,19 +149,70 @@ function bareToken(token) {
     const unquoted = token.replace(/^["']/, "").replace(/["']$/, "");
     return unquoted.replace(/^\$\{?CLAUDE_PROJECT_DIR\}?[/\\]/, "");
 }
+/**
+ * Drop only the COMMANDS this hook file owns from one entry, keeping the rest.
+ *
+ * Returns the entry UNCHANGED (same reference) when it owns nothing here, a
+ * narrowed copy when it owns some, and `null` when the entry is left empty and
+ * should disappear.
+ *
+ * 🔴 THE GRANULARITY IS THE WHOLE POINT, and getting it wrong cost a consumer
+ * repo half its hook wiring. Claude Code's shape is
+ * `{matcher, hooks: [command, command, …]}` — SEVERAL commands share one
+ * matcher block — so "is this entry mine?" is the wrong question: an entry can
+ * be partly mine. The previous merge asked exactly that (`managesHook(e)` →
+ * drop `e`), which is true when ANY command matches, and then deleted the
+ * block wholesale.
+ *
+ * Measured 2026-09-15 on a real `.claude/settings.json`: its
+ * `PostToolUse`/`Edit|Write|MultiEdit` entry held SIX commands — four vigiles
+ * hooks and the user's own `kb-lint.mjs post` and `paper-lint.mjs post`.
+ * Recompiling any ONE of the four took all six, so two hand-written checks
+ * silently stopped running. Silently is the operative word: the file stayed
+ * valid JSON, the remaining hooks kept firing, and nothing reported a loss —
+ * the same failure mode this repo has already paid for three times (a step
+ * that stops executing without saying so).
+ *
+ * The cost asymmetry that decides the rule: a MISS leaves a duplicate block
+ * (visible, harmless, fixed by the next recompile), an OVER-MATCH deletes a
+ * hook the user wrote (invisible, unrecoverable from the file itself). So the
+ * filter is per-command, and an entry is removed only when we emptied it.
+ */
+function withoutHookCommands(entry, hookPath) {
+    if (!managesHook(entry, hookPath))
+        return entry;
+    const kept = entry.hooks.filter((h) => !managesHook({ matcher: entry.matcher, hooks: [h] }, hookPath));
+    if (kept.length === entry.hooks.length)
+        return entry;
+    return kept.length === 0 ? null : { ...entry, hooks: kept };
+}
 /**
  * Idempotently merge a compiled hook's block into an existing `settings.json`
- * object. Entries managed by THIS hook file (the runtime command references
- * `hookPath`) are replaced; every unrelated entry — including the user's own
- * hand-written hooks — is preserved.
+ * object. Commands managed by THIS hook file (the runtime command references
+ * `hookPath`) are replaced; every unrelated command — including the user's own
+ * hand-written hooks SHARING A MATCHER BLOCK with ours — is preserved. See
+ * {@link withoutHookCommands} for why the granularity is the command and not
+ * the entry.
  */
 function mergeHooksJson(existing, compiled, hookPath) {
-    const hooks = { ...(existing.hooks ?? {}) };
-    for (const [event, entries] of Object.entries(compiled)) {
-        const kept = (hooks[event] ?? []).filter((e) => !managesHook(e, hookPath));
-        hooks[event] = [...kept, ...entries];
-    }
-    return { ...existing, hooks };
+    // No keyed assignment into a shallow copy, and the containers are `readonly`.
+    // That copy would SHARE its arrays with the caller's object, so the purity of
+    // the old loop rested on every future author reaching for `hooks[e] = [...]`
+    // rather than `hooks[e].push(...)` — one is fine, the other silently mutates
+    // the argument, and nothing told them apart. `readonly` makes the bad one a
+    // tsc error instead of a convention (ts-essentials: irrepresentable beats
+    // remembered).
+    const before = existing.hooks ?? {};
+    const rewritten = Object.fromEntries(Object.entries(compiled).map(([event, entries]) => [
+        event,
+        [
+            ...(before[event] ?? [])
+                .map((e) => withoutHookCommands(e, hookPath))
+                .filter((e) => e !== null),
+            ...entries,
+        ],
+    ]));
+    return { ...existing, hooks: { ...before, ...rewritten } };
 }
 /** Flatten a CC-shaped entry to Codex's flat `{matcher?, command}` form. */
 function toTomlEntries(entries) {
@@ -171,13 +222,21 @@ function toTomlEntries(entries) {
 }
 /** The TOML sibling of {@link mergeHooksJson} (Codex `[[hooks.<event>]]`). */
 function mergeHooksToml(existing, compiled, hookPath) {
-    const hooks = { ...(existing.hooks ?? {}) };
-    for (const [event, entries] of Object.entries(compiled)) {
-        // Same canonical-path keying as the JSON merge (one flat command per entry).
-        const kept = (hooks[event] ?? []).filter((e) => !managesHook({ hooks: [{ type: "command", command: e.command }] }, hookPath));
-        hooks[event] = [...kept, ...toTomlEntries(entries)];
-    }
-    return { ...existing, hooks };
+    // Same canonical-path keying as the JSON merge, and the same no-assignment
+    // shape. No per-command narrowing is needed HERE, and that is a fact about the
+    // format rather than an oversight: Codex's `[[hooks.<event>]]` carries ONE
+    // command per entry (see `toTomlEntries`), so entry- and command-granularity
+    // coincide. The CC shape nests several commands under one matcher, which is
+    // where the loss happened.
+    const before = existing.hooks ?? {};
+    const rewritten = Object.fromEntries(Object.entries(compiled).map(([event, entries]) => [
+        event,
+        [
+            ...(before[event] ?? []).filter((e) => !managesHook({ hooks: [{ type: "command", command: e.command }] }, hookPath)),
+            ...toTomlEntries(entries),
+        ],
+    ]));
+    return { ...existing, hooks: { ...before, ...rewritten } };
 }
 /** Serialize a merged config back to its on-disk text (with trailing newline). */
 function serializeConfig(merged, format) {

package/dist/hook-runtime.js

@@ -51,6 +51,7 @@ const hook_providers_js_1 = require("./core/hook-providers.js");
 const hook_state_store_js_1 = require("./hook-state-store.js");
 const observe_js_1 = require("./observe.js");
 const load_hook_js_1 = require("./load-hook.js");
+const event_capability_js_1 = require("./core/event-capability.js");
 /**
  * Which events accept injected context, from the ACTIVE adapter — the one
  * harness-specific fact a react needs, read through the `HookProtocol` port so
@@ -63,7 +64,9 @@ const load_hook_js_1 = require("./load-hook.js");
  */
 function injectableEventsFor(root) {
     const { resolveAdapter } = require("./adapter-registry.js");
-    return resolveAdapter(root).hookProtocol?.injectableEvents ?? [];
+    const adapter = resolveAdapter(root);
+    // eslint-disable-next-line @typescript-eslint/no-deprecated -- the legacy list is the FALLBACK an adapter without a capability table still relies on; reading it here is the point
+    return (0, event_capability_js_1.injectableEventsOf)(adapter.dialect, adapter.hookProtocol?.injectableEvents); // prettier-ignore
 }
 /**
  * Load a compiled-hook program's default export — the SHARED loader, also the

package/dist/posix-path.js

@@ -20,7 +20,7 @@
  * behavioural divergence from `node:path` (which the disk-vs-browser parity gate
  * relies on), so the metric rules are disabled for this file only.
  */
-/* eslint-disable complexity, max-depth, sonarjs/cognitive-complexity, sonarjs/nested-control-flow */
+/* eslint-disable complexity, max-depth, sonarjs/cognitive-complexity, sonarjs/nested-control-flow, no-param-reassign -- verbatim Node `path.js` port: it reassigns its own string parameters, and a string is copied by value so nothing escapes to the caller. Rewriting that away would diverge from the algorithm the parity gate pins. */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isAbsolute = isAbsolute;
 exports.normalize = normalize;

package/dist/run-script.js

@@ -33,12 +33,12 @@ exports.runScript = runScript;
  */
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
-const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const egress_js_1 = require("./egress.js");
 const sandbox_js_1 = require("./sandbox.js");
 const check_count_js_1 = require("./check-count.js");
 const coverage_probe_js_1 = require("./coverage-probe.js");
+const tmp_root_js_1 = require("./core/tmp-root.js");
 /**
  * True when the exit code is the shell's own report that it never reached the
  * program — so nothing of the harness ran and no surface may be credited.
@@ -260,7 +260,7 @@ function snapshotTree(dir) {
     return out;
 }
 function sandboxedSpawn(command, stdin, opts) {
-    const ioDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-hook-sbx-"));
+    const ioDir = (0, tmp_root_js_1.makeTmpDir)("hook-sbx");
     const home = (0, node_path_1.join)(ioDir, "home");
     (0, node_fs_1.mkdirSync)(home);
     // The hook's confined writable work dir: the caller's cwd if given, else a
@@ -354,7 +354,7 @@ function readEgressResult(resultFile) {
         : { status: 1, signal: null, stdout: "", stderr: "", counters: "" };
 }
 function egressSpawn(command, stdin, opts) {
-    const ioDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-hook-egr-"));
+    const ioDir = (0, tmp_root_js_1.makeTmpDir)("hook-egr");
     const home = (0, node_path_1.join)(ioDir, "home");
     (0, node_fs_1.mkdirSync)(home);
     const work = opts.cwd ?? (0, node_path_1.join)(ioDir, "work");

package/dist/sandbox.js

@@ -33,9 +33,9 @@ exports.runSandboxed = runSandboxed;
  */
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
-const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const runtime_js_1 = require("./adapters/claude-code/runtime.js");
+const tmp_root_js_1 = require("./core/tmp-root.js");
 let cachedAvailable;
 /**
  * Whether this environment can ACTUALLY confine untrusted code under bubblewrap.
@@ -247,7 +247,7 @@ const WRAPPER = [
    bwrap-backed integration test (skipped without bwrap), not the unit gate —
    the pure policy/args/parse helpers above carry the testable logic. */
 function runSandboxed(opts) {
-    const ioDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-sbx-"));
+    const ioDir = (0, tmp_root_js_1.makeTmpDir)("sbx");
     const home = (0, node_path_1.join)(ioDir, "home");
     (0, node_fs_1.mkdirSync)(home);
     const scriptF = (0, node_path_1.join)(ioDir, "script.json");

package/dist/scan-behavioral.js

@@ -34,7 +34,6 @@ exports.formatGateReport = formatGateReport;
 const node_fs_1 = require("node:fs");
 const foreign_runner_js_1 = require("./core/foreign-runner.js");
 const eval_load_phase_js_1 = require("./core/eval-load-phase.js");
-const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const node_child_process_1 = require("node:child_process");
 const scan_js_1 = require("./scan.js");
@@ -46,6 +45,7 @@ const harness_test_js_1 = require("./harness-test.js");
 const plugin_loader_js_1 = require("./adapters/claude-code/plugin-loader.js");
 const eval_js_2 = require("./adapters/codex/eval.js");
 const driver_js_1 = require("./adapters/codex/driver.js");
+const tmp_root_js_1 = require("./core/tmp-root.js");
 function buildProbe(dir, harness) {
     if (harness === "codex") {
         return {
@@ -529,7 +529,7 @@ function gateRubric(gate) {
 }
 /** Run ONE attack against the unstubbed plugin → the agent's output (or errored). */
 async function runGateAttack(dir, job, deps, model) {
-    const cwd = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-gate-"));
+    const cwd = (0, tmp_root_js_1.makeTmpDir)("gate");
     try {
         const out = await deps.driver.runner({
             task: job.attack,

package/dist/scan-files.js

@@ -42,6 +42,7 @@ const posix_path_js_1 = require("./posix-path.js");
 const toml_1 = require("@iarna/toml");
 const layout_js_1 = require("./adapters/claude-code/layout.js");
 const dialect_js_1 = require("./adapters/claude-code/dialect.js");
+const instruction_weight_js_1 = require("./core/instruction-weight.js");
 const hook_normalize_js_1 = require("./core/hook-normalize.js");
 const hook_events_js_1 = require("./core/hook-events.js");
 const mcp_config_js_1 = require("./core/mcp-config.js");
@@ -59,6 +60,7 @@ const scan_core_js_1 = require("./scan-core.js");
 const skill_refs_js_1 = require("./skill-refs.js");
 const merge_conflict_js_1 = require("./core/merge-conflict.js");
 const scan_core_js_2 = require("./scan-core.js");
+const event_capability_js_1 = require("./core/event-capability.js");
 /**
  * The synthetic absolute root every path in a browser scan resolves against. A
  * pure, deterministic string (never `process.cwd()`), so `join`/`relative` stay
@@ -550,10 +552,10 @@ function scanFiles(files, layout = layout_js_1.claudeCodeLayout, dialect = diale
         skillFenceIssues: skillFenceFindings,
         pluginLayoutIssues: (0, plugin_dir_layout_js_1.pluginDirLayoutIssues)((0, posix_path_js_1.join)(exports.BROWSER_ROOT, (0, posix_path_js_1.dirname)(lay.manifestPath)), [...new Set([...lay.surfaceDirs, lay.hooksConventionPath.split("/")[0]])], { existsSync: exists, isDirectory: mapIsDirectory(files) }),
         delegationTrifecta: (0, scan_core_js_1.collectDelegationTrifecta)(agents, dialect),
-        hookBlockFindings: dialect.noEffectHookEvents
+        hookBlockFindings: (0, event_capability_js_1.blockIneffectiveEventsOf)(dialect).length > 0
             ? (0, hook_block_ineffective_js_1.hookBlockIssues)((0, scan_core_js_1.collectHookBlockEntries)(hookRegs, exports.BROWSER_ROOT, lay.pluginRootToken, exists), {
-                noEffectEvents: new Set(dialect.noEffectHookEvents),
-                permissionDecisionEvents: new Set(dialect.permissionDecisionHookEvents ?? []),
+                noEffectEvents: new Set((0, event_capability_js_1.blockIneffectiveEventsOf)(dialect)),
+                permissionDecisionEvents: new Set((0, event_capability_js_1.permissionDecisionEventsOf)(dialect)),
                 readFileSync: mapReadFile(files),
             })
             : [],
@@ -566,6 +568,11 @@ function scanFiles(files, layout = layout_js_1.claudeCodeLayout, dialect = diale
             ...loaded.warnings,
             ...(0, merge_conflict_js_1.conflictedHarnessConfigs)((f) => files[f]).map(merge_conflict_js_1.mergeConflictWarning),
         ],
+        // The browser side needs no directory walk — the file map IS the repo, so
+        // the glob filter inside weighInstructions does the whole job.
+        instructionWeight: dialect.instructionBudget
+            ? (0, instruction_weight_js_1.weighInstructions)(files, dialect.instructionBudget)
+            : null,
         untested: coverage.untested.length,
         untestedHarness: coverage.harness.untested.length,
         unevaluated: coverage.evals.untested.length,

package/dist/scan.d.ts

@@ -30,6 +30,7 @@ import { type HookBlockFinding } from "./core/hook-block-ineffective.js";
 import { type HookMatcherFinding } from "./core/hook-matcher.js";
 import { type EvidenceCounts } from "./coverage-evidence.js";
 import type { PurityLevel, EffectSurface } from "./core/effects.js";
+import { type InstructionWeight } from "./core/instruction-weight.js";
 export * from "./scan-core.js";
 export interface ScanSkill {
     readonly name: string;
@@ -304,6 +305,14 @@ export interface ScanReport {
      * `scan` and the `hook-matcher` lint rule (one detector, no drift).
      */
     readonly hookMatcherFindings: readonly HookMatcherFinding[];
+    /**
+     * What the harness loads WITHOUT being asked, weighed in ITS OWN unit — and
+     * what it does when that is too much. `null` when the adapter declares no
+     * budget. Reported, never gated: both corpora this was built against sit near
+     * four times the Claude Code threshold, and a rule that fails every real repo
+     * on day one is switched off on day one.
+     */
+    readonly instructionWeight: InstructionWeight | null;
     /** Skills/agents whose `---` block isn't valid YAML — informational (may still load via salvage). */
     readonly malformedFrontmatter: readonly FrontmatterParseIssue[];
     readonly warnings: readonly string[];
@@ -430,6 +439,5 @@ export declare function inspectMarketplace(dir: string, layout?: PluginLayout):
  * alone ships 80+ plugins under one `marketplace.json`. See {@link inspectMarketplace}.
  */
 export declare function expandMarketplace(dir: string, layout?: PluginLayout): string[] | null;
-/** Format a scan report as human-readable text. */
 export declare function formatScanReport(r: ScanReport): string;
 //# sourceMappingURL=scan.d.ts.map

package/dist/scan.js

@@ -54,6 +54,8 @@ const hook_matcher_js_1 = require("./core/hook-matcher.js");
 const test_coverage_js_1 = require("./test-coverage.js");
 const coverage_evidence_js_1 = require("./coverage-evidence.js");
 const scan_core_js_1 = require("./scan-core.js");
+const instruction_weight_js_1 = require("./core/instruction-weight.js");
+const event_capability_js_1 = require("./core/event-capability.js");
 // Re-export the pure detectors (and their public types: SurfaceClassifier,
 // SkillScanContext, isManagedHookCommand, preferCompiledHooksMessage, ...) that
 // moved to the node-free `./scan-core.js`, so every existing consumer of
@@ -233,10 +235,10 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts
         // — derive its first segment and dedupe so the detector watches it as well.
         [...new Set([...lay.surfaceDirs, lay.hooksConventionPath.split("/")[0]])], { existsSync: node_fs_1.existsSync, isDirectory: nodeIsDirectory }),
         delegationTrifecta: (0, scan_core_js_1.collectDelegationTrifecta)(agents, dialect),
-        hookBlockFindings: dialect.noEffectHookEvents
+        hookBlockFindings: (0, event_capability_js_1.blockIneffectiveEventsOf)(dialect).length > 0
             ? (0, hook_block_ineffective_js_1.hookBlockIssues)((0, scan_core_js_1.collectHookBlockEntries)(hookRegs, (0, node_path_1.resolve)(dir), lay.pluginRootToken, node_fs_1.existsSync), {
-                noEffectEvents: new Set(dialect.noEffectHookEvents),
-                permissionDecisionEvents: new Set(dialect.permissionDecisionHookEvents ?? []),
+                noEffectEvents: new Set((0, event_capability_js_1.blockIneffectiveEventsOf)(dialect)),
+                permissionDecisionEvents: new Set((0, event_capability_js_1.permissionDecisionEventsOf)(dialect)),
                 readFileSync: nodeReadFile,
             })
             : [],
@@ -255,6 +257,9 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts
                 return (0, node_fs_1.existsSync)(p) ? nodeReadFile(p) : undefined;
             }).map(merge_conflict_js_1.mergeConflictWarning),
         ],
+        instructionWeight: dialect.instructionBudget
+            ? (0, instruction_weight_js_1.weighInstructions)(readAlwaysLoaded(dir, dialect.instructionBudget), dialect.instructionBudget)
+            : null,
         untested: coverage.untested.length,
         untestedHarness: coverage.harness.untested.length,
         unevaluated: coverage.evals.untested.length,
@@ -448,6 +453,90 @@ function agentLines(a) {
     return lines;
 }
 /** Format a scan report as human-readable text. */
+/**
+ * Read every unconditionally-loaded instruction file off disk.
+ *
+ * Separate from `loadPlugin` on purpose: that materializes the harness's
+ * SURFACES (skills, agents, hooks), while this reads what the harness loads
+ * before any surface is involved — including `.claude/rules/**`, which is
+ * exactly the directory a repo relocates into when it wants the root file to
+ * look smaller.
+ */
+function readAlwaysLoaded(dir, budget) {
+    const out = {};
+    const walk = (rel) => {
+        const abs = (0, node_path_1.join)(dir, rel);
+        if (!(0, node_fs_1.existsSync)(abs) || !(0, node_fs_1.statSync)(abs).isDirectory())
+            return;
+        for (const entry of (0, node_fs_1.readdirSync)(abs)) {
+            const child = `${rel}/${entry}`;
+            if ((0, node_fs_1.statSync)((0, node_path_1.join)(dir, child)).isDirectory())
+                walk(child);
+            else
+                out[child] = (0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, child), "utf-8");
+        }
+    };
+    // `**/NAME` — Codex reads nested AGENTS.md root-to-leaf and they all pay into
+    // the SAME budget, so leaving them out under-reports in the one direction that
+    // matters: the harness truncates silently, and an under-report reads as "you
+    // are fine". Skipped dirs are the ones that are never the user's instructions
+    // and would dominate the walk.
+    const SKIP = new Set(["node_modules", ".git", "dist", "build", "vendor"]);
+    const findNested = (name, rel = "") => {
+        const abs = rel === "" ? dir : (0, node_path_1.join)(dir, rel);
+        if (!(0, node_fs_1.existsSync)(abs))
+            return;
+        for (const entry of (0, node_fs_1.readdirSync)(abs)) {
+            if (SKIP.has(entry) || entry.startsWith("."))
+                continue;
+            const child = rel === "" ? entry : `${rel}/${entry}`;
+            const childAbs = (0, node_path_1.join)(dir, child);
+            if ((0, node_fs_1.statSync)(childAbs).isDirectory())
+                findNested(name, child);
+            else if (entry === name && out[child] === undefined)
+                out[child] = (0, node_fs_1.readFileSync)(childAbs, "utf-8");
+        }
+    };
+    for (const glob of budget.alwaysLoaded) {
+        if (!glob.includes("*")) {
+            const abs = (0, node_path_1.join)(dir, glob);
+            if ((0, node_fs_1.existsSync)(abs) && (0, node_fs_1.statSync)(abs).isFile())
+                out[glob] = (0, node_fs_1.readFileSync)(abs, "utf-8");
+        }
+        else if (glob.endsWith("/**"))
+            walk(glob.slice(0, -3));
+        else if (glob.startsWith("**/"))
+            findNested(glob.slice(3));
+    }
+    return out;
+}
+/**
+ * The weight report. States the SUM first and the per-file breakdown second,
+ * because the sum is the number a reader can act on and the breakdown is only
+ * where to start.
+ *
+ * The verb changes with the harness on purpose: over budget on Claude Code is
+ * "warns" (costs money, rules still arrive), on Codex it is "truncates" (rules
+ * silently do not arrive). Same number, different emergency.
+ */
+function instructionWeightLines(w) {
+    const g = (n) => String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+    const head = `Always-loaded instructions: ${g(w.total)} ${w.unit} (budget ${g(w.limit)})`;
+    if (w.overBy === null)
+        return [head];
+    const factor = (w.total / w.limit).toFixed(1);
+    const consequence = w.onExceed === "truncates"
+        ? "past the budget is SILENTLY TRUNCATED — those rules never reach the model"
+        : "the harness warns; the rules still reach the model, you pay for them every request";
+    return [
+        `${head} — ${factor}x OVER by ${g(w.overBy)} ${w.unit}`,
+        `  ${consequence}`,
+        ...w.files.slice(0, 5).map((f) => `  ${g(f.size).padStart(9)}  ${f.path}`),
+        ...(w.files.length > 5
+            ? [`  …and ${String(w.files.length - 5)} more`]
+            : []),
+    ];
+}
 function formatScanReport(r) {
     const out = [`Scan: ${r.dir}`, ""];
     if (r.instructions) {
@@ -456,6 +545,10 @@ function formatScanReport(r) {
             : "hand-written, no spec";
         out.push(`Instructions: ${r.instructions.file} (${tag})`, "");
     }
+    // Right under the instruction file, because that is the line a reader is
+    // already looking at when they wonder what it costs.
+    if (r.instructionWeight)
+        out.push(...instructionWeightLines(r.instructionWeight), ""); // prettier-ignore
     out.push(...section("Skills", r.skills.map(skillLine)));
     out.push(...section("Agents", r.agents.flatMap(agentLines), r.agents.length));
     const hookMark = {

package/dist/setup-plan.d.ts

@@ -64,6 +64,14 @@ export interface ParsedSetupArgs {
      * `init` is unchanged), so this is opt-IN — it never buries the richer layers
      * behind a default flip. (Named for what it sets up — the CI check — not the
      * internal "integrity gate" concept.)
+     *
+     * THE DISCOVERY FAILURE THIS FLAG IS THE WORKED EXAMPLE OF: it shipped in the
+     * CLI and was invisible on the README, the site, the recommended agent prompt
+     * and the internal doc, so an agent taking the full default never learned it
+     * existed. Working code is not a delivered capability — a flag nobody can FIND
+     * is not done. The fix was a pointer in the non-interactive summary, `--help`,
+     * docs/agent-setup.md and the README; the standing rule it produced is the
+     * DISCOVERY row of `cohesive-feature-delivery`.
      */
     ciOnly: boolean;
 }

package/dist/test.d.ts

@@ -51,6 +51,7 @@
  * distinction in its config rather than in its imports.
  */
 export { recordCheck } from "./check-count.js";
+export { makeTmpDir, cleanupTmpDir } from "./core/tmp-root.js";
 export { runScript } from "./run-script.js";
 export type { RunScriptOptions, ScriptRunResult } from "./run-script.js";
 export { runHook, parseHookOutput, decideHook, propertyHook, fileToolEvents, egressRoutes, } from "./run-hook.js";

package/dist/test.js

@@ -66,8 +66,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseOutput = exports.parseResultEvent = exports.parseSubagents = exports.parseToolCalls = exports.runHarness = exports.runHarnessTest = exports.experimental_formatPluginGuardReport = exports.experimental_verifyPluginGuards = exports.experimental_alternateSpellings = exports.formatGuardrailReport = exports.assertBlocksDisasters = exports.unblockedDisasters = exports.verifyGuardrail = exports.DISASTER_CATALOG = exports.cacheTokens = exports.outputTokens = exports.inputTokens = exports.tokens = exports.latency = exports.cost = exports.mcp = exports.allowed = exports.blocked = exports.subagent = exports.didNotWrite = exports.wrote = exports.turns = exports.received = exports.hookFired = exports.output = exports.skill = exports.onlyTools = exports.notTool = exports.toolWith = exports.tool = exports.assertChecks = exports.evalChecks = exports.experimental_hookState = exports.loadHook = exports.experimental_assertEmittedOk = exports.experimental_parseEmitted = exports.experimental_emitTool = exports.egressRoutes = exports.fileToolEvents = exports.propertyHook = exports.decideHook = exports.parseHookOutput = exports.runHook = exports.runScript = exports.recordCheck = void 0;
-exports.experimental_makeDockerRuntime = exports.experimental_dockerRuntime = exports.experimental_withServices = exports.experimental_startServices = exports.stubSkillBody = exports.parseClaudeRun = exports.formatTriggerRateReport = exports.formatEvalReport = exports.formatCheckReport = exports.checkReportToJUnit = exports.checkPromptDiversity = exports.assertPromptDiversity = exports.assertRates = exports.defineEval = exports.formatContainment = exports.compareContainment = exports.skillContract = exports.mustNotInclude = exports.mustInclude = exports.commandsIn = exports.sandboxAvailable = exports.specTrusted = exports.decideSandbox = exports.parseHooks = void 0;
+exports.parseSubagents = exports.parseToolCalls = exports.runHarness = exports.runHarnessTest = exports.experimental_formatPluginGuardReport = exports.experimental_verifyPluginGuards = exports.experimental_alternateSpellings = exports.formatGuardrailReport = exports.assertBlocksDisasters = exports.unblockedDisasters = exports.verifyGuardrail = exports.DISASTER_CATALOG = exports.cacheTokens = exports.outputTokens = exports.inputTokens = exports.tokens = exports.latency = exports.cost = exports.mcp = exports.allowed = exports.blocked = exports.subagent = exports.didNotWrite = exports.wrote = exports.turns = exports.received = exports.hookFired = exports.output = exports.skill = exports.onlyTools = exports.notTool = exports.toolWith = exports.tool = exports.assertChecks = exports.evalChecks = exports.experimental_hookState = exports.loadHook = exports.experimental_assertEmittedOk = exports.experimental_parseEmitted = exports.experimental_emitTool = exports.egressRoutes = exports.fileToolEvents = exports.propertyHook = exports.decideHook = exports.parseHookOutput = exports.runHook = exports.runScript = exports.cleanupTmpDir = exports.makeTmpDir = exports.recordCheck = void 0;
+exports.experimental_makeDockerRuntime = exports.experimental_dockerRuntime = exports.experimental_withServices = exports.experimental_startServices = exports.stubSkillBody = exports.parseClaudeRun = exports.formatTriggerRateReport = exports.formatEvalReport = exports.formatCheckReport = exports.checkReportToJUnit = exports.checkPromptDiversity = exports.assertPromptDiversity = exports.assertRates = exports.defineEval = exports.formatContainment = exports.compareContainment = exports.skillContract = exports.mustNotInclude = exports.mustInclude = exports.commandsIn = exports.sandboxAvailable = exports.specTrusted = exports.decideSandbox = exports.parseHooks = exports.parseOutput = exports.parseResultEvent = void 0;
 // --- reporting: how much did this script actually do? ---
 // `vigiles test` can otherwise see only an exit code, so a file that runs NOTHING
 // prints the same `✓` as one that ran and passed (measured 2026-08-08 on a file
@@ -76,6 +76,21 @@ exports.experimental_makeDockerRuntime = exports.experimental_dockerRuntime = ex
 // visible to the runner too. See check-count.ts.
 var check_count_js_1 = require("./check-count.js");
 Object.defineProperty(exports, "recordCheck", { enumerable: true, get: function () { return check_count_js_1.recordCheck; } });
+// --- fixture roots: a temp directory whose two spellings agree ---
+// 🔴 DO NOT hand-roll `mkdtempSync(join(tmpdir(), …))` in a harness. On macOS
+// `/var` is a symlink to `/private/var`, so that shape hands you a directory with
+// TWO spellings: Node resolves a module's own URL to the realpath but leaves
+// `process.argv[1]` and any path you composed as typed. Every assertion that
+// compares them is then red on macOS and green on Linux, for a reason that
+// belongs to neither the test nor the code under test — measured three times in
+// one consumer suite (#241, zernie/research-paper-pipeline#9).
+//
+// `makeTmpDir` resolves the root once, at creation. The trap is unreachable from
+// anything built under it, including a symlink the harness creates ITSELF to test
+// symlink handling — that stays a genuine test, because it is explicit.
+var tmp_root_js_1 = require("./core/tmp-root.js");
+Object.defineProperty(exports, "makeTmpDir", { enumerable: true, get: function () { return tmp_root_js_1.makeTmpDir; } });
+Object.defineProperty(exports, "cleanupTmpDir", { enumerable: true, get: function () { return tmp_root_js_1.cleanupTmpDir; } });
 // --- the process primitives: runScript (any program) + runHook (plus a decision) ---
 // `runScript` runs any program and reports what it DID (exit, both streams,
 // writes, egress). `runHook` is that plus the hook protocol: event to stdin,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "27.1.7",
+  "version": "27.3.0",
   "description": "Audit, test and measure the harness your AI agent runs on — grade your CLAUDE.md / AGENTS.md, skills, subagents and hooks, run them against a scripted model, and measure whether they actually fire.",
   "keywords": [
     "claude-code",

package/skills/adopt-spec/SKILL.md

@@ -67,7 +67,13 @@ export default claude({
   },
 
   keyFiles: {
-    // Key files here
+    // Key files here. A path maps to ONE LINE saying what the file is for —
+    // aim for 120 characters, never exceed ~200. The entry is a pointer, not a
+    // summary: how the file works belongs in its own header comment, which is
+    // read when someone opens it. This file is loaded on every request, so a
+    // paragraph here is paid for every turn. Prune a stale neighbour whenever
+    // you add one; `vigiles audit` prints the running total as
+    // `Always-loaded instructions`.
   },
 
   commands: {

package/skills/edit-spec/SKILL.md

@@ -111,6 +111,19 @@ Based on what the user asked for:
 - Add to `keyFiles` or `commands`. The compiler verifies these exist at compile time
 - For commands: must match a script in `package.json`
 - For key files: must exist on disk
+- 🔴 **KEEP THE DESCRIPTION TO ONE LINE — aim for 120 characters, never exceed
+  ~200.** A `keyFiles` entry is a POINTER: what the file is for, so a reader knows
+  whether to open it. The explanation of how it works belongs in that file's own
+  header comment, where it is read when someone is actually in the file. An
+  instruction file is loaded on EVERY request, so a paragraph here is paid for
+  every turn, forever, by every reader — including the ones who never touch that
+  file.
+- **This list only ever grows unless you shrink it.** Every session adds entries
+  and none removes them, so before adding, check whether a NEARBY entry is now
+  stale (the file moved, the role changed, the description restates its header)
+  and fix it in the same edit. Adding without ever pruning is how an instruction
+  file reaches four times its harness's budget — `vigiles audit` reports that
+  number as `Always-loaded instructions`, so check it when you touch this list.
 
 ### Step 4: Compile