vigiles 2.0.0 → 2.1.1

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 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)
+
+Promote your rules into a `vigiles:` block at the top of the file:
 
-## The Fix
+```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"
+---
+```
 
-Write your conventions as TypeScript. The compiler catches the lies.
+`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,6 +193,21 @@ 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:
@@ -218,7 +220,7 @@ export default claude({
     architecture: instructions`
       Core engine in ${file("src/compile.ts")}.
       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
   },
@@ -240,14 +242,18 @@ $ 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 + coverage
+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 +286,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 +301,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
 
@@ -365,12 +340,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