vigiles 18.1.2 → 19.0.0

package/dist/adapters/claude-code/run-scripts.d.ts

@@ -61,7 +61,7 @@ export declare const SKIP_EXIT_CODE = 77;
  * `assertNoWrite` already draws: "nobody looked" must not read as "nothing
  * happened".
  */
-export declare function statusFor(code: number, checks: number | undefined): ScriptStatus;
+export declare function statusFor(code: number, checks: number | undefined, output?: string): ScriptStatus;
 /** Filename extensions accepted for harness/eval scripts (JS and TS). */
 export declare const SCRIPT_EXTS: readonly ["mjs", "cjs", "js", "mts", "cts", "ts"];
 /** Glob suffix matching every accepted script extension, e.g. `harness`. */

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

@@ -60,13 +60,47 @@ exports.SKIP_EXIT_CODE = 77;
  * `assertNoWrite` already draws: "nobody looked" must not read as "nothing
  * happened".
  */
-function statusFor(code, checks) {
+function statusFor(code, checks, output) {
     if (code === exports.SKIP_EXIT_CODE)
         return "skip";
     if (code !== 0)
-        return "fail";
+        return didNotLoad(output) ? "skip" : "fail";
     return checks === 0 ? "vacuous" : "pass";
 }
+/**
+ * Did the script fail to LOAD, rather than fail?
+ *
+ * 🔴 The distinction is not cosmetic, because `fail` RETRACTS coverage while
+ * `skip` does not (see the table on `runsFromResults`). The rule for `fail` —
+ * "it ran and proved nothing, so it must not keep yesterday's green record
+ * alive" — is right, and it does not describe a file the runtime never
+ * evaluated. A module that cannot resolve executed no assertion; it is the same
+ * "did not run" as a missing `claude` CLI, arriving through a different door.
+ *
+ * MEASURED, twice in one session on 2026-08-20: a container restore left an old
+ * `node_modules` behind, every harness in the consumer repo died on `Named export
+ * '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.
+ *
+ * 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
+ * asserts on one of them exits 0 or asserts, and never reaches here.
+ */
+function didNotLoad(output) {
+    if (output === undefined || output === "")
+        return false;
+    return (output.includes("ERR_MODULE_NOT_FOUND") ||
+        output.includes("Cannot find package") ||
+        output.includes("Cannot find module") ||
+        /SyntaxError: Named export '[^']*' not found/.test(output) ||
+        output.includes("ERR_UNSUPPORTED_DIR_IMPORT") ||
+        output.includes("ERR_PACKAGE_PATH_NOT_EXPORTED"));
+}
 /** Filename extensions accepted for harness/eval scripts (JS and TS). */
 exports.SCRIPT_EXTS = ["mjs", "cjs", "js", "mts", "cts", "ts"];
 /** Glob suffix matching every accepted script extension, e.g. `harness`. */
@@ -225,12 +259,13 @@ async function runScripts(files, cwd, env = {}, opts = {}) {
         child.stdout.on("data", (c) => chunks.push(c));
         child.stderr.on("data", (c) => chunks.push(c));
         const finish = (code) => {
-            process.stdout.write(Buffer.concat(chunks));
+            const output = Buffer.concat(chunks).toString("utf8");
+            process.stdout.write(output);
             const report = readCheckReport(countFile);
             resolveRun({
                 file,
                 code,
-                status: statusFor(code, report?.checks),
+                status: statusFor(code, report?.checks, output),
                 checks: report?.checks,
                 ...(report ? { surfaces: report.surfaces } : {}),
             });

package/dist/cli.js

@@ -701,11 +701,14 @@ function lintExitCode(report) {
         report.hookBlockErrors > 0 ||
         report.hookMatcherErrors > 0 ||
         report.symbolRefErrors > 0 ||
-        report.mcpRefErrors > 0)
-        return 2;
-    if (report.duplicatePairs > 0 ||
-        report.orphanCount > 0 ||
+        report.mcpRefErrors > 0 ||
+        // `doc-refs` is opt-in and this counter is only non-zero when the user set
+        // it to "error", so it belongs in the hard tier with every other explicit
+        // error — it used to sit at exit 1 because it fired unasked and could not be
+        // turned off.
         report.docRefErrors > 0)
+        return 2;
+    if (report.duplicatePairs > 0 || report.orphanCount > 0)
         return 1;
     // Guidance counts are informational, not failures
     return 0;
@@ -1135,11 +1138,28 @@ async function runLint(restArgs, flags, config) {
     // typo, an uncompilable or unreachable MCP pattern, one too narrow for real
     // server naming, or an undeclared MCP server).
     const hookMatcher = checkHookMatcher(config, silent, adapter, scanRoot);
-    // 8. Validate vigiles builder calls inside markdown code blocks. Default
-    // is to validate every ref; illustrative blocks opt out via
-    // `<!-- vigiles:ignore -->` (single block) or
-    // `<!-- vigiles:ignore-file -->` (whole file). Same engine as spec.ts.
-    if (!silent)
+    // 8. Validate vigiles builder calls inside markdown code blocks — the
+    // `doc-refs` rule, DEFAULT OFF. Illustrative blocks opt out via
+    // `<!-- vigiles:ignore -->` (single block) or `<!-- vigiles:ignore-file -->`
+    // (whole file). Same engine as spec.ts.
+    //
+    // 🔴 WHY OFF BY DEFAULT — the measurement, not a preference. Run across two
+    // real repositories on 2026-08-19: 2 582 markdown files, 52 builder refs,
+    // **0 true positives**, and every error it had ever raised was false — a
+    // design note writing `cmd("npm test")` for a package that doesn't have that
+    // script yet, a third-party `CLAUDE.md` captured verbatim as benchmark data.
+    // The cause is structural: a fenced block in prose is a DRAWING of config, and
+    // this pass read it as config. The consumer repo reached a clean `lint` only by
+    // excluding a third of itself, after which the pass walked 604 files and found
+    // 0 refs — fully inert, still paying for the walk. So it is now opt-in, and
+    // when off the walk does not happen at all (that is the whole subtraction).
+    //
+    // ⚠️ Known gap for whoever improves it before flipping this back: the walker
+    // globs without `dot`, so `.claude/**` — where real skills and agents live —
+    // has never been scanned. The rule has never once looked at a deployed
+    // instruction file; every ref it has ever judged was in prose.
+    const docRefSeverity = (0, types_js_1.ruleSeverity)(config?.rules?.["doc-refs"]);
+    if (!silent && docRefSeverity)
         console.log("\nMarkdown code block refs:\n");
     // 🔴 `config.exclude` REACHES THIS PASS. It did not, and that single omission is
     // why `lint` could not exit 0 on a repository that vendors other people's
@@ -1154,12 +1174,20 @@ async function runLint(restArgs, flags, config) {
     // With no way to reach 0 the step was made `continue-on-error: true`, and a lint
     // whose exit code is discarded gates nothing — after which hand-written CI steps
     // grew to do the gating instead. One unpassed argument, that whole chain.
-    const docRefReport = (0, doc_refs_js_1.findDocRefs)({
-        basePath: process.cwd(),
-        ignore: config?.exclude,
-    });
-    if (!silent) {
-        for (const line of (0, doc_refs_js_1.formatDocRefReport)(docRefReport).split("\n")) {
+    const docRefReport = docRefSeverity
+        ? (0, doc_refs_js_1.findDocRefs)({ basePath: process.cwd(), ignore: config?.exclude })
+        : {
+            filesScanned: 0,
+            filesIgnored: 0,
+            blocksIgnored: 0,
+            refs: [],
+            errors: [],
+            unverified: 0,
+            placeholders: 0,
+        };
+    if (!silent && docRefSeverity) {
+        const rendered = (0, doc_refs_js_1.formatDocRefReport)(docRefReport, docRefSeverity === "error" ? "error" : "warn");
+        for (const line of rendered.split("\n")) {
             console.log(`  ${line}`);
         }
     }
@@ -1168,9 +1196,9 @@ async function runLint(restArgs, flags, config) {
     // 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) {
+    if (isGitHubActions() && !silent && docRefSeverity) {
         for (const e of docRefReport.errors) {
-            ghAnnotate("error", `${e.kind}("${e.value}") — ${e.message}`, e.file, e.line);
+            ghAnnotate(docRefSeverity === "error" ? "error" : "warning", `${e.kind}("${e.value}") — ${e.message}`, e.file, e.line);
         }
     }
     // 9. Verify code-shaped symbol references live (see src/refs.ts).
@@ -1234,7 +1262,10 @@ async function runLint(restArgs, flags, config) {
         hookBlockErrors: hookBlock.errors,
         hookMatcherIssues: hookMatcher.issues,
         hookMatcherErrors: hookMatcher.errors,
-        docRefErrors: docRefReport.errors.length,
+        // Only the "error" tier gates. At "warn" the findings are printed and
+        // annotated, and the exit code is untouched — same contract as every other
+        // opt-in rule here.
+        docRefErrors: docRefSeverity === "error" ? docRefReport.errors.length : 0,
         symbolRefErrors,
         mcpRefErrors,
         files,

package/dist/core/doc-refs.d.ts

@@ -55,6 +55,12 @@ interface ExtractResult {
  */
 export declare function findDocRefs(options?: FindDocRefsOptions): DocRefReport;
 /** Format a DocRefReport as human-readable text. */
-export declare function formatDocRefReport(report: DocRefReport): string;
+export declare function formatDocRefReport(report: DocRefReport, 
+/**
+ * The severity `doc-refs` is configured at. A `✗` next to an exit code of 0
+ * reads as a gate that failed to gate, so the marker follows the severity the
+ * user actually set rather than always claiming the hard tier.
+ */
+severity?: "error" | "warn"): string;
 export {};
 //# sourceMappingURL=doc-refs.d.ts.map

package/dist/core/doc-refs.js

@@ -272,7 +272,13 @@ function findDocRefs(options = {}) {
     };
 }
 /** Format a DocRefReport as human-readable text. */
-function formatDocRefReport(report) {
+function formatDocRefReport(report, 
+/**
+ * The severity `doc-refs` is configured at. A `✗` next to an exit code of 0
+ * reads as a gate that failed to gate, so the marker follows the severity the
+ * user actually set rather than always claiming the hard tier.
+ */
+severity = "error") {
     const lines = [];
     const meta = [];
     if (report.filesIgnored > 0)
@@ -288,7 +294,7 @@ function formatDocRefReport(report) {
     lines.push(`${String(report.refs.length)} vigiles refs in code blocks${report.errors.length === 0 ? " — all valid" : ""}`);
     if (report.errors.length === 0)
         return lines.join("\n");
-    lines.push(`✗ ${String(report.errors.length)} broken ref(s):`);
+    lines.push(`${severity === "error" ? "✗" : "ℹ"} ${String(report.errors.length)} broken ref(s):`);
     for (const e of report.errors.slice(0, 12)) {
         const trunc = e.message.length > 80 ? `${e.message.slice(0, 80)}…` : e.message;
         lines.push(`    ${e.file}:${String(e.line)} ${e.kind}("${e.value}") — ${trunc}`);

package/dist/core/hook-program.d.ts

@@ -262,6 +262,10 @@ export interface HookProgram<N extends readonly NeedSpec[] = readonly ProviderNa
 export declare const tool: (name: string) => {
     tool: string;
 };
+/**
+ * @experimental Compiled hooks are provisional — see docs/experimental.md.
+ * Imported as `experimental_defineHook`; alias it at the import site.
+ */
 export declare function defineHook<const N extends readonly NeedSpec[] = readonly []>(p: HookProgram<N>): HookProgram<N>;
 /**
  * Build the typed event from a raw PreToolUse event, then decide.
@@ -506,6 +510,10 @@ export interface FileGateHook<N extends readonly NeedSpec[] = readonly ProviderN
 export declare const tools: (...names: string[]) => {
     tools: string[];
 };
+/**
+ * @experimental Compiled hooks are provisional — see docs/experimental.md.
+ * Imported as `experimental_defineFileGate`; alias it at the import site.
+ */
 export declare function defineFileGate<const N extends readonly NeedSpec[] = readonly []>(p: Omit<FileGateHook<N>, "role">): FileGateHook<N>;
 /**
  * Run a file-tool gate against a raw PreToolUse event (reads `file_path`).
@@ -542,6 +550,10 @@ export interface PromptGateHook<N extends readonly NeedSpec[] = readonly Provide
     /** Decide over the prompt. `deny` blocks/erases the prompt; `ask` defers to the user. */
     readonly decide: (e: PromptEvent<N>) => Decision;
 }
+/**
+ * @experimental Compiled hooks are provisional — see docs/experimental.md.
+ * Imported as `experimental_definePromptGate`; alias it at the import site.
+ */
 export declare function definePromptGate<const N extends readonly NeedSpec[] = readonly []>(p: Omit<PromptGateHook<N>, "role">): PromptGateHook<N>;
 /** Run a prompt gate against a raw UserPromptSubmit event (reads `prompt`). */
 export declare function decidePromptGate<N extends readonly NeedSpec[]>(hook: PromptGateHook<N>, raw: {
@@ -573,6 +585,10 @@ export interface StopGateHook<N extends readonly NeedSpec[] = readonly ProviderN
     /** Decide whether the agent may stop. `deny` keeps it going; `allow` lets it stop. */
     readonly decide: (e: StopEvent<N>) => Decision;
 }
+/**
+ * @experimental Compiled hooks are provisional — see docs/experimental.md.
+ * Imported as `experimental_defineStopGate`; alias it at the import site.
+ */
 export declare function defineStopGate<const N extends readonly NeedSpec[] = readonly []>(p: Omit<StopGateHook<N>, "role">): StopGateHook<N>;
 /** Run a Stop gate against a raw Stop/SubagentStop event (reads `stop_hook_active`). */
 export declare function decideStopGate<N extends readonly NeedSpec[]>(hook: StopGateHook<N>, raw: {
@@ -618,6 +634,10 @@ export interface InjectHook<N extends readonly NeedSpec[] = readonly ProviderNam
     /** Produces context to add. Its return type (Injection) has no `deny` — by design. */
     readonly produce: (e: SessionEvent<N>) => Injection;
 }
+/**
+ * @experimental Compiled hooks are provisional — see docs/experimental.md.
+ * Imported as `experimental_defineInject`; alias it at the import site.
+ */
 export declare function defineInject<const N extends readonly NeedSpec[] = readonly []>(p: Omit<InjectHook<N>, "role">): InjectHook<N>;
 /**
  * Run an inject hook → the CC JSON the author never hand-writes. The compiler
@@ -719,6 +739,10 @@ export interface ReactHook<N extends readonly NeedSpec[] = readonly ProviderName
     /** Reacts to a tool that already ran. Returns a Reaction — NO `deny` exists here. */
     readonly react: (e: ReactEvent<N>) => Reaction;
 }
+/**
+ * @experimental Compiled hooks are provisional — see docs/experimental.md.
+ * Imported as `experimental_defineReact`; alias it at the import site.
+ */
 export declare function defineReact<const N extends readonly NeedSpec[] = readonly []>(p: Omit<ReactHook<N>, "role">): ReactHook<N>;
 /**
  * Run a react hook against a raw PostToolUse event → the (classified) Reaction.

package/dist/core/hook-program.js

@@ -535,6 +535,10 @@ function commandView(raw, root) {
 }
 const tool = (name) => ({ tool: name });
 exports.tool = tool;
+/**
+ * @experimental Compiled hooks are provisional — see docs/experimental.md.
+ * Imported as `experimental_defineHook`; alias it at the import site.
+ */
 function defineHook(p) {
     return p;
 }
@@ -913,6 +917,10 @@ const tools = (...names) => ({
     tools: names,
 });
 exports.tools = tools;
+/**
+ * @experimental Compiled hooks are provisional — see docs/experimental.md.
+ * Imported as `experimental_defineFileGate`; alias it at the import site.
+ */
 function defineFileGate(p) {
     return { role: "gate", ...p };
 }
@@ -940,6 +948,10 @@ function decideFileGate(hook, raw, ctx = {}, root = typeof raw.cwd === "string"
         ctx: ctx,
     });
 }
+/**
+ * @experimental Compiled hooks are provisional — see docs/experimental.md.
+ * Imported as `experimental_definePromptGate`; alias it at the import site.
+ */
 function definePromptGate(p) {
     return { role: "prompt-gate", ...p };
 }
@@ -952,6 +964,10 @@ function decidePromptGate(hook, raw, ctx = {}) {
         ctx: ctx,
     });
 }
+/**
+ * @experimental Compiled hooks are provisional — see docs/experimental.md.
+ * Imported as `experimental_defineStopGate`; alias it at the import site.
+ */
 function defineStopGate(p) {
     return { role: "stop-gate", ...p };
 }
@@ -977,6 +993,10 @@ const inject = (context, ...records) => ({
     records,
 });
 exports.inject = inject;
+/**
+ * @experimental Compiled hooks are provisional — see docs/experimental.md.
+ * Imported as `experimental_defineInject`; alias it at the import site.
+ */
 function defineInject(p) {
     return { role: "inject", ...p };
 }
@@ -1055,6 +1075,10 @@ const nothing = (...records) => ({
     records,
 });
 exports.nothing = nothing;
+/**
+ * @experimental Compiled hooks are provisional — see docs/experimental.md.
+ * Imported as `experimental_defineReact`; alias it at the import site.
+ */
 function defineReact(p) {
     return { role: "react", ...p };
 }

package/dist/core/rule-meta.js

@@ -143,6 +143,14 @@ exports.RULE_META = {
         detector: "hookMatcherIssues",
         upstreamPrevention: "compiled hook tool()/tools() matcher is typed",
     },
+    "doc-refs": {
+        id: "doc-refs",
+        bucket: "external-decidable",
+        surface: ["docs"],
+        defaultSeverity: "off",
+        summary: "Builder calls quoted in markdown ```ts fences resolve for real (opt-in: a fence is usually a drawing of config, not config).",
+        detector: "findDocRefs",
+    },
     "prefer-compiled-hooks": {
         id: "prefer-compiled-hooks",
         bucket: "heuristic-behavioral",

package/dist/core/skill-resources.js

@@ -210,6 +210,44 @@ const ILLUSTRATIVE_CUE = /\b(example|examples|e\.g\.?|i\.e\.?|such as|for instan
  * net is affordable where a blanket one is not.
  */
 const MD_HEADING = /^\s{0,3}#{1,6}\s/;
+/**
+ * Whether the line describes a file the skill PRODUCES rather than one it ships.
+ *
+ * 🔴 WHY THIS IS SEPARATE FROM {@link ILLUSTRATIVE_CUE}. That one vetoes a
+ * HYPOTHETICAL mention — "a `scripts/rotate.py` would be helpful". This one
+ * vetoes a mention that is entirely real and entirely concrete, and still names
+ * a file that cannot be a bundled resource, because the skill's own prose says
+ * the file is written at runtime. Same veto, different reason, and collapsing
+ * them into one list would make the next reader think a gitignored cache is a
+ * kind of example.
+ *
+ * It is the read the module already takes elsewhere: {@link USE_DIRECTIVE}
+ * deliberately EXCLUDES authoring verbs (store/create/add/move/write) because
+ * "a file to CREATE" is not "a file the skill already ships". A cache written
+ * by the skill's own script is that same case; the verb list simply never
+ * covered the writing side.
+ *
+ * MEASURED 2026-08-20 on a real consumer skill (`verify-citations`), which read:
+ *
+ *     API responses are cached to `scripts/.cite-cache.json` (gitignored) so
+ *     re-runs are cheap.
+ *
+ * That produced `bundled resource not found`. Isolated to one word with a
+ * three-line fixture differing only in its tail: the same sentence ending
+ * "so subsequent invocations are cheap" stayed silent, and the same sentence
+ * with no tail stayed silent. The culprit is `re-runs` — JavaScript's `\b`
+ * counts a hyphen as a word boundary, so `USE_DIRECTIVE`'s `runs` matches
+ * INSIDE it, and a plural noun about repetition was read as an instruction to
+ * run the file.
+ *
+ * Fixing the hyphen instead was rejected by that same measurement: "re-run
+ * `scripts/x.sh` before submitting" is a genuine directive, so a rule about
+ * hyphens would trade this false positive for a false negative. The honest
+ * discriminator is not the hyphen, it is that the line says the file is made,
+ * not read. `gitignored` is the strongest form — a file the author states is
+ * outside the repository cannot be shipped inside it.
+ */
+const GENERATED_FILE_CUE = /\bgit-?ignored\b|\.gitignore\b|\bcached? to\b|\bcache file\b|\bwrit(?:ten|es) to\b|\b(?:generated|created) at runtime\b/i;
 /**
  * Whether a bundle-path reference on this line reads as a REAL reference (the
  * agent is told to use the file) rather than an illustrative mention. Requires
@@ -222,7 +260,7 @@ const MD_HEADING = /^\s{0,3}#{1,6}\s/;
  * real dead ref.
  */
 function inlinePathIsUsed(line) {
-    if (ILLUSTRATIVE_CUE.test(line))
+    if (ILLUSTRATIVE_CUE.test(line) || GENERATED_FILE_CUE.test(line))
         return false;
     return USE_DIRECTIVE.test(line) || MD_HEADING.test(line);
 }
@@ -241,7 +279,7 @@ function candidateFor(ref, line) {
         // Suppress it ONLY on an illustrative cue; do NOT also require a use
         // directive, or a plain `Resources: [API](references/api.md)` (no verb)
         // goes unchecked (Codex review — that under-detection).
-        if (ILLUSTRATIVE_CUE.test(line))
+        if (ILLUSTRATIVE_CUE.test(line) || GENERATED_FILE_CUE.test(line))
             return null;
         const resolved = localResourceTarget(ref.value);
         if (resolved === null)

package/dist/core/types.d.ts

@@ -321,6 +321,25 @@ export interface RulesConfig {
      * docs/rules/hook-matcher.md.
      */
     "hook-matcher"?: RuleSeverity;
+    /**
+     * Validate vigiles-builder calls quoted inside ```ts fences in markdown —
+     * `enforce()` / `file()` / `cmd()` / `ref()` — against the real linter catalog,
+     * filesystem and package scripts.
+     *
+     * DEFAULT OFF, and the default is the finding. Measured on two repositories
+     * 2026-08-19 (2 582 markdown files, 52 refs): **zero true positives, and every
+     * error it has ever raised was a false one** — a design sketch writing
+     * `cmd("npm test")` for a package that doesn't exist yet, or a third-party
+     * `CLAUDE.md` captured verbatim as benchmark data. The reason is structural,
+     * not calibration: a fenced block in prose is a DRAWING of config, and this
+     * rule reads it as config. The consumer repo could only reach a clean `lint`
+     * by excluding a third of itself, after which the pass scanned 604 files and
+     * found 0 refs — inert, and still paying for the walk.
+     *
+     * Turn it on where markdown really is the source (a docs site whose fences are
+     * copy-pasted into live specs). See docs/rules/doc-refs.md.
+     */
+    "doc-refs"?: RuleSeverity;
 }
 /** Extract severity from a rule value (handles both simple and tuple forms). */
 export declare function ruleSeverity<T>(rule: RuleWithOptions<T> | undefined): RuleSeverity;

package/dist/core/validate.js

@@ -98,6 +98,12 @@ exports.DEFAULT_RULES = {
     // that matches no tool name, or one too narrow for real server names) — WARN
     // by default (high-precision); raise to error to gate CI.
     "hook-matcher": "warn",
+    // Builder calls quoted inside ```ts fences in markdown — default OFF. Measured
+    // over 2 582 markdown files across two repos: 52 refs, 0 true positives, and
+    // every error raised was a false one (a design sketch's `cmd("npm test")`, a
+    // vendored third-party CLAUDE.md). A fence in prose is a DRAWING of config;
+    // reading it as config is the defect. Opt in where markdown IS the source.
+    "doc-refs": false,
 };
 const DEFAULT_CONFIG = {
     ruleMarkers: ["headings", "checkboxes"],

package/dist/hook.d.ts

@@ -45,7 +45,7 @@
  * tool calls. A gate is a strong default, never an unbypassable wall. See
  * `docs/compiled-hooks.md`.
  */
-export { defineHook, defineFileGate, definePromptGate, defineStopGate, tool, tools, allow, deny, ask, commandView, pathView, gateAction, hookMode, defineInject, inject, defineReact, run, notice, nothing, responseView, decideProgram, decideFileGate, decidePromptGate, decideStopGate, runInject, runReact, runHookProgram, decisionExitCode, dispatchKind, hookRouting, hookNeeds, injectionOf, outcomeWrites, matchesTool, invalidToolPatterns, compileHookProgram, checkHookImports, stampHook, verifyHookStamp, HookCompileError, } from "./core/hook-program.js";
+export { defineHook as experimental_defineHook, defineFileGate as experimental_defineFileGate, definePromptGate as experimental_definePromptGate, defineStopGate as experimental_defineStopGate, tool, tools, allow, deny, ask, commandView, pathView, gateAction, hookMode, defineInject as experimental_defineInject, inject, defineReact as experimental_defineReact, run, notice, nothing, responseView, decideProgram, decideFileGate, decidePromptGate, decideStopGate, runInject, runReact, runHookProgram, decisionExitCode, dispatchKind, hookRouting, hookNeeds, injectionOf, outcomeWrites, matchesTool, invalidToolPatterns, compileHookProgram, checkHookImports, stampHook, verifyHookStamp, HookCompileError, } from "./core/hook-program.js";
 export type { Decision, HookMode, GateAction, CommandView, PathView, ResponseView, BashToolEvent, FileToolEvent, PromptEvent, StopEvent, ReactEvent, SessionEvent, HookProgram, FileGateHook, PromptGateHook, StopGateHook, InjectHook, ReactHook, AnyHook, DispatchKind, Injection, Reaction, RunReaction, CompiledHookProgram, CompileHookOptions, RawHookEvent, HookProgramOutcome, } from "./core/hook-program.js";
 export { provide, dangerously, defineProvider, provider, } from "./core/hook-providers.js";
 export { state, record, stateFact, isValidStateKey, isStateNeed, isStateWrite, admissibleWrites, durationSeconds, HookStateError, } from "./core/hook-state.js";

package/dist/hook.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isStateWrite = exports.isStateNeed = exports.isValidStateKey = exports.stateFact = exports.record = exports.state = exports.provider = exports.defineProvider = exports.dangerously = exports.provide = exports.HookCompileError = exports.verifyHookStamp = exports.stampHook = exports.checkHookImports = exports.compileHookProgram = exports.invalidToolPatterns = exports.matchesTool = exports.outcomeWrites = exports.injectionOf = exports.hookNeeds = exports.hookRouting = exports.dispatchKind = exports.decisionExitCode = exports.runHookProgram = exports.runReact = exports.runInject = exports.decideStopGate = exports.decidePromptGate = exports.decideFileGate = exports.decideProgram = exports.responseView = exports.nothing = exports.notice = exports.run = exports.defineReact = exports.inject = exports.defineInject = exports.hookMode = exports.gateAction = exports.pathView = exports.commandView = exports.ask = exports.deny = exports.allow = exports.tools = exports.tool = exports.defineStopGate = exports.definePromptGate = exports.defineFileGate = exports.defineHook = void 0;
+exports.isStateWrite = exports.isStateNeed = exports.isValidStateKey = exports.stateFact = exports.record = exports.state = exports.provider = exports.defineProvider = exports.dangerously = exports.provide = exports.HookCompileError = exports.verifyHookStamp = exports.stampHook = exports.checkHookImports = exports.compileHookProgram = exports.invalidToolPatterns = exports.matchesTool = exports.outcomeWrites = exports.injectionOf = exports.hookNeeds = exports.hookRouting = exports.dispatchKind = exports.decisionExitCode = exports.runHookProgram = exports.runReact = exports.runInject = exports.decideStopGate = exports.decidePromptGate = exports.decideFileGate = exports.decideProgram = exports.responseView = exports.nothing = exports.notice = exports.run = exports.experimental_defineReact = exports.inject = exports.experimental_defineInject = exports.hookMode = exports.gateAction = exports.pathView = exports.commandView = exports.ask = exports.deny = exports.allow = exports.tools = exports.tool = exports.experimental_defineStopGate = exports.experimental_definePromptGate = exports.experimental_defineFileGate = exports.experimental_defineHook = void 0;
 exports.leafCommandsNormalized = exports.HookStateError = exports.durationSeconds = exports.admissibleWrites = void 0;
 /**
  * `vigiles/hook` — the **closed vocabulary** for authoring a compiled hook.
@@ -50,11 +50,19 @@ exports.leafCommandsNormalized = exports.HookStateError = exports.durationSecond
  * `docs/compiled-hooks.md`.
  */
 var hook_program_js_1 = require("./core/hook-program.js");
-// gate vocabulary
-Object.defineProperty(exports, "defineHook", { enumerable: true, get: function () { return hook_program_js_1.defineHook; } });
-Object.defineProperty(exports, "defineFileGate", { enumerable: true, get: function () { return hook_program_js_1.defineFileGate; } });
-Object.defineProperty(exports, "definePromptGate", { enumerable: true, get: function () { return hook_program_js_1.definePromptGate; } });
-Object.defineProperty(exports, "defineStopGate", { enumerable: true, get: function () { return hook_program_js_1.defineStopGate; } });
+// ── the six ENTRY POINTS carry the experimental marking ─────────────────────
+// Same shape as `experimental_skill`, and for the same stated reason: every
+// other name in this file — `allow`, `deny`, `tool`, `pathView`, `state`,
+// `record` — is reachable ONLY from inside a `define*` call, so prefixing the
+// entry points makes the marking structural for the whole vocabulary. A
+// per-name prefix could not guarantee that; a chokepoint can.
+//
+// Import them aliased, so the word crosses the package boundary exactly once:
+//   import { experimental_defineInject as defineInject, state } from "vigiles/hook";
+Object.defineProperty(exports, "experimental_defineHook", { enumerable: true, get: function () { return hook_program_js_1.defineHook; } });
+Object.defineProperty(exports, "experimental_defineFileGate", { enumerable: true, get: function () { return hook_program_js_1.defineFileGate; } });
+Object.defineProperty(exports, "experimental_definePromptGate", { enumerable: true, get: function () { return hook_program_js_1.definePromptGate; } });
+Object.defineProperty(exports, "experimental_defineStopGate", { enumerable: true, get: function () { return hook_program_js_1.defineStopGate; } });
 Object.defineProperty(exports, "tool", { enumerable: true, get: function () { return hook_program_js_1.tool; } });
 Object.defineProperty(exports, "tools", { enumerable: true, get: function () { return hook_program_js_1.tools; } });
 Object.defineProperty(exports, "allow", { enumerable: true, get: function () { return hook_program_js_1.allow; } });
@@ -65,10 +73,10 @@ Object.defineProperty(exports, "pathView", { enumerable: true, get: function ()
 Object.defineProperty(exports, "gateAction", { enumerable: true, get: function () { return hook_program_js_1.gateAction; } });
 Object.defineProperty(exports, "hookMode", { enumerable: true, get: function () { return hook_program_js_1.hookMode; } });
 // inject vocabulary
-Object.defineProperty(exports, "defineInject", { enumerable: true, get: function () { return hook_program_js_1.defineInject; } });
+Object.defineProperty(exports, "experimental_defineInject", { enumerable: true, get: function () { return hook_program_js_1.defineInject; } });
 Object.defineProperty(exports, "inject", { enumerable: true, get: function () { return hook_program_js_1.inject; } });
 // react vocabulary
-Object.defineProperty(exports, "defineReact", { enumerable: true, get: function () { return hook_program_js_1.defineReact; } });
+Object.defineProperty(exports, "experimental_defineReact", { enumerable: true, get: function () { return hook_program_js_1.defineReact; } });
 Object.defineProperty(exports, "run", { enumerable: true, get: function () { return hook_program_js_1.run; } });
 Object.defineProperty(exports, "notice", { enumerable: true, get: function () { return hook_program_js_1.notice; } });
 Object.defineProperty(exports, "nothing", { enumerable: true, get: function () { return hook_program_js_1.nothing; } });

package/dist/setup-plan.d.ts

@@ -123,7 +123,7 @@ export declare const WORKFLOW_RULES: readonly ["require-instructions-spec", "unt
  * keep their own default severities. Named for the group taxonomy
  * (research/install-enforcement-dx.md).
  */
-export declare const NUDGE_RULES: readonly ["skill-description-budget", "frontmatter-valid", "skill-frontmatter", "prefer-compiled-hooks", "unmarked-refs", "lethal-trifecta", "skill-resource-resolves", "skill-missing-fence", "plugin-dir-layout", "delegation-trifecta", "hook-block-ineffective", "hook-matcher"];
+export declare const NUDGE_RULES: readonly ["skill-description-budget", "frontmatter-valid", "skill-frontmatter", "prefer-compiled-hooks", "unmarked-refs", "lethal-trifecta", "skill-resource-resolves", "skill-missing-fence", "plugin-dir-layout", "delegation-trifecta", "hook-block-ineffective", "hook-matcher", "doc-refs"];
 export declare function mergeProjectConfig(existing: Record<string, unknown>, opts: {
     harness: string | string[];
     strict: boolean;

package/dist/setup-plan.js

@@ -140,6 +140,10 @@ exports.NUDGE_RULES = [
     "delegation-trifecta",
     "hook-block-ineffective",
     "hook-matcher",
+    // Default OFF for a measured reason, not a rollout one: 0 true positives over
+    // 2 582 markdown files, because a fence in prose is a drawing of config rather
+    // than config. See docs/rules/doc-refs.md.
+    "doc-refs",
 ];
 function mergeProjectConfig(existing, opts) {
     const config = { ...existing };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "18.1.2",
+  "version": "19.0.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",