vigiles 2.0.0

package/CLAUDE.md.spec.ts

@@ -0,0 +1,142 @@
+/**
+ * CLAUDE.md specification for the vigiles project.
+ *
+ * This is the source of truth. CLAUDE.md is a compiled build artifact.
+ * Run `npm run compile:spec` to regenerate CLAUDE.md from this spec.
+ */
+import { claude, guidance } from "./src/spec.js";
+
+export default claude({
+  sections: {
+    positioning: `vigiles compiles \`.spec.ts\` files to instruction files (CLAUDE.md, AGENTS.md, or any markdown target). The spec is the source of truth. The markdown is a build artifact. Nobody else does this — other tools lint markdown after the fact. vigiles eliminates the problem at the source.
+
+The linter cross-referencing engine is the core moat: \`enforce("@typescript-eslint/no-floating-promises")\` verifies the rule exists AND is enabled in your linter config. Same for ESLint, Ruff, Clippy, Pylint, RuboCop, and Stylelint. No other tool resolves rules against 6 linter APIs.
+
+\`generate-types\` is the second moat: scans all 6 linter APIs, package.json, and project files to emit a \`.d.ts\` with type unions. The TS compiler then PROVES references are valid at authoring time — typos become type errors, not runtime surprises.
+
+vigiles does NOT do architectural linting. Use ast-grep, Dependency Cruiser, Steiger, or eslint-plugin-boundaries for that. vigiles can reference their rules via \`enforce()\`.`,
+
+    architecture: `Two rule types in specs:
+
+- \`enforce()\` — delegated to external tool (linter, ast-grep, dependency-cruiser). vigiles verifies the rule exists and is enabled.
+- \`guidance()\` — prose only, compiles to \`**Guidance only**\` in markdown.
+
+Architectural linting (file pairing, import boundaries, AST patterns) belongs in external tools — reference them via \`enforce()\`.
+
+Template literal types ensure linter names (\`eslint/\`, \`ruff/\`, etc.) are type-safe. Branded types (\`VerifiedPath\`, \`VerifiedCmd\`, \`VerifiedRef\`) distinguish verified references from raw strings.
+
+Compilation: spec.ts → compiler reads spec, validates references (file paths via existsSync, npm scripts via package.json, linter rules via linter APIs), generates markdown with SHA-256 integrity hash.
+
+Core modules: \`src/spec.ts\` (types + builders), \`src/compile.ts\` (compiler), \`src/linters.ts\` (6-linter cross-referencing engine), \`src/generate-types.ts\` (type generator), \`src/proofs.ts\` (proof algorithms for self-evolving specs), \`src/evolve.ts\` (evolution engine).`,
+  },
+
+  keyFiles: {
+    "src/spec.ts":
+      "Type system and builder functions (enforce, guidance, claude, skill, file, cmd, ref)",
+    "src/compile.ts":
+      "Compiler: spec → markdown with SHA-256 hash, linter verification, reference validation",
+    "src/linters.ts":
+      "Linter cross-referencing engine (ESLint, Stylelint, Ruff, Clippy, Pylint, RuboCop)",
+    "src/generate-types.ts":
+      "Type generator: scans linters/package.json/filesystem → emits .d.ts",
+    "src/cli.ts":
+      "CLI: init, compile, audit (3 primary commands + generate-types plumbing)",
+    "src/inline.ts":
+      "Inline-mode parser: `<!-- vigiles:enforce ... -->` comments in markdown for gradual adoption",
+    "src/action.ts": "GitHub Action wrapper",
+    "src/spec.test.ts": "Spec + compiler test suite (node:test)",
+    "src/validate.test.ts": "Validation test suite (node:test)",
+    "src/cli.test.ts": "CLI integration + E2E test suite (node:test)",
+    "src/freshness.ts":
+      "Freshness detection: lock file detection, input discovery, hash computation, staleness checks",
+    "src/freshness.test.ts":
+      "Freshness test suite: lock files (15 ecosystems), input discovery, hash computation, staleness",
+    "src/proofs.ts":
+      "Deterministic proof algorithms (monotonicity lattice, NCD, Bloom filter, Merkle DAG, fixed-point, property testing)",
+    "src/evolve.ts":
+      "Evolution engine: mutation operators, fitness function, proof-gated selection",
+    "src/proofs.test.ts": "Proof system + evolution engine tests (node:test)",
+    "CLAUDE.md.spec.ts": "This file — the source of truth for CLAUDE.md",
+    "examples/SKILL.md.spec.ts": "Example SKILL.md spec",
+    "research/adoption-strategy.md":
+      "Adoption strategy: zero-config setup, progressive enforcement, agent workflows",
+    "research/competitive-landscape.md":
+      "Competitive landscape: rule-porter, rulesync, vibe-cli, Ruler",
+    "research/executable-specs.md": "Design doc: executable spec system",
+    "research/feature-ideas.md":
+      "Feature ideas: plugin API, custom rules, exhaustive coverage",
+    "research/ai-code-quality.md": "Research: AI code quality patterns",
+    "research/self-evolving-specs.md":
+      "Design doc: self-evolving spec system (proofs, Merkle history, evolution engine)",
+    "research/code-search-for-agents.md":
+      "Research: code search approaches (grep vs embeddings vs AST-grep)",
+    "research/doc-freshness.md":
+      "Research: input fingerprinting, TOC manifests, and stale spec detection",
+    "docs/agent-workflows.md":
+      "Agent-specific workflows (Claude Code, Codex, multi-agent, Cursor)",
+    "docs/agent-setup.md":
+      "Non-interactive agent setup guide (hooks via settings.json)",
+    "docs/spec-format.md": "Spec format reference (target, sections, rules)",
+    "docs/linter-support.md":
+      "Linter support details (6 linters + generate-types)",
+    "docs/comparison.md":
+      "Before/after tables (Claude Code, Codex), determinism breakdown, flow diagram",
+    "docs/freshness.md":
+      "Freshness detection: strict/input-hash/output-hash modes, lock file detection, input fingerprinting",
+    "docs/inline-mode.md":
+      "Inline mode: `<!-- vigiles:enforce ... -->` comments for gradual adoption without a .spec.ts",
+    "skills/linter-docs/eslint.md":
+      "ESLint reference: plugin table, AST selectors, type-aware rules, auto-fix, edge cases",
+    "skills/linter-docs/rubocop.md":
+      "RuboCop reference: gem table, node pattern DSL, auto-correct, custom cops",
+    "skills/linter-docs/pylint.md":
+      "Pylint reference: plugin table, astroid AST, type inference, custom checkers",
+    "skills/linter-docs/ruff.md":
+      "Ruff reference: 800+ reimplemented rules, rule selection, auto-fix, pyproject.toml config",
+    "skills/linter-docs/stylelint.md":
+      "Stylelint reference: plugin table, PostCSS AST, custom rules, CSS-in-JS, SCSS",
+    "skills/strengthen/SKILL.md":
+      "Strengthen skill: upgrade guidance() → enforce() by finding existing linter rules",
+  },
+
+  commands: {
+    "npm run build": "Compile TypeScript to dist/",
+    "npm test": "Build and run all tests",
+    "npm run fmt": "Format with prettier",
+    "npm run fmt:check": "Check formatting",
+  },
+
+  rules: {
+    "never-skip-tests": guidance(
+      "All tests must pass. If a test requires a CLI tool (pylint, rubocop, ruff, clippy), install the tool, don't skip the test.",
+    ),
+
+    "zero-config-by-default": guidance(
+      "`vigiles compile` should work with just a .spec.ts file. Config exists only for overrides (maxRules, maxTokens).",
+    ),
+
+    "dont-reimplement-linters": guidance(
+      "Architectural linting belongs in ast-grep/Dependency Cruiser/Steiger. Per-file code rules belong in ESLint/Ruff/Clippy. vigiles owns: spec compilation, linter cross-referencing, type generation, stale reference detection, and proof-based spec evolution.",
+    ),
+
+    "smooth-adoption": guidance(
+      "`npx vigiles init && npx skills add zernie/vigiles` must work on first run with zero config. The wizard auto-detects the project, creates specs, generates types, compiles, and wires CI. After install the agent edits specs automatically — no workflow change required. Start permissive (guidance rules, `require-spec: false` available), tighten over time. Hesitant adopters can use inline mode (`<!-- vigiles:enforce ... -->` comments) without a .spec.ts — see `docs/inline-mode.md`. See `research/adoption-strategy.md`.",
+    ),
+
+    "format-before-commit": guidance(
+      "Run `npm run fmt:check` before committing. Inline code spans in markdown need surrounding spaces to render correctly.",
+    ),
+
+    "progressive-adoption": guidance(
+      "vigiles must be adoptable incrementally, like TypeScript. Three on-ramps, zero friction: (1) inline mode — add `<!-- vigiles:enforce ... -->` comments to an existing CLAUDE.md, no new files; (2) spec mode with `guidance()` only — `npx vigiles init` creates a .spec.ts, compiles to markdown, zero linter setup; (3) strict mode — `enforce()` rules, CI gating, `--strict` flag. Each level adds value without requiring the next. Never gate basic functionality on advanced setup. README examples should always show the simplest path first.",
+    ),
+
+    "no-session-links": guidance(
+      "This is a public repo. Claude Code session URLs are private and must not appear in commits or PRs.",
+    ),
+
+    "readme-brevity": guidance(
+      "README.md should be a concise pitch + quick start, not a reference manual. Extract detailed sections into docs/ and link with `[Details →](docs/X.md)`. Target ~300 lines max.",
+    ),
+  },
+});

package/CONTRIBUTING.md

@@ -0,0 +1,121 @@
+# Contributing to vigiles
+
+Thanks for your interest in contributing! This guide covers everything you need to get started.
+
+## Prerequisites
+
+- **Node.js** 20+
+- **npm** 10+
+- For full test coverage, you'll also need these linter CLIs on your PATH:
+  - `ruff` and `pylint` (Python)
+  - `rubocop` (Ruby)
+  - `cargo` with `clippy` (Rust)
+
+## Setup
+
+```bash
+git clone https://github.com/zernie/vigiles.git
+cd vigiles
+npm install
+npm run build
+```
+
+## Project structure
+
+```
+src/
+  types.ts          Type definitions (interfaces, type aliases)
+  validate.ts       Core validation engine (parsing, config, linter checks)
+  action.ts         GitHub Action wrapper (reads env vars, calls validatePaths)
+  cli.ts            CLI entry point (arg parsing, output formatting)
+  validate.test.ts  Test suite (node:test)
+schemas/            Built-in mdschema YAML presets
+skills/             Claude Code skills (enforce-rules-format, audit-feedback-loop, pr-to-lint-rule)
+dist/               Compiled JavaScript output (git-ignored)
+```
+
+## Development workflow
+
+### Build
+
+```bash
+npm run build        # Compile TypeScript → dist/
+```
+
+### Test
+
+```bash
+npm test             # Build + run all tests
+```
+
+Tests use Node.js built-in test runner (`node:test`) and `node:assert/strict`. No extra test framework needed.
+
+### Format
+
+```bash
+npm run fmt          # Auto-format with Prettier
+npm run fmt:check    # Check formatting (CI uses this)
+```
+
+### Type check
+
+```bash
+npx tsc --noEmit     # Type-check without emitting
+```
+
+### Run locally
+
+```bash
+npx vigiles CLAUDE.md                          # Validate a file
+npx vigiles --markers=headings,checkboxes .    # Custom markers
+npx vigiles                                    # Auto-discover instruction files
+```
+
+## TypeScript conventions
+
+This project uses **TypeScript strict mode** with these compiler options enabled:
+
+- `strict: true` (includes `strictNullChecks`, `noImplicitAny`, etc.)
+- `noUncheckedIndexedAccess: true`
+- `noUnusedLocals: true`
+- `noUnusedParameters: true`
+
+### Guidelines
+
+- **Explicit types** on all exported function signatures (parameters and return types).
+- **No `any`** — use `unknown` and narrow with type guards when the type is truly unknown.
+- Import types with `import type { ... }` when only used in type positions.
+- Use `.js` extensions in import paths (required by Node16 module resolution).
+- Keep the single-file core architecture — `validate.ts` contains all validation logic.
+
+## Adding a new validation rule
+
+1. Add the rule name and default value to `RulesConfig` in `src/types.ts`.
+2. Add the default to `RULE_PACKS` in `src/validate.ts`.
+3. Implement the check inside the `validate()` function.
+4. Add tests in `src/validate.test.ts`.
+5. Document the rule in `README.md` and `CLAUDE.md`.
+
+## Adding a new linter resolver
+
+1. Add a Node API resolver to `LINTER_RESOLVERS` (if the linter has a Node API).
+2. Or add a CLI checker to `CLI_RULE_CHECKS` and map it in `CLI_TOOL_FOR_LINTER`.
+3. Optionally add a config-enabled checker to `LINTER_CONFIG_CHECKERS`.
+4. Add tests covering both existing and nonexistent rules.
+
+## Pull requests
+
+- Keep PRs focused — one feature or fix per PR.
+- All tests must pass (`npm test`).
+- Code must compile without errors (`npx tsc --noEmit`).
+- Code must be formatted (`npm run fmt:check`).
+- Update `CLAUDE.md` if you change exported APIs or add new rules.
+- Write descriptive commit messages explaining _why_, not just _what_.
+
+## Architecture decisions
+
+- **Single-file core**: All validation logic lives in `validate.ts` for portability and minimal dependency surface.
+- **Zero config by default**: vigiles works out of the box. Config exists only for overrides.
+- **Two rule packs**: `"recommended"` (permissive defaults) and `"strict"` (tighter constraints).
+- **Linter auto-detection**: No need to declare which linters you use — vigiles discovers them.
+- **Agent auto-discovery**: Detects AI coding tools by their config directories and validates their instruction files exist.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 vigiles contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,377 @@
+<p align="center">
+  <img src="logo.png" width="140" alt="vigiles logo" />
+</p>
+
+<h1 align="center">vigiles</h1>
+
+<p align="center">
+  <em>Quis custodiet ipsos custodes?</em> — Who watches the watchmen?
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/vigiles"><img src="https://img.shields.io/npm/v/vigiles?color=orange" alt="npm version" /></a>
+  <a href="https://github.com/zernie/vigiles/actions"><img src="https://img.shields.io/github/actions/workflow/status/zernie/vigiles/ci.yml?branch=main" alt="CI" /></a>
+  <a href="https://github.com/zernie/vigiles/blob/main/LICENSE"><img src="https://img.shields.io/github/license/zernie/vigiles" alt="License" /></a>
+</p>
+
+---
+
+You wouldn't ship code without a linter. Why ship agent instructions without one?
+
+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:
+
+```markdown
+## Code Style
+
+Never use `any` — the `@typescript-eslint/no-explicit-any` rule
+catches this. Always use `unknown` and narrow with type guards.
+See `src/utils/type-helpers.ts` for project utilities.
+
+## Testing
+
+Run `npm run typecheck` before submitting. Every service in
+src/services/ should have a corresponding test file.
+```
+
+Reads fine. Four things are wrong:
+
+1. `@typescript-eslint/no-explicit-any` — disabled to unblock a deadline, never re-enabled
+2. `src/utils/type-helpers.ts` — renamed to `src/utils/narrowing.ts` last quarter
+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.
+
+## What Changes With vigiles
+
+### Claude Code
+
+|                                     | 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 |
+
+<details>
+<summary><b>Codex</b> (same compile-time checks, no hooks)</summary>
+
+|                               | 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                 |
+
+</details>
+
+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)
+
+## The Fix
+
+Write your conventions as TypeScript. The compiler catches the lies.
+
+```typescript
+// CLAUDE.md.spec.ts
+import { claude, enforce, guidance } from "vigiles/spec";
+
+export default claude({
+  commands: {
+    "npm run build": "Compile TypeScript to dist/",
+    "npm test": "Build and run all tests",
+    // ✗ "npm run typecheck" → compile error: script not in package.json
+  },
+
+  keyFiles: {
+    "src/utils/narrowing.ts": "Type guard utilities",
+    // ✗ "src/utils/type-helpers.ts" → compile error: file not found
+  },
+
+  rules: {
+    "no-explicit-any": enforce(
+      "@typescript-eslint/no-explicit-any",
+      "Use unknown and narrow with type guards.",
+    ),
+    // ✗ if rule is disabled in config → compile error
+
+    "research-first": guidance("Google unfamiliar APIs first."),
+  },
+});
+```
+
+```bash
+$ npx vigiles compile
+
+✓ CLAUDE.md.spec.ts → CLAUDE.md
+  2 rules (1 linter-verified, 1 guidance)
+  ~180 tokens
+```
+
+The spec is the source of truth. CLAUDE.md is a build artifact.
+
+## Quick Start
+
+```bash
+npx vigiles init
+```
+
+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.
+
+```
+  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
+```
+
+**After install, it just works:**
+
+- 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
+
+### Hesitant about a new file type? Try inline mode
+
+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`:
+
+```md
+<!-- vigiles:enforce eslint/no-console "Route output through logger.ts" -->
+```
+
+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.
+
+**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.
+
+**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.
+
+**Already have a hand-written CLAUDE.md?** The wizard detects it and suggests migration.
+
+**Ready to enforce?** Run `npx vigiles init --strict` to set rules to `"error"` — CI fails if any instruction file lacks a spec.
+
+| Flag                 | Effect                                                |
+| -------------------- | ----------------------------------------------------- |
+| `--strict`           | Sets require-spec and require-skill-spec to `"error"` |
+| `--target=AGENTS.md` | Creates AGENTS.md spec instead of CLAUDE.md           |
+| `--no-gha`           | Skip adding CI step to GHA workflow                   |
+
+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
+
+**`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.
+
+```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)
+
+**`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.
+
+```typescript
+"research-first": guidance("Google unfamiliar APIs first."),
+```
+
+## Verified References
+
+`file()`, `cmd()`, and `ref()` catch stale references at compile time:
+
+```typescript
+import { claude, file, cmd, ref, instructions } from "vigiles/spec";
+
+export default claude({
+  sections: {
+    architecture: instructions`
+      Core engine in ${file("src/compile.ts")}.
+      Run ${cmd("npm test")} to verify.
+      See ${ref("skills/deploy/SKILL.md")} for deployment.
+    `,
+    // If any path is stale → compile error
+  },
+  // ...
+});
+```
+
+Skill specs use the same helpers for verified references inside instructions. [Full spec format →](docs/spec-format.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.
+
+```bash
+$ npx vigiles generate-types
+  eslint: 64 enabled rules  |  ruff: 12  |  npm scripts: 5  |  project files: 42
+✓ Generated .vigiles/generated.d.ts
+```
+
+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)
+
+## 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 generate-types --check  # Verify .d.ts is up to date
+```
+
+## GitHub Action
+
+```yaml
+- uses: zernie/vigiles@main # runs `audit` by default
+- uses: zernie/vigiles@main
+  with:
+    command: compile # compile specs in CI
+```
+
+To verify generated types are fresh in CI:
+
+```yaml
+- run: npx vigiles generate-types --check
+```
+
+## Claude Code Plugin
+
+**Install the plugin.** Without it, you're responsible for manually running `compile` and `generate-types`. With it, the agent works with fresh instruction files automatically.
+
+```bash
+npx skills add zernie/vigiles
+```
+
+The plugin provides two hooks:
+
+- **PreToolUse** (Edit/Write) — blocks direct edits to compiled `.md` files and redirects the agent to the `.spec.ts` source
+- **PostToolUse** (Edit/Write) — auto-runs `generate-types` on linter config changes, `compile` on `.spec.ts` changes
+
+## Validation
+
+`vigiles audit` validates instruction files with three 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
+```
+
+Configure in `.vigilesrc.json`:
+
+```json
+{
+  "rules": {
+    "require-spec": "error",
+    "freshness": "error"
+  }
+}
+```
+
+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)
+
+## Skills
+
+Install with [Vercel Skills](https://github.com/vercel-labs/skills): `npx skills add zernie/vigiles`
+
+| Skill                  | What it does                                                            |
+| ---------------------- | ----------------------------------------------------------------------- |
+| `strengthen`           | Upgrade `guidance()` → `enforce()` using linter-specific reference docs |
+| `edit-spec`            | Edit a spec file — guided workflow with compile step                    |
+| `migrate-to-spec`      | Convert a hand-written CLAUDE.md to a typed `.spec.ts`                  |
+| `generate-rule`        | Add a new `enforce()` / `guidance()` rule to a spec                     |
+| `pr-to-lint-rule`      | Turn a recurring PR review comment into a lint rule + spec entry        |
+| `enforce-rules-format` | Validate all rules have enforcement classification                      |
+| `audit-feedback-loop`  | Score your repo's feedback loop maturity                                |
+
+## Maturity Levels
+
+From [Feedback Loop Is All You Need](https://zernie.com/blog/feedback-loop-is-all-you-need):
+
+| Level | Name                 | What it means                                                       |
+| ----- | -------------------- | ------------------------------------------------------------------- |
+| 0     | Vibes                | No CI, no linters, no CLAUDE.md                                     |
+| 1     | Guardrails           | CI + standard linters, no custom rules                              |
+| 2     | Architecture as Code | Custom lint rules + enforced CLAUDE.md                              |
+| 3     | The Organism         | CI + custom rules + visual tests + observability + scheduled agents |
+
+## Output Targets
+
+Specs compile to `CLAUDE.md` by default. Set `target: "AGENTS.md"` or `target: ["CLAUDE.md", "AGENTS.md"]` for multiple outputs from one spec. For non-markdown formats (`.cursorrules`, Copilot), use [rule-porter](https://github.com/nichochar/rule-porter) or [rulesync](https://github.com/dyoshikawa/rulesync) to convert. [Spec format →](docs/spec-format.md)
+
+## Related Tools
+
+vigiles doesn't try to do everything:
+
+- **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.
+- **Prose quality** — [Vale](https://vale.sh). Different concern.
+
+## License
+
+[MIT](LICENSE)