vigiles 27.1.7 → 27.3.0

package/dist/adapter-conformance.js

@@ -13,12 +13,13 @@ exports.assertAdapterLoadsHooks = assertAdapterLoadsHooks;
  * in their test suite. See `docs/authoring-an-adapter.md`.
  */
 const node_fs_1 = require("node:fs");
-const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const compile_js_1 = require("./core/compile.js");
 const spec_js_1 = require("./core/spec.js");
 const plugin_loader_js_1 = require("./plugin-loader.js");
 const vocabulary_consistency_js_1 = require("./core/vocabulary-consistency.js");
+const event_capability_js_1 = require("./core/event-capability.js");
+const tmp_root_js_1 = require("./core/tmp-root.js");
 /** Check an adapter against the port contracts; returns the (possibly empty) failure list. */
 function checkAdapterConformance(adapter) {
     const failures = [];
@@ -89,7 +90,18 @@ function checkAdapterConformance(adapter) {
             // deliver an inject hook?" a tested contract — the gap that let Codex's
             // inject support sit unverified in prose. Empty would mean the harness
             // can't inject context from a hook at all; every harness we support can.
-            need(adapter.hookProtocol.injectableEvents.length > 0, "hookProtocol.injectableEvents is empty — a shell-hook harness must declare the events that honor additionalContext injection (or it can't deliver an inject/nudge hook)");
+            // eslint-disable-next-line @typescript-eslint/no-deprecated -- the legacy list is the FALLBACK for an adapter with no capability table, and the thing checked for drift below
+            const declaredInject = adapter.hookProtocol.injectableEvents;
+            need((0, event_capability_js_1.injectableEventsOf)(adapter.dialect, declaredInject).length > 0, "hookProtocol.injectableEvents is empty — a shell-hook harness must declare the events that honor additionalContext injection (or it can't deliver an inject/nudge hook)");
+            // …and when an adapter declares BOTH, they must agree. Without this the
+            // table silently COVERS FOR a broken list: an adapter could ship
+            // `injectableEvents: []` and still pass, because the effective answer came
+            // from the dialect. Two sources that disagree are worse than one, and this
+            // is the assertion that keeps the deprecation honest rather than lossy.
+            if (adapter.dialect.eventCapabilities) {
+                const derived = [...(0, event_capability_js_1.injectableEventsOf)(adapter.dialect, [])].sort();
+                need(derived.join("|") === [...declaredInject].sort().join("|"), `hookProtocol.injectableEvents disagrees with dialect.eventCapabilities — the list says [${[...declaredInject].sort().join(", ")}], the table says [${derived.join(", ")}]; they describe the same fact and must match`);
+            }
             portNames.push(["hookProtocol", adapter.hookProtocol.name]);
         }
     }
@@ -154,7 +166,7 @@ function assertHarnessTestable(adapter) {
  * run with zero hooks. Does filesystem IO, so it's a separate opt-in assert.
  */
 function assertAdapterLoadsHooks(adapter) {
-    const dir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-conformance-"));
+    const dir = (0, tmp_root_js_1.makeTmpDir)("conformance");
     try {
         const settingsAbs = (0, node_path_1.join)(dir, adapter.layout.settingsPath);
         (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(settingsAbs), { recursive: true });

package/dist/adapters/claude-code/dialect.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.claudeCodeDialect = exports.claudeCodeSideEffectingTools = exports.claudeCodeBuiltinAgentTools = void 0;
+const event_capability_js_1 = require("./event-capability.js");
 const vocabulary_js_1 = require("./vocabulary.js");
 /**
  * The Claude Code built-in subagent tool catalog as a `const` tuple, so a typed
@@ -61,6 +62,35 @@ exports.claudeCodeDialect = {
         "Notification",
         "PreCompact",
     ],
+    // What Claude Code loads unasked, and what it does with too much of it.
+    //
+    // WARNS, does not truncate: `/doctor` reports "Large file will impact
+    // performance" and the instructions still reach the model. So being over
+    // budget here costs money and attention — not rules. (Codex is the opposite;
+    // see its dialect, and see why `onExceed` is reported at all.)
+    //
+    // 🔴 `alwaysLoaded` IS THE POINT, and `.claude/rules/**` is in it on a
+    // MEASUREMENT, not a doc: a consumer repo moved 225 837 characters out of
+    // CLAUDE.md into that directory and the request cost did not move, because
+    // the harness loads it either way. A per-file check would have called that
+    // split a success.
+    instructionBudget: {
+        unit: "chars",
+        limit: 40000,
+        onExceed: "warns",
+        capturedFrom: "claude-code /doctor large-file warning; .claude/rules/** measured 2026-09-16 in a consumer repo",
+        alwaysLoaded: [
+            "CLAUDE.md",
+            "CLAUDE.local.md",
+            ".claude/CLAUDE.md",
+            ".claude/rules/**",
+        ],
+    },
+    // The capability table — what each event CARRIES and HONOURS. Nine of the 31
+    // events, each with its basis; see ./event-capability.ts. The three flat lists
+    // above are kept for now and are ASSERTED against this table in
+    // event-capability.test.ts, so there is one source rather than two truths.
+    eventCapabilities: event_capability_js_1.claudeCodeEventCapabilities,
     // PreToolUse is the one event whose deny needs the structured
     // `hookSpecificOutput.permissionDecision:"deny"`; the legacy top-level
     // `decision` field is ignored there.

package/dist/adapters/claude-code/event-capability.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Claude Code's hook-event capability table — what each event carries and what
+ * it honours. The CAPTURE half of `core/event-capability.ts`; see that module
+ * for why the table is partial and why `unknown` is fail-open.
+ *
+ * NINE of the vendor's 31 events are recorded here, and the other 22 are absent
+ * ON PURPOSE. These nine are the ones a capability is actually KNOWN for —
+ * either documented by the vendor or measured against a real binary — and every
+ * row below carries which. The 22 absent ones are not "no capabilities"; they
+ * are "we have not looked", and the classifier says so rather than guessing.
+ *
+ * Adding a row is a claim about somebody else's product, so it needs a basis in
+ * the comment beside it: `doc` (the vendor documents it) or `measured <date> on
+ * <version>` (we ran it). "Probably the same as its sibling event" is not a
+ * basis — `SubagentStop` is in here on the vendor's own wording, not on its
+ * resemblance to `Stop`.
+ */
+import type { EventCapabilityTable } from "../../core/event-capability.js";
+export declare const claudeCodeEventCapabilities: EventCapabilityTable;
+//# sourceMappingURL=event-capability.d.ts.map

package/dist/adapters/claude-code/event-capability.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeCodeEventCapabilities = void 0;
+exports.claudeCodeEventCapabilities = {
+    capturedFrom: "code.claude.com/docs/en/hooks (claude-code 2.1.273) + inject/veto measured 2026-09-16 headless",
+    events: {
+        // doc: SessionStart context is prepended to the session. MEASURED 2026-09-16:
+        // inject lands; exit 2 is ignored entirely (it is in noEffectHookEvents).
+        SessionStart: {
+            carries: "session",
+            honours: ["inject"],
+            matcher: false,
+            denyShape: "exit-code",
+        },
+        // doc: exit 2 blocks the prompt and erases it; stdout becomes context.
+        UserPromptSubmit: {
+            carries: "prompt",
+            honours: ["veto", "inject"],
+            matcher: false,
+            denyShape: "exit-code",
+        },
+        // doc: the one event whose deny needs `hookSpecificOutput.permissionDecision`
+        // (the legacy top-level `decision` is ignored), and the one that can `ask`.
+        // MEASURED 2026-09-16: additionalContext also lands here — the reason this
+        // table exists at all, since `injectableEvents` had said otherwise on an
+        // assumption nobody had run.
+        PreToolUse: {
+            carries: "tool",
+            honours: ["veto", "ask", "inject"],
+            matcher: true,
+            denyShape: "permission-decision",
+        },
+        // doc: exit 2 feeds stderr back to the MODEL but the tool has already run —
+        // feedback, never a veto. This distinction is why `hook-block-ineffective`
+        // does not flag PostToolUse and would cry wolf if it did.
+        PostToolUse: {
+            carries: "tool",
+            honours: ["feedback", "inject"],
+            matcher: true,
+            denyShape: "exit-code",
+        },
+        // doc: exit 2 blocks the agent from stopping (the gate-until-tests-pass
+        // shape). MEASURED 2026-09-16: inject lands too.
+        Stop: {
+            carries: "stop",
+            honours: ["veto", "inject"],
+            matcher: false,
+            denyShape: "exit-code",
+        },
+        // doc: same block semantics as Stop, for a subagent. Inject NOT claimed —
+        // it was not measured, and Stop's behaviour is not evidence about it.
+        SubagentStop: {
+            carries: "stop",
+            honours: ["veto"],
+            matcher: false,
+            denyShape: "exit-code",
+        },
+        // doc + noEffectHookEvents: a block decision here is silently ignored
+        // ENTIRELY — no veto AND no model feedback. A hook on these three is inert
+        // whatever it returns, which is exactly what `honours: []` says.
+        SessionEnd: {
+            carries: "none",
+            honours: [],
+            matcher: false,
+            denyShape: "exit-code",
+        },
+        Notification: {
+            carries: "none",
+            honours: [],
+            matcher: false,
+            denyShape: "exit-code",
+        },
+        PreCompact: {
+            carries: "none",
+            honours: [],
+            matcher: false,
+            denyShape: "exit-code",
+        },
+    },
+};
+//# sourceMappingURL=event-capability.js.map

package/dist/adapters/claude-code/hook-protocol.js

@@ -11,9 +11,32 @@ exports.claudeCodeHookProtocol = {
     // the agent — a stronger stop than a per-call deny, and a documented one.
     haltsTurnField: "continue",
     // Events that honor `hookSpecificOutput.additionalContext` (developer-context
-    // injection). Covers vigiles's shipped inject hooks: the SessionStart lint
-    // summary and the PostToolUse refs / eval-lock nudges.
-    injectableEvents: ["SessionStart", "UserPromptSubmit", "PostToolUse"],
+    // injection). Covers vigiles's shipped inject hooks (the SessionStart lint
+    // summary, the PostToolUse refs / eval-lock nudges) AND the two events added
+    // 2026-09-15 after a MEASUREMENT contradicted the assumption below.
+    //
+    // `PreToolUse` and `Stop` were absent because the port's doc-comment asserted
+    // that "a few (Stop, SubagentStop, PreCompact) carry no context on either"
+    // harness. That was never measured for Claude Code. Measured on 2.1.273 by
+    // emitting `additionalContext` from a hook on each event and reading the
+    // model's OWN request back (`requestContains` over a real `runHarnessTest`
+    // run, not the hook's stdout): both events DELIVER. The prior list was
+    // therefore a self-inflicted gate — the runtime refused to emit a shape the
+    // harness would have honored, and the four affected react hooks read as
+    // "undeliverable by vocabulary" when they were undeliverable by our choice.
+    //
+    // HONEST SCOPE: measured HEADLESS (`claude -p`, which is what runHarnessTest
+    // drives). Interactive is unverified, and for the `ask` channel the two
+    // plausibly differ (headless has nobody to ask) — but `ask` is a GATE
+    // channel, not this inject one, so it does not bear on this list.
+    // `SubagentStop`/`PreCompact` stay out: not measured, so not claimed.
+    injectableEvents: [
+        "SessionStart",
+        "UserPromptSubmit",
+        "PreToolUse",
+        "PostToolUse",
+        "Stop",
+    ],
     // The `if` field: a permission-rule pattern deciding whether the hook is spawned
     // at all. See ./hook-condition.ts — without it a conditional guard was reported
     // as blocking every disaster in the battery.

package/dist/adapters/claude-code/run-scripts.js

@@ -26,7 +26,6 @@ const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const node_url_1 = require("node:url");
 const node_fs_1 = require("node:fs");
-const node_os_2 = require("node:os");
 const glob_1 = require("glob");
 const check_count_js_1 = require("../../check-count.js");
 /**
@@ -64,8 +63,21 @@ exports.SKIP_EXIT_CODE = 77;
 function statusFor(code, checks, output) {
     if (code === exports.SKIP_EXIT_CODE)
         return "skip";
+    // 🔴 `checks === undefined` GUARDS THE TEXT MATCH, and it is the load-bearing
+    // half. A script that REPORTED a count executed: the counter is written by an
+    // exit handler that exists only once the module was linked and run
+    // (`check-count.ts`), so the count is a STRUCTURAL fact about the child, while
+    // `didNotLoad` is a guess about its text.
+    //
+    // MEASURED: `statusFor(1, 3, "<hook stderr: Cannot find module …>\nAssertionError")`
+    // returned `"skip"` and the run exited 0 — a harness that ran, recorded three
+    // checks and FAILED an assertion, reported as skipped. That is not an exotic
+    // input: vigiles harnesses drive hooks and print their transcripts, so a
+    // loader phrase in the output is ordinary EVIDENCE about the thing under test,
+    // not a diagnosis of the harness. Watching the child from outside cannot tell
+    // those apart. The count can, and it was already in hand.
     if (code !== 0)
-        return didNotLoad(output) ? "skip" : "fail";
+        return checks === undefined && didNotLoad(output) ? "skip" : "fail";
     return checks === 0 ? "vacuous" : "pass";
 }
 /**
@@ -83,10 +95,17 @@ function statusFor(code, checks, output) {
  * 'recordCheck' not found`, and the ledger dropped from 48 records to 34 and from
  * 47 to 33. Nothing about those surfaces had changed — the machine had.
  *
- * ⚠️ This does NOT make a broken environment quiet. A skip still prints `⊘
- * SKIPPED`, and `--no-skip` — which this repo's own CI passes — still fails the
- * run. What changes is only whether a machine problem is allowed to delete a
- * measurement taken on a machine that worked.
+ * ⚠️ This does NOT make a broken environment quiet: a script classified here
+ * fails the run by default (`cli-main.ts`, right after `anyFailed`), because a
+ * skip the AUTHOR never declared is not a skip. What this classification buys is
+ * only that a machine problem may not delete a measurement taken on a machine
+ * that worked.
+ *
+ * 🔴 That default is new, and the sentence it replaces was false. It read
+ * «`--no-skip` — which this repo's own CI passes — still fails the run».
+ * Measured: `--no-skip` appears ZERO times under `.github/`, `package.json`,
+ * `scripts/` and `.claude/`; CI passes `--min=14` and nothing else. The
+ * safety net the non-fatal classification leaned on was never strung.
  *
  * Deliberately literal, and only the loader's own vocabulary: these strings come
  * from Node's module resolution, not from user code. A test that legitimately
@@ -99,6 +118,13 @@ function didNotLoad(output) {
         output.includes("Cannot find package") ||
         output.includes("Cannot find module") ||
         /SyntaxError: Named export '[^']*' not found/.test(output) ||
+        // Same event, ESM spelling. Node phrases a missing named export one way for
+        // a CommonJS target and another for an ES module, and only the first was
+        // listed — so the 2026-08-20 class below still RETRACTED coverage whenever
+        // the dependency happened to be ESM. Measured on Node 22:
+        //   CJS: SyntaxError: Named export 'recordCheck' not found. The requested module …
+        //   ESM: SyntaxError: The requested module './x.mjs' does not provide an export named 'recordCheck'
+        /SyntaxError: The requested module '[^']*' does not provide an export named/.test(output) ||
         output.includes("ERR_UNSUPPORTED_DIR_IMPORT") ||
         output.includes("ERR_PACKAGE_PATH_NOT_EXPORTED"));
 }
@@ -118,6 +144,7 @@ var ts_runner_caps_js_1 = require("../../ts-runner-caps.js");
 Object.defineProperty(exports, "detectNodeCaps", { enumerable: true, get: function () { return ts_runner_caps_js_1.detectNodeCaps; } });
 Object.defineProperty(exports, "canRunTypeScript", { enumerable: true, get: function () { return ts_runner_caps_js_1.canRunTypeScript; } });
 const ts_runner_caps_js_2 = require("../../ts-runner-caps.js");
+const tmp_root_js_1 = require("../../core/tmp-root.js");
 /**
  * The `node` argv (after the binary) to run a single script. Plain JS runs
  * directly; a TypeScript script picks `tsx` when available, else Node's native
@@ -159,7 +186,13 @@ function discoverScripts(patterns, defaultGlob, cwd, ignore) {
     const globs = patterns.length > 0 ? patterns : [defaultGlob];
     const found = new Set();
     for (const p of globs) {
-        if ((0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, p))) {
+        // 🔴 `isFile`, not `existsSync`: a DIRECTORY exists too. `vigiles test .`
+        // therefore passed `.` through as a script, `spawn("node", ["."])` died with
+        // Node's `ERR_UNSUPPORTED_DIR_IMPORT` stack, and the classifier downstream
+        // read that stack as "did not load" — a crash reported as a skip, exit 0.
+        // A directory now contributes no files, so the caller's own loud
+        // nothing-matched path owns the message (see `cli-main.ts`).
+        if ((0, node_fs_1.statSync)((0, node_path_1.resolve)(cwd, p), { throwIfNoEntry: false })?.isFile()) {
             found.add(p);
             continue;
         }
@@ -174,10 +207,16 @@ function discoverScripts(patterns, defaultGlob, cwd, ignore) {
         // `test-coverage.ts` and `cli.ts` both pass `dot: true` with comments saying why, and
         // `test-coverage.test.ts` records "glob without `dot:true` never found it and the surface
         // looked untested". Coverage learned it; the runner did not.
+        // 🔴 `nodir: true` for the same reason as the `isFile` guard above, and the
+        // guard alone was NOT enough — caught by its own test. A pattern that names
+        // an existing directory (`sub`, `.`) skips the fast path and then comes back
+        // out of the globber, because a directory matches a glob perfectly well.
+        // Asked of the globber rather than filtered afterwards: it already knows.
         for (const m of (0, glob_1.globSync)(p, {
             cwd,
             ignore: [...ignore],
             dot: true,
+            nodir: true,
         })) {
             found.add(m);
         }
@@ -219,7 +258,7 @@ function readCheckReport(path) {
  */
 async function runScripts(files, cwd, env = {}, opts = {}) {
     const caps = (0, ts_runner_caps_js_2.detectNodeCaps)(cwd);
-    const countDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_2.tmpdir)(), "vigiles-checks-"));
+    const countDir = (0, tmp_root_js_1.makeTmpDir)("checks");
     // 🔴 THE DEFAULT IS DECIDED BY `entry`, NOT BY A FLAG, because the two commands
     // that share this runner have OPPOSITE right answers and the caller already
     // distinguishes them:

package/dist/adapters/codex/dialect.js

@@ -21,6 +21,25 @@ exports.codexDialect = {
         "UserPromptSubmit",
         "Stop",
     ],
+    // 🔴 TRUNCATES, SILENTLY — the asymmetry that makes `onExceed` worth carrying.
+    // Codex's own source: "Maximum number of bytes of the documentation that will
+    // be embedded. Larger files are *silently truncated*" (openai/codex#7138,
+    // CLOSED AS NOT PLANNED — standing behaviour, not a bug in flight). Default
+    // `project_doc_max_bytes` is 32 * 1024. Over budget on Claude Code costs
+    // money; over budget here means some of your rules DO NOT EXIST for the model
+    // and nothing in the session says which.
+    //
+    // BYTES, not chars: the two diverge on any non-ASCII instruction file, and
+    // this is the unit Codex actually counts.
+    instructionBudget: {
+        unit: "bytes",
+        limit: 32768,
+        onExceed: "truncates",
+        capturedFrom: "codex config project_doc_max_bytes default 32 * 1024; truncation quoted in openai/codex#7138",
+        // Read root-to-leaf and concatenated, so a nested AGENTS.md pays into the
+        // same budget — the sum is what gets cut, not the individual file.
+        alwaysLoaded: ["AGENTS.md", "**/AGENTS.md"],
+    },
     instructionTargets: ["AGENTS.md"],
     pluginRootToken: "${PLUGIN_ROOT}",
     // Codex SKILL.md frontmatter is name + description ONLY — the CC-only keys

package/dist/cli-main.js

@@ -16,6 +16,7 @@ exports.discoverNestedBundles = discoverNestedBundles;
 exports.handleHookRuntime = handleHookRuntime;
 exports.main = main;
 const node_fs_1 = require("node:fs");
+const event_capability_js_1 = require("./core/event-capability.js");
 const node_path_1 = require("node:path");
 const repo_path_js_1 = require("./core/repo-path.js");
 const node_child_process_1 = require("node:child_process");
@@ -323,7 +324,7 @@ function compileGeneratorSkillToFile(specPath, source) {
     if (artifact)
         writeArtifact(outputPath, artifact);
     if (errors.length === 0) {
-        console.log(`\n✓ ${specPath} → ${outputPath} (generator skill)`);
+        console.log(`\n✓ ${specPath} → ${outputPath} (generator skill${artifact ? `, ${formatArtifactSize(artifact)}` : ""})`);
         return true;
     }
     console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
@@ -334,7 +335,7 @@ function compileGeneratorSkillToFile(specPath, source) {
 /** Compile a ClaudeSpec → its primary + any additional targets. */
 function compileClaudeToFile(spec, specPath, config, dialect) {
     const basePath = process.cwd();
-    const { markdown, errors, linterResults, targets } = (0, compile_js_1.compileClaude)(spec, {
+    const { markdown, errors, warnings, linterResults, targets } = (0, compile_js_1.compileClaude)(spec, {
         basePath,
         specFile: specPath,
         dialect,
@@ -345,6 +346,16 @@ function compileClaudeToFile(spec, specPath, config, dialect) {
         linters: config.linters,
     });
     const primaryOutput = specPath.replace(/\.spec\.ts$/, "");
+    // Budget findings print BEFORE the pass/fail line and never change the exit
+    // code. A number nobody prints cannot be acted on — the same reason the
+    // compiled size is printed at all — and an instruction file grows one
+    // unremarkable entry at a time, so the warning has to arrive at the moment
+    // the entry is added rather than at some later audit.
+    if (warnings.length > 0) {
+        console.log(`\nℹ ${specPath} — ${String(warnings.length)} budget warning(s)`);
+        for (const w of warnings)
+            console.log(`  ${w.message}`);
+    }
     if (errors.length > 0) {
         console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
         printErrors(specPath, errors);
@@ -376,7 +387,7 @@ function compileClaudeToFile(spec, specPath, config, dialect) {
         outputNames.push(targetPath);
     }
     const linterCount = linterResults.filter((r) => r.exists).length;
-    console.log(`\n✓ ${specPath} → ${outputNames.join(", ")}`);
+    console.log(`\n✓ ${specPath} → ${outputNames.join(", ")} (${formatArtifactSize(markdown)})`);
     console.log(`  ${String(Object.keys(spec.rules).length)} rules (${String(linterCount)} linter-verified)`);
     return true;
 }
@@ -419,6 +430,44 @@ function writeInstructionMirrors(primaryOutput, harnesses) {
         console.log(`  ↳ mirrored ${primaryName} → ${target} (byte-identical)`);
     }
 }
+/**
+ * The size of a compiled artifact, printed beside every `✓` on STDOUT.
+ *
+ * WHY STDOUT: every human line `compile` emits already goes there (the `✓`
+ * lines, `Compilation complete`), and stderr in this CLI is the ERROR channel.
+ * An informational number in the error stream reads as a problem in CI logs and
+ * is killed by `2>/dev/null`. This is part of the operation's RESULT, like the
+ * output path beside it — not a diagnostic about a failure.
+ *
+ * WHY BYTES AND CHARS, AND WHY THE TOKEN COUNT IS ONLY AN ESTIMATE. These are
+ * the units the HARNESSES themselves measure, and both are exact:
+ *
+ *   - Claude Code warns per FILE CHARS (`/doctor`: "Large file will impact
+ *     performance"), and skips a file past a hard size;
+ *   - Codex caps AGENTS.md by BYTES (`project_doc_max_bytes`) and TRUNCATES —
+ *     instructions past that byte simply do not exist for the model.
+ *
+ * Neither gates on tokens, so a real tokenizer would buy precision in a unit
+ * nothing decides on. It is also not available: Anthropic publishes no local
+ * tokenizer for current Claude models (the supported count is a NETWORK call
+ * with an API key, which a zero-config offline compile must not need), while
+ * OpenAI's is local — so tokenizing would make us precise for one harness and
+ * blind for the other, and the two numbers would stop being comparable.
+ *
+ * `estimateTokens` is `length / 4`, calibrated for ASCII English; it undercounts
+ * Cyrillic and CJK substantially. It is labelled `est.` for that reason and must
+ * never become the number a rule gates on — see the instruction-weight rule.
+ */
+function formatArtifactSize(markdown) {
+    const chars = markdown.length;
+    const bytes = Buffer.byteLength(markdown, "utf8");
+    const group = (n) => String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+    const kTokens = Math.round((0, compile_js_1.estimateTokens)(markdown) / 100) / 10;
+    const size = bytes === chars
+        ? `${group(chars)} chars`
+        : `${group(chars)} chars / ${group(bytes)} bytes`;
+    return `${size} · ~${String(kTokens)}k tokens est.`;
+}
 /** Compile a declarative SkillSpec → SKILL.md. */
 function compileSkillToFile(spec, specPath, dialect) {
     const outputPath = specPath.replace(/\.spec\.ts$/, "");
@@ -434,7 +483,7 @@ function compileSkillToFile(spec, specPath, dialect) {
     if (artifact)
         writeArtifact(outputPath, artifact);
     if (errors.length === 0) {
-        console.log(`\n✓ ${specPath} → ${outputPath}`);
+        console.log(`\n✓ ${specPath} → ${outputPath}${artifact ? ` (${formatArtifactSize(artifact)})` : ""}`);
         printWarnings(specPath, warnings);
         return true;
     }
@@ -456,7 +505,7 @@ function compileAgentToFile(spec, specPath, dialect) {
     if (artifact)
         writeArtifact(outputPath, artifact);
     if (errors.length === 0) {
-        console.log(`\n✓ ${specPath} → ${outputPath}`);
+        console.log(`\n✓ ${specPath} → ${outputPath}${artifact ? ` (${formatArtifactSize(artifact)})` : ""}`);
         printWarnings(specPath, warnings);
         return true;
     }
@@ -481,7 +530,7 @@ function compileRailwayToFile(spec, specPath, knownAgents) {
     if (artifact)
         writeArtifact(outputPath, artifact);
     if (errors.length === 0) {
-        console.log(`\n✓ ${specPath} → ${outputPath}`);
+        console.log(`\n✓ ${specPath} → ${outputPath}${artifact ? ` (${formatArtifactSize(artifact)})` : ""}`);
         return true;
     }
     console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
@@ -4887,10 +4936,19 @@ async function handleRunScripts(kind, args, restArgs, excludes) {
         // VALUE cannot tell them apart — only the flag's presence can. (Caught by a control:
         // the first version read `minRequired === 0` and made `--min=0` do nothing.)
         if (restArgs.length > 0 && minFlag === undefined) {
-            console.error(`✗ vigiles ${kind}: ${String(restArgs.length)} target(s) given and NOTHING matched — ` +
-                `${restArgs.join(", ")}\n` +
-                `  Nothing ran. A stale path, a wrong glob, or a moved file all look like this.\n` +
-                `  If an empty match is expected here, say so with --min=0.`);
+            // A DIRECTORY is the one stale-looking target whose cause we actually know,
+            // so say it instead of listing the three guesses. `vigiles test .` used to
+            // reach `spawn("node", ["."])` and surface Node's module-resolution stack;
+            // the generic message above would now be true but unhelpful.
+            const dirs = restArgs.filter((a) => (0, node_fs_1.lstatSync)(a, { throwIfNoEntry: false })?.isDirectory() === true);
+            console.error(dirs.length > 0
+                ? `✗ vigiles ${kind}: ${dirs.join(", ")} ${dirs.length === 1 ? "is a directory" : "are directories"} — ` +
+                    `pass a file, or a glob like "${defaultGlob}".\n` +
+                    `  A directory is not a script; nothing ran.`
+                : `✗ vigiles ${kind}: ${String(restArgs.length)} target(s) given and NOTHING matched — ` +
+                    `${restArgs.join(", ")}\n` +
+                    `  Nothing ran. A stale path, a wrong glob, or a moved file all look like this.\n` +
+                    `  If an empty match is expected here, say so with --min=0.`);
             process.exit(1);
         }
         console.log(`No ${defaultGlob} files found.`);
@@ -4953,6 +5011,35 @@ async function handleRunScripts(kind, args, restArgs, excludes) {
     console.log("\n" + (0, run_scripts_js_1.formatScriptSummary)(results));
     if ((0, run_scripts_js_1.anyFailed)(results))
         process.exit(1);
+    // 🔴 A SKIP THE AUTHOR NEVER DECLARED IS NOT A SKIP — and the discriminator was
+    // already sitting in the result. `skip()` exits 77 (`SKIP_EXIT_CODE`); a script
+    // the runtime could not evaluate exits with whatever the loader gave it, 1 in
+    // practice. Both are classified `"skip"` so that neither RETRACTS coverage —
+    // which is right, a file that did not run proved nothing either way — but only
+    // the declared one is a reason to stay green.
+    //
+    // Reported as #243: `vigiles test .` printed a resolver stack over a `⊘`, said
+    // `0 passed, 1 skipped`, and exited 0. Downstream a consumer's README shipped
+    // that exact command as its first setup step, so a new reader's suite silently
+    // never ran. `--no-skip` would have caught it and is not the default; `--min=1`
+    // does not, because it counts files MATCHED, not scripts executed.
+    //
+    // This is deliberately NOT a fifth `ScriptStatus`. Coverage retraction reads the
+    // status as a bare STRING (`executedScripts`, `coverage-artifact.ts`, whose
+    // parameter is typed `string`), so a new member would start retracting silently
+    // with no type error — breaking the one property the classification exists to
+    // protect.
+    const notEvaluated = results.filter((r) => r.status === "skip" && r.code !== run_scripts_js_1.SKIP_EXIT_CODE);
+    if (notEvaluated.length > 0) {
+        console.error(`\n✗ vigiles ${kind}: ${String(notEvaluated.length)} script(s) never ran — the runtime could not load them:\n` +
+            notEvaluated
+                .map((r) => `  ${r.file} (exit ${String(r.code)})`)
+                .join("\n") +
+            `\n  Their previous coverage is kept, because a script that did not run retracts nothing.\n` +
+            `  If a missing dependency is expected here, import it dynamically and call skip() — ` +
+            `a declared skip stays green.`);
+        process.exit(1);
+    }
     // `--no-skip`: in a context that ASSERTS the capability is present (a CI job),
     // a skipped tier is untested surface — fail loudly instead of passing green.
     if (args.includes("--no-skip") && results.some((r) => r.status === "skip")) {
@@ -5730,7 +5817,9 @@ async function installHookFile(file, adapter, registeredProviders = []) {
     // cross-harness and never warns.
     const role = (0, hook_program_js_1.dispatchKind)(program);
     const event = typeof program.on === "string" ? program.on : "";
-    const injectable = adapter.hookProtocol?.injectableEvents ?? [];
+    const injectable = (0, event_capability_js_1.injectableEventsOf)(adapter.dialect, 
+    // 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
+    adapter.hookProtocol?.injectableEvents);
     const matcher = (0, hook_program_js_1.hookRouting)(program).matcher;
     let warning;
     // A react on an event this harness does NOT inject can still call `notice()`,

package/dist/core/adopt.js

@@ -25,6 +25,7 @@ exports.adoptToSpec = adoptToSpec;
 exports.adoptMarkdown = adoptMarkdown;
 exports.adoptSkill = adoptSkill;
 exports.adoptAgent = adoptAgent;
+const compile_js_1 = require("./compile.js");
 const integrity_js_1 = require("./integrity.js");
 const frontmatter_read_js_1 = require("./frontmatter-read.js");
 const spec_js_1 = require("./spec.js");
@@ -195,8 +196,15 @@ function renderSpecSource(spec, exists) {
     const targetLine = spec.target !== "CLAUDE.md"
         ? `\n  target: ${JSON.stringify(spec.target)},`
         : "";
+    // The raised guard is rendered WITH the debt spelled out. A bare number reads
+    // as a considered setting; the comment says it was accepted as-is and by how
+    // much, so the next author sees a debt rather than a decision.
+    const over = (spec.maxSectionLines ?? 0) - compile_js_1.DEFAULT_MAX_SECTION_LINES;
     const maxLine = spec.maxSectionLines !== undefined
-        ? `\n  maxSectionLines: ${String(spec.maxSectionLines)},`
+        ? `\n  // Adopted as-is: the longest section is ${String(spec.maxSectionLines)} lines, ` +
+            `${String(over)} over the ${String(compile_js_1.DEFAULT_MAX_SECTION_LINES)}-line budget.` +
+            `\n  // Lower this as you split that section up; it is a debt, not a setting.` +
+            `\n  maxSectionLines: ${String(spec.maxSectionLines)},`
         : "";
     const adopted = [];
     const entries = Object.entries(spec.sections)
@@ -269,14 +277,24 @@ function adoptToSpec(markdown, target) {
     const sections = {};
     for (const { key, content } of ordered)
         sections[key] = content;
-    // A faithful section can legitimately be long; lift the 200-line guard above
-    // the longest one so adoption never trips it (only when actually needed, so a
-    // normal spec stays free of the override).
+    // A faithful section can legitimately be long, and adoption must not fail on
+    // prose the user already has — so the 200-line guard is raised to EXACTLY the
+    // longest section, never above it.
+    //
+    // IT USED TO BE `longest + 50`, and that headroom is the bug this block exists
+    // to name: the guard was disarmed hardest for the population that needs it
+    // most — someone adopting a spec over a file that is already oversized — and
+    // the next fifty lines of growth were pre-approved, silently, by the tool
+    // meant to notice them. Raising to `longest` keeps adoption green on the file
+    // as it stands and makes the very next line that grows trip the gate. The
+    // override is rendered with a comment stating how far above the budget it
+    // sits, so the debt is visible in the spec rather than inferable from a number
+    // nobody reads.
     const longest = ordered.reduce((n, s) => Math.max(n, s.content.split("\n").length), 0);
     return {
         target,
         sections,
-        maxSectionLines: longest > 190 ? longest + 50 : undefined,
+        maxSectionLines: longest > compile_js_1.DEFAULT_MAX_SECTION_LINES ? longest : undefined,
         tier: synthesizedHeading || ordered.length === 0 ? "raw" : "structured",
     };
 }