vigiles 6.0.0 → 8.0.0

package/dist/self-command-refs.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findStaleCommandRefs = findStaleCommandRefs;
+/**
+ * Self-command-reference verification — the cross-reference moat applied to
+ * vigiles's OWN docs. vigiles verifies that a CLAUDE.md's commands resolve; its
+ * own docs cite ITS OWN commands, and nothing checked those until a rename left
+ * `vigiles compile-hook` / `vigiles run-skill` rotting in the docs. This is the
+ * deterministic gate: every `vigiles <cmd>` reference in a doc/comment must
+ * resolve to a real command (a VERB or a `hook-runtime <kind>`).
+ *
+ * HIGH-PRECISION by construction (don't-cry-wolf). A reference is inspected only
+ * when it's an unambiguous COMMAND — i.e. it sits inside an inline `` `span` ``,
+ * inside a ```shell fence```, or is prefixed `npx vigiles` / `Usage: vigiles` /
+ * is a `cli.js` or `${CLI}` invocation (the harness-test convention `node ${CLI}
+ * <cmd>`). Prose ("vigiles compiles the spec", "adds vigiles to devDependencies")
+ * and non-shell fences (```text agent prompts, ```ts) are never matched. A bare unknown VERB is flagged only when hyphenated (every
+ * renamed vigiles command is — `compile-hook`, `run-skill`) or in an explicit
+ * invocation; `hook-runtime <kind>` is checked in any command context. Source of
+ * truth: {@link VERBS} / {@link HOOK_RUNTIME_KINDS}.
+ *
+ * KNOWN LIMITATION (measured, deliberately not "fixed"): this catches the
+ * `vigiles <cmd>` / `cli.js <cmd>` INVOCATION form. It does NOT flag a BARE
+ * command name (`agent-hook` without the `vigiles ` prefix) nor a bare file path
+ * (`src/foo.ts`), because both collide with legitimate non-references: bare
+ * command names double as CONCEPT names (`the refs-hook nudge` appears as a
+ * feature name in ~10 files; `agent-hook` as a rail name + in test labels +
+ * `makeTmpDir("agent-hook-cli")`), and bare paths collide with ILLUSTRATIVE
+ * examples (the README's `src/auth/login.ts`, `docs/foo.md`) and test fixtures
+ * (`session.test.ts` builds fake `src/compile.ts` diffs). A denylist over either
+ * would cry wolf on dozens of valid usages — so terminology/path-accuracy stays
+ * the JUDGMENT half the `doc-consistency` rule assigns to discipline, not a check.
+ */
+const cli_commands_js_1 = require("./cli-commands.js");
+const DEFAULT_KNOWN = {
+    verbs: cli_commands_js_1.VERBS,
+    kinds: cli_commands_js_1.HOOK_RUNTIME_KINDS,
+};
+const TOKEN = "[a-z][a-z0-9-]*";
+// `[npx ][vigiles|cli.js|${CLI}] <verb> [<kind>]` — capture the optional prefix +
+// literal. `${CLI}` is the harness-test convention (`const CLI = new
+// URL("…/dist/cli.js")` → `node ${CLI} <cmd>`); without it a stale runtime ref in
+// a `.mjs`/`.test.ts` invocation slips through (it did: refs-nudge.harness.mjs kept
+// calling `refs-hook` after the hook-runtime rename). `\b` can't anchor `${CLI}`
+// (it starts with `$`, a non-word char), so each word literal carries its own `\b`.
+const INVOKE = new RegExp(String.raw `(npx |Usage: )?(\bvigiles|\bcli\.js|\$\{CLI\})\s+(${TOKEN})(?:\s+(${TOKEN}))?`, "g");
+// A bare `hook-runtime <kind>` (e.g. `node ${CLI} hook-runtime agent` in a test).
+const KIND = new RegExp(String.raw `hook-runtime\s+(${TOKEN})`, "g");
+const SHELL_FENCE = /^\s*```(?:bash|sh|shell|zsh|console|shell-session)\s*$/;
+const FENCE = /^\s*```/;
+/** Inclusive index ranges of inline `code spans` in a line. */
+function codeSpans(line) {
+    const ranges = [];
+    for (const m of line.matchAll(/`[^`\n]+`/g))
+        ranges.push([m.index, m.index + m[0].length]);
+    return ranges;
+}
+const inSpan = (i, spans) => spans.some(([a, b]) => i >= a && i < b);
+function scanLine(line, inShellFence, known) {
+    const spans = inShellFence ? null : codeSpans(line);
+    const ctx = (i) => inShellFence || inSpan(i, spans ?? []);
+    const out = [];
+    const seen = new Set();
+    const push = (ref, reason) => {
+        const key = ref + "\0" + reason;
+        if (!seen.has(key)) {
+            seen.add(key);
+            out.push({ ref, reason });
+        }
+    };
+    for (const m of line.matchAll(INVOKE)) {
+        const explicit = inShellFence || Boolean(m[1]) || m[2] === "cli.js" || m[2] === "${CLI}";
+        if (!explicit && !ctx(m.index))
+            continue;
+        const verb = m[3];
+        if (verb === "hook-runtime") {
+            if (m[4] !== undefined && !known.kinds.includes(m[4]))
+                push(`hook-runtime ${m[4]}`, `unknown hook-runtime kind "${m[4]}"`);
+        }
+        else if (!known.verbs.includes(verb) &&
+            (verb.includes("-") || explicit)) {
+            push(`${m[2]} ${verb}`, `unknown/removed command "${verb}"`);
+        }
+    }
+    // Bare `hook-runtime <kind>` (no vigiles/cli.js literal) inside a command context.
+    for (const m of line.matchAll(KIND)) {
+        if (!ctx(m.index))
+            continue;
+        if (!known.kinds.includes(m[1]))
+            push(`hook-runtime ${m[1]}`, `unknown hook-runtime kind "${m[1]}"`);
+    }
+    return out;
+}
+/**
+ * Find stale/unknown vigiles command references across the given files. Pure —
+ * the caller supplies file contents (so it works over the repo in a test, or any
+ * file set).
+ */
+function findStaleCommandRefs(files, known = DEFAULT_KNOWN) {
+    const issues = [];
+    for (const { path, content } of files) {
+        let inAnyFence = false;
+        let inShellFence = false;
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (FENCE.test(line)) {
+                if (inAnyFence) {
+                    inAnyFence = inShellFence = false;
+                }
+                else {
+                    inAnyFence = true;
+                    inShellFence = SHELL_FENCE.test(line);
+                }
+                continue;
+            }
+            if (line.includes("vigiles:ignore-cmd"))
+                continue;
+            for (const f of scanLine(line, inShellFence, known))
+                issues.push({ file: path, line: i + 1, ref: f.ref, reason: f.reason });
+        }
+    }
+    return issues;
+}
+//# sourceMappingURL=self-command-refs.js.map

package/dist/setup-plan.d.ts

@@ -27,6 +27,10 @@ export interface SetupPlan {
 export interface ParsedSetupArgs {
     target?: string;
     strict: boolean;
+    /** `--report-only` — write the gating rules at "warn" (nothing fails CI). The
+     * orthogonal severity dial; composes with `--strict` (which rules) by setting
+     * their severity. */
+    reportOnly: boolean;
     yes: boolean;
     /** `--force` — rewrite a stale CI workflow in place. */
     force: boolean;
@@ -51,9 +55,52 @@ export declare function defaultPlan(strict?: boolean): SetupPlan;
  * changed (so the IO layer skips the write). The IO (read/parse/write + the
  * malformed-file guard) stays in cli.ts.
  */
+/**
+ * The structural rules `init` gates BY DEFAULT (severity `error`, so a broken
+ * surface fails `vigiles lint`). Every one is HIGH-PRECISION / FP-safe — it fires
+ * only on a genuine defect (a never-available/typo'd tool, a subagent missing
+ * `name`/`description`, a typo'd hook event, a dead hook script, a broken MCP
+ * ref, two skills that collide in the selector) — so a well-formed plugin stays
+ * green and catching real breakage out of the box never cries wolf.
+ *
+ * Deliberately EXCLUDES `require-instructions-spec` and the workflow-forcing rules:
+ * those make a CLEAN repo fail (you simply haven't written the spec/test yet), so
+ * they stay opt-in under `--strict` (progressive adoption — see
+ * `STRICT_EXTRA_RULES`).
+ *
+ * This is the **`structural`** rule group (see research/install-enforcement-dx.md).
+ */
+export declare const STRUCTURAL_RULES: readonly ["subagent-tool-contract", "subagent-frontmatter", "hook-events", "hook-script-exists", "mcp-config", "mcp-tool-resolves", "mcp-hook-target-resolves", "disallowed-tools-contract", "description-overlap"];
+/**
+ * The **`workflow`** group — the WORKFLOW-FORCING / opinionated tier `--strict`
+ * gates, which a clean repo can still fail because you haven't done the work yet:
+ * a spec per instruction file (`require-instructions-spec`), a test/eval per
+ * surface (`untested-*`). Opt-in by design (the smooth-adoption on-ramp). The
+ * Clippy-`pedantic` / TS-`strict` analog — ONE opinionated opt-in.
+ *
+ * NB `frontmatter-valid` / `skill-frontmatter` live in the `nudge` group, not
+ * here: they're acknowledged-noisy recommendations we never gate on (see
+ * research/install-enforcement-dx.md).
+ */
+export declare const WORKFLOW_RULES: readonly ["require-instructions-spec", "untested-skill", "untested-subagent", "untested-hook"];
+/**
+ * The **`nudge`** group — recommendations / acknowledged-noisy checks that NEVER
+ * gate (not even under `--strict`): `frontmatter-valid` (js-yaml is stricter than
+ * CC's loader), `skill-frontmatter` (skills load without it) and `unmarked-refs`
+ * (the undecidable-plaintext nudge) sit at `warn`; `prefer-compiled-hooks` defaults
+ * OFF (a recommendation that shouldn't fire unasked — the shell lane stays
+ * first-class). `init` does not write these — they keep their own default
+ * severities. Named for the group taxonomy (research/install-enforcement-dx.md).
+ */
+export declare const NUDGE_RULES: readonly ["frontmatter-valid", "skill-frontmatter", "prefer-compiled-hooks", "unmarked-refs"];
 export declare function mergeProjectConfig(existing: Record<string, unknown>, opts: {
     harness: string | string[];
     strict: boolean;
+    reportOnly?: boolean;
+    /** Whether the LINT pillar is on (default true). The rule gate is a lint-layer
+     * concern, so a test-only setup (`init --test` / `--no-lint`) records the
+     * harness but writes NO lint rules. */
+    lint?: boolean;
 }): Record<string, unknown> | null;
 /**
  * Whether to drop into interactive prompts: a human at a TTY who passed neither
@@ -62,7 +109,18 @@ export declare function mergeProjectConfig(existing: Record<string, unknown>, op
  */
 export declare function shouldPrompt(parsed: ParsedSetupArgs, isTTY: boolean): boolean;
 /** Interactive answers (only the fields the prompts cover). */
-export type SetupAnswers = Partial<Pick<SetupPlan, "lint" | "test" | "gha" | "plugin">>;
+export type SetupAnswers = Partial<Pick<SetupPlan, "lint" | "test" | "gha" | "plugin" | "strict">>;
+/** Ask one question with a default — injected so the interactive Q&A is pure +
+ *  unit-testable (a fake `ask` scripts answers; no TTY, no readline). */
+export type AskFn = (question: string, def: string) => Promise<string>;
+/**
+ * The interactive setup Q&A as PURE logic over an injected `ask` — the prompts,
+ * their defaults, and the answer→`SetupAnswers` mapping. The IO shell (readline)
+ * lives in `cli.ts`'s `promptSetup`, which just supplies a real `ask`. Keeping
+ * this here means the fragile interactive path is unit-tested deterministically
+ * (the questions can't silently break) without a terminal.
+ */
+export declare function collectSetupAnswers(ask: AskFn): Promise<SetupAnswers>;
 /**
  * How to install vigiles's skills/hooks for ONE harness — the deterministic
  * decision behind the IO in cli.ts, so a CI test asserts WHICH commands an

package/dist/setup-plan.js

@@ -10,10 +10,12 @@
  * on a prompt. See docs/agent-setup.md.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.NUDGE_RULES = exports.WORKFLOW_RULES = exports.STRUCTURAL_RULES = void 0;
 exports.parseSetupArgs = parseSetupArgs;
 exports.defaultPlan = defaultPlan;
 exports.mergeProjectConfig = mergeProjectConfig;
 exports.shouldPrompt = shouldPrompt;
+exports.collectSetupAnswers = collectSetupAnswers;
 exports.planPluginInstall = planPluginInstall;
 exports.resolvePlan = resolvePlan;
 function flagValue(args, prefix) {
@@ -33,6 +35,7 @@ function parseSetupArgs(args) {
     return {
         target: flagValue(args, "--target="),
         strict: args.includes("--strict"),
+        reportOnly: args.includes("--report-only"),
         yes: args.includes("--yes") || args.includes("-y"),
         force: args.includes("--force"),
         lint: boolFlag(args, "lint"),
@@ -60,6 +63,64 @@ function defaultPlan(strict = false) {
  * changed (so the IO layer skips the write). The IO (read/parse/write + the
  * malformed-file guard) stays in cli.ts.
  */
+/**
+ * The structural rules `init` gates BY DEFAULT (severity `error`, so a broken
+ * surface fails `vigiles lint`). Every one is HIGH-PRECISION / FP-safe — it fires
+ * only on a genuine defect (a never-available/typo'd tool, a subagent missing
+ * `name`/`description`, a typo'd hook event, a dead hook script, a broken MCP
+ * ref, two skills that collide in the selector) — so a well-formed plugin stays
+ * green and catching real breakage out of the box never cries wolf.
+ *
+ * Deliberately EXCLUDES `require-instructions-spec` and the workflow-forcing rules:
+ * those make a CLEAN repo fail (you simply haven't written the spec/test yet), so
+ * they stay opt-in under `--strict` (progressive adoption — see
+ * `STRICT_EXTRA_RULES`).
+ *
+ * This is the **`structural`** rule group (see research/install-enforcement-dx.md).
+ */
+exports.STRUCTURAL_RULES = [
+    "subagent-tool-contract",
+    "subagent-frontmatter",
+    "hook-events",
+    "hook-script-exists",
+    "mcp-config",
+    "mcp-tool-resolves",
+    "mcp-hook-target-resolves",
+    "disallowed-tools-contract",
+    "description-overlap",
+];
+/**
+ * The **`workflow`** group — the WORKFLOW-FORCING / opinionated tier `--strict`
+ * gates, which a clean repo can still fail because you haven't done the work yet:
+ * a spec per instruction file (`require-instructions-spec`), a test/eval per
+ * surface (`untested-*`). Opt-in by design (the smooth-adoption on-ramp). The
+ * Clippy-`pedantic` / TS-`strict` analog — ONE opinionated opt-in.
+ *
+ * NB `frontmatter-valid` / `skill-frontmatter` live in the `nudge` group, not
+ * here: they're acknowledged-noisy recommendations we never gate on (see
+ * research/install-enforcement-dx.md).
+ */
+exports.WORKFLOW_RULES = [
+    "require-instructions-spec",
+    "untested-skill",
+    "untested-subagent",
+    "untested-hook",
+];
+/**
+ * The **`nudge`** group — recommendations / acknowledged-noisy checks that NEVER
+ * gate (not even under `--strict`): `frontmatter-valid` (js-yaml is stricter than
+ * CC's loader), `skill-frontmatter` (skills load without it) and `unmarked-refs`
+ * (the undecidable-plaintext nudge) sit at `warn`; `prefer-compiled-hooks` defaults
+ * OFF (a recommendation that shouldn't fire unasked — the shell lane stays
+ * first-class). `init` does not write these — they keep their own default
+ * severities. Named for the group taxonomy (research/install-enforcement-dx.md).
+ */
+exports.NUDGE_RULES = [
+    "frontmatter-valid",
+    "skill-frontmatter",
+    "prefer-compiled-hooks",
+    "unmarked-refs",
+];
 function mergeProjectConfig(existing, opts) {
     const config = { ...existing };
     let changed = false;
@@ -67,13 +128,23 @@ function mergeProjectConfig(existing, opts) {
         config.harness = opts.harness;
         changed = true;
     }
-    if (opts.strict) {
+    // The rule gate belongs to the LINT layer — a test-only setup records the
+    // harness but writes no rules (honoring the positive-flag contract that
+    // `--test` selects only the test pillar).
+    if (opts.lint !== false) {
+        // Gate the FP-safe `structural` group by default; `--strict` adds the
+        // `workflow` group on top. `--report-only` is the orthogonal severity dial —
+        // it writes the SAME rule set at "warn" (nothing fails CI; the
+        // migration/observe mode). Never clobber a severity the user already set —
+        // only fill the undefined ones.
+        const severity = opts.reportOnly ? "warn" : "error";
+        const gate = opts.strict
+            ? [...exports.STRUCTURAL_RULES, ...exports.WORKFLOW_RULES]
+            : [...exports.STRUCTURAL_RULES];
         const rules = { ...config.rules };
-        // `require-skill-spec` is deprecated (skills can be hand-written), so --strict
-        // no longer promotes it; it tightens only `require-spec` (instruction files).
-        for (const r of ["require-spec"]) {
+        for (const r of gate) {
             if (rules[r] === undefined) {
-                rules[r] = "error";
+                rules[r] = severity;
                 changed = true;
             }
         }
@@ -93,6 +164,31 @@ function shouldPrompt(parsed, isTTY) {
     const allPinned = pillarsPinned && parsed.gha !== undefined && parsed.plugin !== undefined;
     return !allPinned;
 }
+const isYesAnswer = (s) => /^y(es)?$/i.test(s);
+/**
+ * The interactive setup Q&A as PURE logic over an injected `ask` — the prompts,
+ * their defaults, and the answer→`SetupAnswers` mapping. The IO shell (readline)
+ * lives in `cli.ts`'s `promptSetup`, which just supplies a real `ask`. Keeping
+ * this here means the fragile interactive path is unit-tested deterministically
+ * (the questions can't silently break) without a terminal.
+ */
+async function collectSetupAnswers(ask) {
+    const pillars = (await ask("Set up which pillars? [both/lint/test] (both): ", "both")).toLowerCase();
+    const gha = isYesAnswer(await ask("Wire CI (GitHub Action)? [Y/n]: ", "y"));
+    const plugin = isYesAnswer(await ask("Install the Claude Code plugin (hooks + skills)? [Y/n]: ", "y"));
+    // Structural gating (broken tools/hooks/MCP/collisions) is always on. This asks
+    // about the WORKFLOW tier — a spec per file + a test per surface — which a clean
+    // repo can fail just for not having done the work yet, so it's the recommended
+    // default a human opts OUT of (never forced on a silent run).
+    const strict = isYesAnswer(await ask("Also enforce specs + a test per surface (recommended)? [Y/n]: ", "y"));
+    return {
+        lint: pillars !== "test",
+        test: pillars !== "lint" && pillars !== "verify",
+        gha,
+        plugin,
+        strict,
+    };
+}
 /**
  * Apply the pillar flags. A positive flag (`--lint` and/or `--test`) is an
  * explicit SELECTION — enable exactly the named pillars. Otherwise default to
@@ -118,6 +214,8 @@ function applyAnswers(plan, answers) {
         plan.gha = answers.gha;
     if (answers.plugin !== undefined)
         plan.plugin = answers.plugin;
+    if (answers.strict !== undefined)
+        plan.strict = answers.strict;
 }
 /** Per-harness install plan. `hasClaude` gates the auto-run `claude plugin` CLI
  * (else the same two steps are printed as `/plugin` slash commands).

package/dist/testing.d.ts

@@ -10,13 +10,15 @@
  * boundary forbids importing `src/adapters/*` from here. See
  * `research/adapter-api-design.md`.
  */
-export * from "./run-hook.js";
-export * from "./eval.js";
+export { runHook, propertyHook } from "./run-hook.js";
+export type { HookRunResult, RunHookOptions, HookInput, HookOutput, HookPropertyResult, } from "./run-hook.js";
+export { runEval, measure, measureArms, measureTriggerRate, assertRates, assertPromptDiversity, checkPromptDiversity, checkReportToJUnit, formatCheckReport, formatEvalReport, formatTriggerRateReport, claudeEvalDriver, parseClaudeRun, stubSkillBody, } from "./eval.js";
+export type { EvalArm, EvalDriver, EvalSpec, EvalReport, EvalUsage, MeasureSpec, ArmsMeasureSpec, ArmReport, ArmUsage, ArmsCheckReport, CheckRate, CheckReport, MetricStat, Metrics, ModelOutputParser, ParsedModelRun, PromptDiversityIssue, PromptTriggerStat, RunContext, RunOut, SelectionTrialResult, TriggerRateReport, TriggerRateSpec, AgentRunArgs, AgentRunner, } from "./eval.js";
 export * from "./harness-assert.js";
 export * from "./check.js";
 export { hookFired } from "./check.js";
 export { judge } from "./judge.js";
 export * from "./tool-stub.js";
-export { runHarnessTest, runHarness, parseToolCalls, parseSubagents, parseResultEvent, parseOutput, parseHooks, decideSandbox, specTrusted, sandboxAvailable, } from "./harness-test.js";
+export { runHarnessTest, runHarness } from "./harness-test.js";
 export type { HarnessTestSpec, Trace, SubagentTrace, HarnessTestResult, RunHarnessTestOptions, ModelTurn, ModelRequest, ToolCall, HookFire, HarnessTestDriver, SandboxMode, } from "./harness-test.js";
 //# sourceMappingURL=testing.d.ts.map

package/dist/testing.js

@@ -1,4 +1,20 @@
 "use strict";
+/**
+ * `vigiles/testing` — Pillar 2 entry point: the **harness-testing** API. Re-exports
+ * the three tiers — `runHook` (unit), `runHarnessTest` (deterministic), `runEval`
+ * (eval) — plus the runner-agnostic predicates/assertions. Kept deliberately
+ * separate from `vigiles/claude-code` so this surface can stay harness-agnostic as
+ * more harnesses are added. Granular paths (`vigiles/run-hook`, etc.) still work.
+ *
+ * It re-exports the composition-root runner modules (which do the Claude-Code
+ * default-wiring), never an adapter directly — the `agnostic-surface` eslint
+ * boundary forbids importing `src/adapters/*` from here. See
+ * `research/adapter-api-design.md`.
+ */
+// Curated public re-exports (named, not `export *`) so the internal seams —
+// the injectable `*With` runners, low-level `parse*`, pool/aggregate/model-tier
+// helpers — stay out of the public surface, the api reports, and the docs site.
+// (vigiles's own tests import those from the source modules directly.)
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -14,21 +30,27 @@ 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.sandboxAvailable = exports.specTrusted = exports.decideSandbox = exports.parseHooks = exports.parseOutput = exports.parseResultEvent = exports.parseSubagents = exports.parseToolCalls = exports.runHarness = exports.runHarnessTest = exports.judge = exports.hookFired = void 0;
-/**
- * `vigiles/testing` — Pillar 2 entry point: the **harness-testing** API. Re-exports
- * the three tiers — `runHook` (unit), `runHarnessTest` (deterministic), `runEval`
- * (eval) — plus the runner-agnostic predicates/assertions. Kept deliberately
- * separate from `vigiles/claude-code` so this surface can stay harness-agnostic as
- * more harnesses are added. Granular paths (`vigiles/run-hook`, etc.) still work.
- *
- * It re-exports the composition-root runner modules (which do the Claude-Code
- * default-wiring), never an adapter directly — the `agnostic-surface` eslint
- * boundary forbids importing `src/adapters/*` from here. See
- * `research/adapter-api-design.md`.
- */
-__exportStar(require("./run-hook.js"), exports);
-__exportStar(require("./eval.js"), exports);
+exports.runHarness = exports.runHarnessTest = exports.judge = exports.hookFired = exports.stubSkillBody = exports.parseClaudeRun = exports.claudeEvalDriver = exports.formatTriggerRateReport = exports.formatEvalReport = exports.formatCheckReport = exports.checkReportToJUnit = exports.checkPromptDiversity = exports.assertPromptDiversity = exports.assertRates = exports.measureTriggerRate = exports.measureArms = exports.measure = exports.runEval = exports.propertyHook = exports.runHook = void 0;
+// --- unit tier: runHook ---
+var run_hook_js_1 = require("./run-hook.js");
+Object.defineProperty(exports, "runHook", { enumerable: true, get: function () { return run_hook_js_1.runHook; } });
+Object.defineProperty(exports, "propertyHook", { enumerable: true, get: function () { return run_hook_js_1.propertyHook; } });
+// --- eval tier: runEval / measure / trigger-rate ---
+var eval_js_1 = require("./eval.js");
+Object.defineProperty(exports, "runEval", { enumerable: true, get: function () { return eval_js_1.runEval; } });
+Object.defineProperty(exports, "measure", { enumerable: true, get: function () { return eval_js_1.measure; } });
+Object.defineProperty(exports, "measureArms", { enumerable: true, get: function () { return eval_js_1.measureArms; } });
+Object.defineProperty(exports, "measureTriggerRate", { enumerable: true, get: function () { return eval_js_1.measureTriggerRate; } });
+Object.defineProperty(exports, "assertRates", { enumerable: true, get: function () { return eval_js_1.assertRates; } });
+Object.defineProperty(exports, "assertPromptDiversity", { enumerable: true, get: function () { return eval_js_1.assertPromptDiversity; } });
+Object.defineProperty(exports, "checkPromptDiversity", { enumerable: true, get: function () { return eval_js_1.checkPromptDiversity; } });
+Object.defineProperty(exports, "checkReportToJUnit", { enumerable: true, get: function () { return eval_js_1.checkReportToJUnit; } });
+Object.defineProperty(exports, "formatCheckReport", { enumerable: true, get: function () { return eval_js_1.formatCheckReport; } });
+Object.defineProperty(exports, "formatEvalReport", { enumerable: true, get: function () { return eval_js_1.formatEvalReport; } });
+Object.defineProperty(exports, "formatTriggerRateReport", { enumerable: true, get: function () { return eval_js_1.formatTriggerRateReport; } });
+Object.defineProperty(exports, "claudeEvalDriver", { enumerable: true, get: function () { return eval_js_1.claudeEvalDriver; } });
+Object.defineProperty(exports, "parseClaudeRun", { enumerable: true, get: function () { return eval_js_1.parseClaudeRun; } });
+Object.defineProperty(exports, "stubSkillBody", { enumerable: true, get: function () { return eval_js_1.stubSkillBody; } });
 __exportStar(require("./harness-assert.js"), exports);
 // The declarative check vocabulary is now first-class at the front door. Its
 // `hookFired` (a `Check<Trace>`) supersedes the legacy boolean predicate of the
@@ -51,12 +73,4 @@ __exportStar(require("./tool-stub.js"), exports);
 var harness_test_js_1 = require("./harness-test.js");
 Object.defineProperty(exports, "runHarnessTest", { enumerable: true, get: function () { return harness_test_js_1.runHarnessTest; } });
 Object.defineProperty(exports, "runHarness", { enumerable: true, get: function () { return harness_test_js_1.runHarness; } });
-Object.defineProperty(exports, "parseToolCalls", { enumerable: true, get: function () { return harness_test_js_1.parseToolCalls; } });
-Object.defineProperty(exports, "parseSubagents", { enumerable: true, get: function () { return harness_test_js_1.parseSubagents; } });
-Object.defineProperty(exports, "parseResultEvent", { enumerable: true, get: function () { return harness_test_js_1.parseResultEvent; } });
-Object.defineProperty(exports, "parseOutput", { enumerable: true, get: function () { return harness_test_js_1.parseOutput; } });
-Object.defineProperty(exports, "parseHooks", { enumerable: true, get: function () { return harness_test_js_1.parseHooks; } });
-Object.defineProperty(exports, "decideSandbox", { enumerable: true, get: function () { return harness_test_js_1.decideSandbox; } });
-Object.defineProperty(exports, "specTrusted", { enumerable: true, get: function () { return harness_test_js_1.specTrusted; } });
-Object.defineProperty(exports, "sandboxAvailable", { enumerable: true, get: function () { return harness_test_js_1.sandboxAvailable; } });
 //# sourceMappingURL=testing.js.map

package/dist/tool-intercept.d.ts

@@ -15,7 +15,7 @@
  *
  * - `decideIntercept` — does this call get intercepted, and with what deny reason;
  * - `buildInterceptSettings` — the PreToolUse hook fragment routing matched tools
- *   through `vigiles intercept-tool-hook`;
+ *   through `vigiles hook-runtime intercept-tool`;
  * - `serializeIntercepts` / `parseIntercepts` — the env round-trip (incl. RegExp
  *   matchers) the hook subprocess reads back.
  *
@@ -32,7 +32,7 @@
  * tools, so deny+reason is the closest available — with that ceiling.
  */
 import { type ArgMatcher } from "./arg-match.js";
-/** Env var the spawned `vigiles intercept-tool-hook` reads its intercept list from. */
+/** Env var the spawned `vigiles hook-runtime intercept-tool` reads its intercept list from. */
 export declare const INTERCEPT_TOOLS_ENV = "VIGILES_INTERCEPT_TOOLS";
 /** Declare a tool to intercept: deny its real execution with a block message. */
 export interface ToolIntercept {
@@ -63,7 +63,7 @@ export type InterceptDecision = {
 /**
  * Decide whether a tool call should be intercepted. Returns the first matching
  * intercept's denial reason (preventing real execution), or `{ intercept: false }`
- * to let the call run for real. Pure — the same logic `vigiles intercept-tool-hook`
+ * to let the call run for real. Pure — the same logic `vigiles hook-runtime intercept-tool`
  * runs.
  */
 export declare function decideIntercept(toolName: string, input: unknown, intercepts: readonly ToolIntercept[]): InterceptDecision;
@@ -81,7 +81,7 @@ export interface InterceptSettings {
 }
 /**
  * Build the PreToolUse hook fragment that routes every intercepted tool through
- * `vigiles intercept-tool-hook`. The `matcher` is a CC tool-name regex over the
+ * `vigiles hook-runtime intercept-tool`. The `matcher` is a CC tool-name regex over the
  * union of intercepted tool names (each escaped), so unrelated tools are never
  * intercepted. Merge the result into an arm's `settings`; the intercept list
  * itself travels in the {@link INTERCEPT_TOOLS_ENV} env var (see

package/dist/tool-intercept.js

@@ -23,7 +23,7 @@ exports.parseIntercepts = parseIntercepts;
  *
  * - `decideIntercept` — does this call get intercepted, and with what deny reason;
  * - `buildInterceptSettings` — the PreToolUse hook fragment routing matched tools
- *   through `vigiles intercept-tool-hook`;
+ *   through `vigiles hook-runtime intercept-tool`;
  * - `serializeIntercepts` / `parseIntercepts` — the env round-trip (incl. RegExp
  *   matchers) the hook subprocess reads back.
  *
@@ -40,7 +40,7 @@ exports.parseIntercepts = parseIntercepts;
  * tools, so deny+reason is the closest available — with that ceiling.
  */
 const arg_match_js_1 = require("./arg-match.js");
-/** Env var the spawned `vigiles intercept-tool-hook` reads its intercept list from. */
+/** Env var the spawned `vigiles hook-runtime intercept-tool` reads its intercept list from. */
 exports.INTERCEPT_TOOLS_ENV = "VIGILES_INTERCEPT_TOOLS";
 /** The default denial reason — honest that the call was intercepted (prevented), NOT executed. */
 exports.DEFAULT_INTERCEPT_REASON = "vigiles intercepted this tool call for testing — it was NOT executed. " +
@@ -48,7 +48,7 @@ exports.DEFAULT_INTERCEPT_REASON = "vigiles intercepted this tool call for testi
 /**
  * Decide whether a tool call should be intercepted. Returns the first matching
  * intercept's denial reason (preventing real execution), or `{ intercept: false }`
- * to let the call run for real. Pure — the same logic `vigiles intercept-tool-hook`
+ * to let the call run for real. Pure — the same logic `vigiles hook-runtime intercept-tool`
  * runs.
  */
 function decideIntercept(toolName, input, intercepts) {
@@ -90,14 +90,14 @@ function uniqueToolNames(intercepts) {
 }
 /**
  * Build the PreToolUse hook fragment that routes every intercepted tool through
- * `vigiles intercept-tool-hook`. The `matcher` is a CC tool-name regex over the
+ * `vigiles hook-runtime intercept-tool`. The `matcher` is a CC tool-name regex over the
  * union of intercepted tool names (each escaped), so unrelated tools are never
  * intercepted. Merge the result into an arm's `settings`; the intercept list
  * itself travels in the {@link INTERCEPT_TOOLS_ENV} env var (see
  * {@link serializeIntercepts}).
  */
 function buildInterceptSettings(intercepts, opts = {}) {
-    const command = opts.command ?? "npx vigiles intercept-tool-hook";
+    const command = opts.command ?? "npx vigiles hook-runtime intercept-tool";
     const matcher = uniqueToolNames(intercepts).map(escapeRegex).join("|");
     return {
         hooks: {

package/dist/unit.d.ts

@@ -16,4 +16,6 @@ export { runHook, parseHookOutput, decideHook, propertyHook, } from "./run-hook.
 export type { HookInput, HookOutput, HookRunResult, RunHookOptions, HookPropertyResult, } from "./run-hook.js";
 export * from "./check.js";
 export { hookFired } from "./check.js";
+export { DISASTER_CATALOG, verifyGuardrail, unblockedDisasters, assertBlocksDisasters, formatGuardrailReport, } from "./guardrail-check.js";
+export type { DisasterEvent, DisasterCategory, GuardrailResult, VerifyGuardrailOptions, } from "./guardrail-check.js";
 //# sourceMappingURL=unit.d.ts.map

package/dist/unit.js

@@ -14,7 +14,7 @@ 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.hookFired = exports.propertyHook = exports.decideHook = exports.parseHookOutput = exports.runHook = void 0;
+exports.formatGuardrailReport = exports.assertBlocksDisasters = exports.unblockedDisasters = exports.verifyGuardrail = exports.DISASTER_CATALOG = exports.hookFired = exports.propertyHook = exports.decideHook = exports.parseHookOutput = exports.runHook = void 0;
 /**
  * `vigiles/unit` — the **no-capability** harness-testing surface.
  *
@@ -39,4 +39,11 @@ Object.defineProperty(exports, "propertyHook", { enumerable: true, get: function
 __exportStar(require("./check.js"), exports);
 var check_js_1 = require("./check.js");
 Object.defineProperty(exports, "hookFired", { enumerable: true, get: function () { return check_js_1.hookFired; } });
+// Guardrail verification — "prove your safety hook actually blocks" (over runHook).
+var guardrail_check_js_1 = require("./guardrail-check.js");
+Object.defineProperty(exports, "DISASTER_CATALOG", { enumerable: true, get: function () { return guardrail_check_js_1.DISASTER_CATALOG; } });
+Object.defineProperty(exports, "verifyGuardrail", { enumerable: true, get: function () { return guardrail_check_js_1.verifyGuardrail; } });
+Object.defineProperty(exports, "unblockedDisasters", { enumerable: true, get: function () { return guardrail_check_js_1.unblockedDisasters; } });
+Object.defineProperty(exports, "assertBlocksDisasters", { enumerable: true, get: function () { return guardrail_check_js_1.assertBlocksDisasters; } });
+Object.defineProperty(exports, "formatGuardrailReport", { enumerable: true, get: function () { return guardrail_check_js_1.formatGuardrailReport; } });
 //# sourceMappingURL=unit.js.map

package/hooks/post-edit.sh

@@ -19,7 +19,7 @@ BASENAME=$(basename "$FILE")
 case "$BASENAME" in
   eslint.config.*|.eslintrc*|.stylelintrc*|.rubocop.yml|pyproject.toml|Cargo.toml|package.json)
     if command -v npx &>/dev/null && [ -f "package.json" ]; then
-      npx vigiles generate-types 2>&1 || true
+      npx vigiles generate types 2>&1 || true
     fi
     ;;
 esac

package/hooks/refs-nudge.sh

@@ -13,7 +13,7 @@ INPUT=$(cat)
 command -v npx >/dev/null 2>&1 || exit 0
 [ -f package.json ] || exit 0
 
-printf '%s' "$INPUT" | npx vigiles refs-hook
+printf '%s' "$INPUT" | npx vigiles hook-runtime refs
 status=${PIPESTATUS[1]}
 
 # Propagate ONLY an explicit block (exit 2). Swallow tool/setup errors so a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "6.0.0",
+  "version": "8.0.0",
   "description": "Lint & test the harness your AI agent runs on — verify the references in your CLAUDE.md / AGENTS.md and test that your hooks and skills actually work.",
   "keywords": [
     "claude-code",
@@ -38,6 +38,7 @@
     "./linting": "./dist/linting.js",
     "./testing": "./dist/testing.js",
     "./unit": "./dist/unit.js",
+    "./hook": "./dist/hook.js",
     "./integration": "./dist/integration.js",
     "./e2e": "./dist/e2e.js",
     "./claude-code": "./dist/claude-code.js",
@@ -82,11 +83,10 @@
     "test:types": "npm run build && tsc --noEmit -p test/types/tsconfig.json",
     "api:report": "npm run build && node scripts/api-extractor.mjs --local",
     "api:check": "npm run build && node scripts/api-extractor.mjs",
-    "docs:api": "npm run api:report && api-documenter markdown -i temp -o api-reference"
+    "docs:api": "typedoc"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@microsoft/api-documenter": "^7.30.7",
     "@microsoft/api-extractor": "^7.58.9",
     "@types/js-yaml": "^4.0.9",
     "@types/minimatch": "^5.1.2",
@@ -102,6 +102,7 @@
     "jest": "^30.4.2",
     "prettier": "^3.8.1",
     "tsx": "^4.21.0",
+    "typedoc": "^0.28.19",
     "typescript": "^5.9.3",
     "vitest": "^4.1.8"
   },
@@ -124,6 +125,7 @@
     "@ast-grep/napi": "^0.43.0",
     "@iarna/toml": "^2.2.5",
     "@jackchuka/mdschema": "^0.12.8",
+    "ci-info": "^4.4.0",
     "cosmiconfig": "^9.0.1",
     "glob": "^13.0.6",
     "js-yaml": "^4.1.0",