vigiles 2.0.0 → 2.2.0

package/README.md

@@ -16,27 +16,9 @@
 
 ---
 
-You wouldn't ship code without a linter. Why ship agent instructions without one?
+Your CLAUDE.md lies to your agent. Here's the fix.
 
-Your CLAUDE.md is a plain text file. Anyone can edit it. Nobody verifies it. The lint rule it references was disabled three months ago. The file path it mentions was renamed. The npm script it suggests was deleted. Your agent reads this, trusts it, and produces code based on lies.
-
-**Markdown can't be validated. TypeScript can.**
-
-```bash
-npx vigiles init
-```
-
-vigiles compiles typed TypeScript specs to instruction files (CLAUDE.md, AGENTS.md). Every linter reference is verified against your actual config — not just that it exists, but that it's enabled. Every file path is checked against the filesystem. Every command is validated against package.json. If something is stale, broken, or disabled — you find out at compile time, not when the agent silently ignores your instructions.
-
-After setup, the agent edits the spec instead of the markdown. Hooks auto-compile. Types catch typos in the editor. CI catches drift. It's self-maintaining.
-
-Not using vigiles with AI agents is like not using ESLint with JavaScript. You can do it. You can't afford to.
-
-Companion repo for [Feedback Loop Is All You Need](https://zernie.com/blog/feedback-loop-is-all-you-need).
-
-## The Problem
-
-Hand-written CLAUDE.md files rot silently. Here's what they actually look like:
+Hand-written CLAUDE.md files rot silently. Here's what a typical one looks like:
 
 ```markdown
 ## Code Style
@@ -58,43 +40,45 @@ Reads fine. Four things are wrong:
 3. `npm run typecheck` — script removed from package.json
 4. Service/test pairing — no automated check, just a hope
 
-The agent reads this, trusts it, and writes code based on stale claims nobody verified.
+The agent reads this, trusts it, and writes code based on stale claims nobody verified. vigiles **verifies the references in your instruction files** — that each linter rule exists and is enabled, that every file path and script is real, and that referenced **code symbols** (functions, classes, constants) actually exist in the files that define them — and meets you at whatever commitment level you want.
 
-## What Changes With vigiles
+Three levels. Each is independently useful; adopt as far up as you like.
 
-### Claude Code
+### Level 0 — inline comments (30 seconds, no new files)
 
-|                                     | Without vigiles              | With vigiles                                                   |
-| ----------------------------------- | ---------------------------- | -------------------------------------------------------------- |
-| **Instructions**                    | Hand-written CLAUDE.md       | Compiled from `.spec.ts` (build artifact)                      |
-| **Linter rule references**          | Trust-based (nobody checks)  | Verified at compile time against real config                   |
-| **File paths**                      | Rot silently when renamed    | `file()` references checked against filesystem                 |
-| **Commands**                        | Stale scripts go unnoticed   | `cmd()` references checked against package.json                |
-| **Direct edits to CLAUDE.md**       | Anyone can, nobody knows     | PreToolUse hook blocks edits, redirects to spec                |
-| **Linter config changes**           | CLAUDE.md drifts out of sync | PostToolUse hook auto-regenerates types                        |
-| **guidance → enforce upgrades**     | Manual guesswork             | `/strengthen` reads per-linter docs, suggests upgrades         |
-| **New lint rules from PR feedback** | Copy-paste from review       | `/pr-to-lint-rule` generates rule + tests + spec entry         |
-| **CI**                              | Nothing to verify            | `vigiles audit` catches hash drift, disabled rules, stale refs |
+Add a comment to your existing CLAUDE.md and audit it:
 
-<details>
-<summary><b>Codex</b> (same compile-time checks, no hooks)</summary>
+```md
+<!-- vigiles:enforce eslint/no-console "Route output through logger.ts" -->
+```
 
-|                               | Without vigiles                  | With vigiles                                            |
-| ----------------------------- | -------------------------------- | ------------------------------------------------------- |
-| **Instructions**              | Hand-written AGENTS.md           | Compiled from `.spec.ts`                                |
-| **Linter rule references**    | Trust-based                      | Verified at compile time                                |
-| **File paths / commands**     | Rot silently                     | Checked at compile time                                 |
-| **Direct edits to AGENTS.md** | Undetected                       | CI catches hash mismatch                                |
-| **Hooks / auto-compile**      | Not available (no plugin system) | Not available — run `vigiles compile` manually or in CI |
-| **CI**                        | Nothing to verify                | Same `vigiles audit` pipeline as Claude                 |
+```bash
+npx vigiles audit CLAUDE.md
+```
 
-</details>
+Each rule is checked against your real linter config — typos get closest-match suggestions, disabled rules are flagged. Zero install commitment, zero new files.
 
-Everything vigiles compiles and audits is **deterministic** — same input, same output, no LLM in the loop. The non-deterministic parts (authoring specs, suggesting upgrades, writing custom rules) are agent skills that run outside the compilation pipeline. [Determinism breakdown and flow diagram →](docs/comparison.md)
+### Level 1 — YAML frontmatter (editor autocomplete, still no TypeScript)
 
-## The Fix
+Promote your rules into a `vigiles:` block at the top of the file:
 
-Write your conventions as TypeScript. The compiler catches the lies.
+```yaml
+---
+# yaml-language-server: $schema=./.vigiles/schema.json
+vigiles:
+  enforce:
+    - rule: "@typescript-eslint/no-explicit-any"
+      why: "Use unknown and narrow with type guards."
+    - rule: eslint/no-console
+      why: "Route output through logger.ts"
+---
+```
+
+`npx vigiles generate-schema` emits a JSON Schema from your project's _actual_ enabled rules, so your editor's built-in YAML language server (VS Code, JetBrains, neovim) autocompletes rule names and red-squiggles typos — at edit time, with no TypeScript in the project. `vigiles audit` enforces the same rules in CI. [Markdown mode →](docs/markdown-mode.md)
+
+### Level 2 — typed spec (compiler-grade guarantees)
+
+When you want the strongest guarantees, compile a typed spec. Every linter rule reference is verified against your real config, every file path against the filesystem, every npm script against package.json. Stale references become compile errors — caught at edit time, not when the agent silently ignores you.
 
 ```typescript
 // CLAUDE.md.spec.ts
@@ -132,53 +116,54 @@ $ npx vigiles compile
   ~180 tokens
 ```
 
-The spec is the source of truth. CLAUDE.md is a build artifact.
-
-## Quick Start
+At this level the spec is the source of truth and CLAUDE.md is a build artifact. The agent edits the spec — hooks auto-compile, types catch typos in the editor, CI catches drift.
 
-```bash
-npx vigiles init
-```
+Companion repo for [Feedback Loop Is All You Need](https://zernie.com/blog/feedback-loop-is-all-you-need).
 
-That's it. One command. The wizard auto-detects your project, creates a spec, scans your linters, compiles to markdown, adds a CI step, and installs Claude Code hooks — all automatically.
+## What Changes With vigiles
 
-```
-  npx vigiles init               guidance() rules, zero config
-          │
-          ▼
-  agent edits spec ◄────────── hooks auto-compile (self-maintaining)
-          │
-          ▼
-  npx vigiles audit              full verification: hashes + linters + coverage
-          │
-          ▼
-  CI catches drift               stale refs, disabled rules, typos, duplicates
-```
+### Claude Code
 
-**After install, it just works:**
+|                                     | Without vigiles              | With vigiles                                                   |
+| ----------------------------------- | ---------------------------- | -------------------------------------------------------------- |
+| **Instructions**                    | Hand-written CLAUDE.md       | Compiled from `.spec.ts` (build artifact)                      |
+| **Linter rule references**          | Trust-based (nobody checks)  | Verified at compile time against real config                   |
+| **File paths**                      | Rot silently when renamed    | `file()` references checked against filesystem                 |
+| **Commands**                        | Stale scripts go unnoticed   | `cmd()` references checked against package.json                |
+| **Direct edits to CLAUDE.md**       | Anyone can, nobody knows     | PreToolUse hook blocks edits, redirects to spec                |
+| **Spec edits**                      | N/A                          | PostToolUse hook auto-compiles to markdown                     |
+| **Linter config changes**           | CLAUDE.md drifts out of sync | PostToolUse hook auto-regenerates types                        |
+| **guidance → enforce upgrades**     | Manual guesswork             | `/strengthen` reads per-linter docs, suggests upgrades         |
+| **New lint rules from PR feedback** | Copy-paste from review       | `/pr-to-lint-rule` generates rule + tests + spec entry         |
+| **CI**                              | Nothing to verify            | `vigiles audit` catches hand-edits, disabled rules, stale refs |
 
-- Agent says "update CLAUDE.md" → plugin blocks the edit, redirects to `.spec.ts`
-- Agent edits the spec → plugin auto-compiles → CLAUDE.md regenerated
-- Agent edits `eslint.config.ts` → plugin auto-regenerates types
-- CI runs `vigiles audit` → catches stale specs, disabled rules, missing files
+<details>
+<summary><b>Codex</b> (same compile-time checks, no hooks)</summary>
 
-### Hesitant about a new file type? Try inline mode
+|                               | Without vigiles                  | With vigiles                                            |
+| ----------------------------- | -------------------------------- | ------------------------------------------------------- |
+| **Instructions**              | Hand-written AGENTS.md           | Compiled from `.spec.ts`                                |
+| **Linter rule references**    | Trust-based                      | Verified at compile time                                |
+| **File paths / commands**     | Rot silently                     | Checked at compile time                                 |
+| **Direct edits to AGENTS.md** | Undetected                       | CI catches hash mismatch                                |
+| **Hooks / auto-compile**      | Not available (no plugin system) | Not available — run `vigiles compile` manually or in CI |
+| **CI**                        | Nothing to verify                | Same `vigiles audit` pipeline as Claude                 |
 
-If a `.spec.ts` feels like too much commitment, you can adopt vigiles one rule at a time by adding HTML comments directly to your existing `CLAUDE.md`:
+</details>
 
-```md
-<!-- vigiles:enforce eslint/no-console "Route output through logger.ts" -->
-```
+Everything vigiles compiles and audits is **deterministic** — same input, same output, no LLM in the loop. The non-deterministic parts (authoring specs, suggesting upgrades, writing custom rules) are agent skills that run outside the compilation pipeline. [Determinism breakdown and flow diagram →](docs/comparison.md)
 
-Running `vigiles audit CLAUDE.md` verifies each inline rule against your real linter config with the same closest-match suggestions and disabled-rule detection as spec mode. Zero build step, zero new files, works with any project. See [docs/inline-mode.md](docs/inline-mode.md) for the format and how to graduate to spec mode later.
+## Quick Start
 
-**It's self-maintaining.** Add a new ESLint rule? The hook regenerates types — your spec gets autocomplete for the new rule immediately. Rename a file? The compiler catches the stale reference. The setup doesn't rot because the hooks keep everything in sync.
+The fastest path is markdown mode — add a marker to your existing CLAUDE.md and audit it, no install or new files (see [Level 0 / Level 1](#level-0--inline-comments-30-seconds-no-new-files) above and [docs/markdown-mode.md](docs/markdown-mode.md)). When you want compiler-grade guarantees, scaffold a typed spec:
 
-**It evolves automatically.** Start with `guidance()` rules (zero config). When you're ready, run `/strengthen` — it reads your linter configs and per-linter reference docs to find `enforce()` upgrades. Each upgrade adds compiler-verified enforcement.
+```bash
+npx vigiles init
+```
 
-**Already have a hand-written CLAUDE.md?** The wizard detects it and suggests migration.
+The wizard auto-detects your project, creates a spec, scans your linters, compiles to markdown, adds a CI step, and installs Claude Code hooks. After install: the agent edits the spec (hooks block direct CLAUDE.md edits), the spec auto-compiles on save, and `vigiles audit` catches drift in CI.
 
-**Ready to enforce?** Run `npx vigiles init --strict` to set rules to `"error"` — CI fails if any instruction file lacks a spec.
+Start with `guidance()` rules (zero config). When you're ready, run `/strengthen` to find rules that can be upgraded to compile-verified `enforce()`. Already have a hand-written CLAUDE.md? The wizard detects it and offers migration.
 
 | Flag                 | Effect                                                |
 | -------------------- | ----------------------------------------------------- |
@@ -188,17 +173,19 @@ Running `vigiles audit CLAUDE.md` verifies each inline rule against your real li
 
 Works the same for humans and agents — fully non-interactive. [Agent setup guide →](docs/agent-setup.md) | [Agent workflows →](docs/agent-workflows.md)
 
-## Two Rule Types
+## Three Rule Types
 
 **`enforce()`** — delegated to a linter. vigiles verifies the rule exists in the catalog AND is enabled in your project config. A disabled rule is a compile error.
 
+<!-- vigiles:ignore -->
+
 ```typescript
 "no-any":    enforce("@typescript-eslint/no-explicit-any", "Use unknown and narrow."),
 "no-print":  enforce("ruff/T201", "Use logging module."),
 "no-unwrap": enforce("clippy/unwrap_used", "Use expect() with context."),
 ```
 
-Supports ESLint, Stylelint, Ruff, Clippy, Pylint, and RuboCop. [Full linter support details →](docs/linter-support.md)
+Supports ESLint, Stylelint, Ruff, Clippy, Pylint, RuboCop, and Cedar policies. [Full linter support details →](docs/linter-support.md)
 
 **`guidance()`** — prose advice. No mechanical enforcement, but not untracked: guidance rules participate in the monotonicity proof system. Once a rule exists, it can be strengthened ( `guidance` → `enforce` ) but never weakened or removed without an explicit allowlist. This prevents silent erosion of conventions over time.
 
@@ -206,21 +193,37 @@ Supports ESLint, Stylelint, Ruff, Clippy, Pylint, and RuboCop. [Full linter supp
 "research-first": guidance("Google unfamiliar APIs first."),
 ```
 
+**`guard()`** — reactive: runs a command when watched files change. One declaration emits hooks for every supported system (Claude Code PostToolUse, husky pre-commit, etc.). Eliminates copy-pasting the same trigger across `.claude/settings.json`, `.husky/`, and CI configs.
+
+```typescript
+"recompile-specs": guard(
+  { watch: "*.spec.ts", run: "npx vigiles compile" },
+  "Recompile instruction files when any spec changes.",
+),
+"regen-types": guard(
+  { watch: ["eslint.config.*", "package.json"], run: "npx vigiles generate-types" },
+  "Regenerate types when linter config or deps change.",
+),
+```
+
+Same monotonicity guarantees as `enforce()` — guards can't be silently removed.
+
 ## Verified References
 
-`file()`, `cmd()`, and `ref()` catch stale references at compile time:
+`file()`, `cmd()`, `symbol()`, and `ref()` catch stale references at compile time:
 
 ```typescript
-import { claude, file, cmd, ref, instructions } from "vigiles/spec";
+import { claude, file, cmd, symbol, ref, instructions } from "vigiles/spec";
 
 export default claude({
   sections: {
     architecture: instructions`
       Core engine in ${file("src/compile.ts")}.
+      Compile specs with ${symbol("src/compile.ts", "compileClaude")}.
       Run ${cmd("npm test")} to verify.
-      See ${ref("skills/deploy/SKILL.md")} for deployment.
+      See ${ref("skills/strengthen/SKILL.md")} for the strengthen skill.
     `,
-    // If any path is stale → compile error
+    // If any path / script / symbol is stale → compile error
   },
   // ...
 });
@@ -228,6 +231,12 @@ export default claude({
 
 Skill specs use the same helpers for verified references inside instructions. [Full spec format →](docs/spec-format.md)
 
+### Symbol references (cross-language)
+
+`symbol("file", "name")` (and the markdown mark `` `vigiles:symbol file#name` ``) verify that the named file actually **defines** the symbol — a function, class, method, or constant — parsed with [ast-grep](https://ast-grep.github.io) across **JS/TS, Python, Ruby, Rust, and CSS**. Rename the function and `audit` fails; no project-wide index, no autoloader guessing — it parses the one named file.
+
+In markdown mode the `refs-hook` (PostToolUse) **forces the mark**: it blocks an edit that leaves a code reference bare, telling the agent to write `` `vigiles:symbol path#name` `` or opt out with `<!-- vigiles:ignore -->`. The harness makes the agent mark its references at write time, with full context; `audit` re-verifies them. [Symbol verification →](research/symbol-verification.md)
+
 ## Type-Safe Rule References
 
 `vigiles generate-types` scans your linter configs and emits `.vigiles/generated.d.ts`. With this file, `enforce("eslint/no-consolee")` is a red squiggle in your editor — a typo caught at authoring time, not a runtime surprise. Without it, everything falls back to broad types and still works.
@@ -240,14 +249,19 @@ $ npx vigiles generate-types
 
 Commit the file to git. CI can verify it's fresh: `npx vigiles generate-types --check`. [How it works →](docs/linter-support.md#generate-types)
 
+For markdown frontmatter (Level 1), `vigiles generate-schema` gives the same authoring-time feedback without TypeScript: it emits a JSON Schema from your enabled rules, and your editor's YAML language server autocompletes rule names and squiggles typos. CI freshness check: `npx vigiles generate-schema --check`.
+
 ## CLI
 
 ```bash
 npx vigiles init [--target=X.md]    # Scaffold a spec (runs full setup wizard by default)
 npx vigiles compile [files...]      # Compile .spec.ts → .md
-npx vigiles audit [files...]        # Verify hashes + linter rules + coverage + suggest upgrades
-npx vigiles generate-types          # Emit .d.ts from project state
+npx vigiles audit [files...]        # Verify hashes + inline/frontmatter/spec rules + symbols + coverage
+npx vigiles refs <file.md>          # Check the symbol references in an instruction file
+npx vigiles generate-types          # Emit .d.ts from project state (for spec mode)
 npx vigiles generate-types --check  # Verify .d.ts is up to date
+npx vigiles generate-schema         # Emit JSON Schema for vigiles: frontmatter (Level 1)
+npx vigiles generate-schema --check # Verify schema.json is up to date
 ```
 
 ## GitHub Action
@@ -280,17 +294,14 @@ The plugin provides two hooks:
 
 ## Validation
 
-`vigiles audit` validates instruction files with three rules:
+`vigiles audit` validates instruction files with four rules:
 
-| Rule                 | Default  | What it checks                                |
-| -------------------- | -------- | --------------------------------------------- |
-| `require-spec`       | `"warn"` | Every CLAUDE.md/AGENTS.md has a `.spec.ts`    |
-| `require-skill-spec` | `"warn"` | Every SKILL.md has a `.spec.ts`               |
-| `freshness`          | `"warn"` | Compiled output matches current project state |
-
-```bash
-npx vigiles audit    # checks specs, hashes, freshness, coverage, duplicates
-```
+| Rule                                                     | Default  | What it checks                                                               |
+| -------------------------------------------------------- | -------- | ---------------------------------------------------------------------------- |
+| [`require-spec`](docs/rules/require-spec.md)             | `"warn"` | Every CLAUDE.md/AGENTS.md has a spec, inline rule, or `vigiles:` frontmatter |
+| [`require-skill-spec`](docs/rules/require-skill-spec.md) | `"warn"` | Every SKILL.md has a `.spec.ts`                                              |
+| [`integrity`](docs/rules/integrity.md)                   | `"warn"` | Compiled markdown wasn't hand-edited (SHA-256 check)                         |
+| [`coverage`](docs/rules/coverage.md)                     | `false`  | Spec covers enough of the project surface                                    |
 
 Configure in `.vigilesrc.json`:
 
@@ -298,41 +309,13 @@ Configure in `.vigilesrc.json`:
 {
   "rules": {
     "require-spec": "error",
-    "freshness": "error"
+    "integrity": "error",
+    "coverage": ["warn", { "scripts": 50, "linterRules": 5 }]
   }
 }
 ```
 
-Disable per-file with an HTML comment:
-
-```markdown
-<!-- vigiles-disable require-spec -->
-
-# CLAUDE.md
-
-...
-```
-
-### Freshness
-
-The `freshness` rule detects when compiled markdown has drifted from project state — disabled linter rules, deleted files, changed configs. Three detection modes:
-
-| Mode                 | What it does                                                            | Cost   |
-| -------------------- | ----------------------------------------------------------------------- | ------ |
-| `"strict"` (default) | Recompiles in memory, diffs output                                      | 2-5s   |
-| `"input-hash"`       | Checks fingerprint of tracked inputs (spec, linter configs, lock files) | <100ms |
-| `"output-hash"`      | Only detects hand-edits to compiled markdown                            | <1ms   |
-
-Strict mode has zero false positives and zero false negatives. Input-hash mode is faster but can false-positive on config whitespace changes. Set the mode in `.vigilesrc.json`:
-
-```json
-{
-  "freshnessMode": "input-hash",
-  "freshnessInputs": ["../../yarn.lock"]
-}
-```
-
-In input-hash mode, vigiles auto-detects lock files across 15 ecosystems (npm, Yarn, pnpm, Bun, Bundler, Poetry, uv, PDM, pip, Cargo, Go, Composer, NuGet, SPM, Mix) and tracks them alongside linter configs, package.json, keyFiles references, and generated types. [Full details →](docs/freshness.md)
+Disable per-file with `<!-- vigiles-disable require-spec -->` at the top of the markdown.
 
 ## Skills
 
@@ -348,6 +331,69 @@ Install with [Vercel Skills](https://github.com/vercel-labs/skills): `npx skills
 | `enforce-rules-format` | Validate all rules have enforcement classification                      |
 | `audit-feedback-loop`  | Score your repo's feedback loop maturity                                |
 
+## Test your Claude Code harness
+
+vigiles also ships a library for **testing the harness itself** — your hooks,
+settings, skills, and instruction files. `Agent = Model + Harness`; this tests
+the harness, at two levels.
+
+**Evals — does my change actually move agent behaviour?** Define a fixture, a set
+of **arms** (a hook on vs off, with/without a CLAUDE.md rule), a task, and a
+metric; `runEval` drives the real `claude` CLI N trials per arm and aggregates.
+
+```typescript
+import { runEval, formatEvalReport } from "vigiles/eval";
+
+const report = await runEval({
+  fixture: { "src/billing.ts": "export function chargeCard() {}" },
+  arms: {
+    vanilla: {},
+    gated: { settings: { hooks: { PostToolUse: [refsHook] } } },
+  },
+  task: "Document chargeCard in SKILL.md, referencing it by name.",
+  measure: (ctx) => ({
+    marked: ctx.sh("grep -c vigiles:symbol SKILL.md") !== "0",
+  }),
+  trials: 6,
+});
+console.log(formatEvalReport(report)); //  vanilla marked=0.00   gated marked=0.50
+```
+
+**Deterministic tests — does my hook fire correctly?** No API key, no cost.
+`runHarnessTest` runs real `claude` against a **scripted mock model**
+(`vigiles/mock-model`), so your real hooks fire but the agent's turns are fixed.
+
+```typescript
+import { runHarnessTest, scriptModel } from "vigiles/harness-test";
+
+const r = await runHarnessTest({
+  settings: {
+    hooks: {
+      Stop: [
+        {
+          hooks: [
+            {
+              type: "command",
+              command: "test -f DONE || { echo 'not done' >&2; exit 2; }",
+            },
+          ],
+        },
+      ],
+    },
+  },
+  model: scriptModel([
+    { text: "I'm done" }, // tries to stop → blocked
+    { tool: "Bash", input: { command: "touch DONE" } },
+    { text: "now done" },
+  ]),
+});
+assert(JSON.parse(r.stdout).num_turns > 1); // the Stop hook forced more work
+```
+
+The deterministic tier is reliable for **Stop hooks**; tool-event hooks
+(Edit/Write) are headless-gated, so test those via the eval tier. Our own
+findings from this harness live in [`research/benchmarks-runtime-gates.md`](research/benchmarks-runtime-gates.md).
+
 ## Maturity Levels
 
 From [Feedback Loop Is All You Need](https://zernie.com/blog/feedback-loop-is-all-you-need):
@@ -365,12 +411,14 @@ Specs compile to `CLAUDE.md` by default. Set `target: "AGENTS.md"` or `target: [
 
 ## Related Tools
 
-vigiles doesn't try to do everything:
+vigiles doesn't try to do everything. It owns one thing: compile-time verification of typed specs against real linter configs, filesystems, and package.json. Everything else, compose:
 
 - **Architectural linting** — [ast-grep](https://ast-grep.github.io/), [Dependency Cruiser](https://github.com/sverweij/dependency-cruiser), [Steiger](https://github.com/feature-sliced/steiger). Reference their rules via `enforce()`.
-- **File sync** — [Ruler](https://github.com/intellectronica/ruler), [rulesync](https://github.com/dyoshikawa/rulesync), [block/ai-rules](https://github.com/block/ai-rules). vigiles compiles the source; sync tools distribute.
-- **Markdown linting** — [markdownlint](https://github.com/DavidAnson/markdownlint). vigiles generates the markdown; structure is correct by construction.
+- **File sync** across agents — [Ruler](https://github.com/intellectronica/ruler), [rulesync](https://github.com/dyoshikawa/rulesync), [block/ai-rules](https://github.com/block/ai-rules). vigiles compiles the source; sync tools distribute.
+- **Markdown linting** — [markdownlint](https://github.com/DavidAnson/markdownlint). vigiles generates markdown; structure is correct by construction.
+- **Code-block linting in docs** — [eslint-plugin-markdown](https://github.com/eslint/eslint-plugin-markdown) for syntax, [twoslash](https://shikijs.github.io/twoslash/) for TS type-checking.
 - **Prose quality** — [Vale](https://vale.sh). Different concern.
+- **Runtime LLM rule checking** (e.g. ai-rulez `"AI-Powered Rule Enforcement"`) — opposite paradigm. Those tools send your code to a model on every check, costing tokens and giving non-reproducible verdicts. vigiles compiles once and checks deterministically forever after with `eslint`, `ruff`, `tsc`, Cedar evaluation — tools as deterministic as their inputs.
 
 ## License
 

package/dist/action-gate.d.ts

@@ -0,0 +1,28 @@
+import { type RuntimeGate } from "./skill-runtime.js";
+export interface ActionGate {
+    /** Tool name to gate, e.g. "Write" | "Edit" | "Bash". */
+    readonly on: string;
+    /** Deterministic check; a `cmd` command may include `{file}`. */
+    readonly gate: RuntimeGate;
+    /** Optional substring the (JSON-serialized) tool input must contain. */
+    readonly when?: string;
+}
+export interface ActionEvent {
+    /** The tool that just ran (PostToolUse `tool_name`). */
+    readonly tool: string;
+    /** The tool input (`tool_input`), e.g. `{ file_path, command }`. */
+    readonly input?: Record<string, unknown>;
+}
+export interface ActionDecision {
+    readonly allow: boolean;
+    readonly message: string;
+}
+/**
+ * Evaluate action gates against a tool event. Runs every gate whose `on`
+ * matches the tool (and whose `when` substring matches the input); the first
+ * failure blocks. Plan-agnostic — order in any runtime workflow is irrelevant.
+ */
+export declare function evaluateAction(event: ActionEvent, gates: readonly ActionGate[], cwd: string): ActionDecision;
+/** Load action gates from `.vigiles/action-gates.json`. */
+export declare function loadActionGates(cwd: string): ActionGate[];
+//# sourceMappingURL=action-gate.d.ts.map

package/dist/action-gate.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateAction = evaluateAction;
+exports.loadActionGates = loadActionGates;
+/**
+ * vigiles — Action gates (the dynamic-workflow reframe).
+ *
+ * A skill gate is bound to a *step* (a fixed position in a plan). When the plan
+ * is generated at runtime (dynamic workflows), the step is the wrong unit. An
+ * **action gate** binds a deterministic check to a *tool action type* instead —
+ * "any time a Write happens to a `.ts` file, eslint must pass on it" — so it
+ * fires regardless of where in the runtime plan the action occurs.
+ *
+ * It is the same deterministic gate primitive (reuses `runGate` + the
+ * author-time reference resolution), re-anchored from step → action. Delivered
+ * as a PostToolUse hook (`vigiles action-hook`): exit 2 blocks the action and
+ * feeds the reason back, exit 0 allows it.
+ *
+ * Config: `.vigiles/action-gates.json` → `{ "gates": [ { on, gate, when? } ] }`.
+ * The gate command may contain `{file}`, substituted with the action's path.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const skill_runtime_js_1 = require("./skill-runtime.js");
+/** The file path an action touched, for `{file}` substitution. */
+function fileOf(event) {
+    const i = event.input ?? {};
+    const v = i.file_path ?? i.path;
+    return typeof v === "string" ? v : "";
+}
+/** Substitute `{file}` in a cmd gate with the action's path. */
+function resolveGate(gate, event) {
+    if (gate.kind !== "cmd" || !gate.command.includes("{file}"))
+        return gate;
+    return { ...gate, command: gate.command.replaceAll("{file}", fileOf(event)) };
+}
+/**
+ * Evaluate action gates against a tool event. Runs every gate whose `on`
+ * matches the tool (and whose `when` substring matches the input); the first
+ * failure blocks. Plan-agnostic — order in any runtime workflow is irrelevant.
+ */
+function evaluateAction(event, gates, cwd) {
+    const inputStr = JSON.stringify(event.input ?? "");
+    for (const g of gates) {
+        if (g.on !== event.tool)
+            continue;
+        if (g.when && !inputStr.includes(g.when))
+            continue;
+        const outcome = (0, skill_runtime_js_1.runGate)(resolveGate(g.gate, event), cwd);
+        if (!outcome.ok) {
+            const tail = outcome.output ? `\n${outcome.output}` : "";
+            return {
+                allow: false,
+                message: `Action gate failed after ${event.tool}: ${(0, skill_runtime_js_1.gateLabel)(g.gate)} did not pass.${tail}`,
+            };
+        }
+    }
+    return { allow: true, message: "" };
+}
+/** Load action gates from `.vigiles/action-gates.json`. */
+function loadActionGates(cwd) {
+    const p = (0, node_path_1.resolve)(cwd, ".vigiles/action-gates.json");
+    if (!(0, node_fs_1.existsSync)(p))
+        return [];
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(p, "utf-8"));
+        return Array.isArray(parsed.gates) ? parsed.gates : [];
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=action-gate.js.map