vigiles 4.0.1 → 4.0.2

package/dist/harness-test.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.claudeCodeDriver = exports.sandboxAvailable = exports.specTrusted = exports.decideSandbox = exports.resolveHarness = exports.loadPlugin = exports.scriptModel = void 0;
 exports.parseToolCalls = parseToolCalls;
+exports.parseSubagents = parseSubagents;
 exports.parseResultEvent = parseResultEvent;
 exports.parseOutput = parseOutput;
 exports.parseHooks = parseHooks;
@@ -9,6 +10,7 @@ exports.buildClaudeArgs = buildClaudeArgs;
 exports.parseClaudeRun = parseClaudeRun;
 exports.claudeAvailable = claudeAvailable;
 exports.runHarnessTest = runHarnessTest;
+exports.runHarness = runHarness;
 /**
  * vigiles — deterministic Claude Code harness testing.
  *
@@ -114,6 +116,82 @@ function parseToolCalls(streamJson) {
         isError: results.get(u.id)?.isError ?? false,
     }));
 }
+/**
+ * Recover sub-agent runs as nested traces. A subagent-dispatch tool call (the
+ * `Agent` tool on the live CLI — older docs say `Task` — carrying an
+ * `input.subagent_type`) spawns a subagent whose own events the CLI tags with a
+ * top-level `parent_tool_use_id` = the dispatch tool-use id. We group those
+ * tagged tool calls under their dispatch, keyed by `subagent_type`. **Schema
+ * verified against real claude output** (`parent_tool_use_id` sibling of
+ * `message`, `subagent_type` in the dispatch input; tool named `Agent`) — the
+ * same `message.content` line shape `parseToolCalls` consumes, and we match the
+ * input field NOT the tool name so a future rename can't break it. Pure; empty
+ * for a harness that doesn't emit `parent_tool_use_id` (e.g. Codex).
+ */
+function parseSubagents(streamJson) {
+    const tasks = new Map(); // dispatch id → subagent name
+    const byParent = new Map();
+    const groupFor = (parent) => {
+        let g = byParent.get(parent);
+        if (!g) {
+            g = { uses: [], results: new Map() };
+            byParent.set(parent, g);
+        }
+        return g;
+    };
+    for (const line of streamJson.split("\n")) {
+        if (!line.trim())
+            continue;
+        let evt;
+        try {
+            evt = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const content = evt.message?.content;
+        if (!Array.isArray(content))
+            continue;
+        const parent = typeof evt.parent_tool_use_id === "string"
+            ? evt.parent_tool_use_id
+            : undefined;
+        for (const b of content) {
+            if (b.type === "tool_use" && typeof b.name === "string") {
+                const id = typeof b.id === "string" ? b.id : "";
+                if (!parent) {
+                    // A subagent dispatch is any top-level tool_use whose input carries a
+                    // `subagent_type` — the dispatch tool is named "Agent" on the live CLI
+                    // (older docs say "Task"), so match the input field, NOT the tool name,
+                    // to survive the rename. Confirmed against real claude output.
+                    const sub = b.input?.subagent_type;
+                    if (typeof sub === "string")
+                        tasks.set(id, sub);
+                }
+                if (parent)
+                    groupFor(parent).uses.push({ id, name: b.name, input: b.input });
+            }
+            else if (b.type === "tool_result" && parent) {
+                const id = typeof b.tool_use_id === "string" ? b.tool_use_id : "";
+                groupFor(parent).results.set(id, {
+                    text: contentText(b.content),
+                    isError: b.is_error === true,
+                });
+            }
+        }
+    }
+    const out = [];
+    for (const [taskId, name] of tasks) {
+        const g = byParent.get(taskId);
+        const toolCalls = (g?.uses ?? []).map((u) => ({
+            name: u.name,
+            input: u.input,
+            resultText: g?.results.get(u.id)?.text ?? "",
+            isError: g?.results.get(u.id)?.isError ?? false,
+        }));
+        out.push({ name, toolCalls });
+    }
+    return out;
+}
 /**
  * The terminal `result` event — present in BOTH `--output-format` shapes (a
  * `{type:"result", …}` line in stream-json, the single object in `json`), or
@@ -297,6 +375,7 @@ function makeResult(cwd, out, parsed, turns, modelRequests) {
         hooks: parsed.hooks,
         output: parsed.output,
         modelRequests,
+        subagents: parseSubagents(out.stdout),
         file: (p) => {
             const f = (0, node_path_1.resolve)(cwd, p);
             return (0, node_fs_1.existsSync)(f) ? (0, node_fs_1.readFileSync)(f, "utf-8") : null;
@@ -380,6 +459,29 @@ async function runHarnessTest(spec, opts = {}) {
         await mock.close();
     }
 }
+/**
+ * `runHarness` — the harness-scope entry of the revamped API (Phase 2 of
+ * `research/testing-api-design.md`). The harness has two execution scopes, `hook`
+ * (`runHook`) and `harness` (the whole assembled agent); today's `integration` /
+ * `e2e` / `eval` are all the **harness** scope under realness flags. This entry is
+ * the **deterministic** harness run (`model: "mock"`, the default) — the
+ * workhorse you gate every commit, with no key. A **real-model** harness run is
+ * non-deterministic by definition, so you don't *assert* a single one — you
+ * `measure()` it across trials (the eval scope). `egress` is a capability of this
+ * scope (the e2e tier), not a separate tier.
+ *
+ * Behaviour is identical to `runHarnessTest` (which it wraps); the new name +
+ * `model` flag make the scope/realness explicit and steer real-model runs to the
+ * right tool.
+ */
+async function runHarness(spec, opts = {}) {
+    if (opts.model === "real") {
+        throw new Error("runHarness runs the harness DETERMINISTICALLY (model: 'mock'). A real-model " +
+            "harness run is non-deterministic, so a single one can't be asserted — " +
+            "measure it across trials with `measure()` / `runEval` (the eval scope) instead.");
+    }
+    return runHarnessTest(spec, opts);
+}
 /** Pull the pillar-2 driver off an adapter, asserting it supports testing. */
 function requireDriver(adapter) {
     (0, adapter_conformance_js_1.assertHarnessTestable)(adapter);

package/dist/integration.d.ts

@@ -8,9 +8,17 @@
  * (the plugin loader). Capability contract: needs the **`claude` binary and
  * bubblewrap**, but **no API key and no network**. A `*.integration.test.ts`
  * imports from here.
+ *
+ * Real **egress** is a CAPABILITY of this scope (the former `e2e` tier), not a
+ * separate tier: `egressRoutes()` probes whether allowlisted egress can route,
+ * and `runHook` takes `egress: { allow }` for allowlisted real outbound — gated
+ * by a routable sandbox + real network (a test self-skips via `egressRoutes()`).
+ * `vigiles/e2e` remains as a thin back-compat alias. See
+ * `research/testing-api-design.md` Part 4.
  */
 export * from "./unit.js";
 export * from "./harness-test.js";
 export * from "./mock-model.js";
 export type { LoadedPlugin } from "./plugin-loader.js";
+export { egressRoutes } from "./run-hook.js";
 //# sourceMappingURL=integration.d.ts.map

package/dist/integration.js

@@ -14,6 +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.egressRoutes = void 0;
 /**
  * `vigiles/integration` — the **deterministic, assembled-machine** tier.
  *
@@ -24,8 +25,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * (the plugin loader). Capability contract: needs the **`claude` binary and
  * bubblewrap**, but **no API key and no network**. A `*.integration.test.ts`
  * imports from here.
+ *
+ * Real **egress** is a CAPABILITY of this scope (the former `e2e` tier), not a
+ * separate tier: `egressRoutes()` probes whether allowlisted egress can route,
+ * and `runHook` takes `egress: { allow }` for allowlisted real outbound — gated
+ * by a routable sandbox + real network (a test self-skips via `egressRoutes()`).
+ * `vigiles/e2e` remains as a thin back-compat alias. See
+ * `research/testing-api-design.md` Part 4.
  */
 __exportStar(require("./unit.js"), exports);
 __exportStar(require("./harness-test.js"), exports);
 __exportStar(require("./mock-model.js"), exports);
+var run_hook_js_1 = require("./run-hook.js");
+Object.defineProperty(exports, "egressRoutes", { enumerable: true, get: function () { return run_hook_js_1.egressRoutes; } });
 //# sourceMappingURL=integration.js.map

package/dist/jest.d.ts

@@ -1,9 +1,11 @@
+import type { Check } from "./check.js";
 declare module "@jest/expect" {
     interface Matchers<R> {
         toHaveCreated(path: string): R;
         toBlock(): R;
         toBeatBaseline(baseline: string, arm: string, metric: string, by?: number): R;
+        toPass(check: Check<any>): R;
+        toPassAll(checks: readonly Check<any>[]): R;
     }
 }
-export {};
 //# sourceMappingURL=jest.d.ts.map

package/dist/jest.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-/* eslint-disable max-params --
-   The matcher signatures mirror the runtime vigilesMatchers (positional args). */
+/* eslint-disable max-params, @typescript-eslint/no-explicit-any --
+   The matcher signatures mirror the runtime vigilesMatchers (positional args);
+   `Check<any>` matches the runtime generic for the type-only augmentation. */
 /**
  * vigiles — jest integration (opt-in).
  *

package/dist/run-hook.d.ts

@@ -1,6 +1,28 @@
 import type { HookProtocol } from "./core/hook-protocol.js";
 import { type SandboxMode, type EgressAttempt } from "./sandbox.js";
 export type { EgressAttempt };
+/** Result of {@link propertyHook}: the first shrunk counterexample, if any. */
+export interface HookPropertyResult<E> {
+    readonly passed: boolean;
+    readonly iterations: number;
+    /** The (shrunk) event that broke an invariant — present iff `!passed`. */
+    readonly counterexample?: E;
+    /** Which invariant failed — present iff `!passed`. */
+    readonly failedInvariant?: string;
+}
+/**
+ * Property-test a hook's decision over generated events. Throws nothing — returns
+ * a result you assert on (`assert.ok(r.passed)`), so the counterexample is
+ * inspectable. `mutate(event, rng)` produces a variation from the running event;
+ * each named invariant is checked against `decide(event)`.
+ */
+export declare function propertyHook<E, D>(opts: {
+    readonly seed: E;
+    readonly mutate: (event: E, rng: number) => E;
+    readonly decide: (event: E) => D;
+    readonly invariants: Record<string, (decision: D, event: E) => boolean>;
+    readonly iterations?: number;
+}): HookPropertyResult<E>;
 /** A hook event payload (the JSON Claude Code writes to the hook's stdin). */
 export interface HookInput {
     /** e.g. "PreToolUse", "PostToolUse", "Stop", "SessionStart", "PreCompact". */

package/dist/run-hook.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.propertyHook = propertyHook;
 exports.parseHookOutput = parseHookOutput;
 exports.decideHook = decideHook;
 exports.runHookWith = runHookWith;
@@ -41,6 +42,33 @@ const node_path_1 = require("node:path");
 const hook_protocol_js_1 = require("./adapters/claude-code/hook-protocol.js");
 const egress_js_1 = require("./egress.js");
 const sandbox_js_1 = require("./sandbox.js");
+const proofs_js_1 = require("./core/proofs.js");
+/**
+ * Property-test a hook's decision over generated events. Throws nothing — returns
+ * a result you assert on (`assert.ok(r.passed)`), so the counterexample is
+ * inspectable. `mutate(event, rng)` produces a variation from the running event;
+ * each named invariant is checked against `decide(event)`.
+ */
+function propertyHook(opts) {
+    const wrapped = {};
+    for (const [name, inv] of Object.entries(opts.invariants)) {
+        wrapped[name] = (e) => inv(opts.decide(e), e);
+    }
+    const r = (0, proofs_js_1.propertyTest)(opts.seed, opts.mutate, wrapped, {
+        iterations: opts.iterations ?? 100,
+        sequenceLength: 1, // each event is independent — no mutation sequence
+        seed: 1,
+    });
+    if (r.passed)
+        return { passed: true, iterations: r.iterations };
+    const last = r.failingSequence?.[r.failingSequence.length - 1];
+    return {
+        passed: false,
+        iterations: r.iterations,
+        counterexample: r.shrunk ?? last,
+        failedInvariant: r.failedInvariant,
+    };
+}
 /** Parse stdout as a hook JSON decision (pure, testable without a process). */
 function parseHookOutput(stdout) {
     const s = stdout.trim();

package/dist/scan.d.ts

@@ -3,7 +3,7 @@
  * and what's broken, with **no model and no API key**.
  *
  * This is the deterministic substrate under the plugin/skill leaderboard
- * (research/divergent-bets.md #9) and the harness-aware audit
+ * (research/divergent-bets.md #9) and the harness-aware scan
  * (research/agent-supply-chain-security.md #1): it re-aims the machinery that
  * already exists — `loadPlugin` (surfaces + dangling-ref/MCP/empty-machine
  * warnings), `parseAgentTools` (the declared tool contract), and

package/dist/scan.js

@@ -4,7 +4,7 @@
  * and what's broken, with **no model and no API key**.
  *
  * This is the deterministic substrate under the plugin/skill leaderboard
- * (research/divergent-bets.md #9) and the harness-aware audit
+ * (research/divergent-bets.md #9) and the harness-aware scan
  * (research/agent-supply-chain-security.md #1): it re-aims the machinery that
  * already exists — `loadPlugin` (surfaces + dangling-ref/MCP/empty-machine
  * warnings), `parseAgentTools` (the declared tool contract), and

package/dist/setup-plan.d.ts

@@ -10,7 +10,7 @@
  */
 /** What `vigiles init` will set up. */
 export interface SetupPlan {
-    /** Lint pillar — verify instruction-file references (specs, types, compile, lint/audit, hooks). */
+    /** Lint pillar — verify instruction-file references (specs, types, compile, lint, hooks). */
     lint: boolean;
     /** Test pillar — test the harness (scaffold a starter harness test + CI job). */
     test: boolean;
@@ -20,12 +20,16 @@ export interface SetupPlan {
     plugin: boolean;
     /** Strict rule severities in `.vigilesrc.json`. */
     strict: boolean;
+    /** Rewrite an existing STALE CI workflow in place (instead of only warning). */
+    force: boolean;
 }
 /** The explicit choices a user pinned via flags (undefined = "not specified"). */
 export interface ParsedSetupArgs {
     target?: string;
     strict: boolean;
     yes: boolean;
+    /** `--force` — rewrite a stale CI workflow in place. */
+    force: boolean;
     /** Lint pillar — `--lint` → true, `--no-lint` → false, absent → undefined. */
     lint?: boolean;
     /** Test pillar — `--test` → true, `--no-test` → false, absent → undefined. */

package/dist/setup-plan.js

@@ -33,6 +33,7 @@ function parseSetupArgs(args) {
         target: flagValue(args, "--target="),
         strict: args.includes("--strict"),
         yes: args.includes("--yes") || args.includes("-y"),
+        force: args.includes("--force"),
         lint: boolFlag(args, "lint"),
         test: boolFlag(args, "test"),
         harness: flagValue(args, "--harness="),
@@ -42,7 +43,14 @@ function parseSetupArgs(args) {
 }
 /** The non-interactive defaults: both pillars, CI, and the plugin. */
 function defaultPlan(strict = false) {
-    return { lint: true, test: true, gha: true, plugin: true, strict };
+    return {
+        lint: true,
+        test: true,
+        gha: true,
+        plugin: true,
+        strict,
+        force: false,
+    };
 }
 /**
  * Whether to drop into interactive prompts: a human at a TTY who passed neither
@@ -151,6 +159,8 @@ function resolvePlan(parsed, answers) {
         plan.gha = false;
     if (parsed.plugin === false)
         plan.plugin = false;
+    if (parsed.force)
+        plan.force = true;
     if (parsed.target)
         plan.test = false;
     if (answers)

package/dist/test-coverage.js

@@ -151,7 +151,14 @@ function discoverHooks(basePath) {
     }));
 }
 function discoverTests(basePath, globs, ignore) {
-    const found = (0, glob_1.globSync)([...globs], { cwd: basePath, ignore });
+    // `dot: true` so a colocated test under a DOT directory is found — most
+    // loose skills live in `.claude/skills/<name>/`, so the eval the warning
+    // suggests (`.claude/skills/<name>/<name>.eval.mjs`) is itself dot-pathed.
+    // Without this, a globstar (`**/*.eval.mjs`) silently skips it while the
+    // skill (matched by the explicit-dot `.claude/skills/*/SKILL.md` pattern) is
+    // still discovered — so the surface looks untested even after the user adds
+    // exactly the suggested file. DEFAULT_IGNORE still drops .git/node_modules/etc.
+    const found = (0, glob_1.globSync)([...globs], { cwd: basePath, ignore, dot: true });
     return found.map((path) => ({ path, content: read((0, node_path_1.join)(basePath, path)) }));
 }
 /** Colocated: a test inside a skill dir, or a name-prefixed sibling of an agent/hook. */

package/dist/testing.d.ts

@@ -14,4 +14,6 @@ export * from "./run-hook.js";
 export * from "./harness-test.js";
 export * from "./eval.js";
 export * from "./harness-assert.js";
+export * from "./check.js";
+export { hookFired } from "./check.js";
 //# sourceMappingURL=testing.d.ts.map

package/dist/testing.js

@@ -14,6 +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 = void 0;
 /**
  * `vigiles/testing` — Pillar 2 entry point: the **harness-testing** API. Re-exports
  * the three tiers — `runHook` (unit), `runHarnessTest` (deterministic), `runEval`
@@ -30,4 +31,10 @@ __exportStar(require("./run-hook.js"), exports);
 __exportStar(require("./harness-test.js"), exports);
 __exportStar(require("./eval.js"), exports);
 __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
+// same name — the explicit re-export below wins over the two `export *`s.
+__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; } });
 //# sourceMappingURL=testing.js.map

package/dist/unit.d.ts

@@ -12,6 +12,8 @@
  * `vigiles/e2e`.
  */
 export * from "./harness-assert.js";
-export { runHook, parseHookOutput, decideHook } from "./run-hook.js";
-export type { HookInput, HookOutput, HookRunResult, RunHookOptions, } from "./run-hook.js";
+export { runHook, parseHookOutput, decideHook, propertyHook, } from "./run-hook.js";
+export type { HookInput, HookOutput, HookRunResult, RunHookOptions, HookPropertyResult, } from "./run-hook.js";
+export * from "./check.js";
+export { hookFired } from "./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.decideHook = exports.parseHookOutput = exports.runHook = void 0;
+exports.hookFired = exports.propertyHook = exports.decideHook = exports.parseHookOutput = exports.runHook = void 0;
 /**
  * `vigiles/unit` — the **no-capability** harness-testing surface.
  *
@@ -33,4 +33,10 @@ 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, "parseHookOutput", { enumerable: true, get: function () { return run_hook_js_1.parseHookOutput; } });
 Object.defineProperty(exports, "decideHook", { enumerable: true, get: function () { return run_hook_js_1.decideHook; } });
+Object.defineProperty(exports, "propertyHook", { enumerable: true, get: function () { return run_hook_js_1.propertyHook; } });
+// The check vocabulary is part of the base surface (pure, no capability). Its
+// `hookFired` check supersedes the legacy boolean predicate of the same name.
+__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; } });
 //# sourceMappingURL=unit.js.map

package/dist/vitest.d.mts

@@ -1,9 +1,11 @@
+import type { Check } from "./check.js";
 declare module "@vitest/expect" {
     interface Matchers<T = any> {
         toHaveCreated(path: string): T;
         toBlock(): T;
         toBeatBaseline(baseline: string, arm: string, metric: string, by?: number): T;
+        toPass(check: Check<any>): T;
+        toPassAll(checks: readonly Check<any>[]): T;
     }
 }
-export {};
 //# sourceMappingURL=vitest.d.mts.map

package/hooks/refs-nudge.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # PostToolUse hook — nudge the agent to express references in instruction files
-# (CLAUDE.md / AGENTS.md / SKILL.md) as vigiles marks, so `vigiles audit` can
+# (CLAUDE.md / AGENTS.md / SKILL.md) as vigiles marks, so `vigiles lint` can
 # actually verify them. Non-blocking by default; set the `unmarked-refs` rule to
 # "error" in .vigilesrc.json to turn the nudge into a hard block, or to false to
 # disable it. Runs as its OWN PostToolUse entry so its stdout stays clean JSON.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "description": "Compile .spec.ts files to instruction files (CLAUDE.md, AGENTS.md) with linter cross-referencing",
   "bin": {
     "vigiles": "dist/cli.js"
@@ -32,7 +32,8 @@
       "types": "./dist/vitest.d.mts",
       "default": "./dist/vitest.mjs"
     },
-    "./jest": "./dist/jest.js"
+    "./jest": "./dist/jest.js",
+    "./check": "./dist/check.js"
   },
   "files": [
     "dist/**/*.js",

package/skills/edit-spec/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: edit-spec
-description: Edit a vigiles spec file to update instruction files (CLAUDE.md, AGENTS.md)
-disable-model-invocation: true
+description: Edit a vigiles .spec.ts to change a compiled instruction file (CLAUDE.md / AGENTS.md) — add, modify, or remove a rule, section, command, or key file. Use whenever you need to change a CLAUDE.md/AGENTS.md that carries a vigiles hash (edit the spec, never the artifact), including adding a new enforce()/check()/guidance() rule.
 argument-hint: <what to change — e.g., "add a rule about error handling" or "update the testing section">
 ---
 
@@ -27,7 +26,8 @@ Look for spec files in the repo root:
 - `AGENTS.md.spec.ts` — source for AGENTS.md
 - Any `*.spec.ts` matching instruction files
 
-If no spec exists, suggest: `npx vigiles setup`
+If no spec exists: if there's a hand-written `CLAUDE.md`, suggest the
+`migrate-to-spec` skill; otherwise suggest `npx vigiles init` to scaffold one.
 
 ### Step 2: Read and Understand the Spec
 
@@ -83,11 +83,22 @@ export default claude({
 
 Based on what the user asked for:
 
-**Adding a rule:**
-
-- Determine the type: `enforce()` if a linter rule exists, `check()` for filesystem conventions, `guidance()` for prose-only
-- For `enforce()`: find the actual linter rule name (e.g., `eslint/no-console`, `@typescript-eslint/no-explicit-any`, `ruff/T201`)
-- Add to the `rules` object with a descriptive key
+**Adding a rule** (this absorbs the old `generate-rule` skill):
+
+- **Classify the rule** from the request:
+  - `enforce()` — a linter rule can back it. Check the project's linter configs
+    (ESLint, Ruff, Clippy, Pylint, RuboCop, Stylelint) for a matching rule; also
+    consider an architectural tool (ast-grep, Dependency Cruiser, Steiger). If
+    uncertain whether a rule exists, **ask the user** rather than guessing.
+  - `check()` — a filesystem structural convention ("every X needs a Y"). Only
+    for file-pairing; never for code content.
+  - `guidance()` — can't be mechanically enforced (subjective conventions,
+    process rules, migration context).
+- For `enforce()`: use the real linter rule name (e.g. `eslint/no-console`,
+  `@typescript-eslint/no-explicit-any`, `ruff/T201`).
+- Add to the `rules` object with a kebab-case key derived from the intent,
+  preserving alphabetical order if the existing rules are alphabetical. Import
+  any new builders needed (e.g. `check` and `every` for the first `check()`).
 
 **Updating a section:**
 
@@ -118,10 +129,10 @@ This regenerates the compiled instruction file(s). Review the output for any err
 ### Step 5: Verify
 
 ```bash
-npx vigiles check
+npx vigiles lint
 ```
 
-If the PostToolUse hook is installed (via `npx skills add zernie/vigiles`), compilation happens automatically after you save the spec.
+If the vigiles plugin is installed (`/plugin marketplace add zernie/vigiles` then `/plugin install vigiles@vigiles`, or `npx vigiles init`), the PostToolUse hook recompiles automatically after you save the spec.
 
 ## Important
 

package/skills/linter-docs/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: linter-docs
+description: Deep linter reference for authoring or debugging a vigiles enforce() rule — plugin tables, AST selectors, type-aware rules, auto-fix, and edge cases for ESLint, Ruff, Pylint, RuboCop, and Stylelint. Use when you need the exact rule name or config for a specific linter, not for running a linter.
+disable-model-invocation: true
+---
+
+Reference material for the linters vigiles cross-references. Open the file for
+the linter you're working with when you need exact rule names, AST selectors,
+or config details to author an `enforce()` rule (or diagnose why one is reported
+missing or disabled).
+
+| Linter    | Reference                                                                              |
+| --------- | -------------------------------------------------------------------------------------- |
+| ESLint    | [`eslint.md`](eslint.md) — plugin table, AST selectors, type-aware rules, auto-fix     |
+| Ruff      | [`ruff.md`](ruff.md) — 800+ reimplemented rules, selection, auto-fix, pyproject config |
+| Pylint    | [`pylint.md`](pylint.md) — plugin table, astroid AST, type inference, custom checkers  |
+| RuboCop   | [`rubocop.md`](rubocop.md) — gem table, node pattern DSL, auto-correct, custom cops    |
+| Stylelint | [`stylelint.md`](stylelint.md) — plugin table, PostCSS AST, custom rules, SCSS         |
+| Clippy    | [`clippy.md`](clippy.md) — Rust lint groups and configuration                          |
+
+These are read by the `strengthen` and `edit-spec` skills when matching a
+guidance rule to a real linter rule. This skill is user-invoked (a reference,
+not an action), so it never fires on its own — open the relevant file directly.

package/skills/migrate-to-spec/SKILL.md

@@ -7,7 +7,7 @@ argument-hint: <path to CLAUDE.md, defaults to CLAUDE.md>
 
 Convert an existing hand-written CLAUDE.md (or AGENTS.md) into a typed `CLAUDE.md.spec.ts` file. This is the incremental adoption path — you keep your existing instruction file as the starting point and get type safety going forward.
 
-> **Don't need full TypeScript?** A typed spec is the deepest commitment level. If the user only wants verified rules without a build step, point them at markdown mode first: inline `<!-- vigiles:enforce ... -->` comments (Level 0) or a `vigiles:` YAML frontmatter block with `vigiles generate-schema` for editor autocomplete (Level 1). Both are verified by `vigiles audit` with the same engine as a spec. See `docs/markdown-mode.md`. Migrate to a spec only when they want compiler-grade guarantees.
+> **Don't need full TypeScript?** A typed spec is the deepest commitment level. If the user only wants verified rules without a build step, point them at markdown mode first: inline `<!-- vigiles:enforce ... -->` comments (Level 0) or a `vigiles:` YAML frontmatter block with `vigiles generate-schema` for editor autocomplete (Level 1). Both are verified by `vigiles lint` with the same engine as a spec. See `docs/markdown-mode.md`. Migrate to a spec only when they want compiler-grade guarantees.
 
 ## Instructions
 

package/skills/strengthen/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: strengthen
-description: Upgrade guidance() rules to enforce() by finding existing linter rules that match
-disable-model-invocation: true
+description: Upgrade a vigiles spec's guidance() rules to enforce() — scan the guidance rules in a CLAUDE.md/AGENTS.md spec and find existing linter rules (ESLint, Ruff, Clippy, Pylint, RuboCop, Stylelint) that back them. Use when asked to strengthen, harden, or make vigiles rules enforceable; NOT for general linting or fixing lint errors.
 ---
 
 Scan spec files for `guidance()` rules and suggest `enforce()` replacements backed by real linter rules.

package/skills/generate-rule/SKILL.md

@@ -1,64 +0,0 @@
-<!-- vigiles:sha256:a9df2c1748576753 compiled from skills/generate-rule/SKILL.md.spec.ts -->
-
----
-
-name: generate-rule
-description: Add a new enforce(), check(), or guidance() rule to an existing spec file
-disable-model-invocation: true
-argument-hint: <rule>
-
----
-
-## Arguments
-
-- `$1` **rule** — natural-language description of what the rule should enforce, e.g. "no console.log in production code"
-
-## Steps
-
-### Step 1
-
-**Find the spec file.** Look for `CLAUDE.md.spec.ts` in the repo root. If it doesn't exist:
-
-- If there's a hand-written `CLAUDE.md`, suggest running the `migrate-to-spec` skill first.
-- If there's no `CLAUDE.md` either, suggest `npx vigiles init` to scaffold one.
-
-### Step 2
-
-**Classify the rule** from the description ($1):
-
-- **enforce()** — if a linter rule can back it. Check the project's linter configs (ESLint, Ruff, Clippy, Pylint, RuboCop, Stylelint) for a matching rule; also consider an architectural tool (ast-grep, Dependency Cruiser, Steiger). If uncertain whether a rule exists, **ask the user** rather than guessing.
-- **check()** — if it's a filesystem structural convention ("every X needs a Y"). Only for file-pairing; never for code content.
-- **guidance()** — if it can't be mechanically enforced (subjective conventions, process rules, migration context).
-
-### Step 3
-
-**Generate the rule.** Create an entry with a kebab-case ID derived from the description. Examples:
-
-    "no-console": enforce("eslint/no-console", "Use structured logger for observability."),
-
-    "controller-tests": check(
-      every("src/**/*.controller.ts").has("{name}.controller.test.ts"),
-      "Every controller must have a co-located test file.",
-    ),
-
-    "research-before-implementing": guidance(
-      "Google unfamiliar APIs before implementing.",
-    ),
-
-### Step 4
-
-**Add it to the spec.** Read the existing spec file and add the new rule to the `rules` object, preserving alphabetical ordering if the existing rules are alphabetical. Import any new builders needed (e.g. `check` and `every` for the first `check()` rule).
-
-### Step 5
-
-**Compile and verify.** Build and recompile; if compilation fails (e.g. the linter rule doesn't exist), report the error and suggest alternatives. Show the user the updated spec and the compiled `CLAUDE.md` diff.
-
-**Gate** — run the project's build command (retry up to 2×); do not proceed until it passes.
-
-<!-- vigiles:gate role:build retry:2 -->
-
-## Result
-
-This skill is complete when the project's build command passes.
-
-<!-- vigiles:result role:build -->