vigiles 2.0.0

package/research/adoption-strategy.md

@@ -0,0 +1,111 @@
+# vigiles Adoption Strategy
+
+Goal: **`npx vigiles setup && npx skills add zernie/vigiles` works on first run with zero config. The agent starts editing specs automatically — no workflow change required. Start permissive, tighten over time.**
+
+### Adoption Principles
+
+1. **Works on first run.** Setup must succeed in any project without configuration. Auto-detect everything. Create reasonable defaults. Don't block on missing tools.
+2. **Zero workflow change.** After plugin install, the agent edits specs instead of markdown. The user doesn't need to learn a new workflow — they say "update CLAUDE.md" and the plugin handles the redirect.
+3. **Start permissive, tighten later.** First run creates `guidance()` rules (no enforcement). User upgrades to `enforce()` as they add linter rules. `require-spec: false` available for incremental migration.
+4. **Every surface tells you the next step.** `vigiles check` says "run setup." The hook says "edit the spec." The wizard says "install the plugin." No dead ends.
+
+---
+
+## Scope: What vigiles Does vs. Doesn't
+
+vigiles compiles typed TypeScript specs to **markdown instruction files** (CLAUDE.md, AGENTS.md). It verifies linter rules, file paths, and commands at compile time. The compiled markdown is the artifact.
+
+**vigiles handles:** CLAUDE.md (Claude Code), AGENTS.md (Codex, GitHub Copilot, any agent that reads AGENTS.md). These are both plain markdown — same compiler, same validation, different `target`.
+
+**vigiles does NOT handle:** `.cursorrules`, `.copilot-instructions.md`, Windsurf format, or any non-markdown target. These have different structures. Use [rule-porter](https://github.com/nichochar/rule-porter) or [rulesync](https://github.com/dyoshikawa/rulesync) to convert compiled markdown to those formats. vigiles is the source; sync tools are the distribution layer.
+
+**No symlinks needed.** AGENTS.md is a first-class target via `target: "AGENTS.md"` or `target: ["CLAUDE.md", "AGENTS.md"]`. The compiler outputs both from one spec.
+
+---
+
+## The Setup Wizard
+
+`npx vigiles setup` is the single entry point. It does everything:
+
+1. **Creates spec** — scaffolds `CLAUDE.md.spec.ts` (or `--target=AGENTS.md` variant)
+2. **Generates types** — scans linters, package.json, project files → `.vigiles/generated.d.ts`
+3. **Compiles** — spec → markdown with SHA-256 hash
+4. **Adds CI step** — finds existing GHA workflow and appends `vigiles check` + `generate-types --check`
+5. **Prompts plugin install** — prints `npx skills add zernie/vigiles` with explanation
+
+After setup, the user edits the spec, runs `vigiles compile`, and commits. The plugin handles everything else automatically.
+
+---
+
+## Adoption Levels
+
+### Level 0: Discovery
+
+User runs `npx vigiles check` on an existing repo. `require-spec` fires: "No spec file found. Run `npx vigiles setup`." First nudge.
+
+### Level 1: Setup
+
+```bash
+npx vigiles setup
+```
+
+One command. Creates spec, types, compiled markdown, CI step. The user has a working pipeline in under a minute.
+
+### Level 2: Plugin
+
+```bash
+npx skills add zernie/vigiles
+```
+
+Two hooks activate:
+
+- **PreToolUse**: Blocks direct edits to compiled `.md` files. Agent gets redirected to `.spec.ts`.
+- **PostToolUse**: Auto-runs `generate-types` on config changes, `compile` on spec changes.
+
+### Level 3: Multi-Target
+
+```typescript
+export default claude({
+  target: ["CLAUDE.md", "AGENTS.md"],
+  rules: { ... },
+});
+```
+
+One spec, multiple outputs. For non-markdown formats, pipe through rule-porter.
+
+### Level 4: Type Narrowing
+
+Commit `.vigiles/generated.d.ts`. Now `enforce("eslint/no-consolee")` is a type error in the editor. Types narrow `enforce()`, `file()`, `cmd()` via declaration merging.
+
+---
+
+## Pain Points (Updated)
+
+| Pain Point                        | Status    | Resolution                                      |
+| --------------------------------- | --------- | ----------------------------------------------- |
+| Multi-step installation           | Fixed     | `vigiles setup` does everything                 |
+| No CI integration from wizard     | Fixed     | Wizard auto-adds GHA step                       |
+| Plugin not mentioned as important | Fixed     | README and wizard both prompt it                |
+| Agent edits compiled .md directly | Fixed     | PreToolUse hook blocks with redirect            |
+| Cursor/Windsurf support           | Won't fix | Out of scope — use sync tools                   |
+| Codex / AGENTS.md                 | Fixed     | First-class target                              |
+| No interactive mode for agents    | Open      | `vigiles setup` works non-interactively already |
+
+## README Structure
+
+The README should have:
+
+1. **Hook** — one compelling sentence
+2. **Problem** — realistic example of rot
+3. **Fix** — the spec that catches it
+4. **Quick Start** — `npx vigiles setup` (one command)
+5. **Three Rule Types** — enforce/check/guidance
+6. **Verified References** — file/cmd/ref
+7. **Type-Safe Rule References** — generate-types + narrowing
+8. **CLI** — reference for all commands
+9. **GitHub Action** — CI snippet
+10. **Plugin** — what it does, install command
+11. **Output Targets** — CLAUDE.md, AGENTS.md, multi-target
+12. **Related Tools** — sync tools for non-markdown formats
+
+No separate installation steps. The wizard IS the installation.

package/research/agent-integration.md

@@ -0,0 +1,145 @@
+# Agent Integration: Proofs, Hooks, and Static Analysis for AI Coding
+
+## Framing
+
+vigiles today helps humans write instruction files that AI agents read. That is useful but thin. The larger opportunity is to make vigiles a **deterministic backstop** around coding agents: a layer that catches the specific failure modes AI models have, before they become committed code.
+
+This doc collects research on where AI agents actually fail, what deterministic tooling can provably prevent, and proposes 10 concrete vigiles improvements. The through-line is: use the spec as the anchor for hooks, proofs, and static checks — so that unreliable probabilistic tools meet a reliable deterministic floor.
+
+## The problem: spiky intelligence
+
+Andrej Karpathy's "jagged intelligence" framing describes it best: LLMs can solve olympiad-level problems in one prompt and fail at `9.11 > 9.9` in the next. Capability is not monotonic across tasks — it is spiky. For coding agents this means:
+
+- The same model that writes a correct Raft implementation will happily `import leftpad` when the package does not exist
+- An agent that refactors 500 lines cleanly will silently delete an unrelated test file one invocation later
+- Context windows fix some of this, but hallucinated imports, stale file paths, and out-of-date API signatures survive even with full-file context
+
+Deterministic tools do not have this problem. A TypeScript compiler does not "sometimes" miss a type error. A linter does not "occasionally" forget a rule. The thesis of this doc: **put deterministic tools on every edge where the agent touches reality**, and use vigiles specs as the schema that drives them.
+
+## What goes wrong in practice
+
+### 1. Documentation drift
+
+ETH Zurich's AGENTS.md study (arxiv 2511.12884) found that well-intentioned AGENTS.md files produced a **3% reduction in task success** and a **20% increase in token cost** when the docs were stale or overlong. Specifically: files over ~300 lines hurt more than they helped. The model pays attention to prose that is wrong.
+
+DAPLab's 9-failure-pattern study of coding agents called this out as pattern #1: "instructions the model treats as ground truth but which no longer reflect the code." A single file in a popular TS monorepo had **59 broken file-path references** in its CLAUDE.md — agents cheerfully followed them and wrote new code against paths that no longer existed.
+
+### 2. Package hallucination / slopsquatting
+
+Lasso Security's 2024 study: **58% of hallucinated package names are reproducible** across runs of the same prompt. The same non-existent name appears over and over. Attackers have started registering those names on npm and PyPI — the so-called "slopsquatting" attack. If you ask an agent to add a CSV parser and it suggests `fast-csv-parser-lite`, that package might not exist today and might be malware tomorrow.
+
+Neither TypeScript nor ESLint catches this. The import looks fine syntactically; it fails at install time or, worse, succeeds and runs attacker code.
+
+### 3. Missing linter backing
+
+CodeRabbit's 2025 aggregate data: AI-generated code has **1.7× more reviewable issues** than human-written code. Of those issues, roughly 40% are things an appropriately configured linter would catch — the linter just wasn't configured. vigiles already addresses this for rules that appear in a spec (via `enforce()` cross-referencing), but the inverse problem is unsolved: rules enabled in the linter that the spec never mentions, and rules in the spec that are disabled in the linter but still appear in CLAUDE.md. Both cases are silent drift.
+
+### 4. Secrets and dangerous commands
+
+GitGuardian's 2025 report: **3.2% of AI-assisted commits leak a secret**, up from 1.1% in pre-agent commits. Models are not malicious — they paste what they see. A `.env` file in the conversation becomes a `.env` file in the commit. Claude Code's PreToolUse hook is the only unbypassable enforcement point for this; vigiles currently does not ship one.
+
+### 5. Hook anti-patterns
+
+Claude Code hook documentation explicitly warns about two anti-patterns people hit repeatedly:
+
+- **Silent matcher ignore**: a PreToolUse matcher like `Edit|Write` written as `"Edit|Write"` with no regex semantics silently matches neither
+- **Trailing-wildcard regex**: `Bash.*` without anchoring matches anything containing "Bash"
+
+These failures do not error. They just quietly stop enforcing anything. Users believe they are protected when they are not.
+
+### 6. Missing product context
+
+The DAPLab study's pattern #7: agents produce syntactically correct code that violates product conventions the codebase has never articulated anywhere. "Use our internal `http.Client` instead of `fetch`." "Log via `logger.ts`, never `console.log`." "All controllers live in `src/controllers/`, not `src/routes/`." These are real rules, but they live in the heads of senior engineers. The moment a rule is not written down, the agent cannot follow it.
+
+vigiles's spec format is the right place for these — if they can be written quickly and enforced automatically.
+
+## Academic + industry landscape (2025–2026)
+
+- **arxiv 2511.12884** (ETH Zurich) — Empirical analysis of AGENTS.md; shorter-and-enforced beats longer-and-prose-only
+- **DAPLab 2025** — 9-failure-pattern taxonomy for agentic coding
+- **Lasso Security 2024** — Package hallucination reproducibility (58%)
+- **GitGuardian 2025** — Secret leak rates in AI-assisted commits (3.2%)
+- **CodeRabbit 2025** — AI code has 1.7× issue density vs human code
+- **Anthropic Claude Code docs** — PreToolUse / PostToolUse / SessionStart hook surface
+- **Karpathy 2024** — "Jagged intelligence" framing for LLM capability distribution
+
+Takeaway: the entire field has converged on the same conclusion. LLMs need deterministic rails. The question is where to put them and who writes the schema.
+
+## Ten vigiles improvements
+
+Each of these maps to one or more failure modes above. All are scoped to vigiles's positioning (compilation + linter cross-reference + filesystem assertions). None of them require us to become a linter.
+
+### 1. Ship a hook pack — SHIPPED
+
+A `vigiles init` flag that installs a curated `settings.json` block with:
+
+- **PreToolUse (Edit|Write)** — block direct edits to any compiled markdown file (CLAUDE.md, AGENTS.md, the target of any discovered `.spec.ts`). Force edits through the spec.
+- **PostToolUse (Edit|Write on \*.spec.ts)** — auto-run `vigiles compile` so the markdown is always in sync without the user thinking about it.
+- **SessionStart (matcher: `compact`)** — run `vigiles audit --summary` and inject the result so the model sees stale-reference warnings every session for free.
+
+Why this matters: PreToolUse is the only unbypassable enforcement point in the Claude Code harness. Without it, any rule is advisory. With it, vigiles becomes a real floor.
+
+### 2. Package-existence check inside `audit` — DROPPED
+
+Reuse the linter-cross-reference machinery to scan imports in the repo against `package.json`/`requirements.txt`/`Cargo.toml`. Flag any import that (a) is not in the manifest and (b) is not a relative path or builtin. This catches slopsquatting at audit time before it reaches install. Cheap, fully local, zero false positives on builtins.
+
+### 3. Dead-enforcement detection — SHIPPED (already wired for all 6 linters)
+
+Today `enforce("eslint/no-console")` verifies that `no-console` exists as a rule. It does not verify that it is **enabled** (severity > 0). Extend the linter engine to surface rules the spec claims are enforced but which the linter reports as `"off"`. This is a silent-drift bug that happens every time someone tweaks eslint config without touching the spec.
+
+### 4. Reverse coverage report — SHIPPED (built into `vigiles audit` coverage stage)
+
+Right now `audit` tells you which files have no spec coverage. The inverse is just as useful: which **linter rules** are enabled in the project but not mentioned in any spec. Output as a sorted list so users can either add `enforce()` entries (promoting the rule to agent-visible prose) or mark it intentionally out-of-scope. Closes the gap that CodeRabbit's 1.7× issue-density number is mostly made of.
+
+### 5. SessionStart audit injection (compact matcher) — SHIPPED
+
+Hook-pack component worth calling out separately: the `compact` SessionStart matcher fires every time context is compacted, which is effectively free in the session's token budget. Injecting a one-line "3 stale file refs, 2 disabled enforced rules, 1 duplicate rule" message at that moment means the model re-notices drift without anyone running a command. This is the single highest-leverage hook integration.
+
+### 6. Hook validation subcommand — NOT BUILT
+
+`vigiles audit --hooks` parses the user's `settings.json`, runs the listed matchers against known-bad inputs, and reports silent failures (matchers that match nothing, trailing-wildcard regex, missing shell escapes). Directly addresses the silent-matcher-ignore anti-pattern documented in Claude Code's own hook docs. No one else ships this check.
+
+### 7. Token-budget compile-time enforcement — SHIPPED
+
+ETH Zurich's finding was that CLAUDE.md files over ~300 lines actively hurt. Add a `maxTokens` / `maxLines` field to the spec (already partially present), but enforce it at **compile** time with a hard error rather than as advisory output. Force the user to choose what to cut. This is the simplest way to align vigiles with the empirical evidence that shorter + enforced beats longer + prose.
+
+### 8. Instruction diff subcommand — NOT BUILT
+
+`vigiles audit --diff <base>` renders a semantic diff of the compiled markdown: rules added, rules **strengthened** (guidance → enforce), rules **weakened**, rules removed. Attach to every PR that touches a `.spec.ts`. Reviewers currently look at a raw markdown diff which hides the monotonicity property — a strengthen looks identical to a reword unless you read carefully. Semantic diff makes it obvious.
+
+### 9. Snapshot tests for structural changes — PARTIALLY SHIPPED (monotonicity lattice rejects weakening; full `--allow-weaken` flag not yet exposed as CLI)
+
+Compile-time assertion: if a spec change would delete an `enforce()` rule, require an explicit `--allow-weaken` flag. This encodes the monotonicity lattice (`guidance < enforce`) from the proofs work as a hard rule rather than advisory output. Pairs with #8: the diff highlights it, the snapshot prevents accidental loss.
+
+### 10. Stale reference detection — DROPPED (compiler's job, not vigiles's)
+
+Generalize the existing path-verification (`file("src/foo.ts")`) to a crawler that, during `audit`, walks every code-fenced path, every backticked identifier that looks like a file, every npm-script reference, every package name, and flags the ones that no longer resolve. The 59-broken-refs example was in a file no one had audited for 8 months. A cheap cron-friendly audit command closes that gap forever.
+
+### 11. Adversarial AI review loop — NOT BUILT
+
+Ship a skill that takes a spec diff and runs a second LLM pass (same model, reviewer prompt) to critique it before the evolution engine accepts. The Codex-reviews-Claude cycle on PR #16 caught ~40 real bugs across 30+ review rounds — reference leaks, merge semantics, monotonicity bypasses, stale command references. That pattern works. Bake it in: `vigiles evolve --review` proposes a mutation, runs the proof suite, THEN asks a reviewer-prompt subagent "what did I miss?", feeds the response back as a second round of mutations, and only commits the final version. Two-LLM adversarial loop with deterministic gates between rounds.
+
+### 12. Inline-to-spec graduation detector — NOT BUILT
+
+When a markdown file accumulates >N inline `<!-- vigiles:enforce ... -->` comments (default: 5), `audit --summary` includes a "graduate to spec mode" nudge. Bonus: print a ready-to-paste `.spec.ts` template pre-filled with all the inline rules already extracted. The adoption funnel becomes: add one comment → add five → see the nudge → paste the template → you're in spec mode. Zero cliff.
+
+### 13. Cross-file rule coherence — NOT BUILT
+
+When a project has multiple specs (e.g., `CLAUDE.md.spec.ts` + `docs/AGENTS.md.spec.ts`), run NCD across specs (not just within) to detect cross-file near-duplicates. Also flag contradictions: spec A enforces `eslint/no-console` while spec B's prose says "use `console.log` for debugging." Today each spec is audited in isolation; coherence requires a cross-spec pass.
+
+## What we are NOT adding
+
+- Not a linter. Architectural and per-file rules live in ESLint / Ruff / Steiger / ast-grep. vigiles references them.
+- Not an agent sandbox. Claude Code and Codex already own the execution surface.
+- Not a secret scanner. GitGuardian / trufflehog already do this well. We can recommend them via `enforce()` but we do not reimplement.
+- Not an embedding / semantic-search layer. That belongs in the agent, not the spec compiler.
+
+## Next moves
+
+1. Hook pack (#1) + SessionStart audit injection (#5) — highest impact, lowest effort, unblocks everything else
+2. Dead-enforcement detection (#3) + reverse coverage report (#4) — extend existing linter engine, no new subsystem
+3. Package-existence check (#2) + stale reference detection (#10) — audit-time crawlers, reuse existing infrastructure
+4. Semantic diff (#8) + snapshot tests (#9) + token budget (#7) — compile-time guardrails
+5. Hook validation (#6) — stretch goal, depends on hook pack being stable first
+
+The first two bullets could ship in one patch and would already move vigiles from "markdown compiler" to "deterministic backstop for coding agents." Everything after that is additive.

package/research/ai-code-quality.md

@@ -0,0 +1,197 @@
+# AI Code Quality Research
+
+Collected April 2026 during the vigiles v2 design session. This document captures the research, insights, and decisions that shaped vigiles v2's architecture.
+
+---
+
+## The Problem
+
+Natural language instruction files (CLAUDE.md, AGENTS.md, .cursorrules) are the interface between humans and AI coding agents. We spent 50 years building compilers, type systems, and linters to escape ambiguity. Now the most powerful code generation tool communicates via markdown.
+
+### Empirical Data
+
+| Finding                                                                          | Source                                                                                                                                                                     |
+| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| AI code produces 1.7x more issues than human code                                | [CodeRabbit report](https://www.coderabbit.ai/blog/state-of-ai-vs-human-code-generation-report)                                                                            |
+| 2.74x more security vulnerabilities in AI code                                   | CodeRabbit report                                                                                                                                                          |
+| 3x more readability problems, 2x naming inconsistencies                          | CodeRabbit report                                                                                                                                                          |
+| 8x more excessive I/O operations                                                 | CodeRabbit report                                                                                                                                                          |
+| LLM-generated instruction files reduce task success by ~3%, increase cost by 20% | [ETH Zurich SRI Lab](https://www.marktechpost.com/2026/02/25/new-eth-zurich-study-proves-your-ai-coding-agents-are-failing-because-your-agents-md-files-are-too-detailed/) |
+| Over 50% of instruction file rules are noise                                     | ETH Zurich study                                                                                                                                                           |
+| Claude Code commits leak secrets at 3.2% (2x human baseline of ~1.5%)            | [GitGuardian State of Secrets Sprawl 2026](https://blog.gitguardian.com/the-state-of-secrets-sprawl-2026/)                                                                 |
+| 60% of AI code faults are silent logic failures                                  | [StackOverflow: Bugs with AI agents](https://stackoverflow.blog/2026/01/28/are-bugs-and-incidents-inevitable-with-ai-coding-agents/)                                       |
+| Instruction files over ~200-300 lines → compliance drops sharply                 | Multiple sources (lost-in-the-middle effect)                                                                                                                               |
+
+### Columbia DAPLab: 9 Critical Failure Patterns
+
+From analysis of Cline, Claude, Cursor, Replit, and V0 across 15+ applications:
+
+1. Error handling suppression — agents suppress errors to make code run
+2. Business logic misunderstanding — pricing rules, constraints not tied in correctly
+3. Codebase awareness degradation — failure rates increase with file count
+4. Style drift — toward generic defaults for naming, architecture, formatting
+5. Deprecated/wrong pattern introduction — statistical inference, not semantic understanding
+6. Secret leakage — 2x higher rates with AI-assisted commits
+7. Invisible drift accumulation — builds up silently until production failure
+8. Review fatigue — 14x projected activity surge overwhelms human review
+9. Concurrency/dependency errors — 2x more likely in AI code
+
+---
+
+## The Core Tension
+
+We can't lint natural language. But we CAN lint the claims natural language makes about the world.
+
+- "Use the logger" → unlintable
+- `enforce("eslint/no-console", "Use structured logger.")` → falsifiable claim, verified at compile time
+
+### Key Framings
+
+- **Martin Fowler's "Harness Engineering"** (Feb 2026): Design deterministic constraints and feedback loops around AI agents. Not prompting. Not instructing. Constraining.
+- **Factory.ai**: "Agents write the code; linters write the law."
+- **The pattern**: "LLM proposes, deterministic tool disposes." The CI gate stays deterministic. AI helps write rules, but rules run deterministically.
+- **Spotify's Honk system**: 650+ agent-generated PRs merged monthly with strong feedback loops.
+
+Sources: [Martin Fowler](https://martinfowler.com/articles/exploring-gen-ai/context-engineering-coding-agents.html), [Factory.ai](https://factory.ai/news/using-linters-to-direct-agents), [Spotify](https://engineering.atspotify.com/2025/12/feedback-loops-background-coding-agents-part-3), [StackOverflow: Guidelines for AI](https://stackoverflow.blog/2026/03/26/coding-guidelines-for-ai-agents-and-people-too/)
+
+---
+
+## Ideas Explored
+
+### 10 Initial Ideas (from broad to medium ambition)
+
+1. **Convention Fingerprinting** — AST-analyze codebase, extract convention profiles, validate new code against them. Prior art: NATURALIZE (94% accuracy on naming), similarity-ts, IntelliCode.
+2. **Architectural Boundary Enforcement** — Define allowed dependency directions, validate import graph. Prior art: Nx, Sheriff, Dependency Cruiser.
+3. **"Guardrails as Tests"** — Lightweight DSL for structural code assertions via AST matching. Prior art: Semgrep, ast-grep.
+4. **PR Review Mining** — Cluster repeated review comments, auto-generate instruction entries. TF-IDF + cosine similarity (no LLM needed).
+5. **API Hallucination Detector** — Validate API calls against knowledge base via AST. Prior art: [arxiv 2601.19106](https://arxiv.org/html/2601.19106v1) — 100% precision, 87.6% recall.
+6. **Convention Compliance Scoring** — Per-PR audit of which instructions are followed. Cross-reference diff against rules.
+7. **Deprecation/Migration Fence** — Block deprecated patterns in new code, allow in existing. "allow-existing, block-new" semantic.
+8. **Context Sufficiency Validator** — Check instruction files reference real things, aren't vague.
+9. **Executable Examples** — Type-check code blocks in instruction files via tsc/py_compile/shellcheck.
+10. **Instruction Effectiveness Tracking** — Correlate rules with linter failures and review comments over time.
+
+### 4 Bold Bets
+
+1. **Executable Spec Files** → CHOSEN. TypeScript specs that compile to markdown. The spec IS the source of truth.
+2. **Convention Genome** → DEFERRED. Extract conventions from AST, encode as machine-readable genome. Promising but large research project.
+3. **Proof-Carrying Code** → REJECTED. Agents produce code + verification receipts. On reflection, this is just ESLint with extra steps.
+4. **Type System for Instructions** → ABSORBED into idea 1. Rich typed annotations become TypeScript types in the spec.
+
+---
+
+## Key Design Decisions
+
+### 1. Compile to markdown, don't lint markdown
+
+The TypeScript type system catches errors at authoring time. `enforce()` must be called with a valid `LinterRule` template literal type. `file()` returns a `VerifiedPath` branded type. The compiler validates everything else. Nobody else does this.
+
+### 2. Three rule types: enforce, check, guidance
+
+| Type      | Builder      | Responsibility                                                            |
+| --------- | ------------ | ------------------------------------------------------------------------- |
+| Delegated | `enforce()`  | External tool (linter, ast-grep, etc.). vigiles verifies it's configured. |
+| Checked   | `check()`    | Filesystem assertions only. vigiles owns what no other tool handles.      |
+| Guidance  | `guidance()` | Prose. No enforcement pretended.                                          |
+
+**Originally had `prove()` with `no().matches()` and `layers()`.** Killed these — ast-grep, Dependency Cruiser, and Steiger already do architectural linting better. vigiles references their rules via `enforce()` instead of reimplementing them.
+
+### 3. Don't be an architectural linter
+
+Existing tools that already handle this:
+
+| Tool                                                                 | Languages    | What it does                               |
+| -------------------------------------------------------------------- | ------------ | ------------------------------------------ |
+| [ast-grep](https://ast-grep.github.io/)                              | 26 languages | Structural search/lint/rewrite, YAML rules |
+| [Steiger](https://github.com/feature-sliced/steiger)                 | JS/TS        | File structure + architecture linting      |
+| [Dependency Cruiser](https://github.com/sverweij/dependency-cruiser) | JS/TS        | Import graph validation                    |
+| [Sheriff](https://github.com/nicedoc/sheriff)                        | TS           | Module boundary enforcement                |
+| Nx `enforce-module-boundaries`                                       | JS/TS        | Layer/tag-based import rules               |
+| eslint-plugin-boundaries                                             | JS/TS        | Import boundary rules in ESLint            |
+
+vigiles can reference all of these via `enforce("ast-grep/rule-name")` etc.
+
+### 4. generate-types as second moat
+
+`vigiles generate-types` scans all 6 linter APIs + package.json + filesystem → emits `.d.ts`:
+
+```typescript
+// .vigiles/generated.d.ts (auto-generated)
+export type EslintRule = "no-console" | "no-unused-vars" | ...;
+export type RuffRule = "E501" | "F401" | ...;
+export type NpmScript = "build" | "test" | "fmt" | ...;
+export type ProjectFile = "src/spec.ts" | "src/compile.ts" | ...;
+```
+
+TS compiler proves references valid at authoring time. Like Prisma for databases, tRPC for APIs. Nobody else does this for linter rules.
+
+### 5. Branded types for references
+
+`file()` returns `VerifiedPath`, not `string`. `cmd()` returns `VerifiedCmd`. Distinguishes "went through vigiles verification" from "random string" at the type level.
+
+### 6. Colocated spec files, not god-object config
+
+- `CLAUDE.md.spec.ts` sits next to `CLAUDE.md`
+- `SKILL.md.spec.ts` sits next to `SKILL.md`
+- Hooks (.claude/settings.json) validated in place — no spec needed
+- `vigiles.config.ts` only for project settings (maxRules, maxTokens)
+
+### 7. Token budget on compiled output
+
+`maxTokens` constrains the compiled artifact. The spec can be any length. Estimated via ~4 chars/token heuristic (swappable for real tokenizer).
+
+### 8. SHA-256 hash on compiled output
+
+Detects manual edits. `vigiles adopt` (future) to merge manual changes back into spec.
+
+---
+
+## Technology Choices
+
+| Tool                            | Decision                                  | Rationale                                                   |
+| ------------------------------- | ----------------------------------------- | ----------------------------------------------------------- |
+| **ast-grep** (`@ast-grep/napi`) | Future dependency for `check()` if needed | 26 languages, Rust-fast, Node.js API                        |
+| **Semgrep**                     | REJECTED                                  | Can't embed (OCaml binary), LGPL + restrictive rule license |
+| **tree-sitter**                 | Too low-level                             | ast-grep wraps it with better API                           |
+| **ESLint v10**                  | Potential output target                   | Inline plugins via flat config                              |
+| **Pulumi model**                | Architectural inspiration                 | TS code → declarative output                                |
+| **Effect.ts Schema**            | Pattern inspiration                       | Inspectable values = executable + documentable              |
+
+---
+
+## Competitive Landscape
+
+15+ tools in the space across 4 categories. See `research/competitive-landscape.md` for full analysis.
+
+**vigiles moat (v2):**
+
+1. Spec compilation (nobody else)
+2. Linter cross-referencing — 6 APIs (nobody else)
+3. Type generation from project state (nobody else)
+4. Branded reference types
+5. SHA-256 integrity hash
+
+---
+
+## What's NOT Worth Building
+
+Based on research, these approaches don't work or are somebody else's job:
+
+- **AI-in-CI for code review** — non-deterministic, can't be a gate. What works: AI writes the rules, deterministic tools run them.
+- **Architectural linting** — ast-grep, Steiger, Dependency Cruiser do this better.
+- **Markdown formatting** — markdownlint. We generate the markdown, structure is correct by construction.
+- **Prose quality validation** — detecting "write clean code" as vague is cute but fragile. Better to just not generate it from specs.
+- **Skill testing via LLM execution** — non-deterministic, expensive, side-effect-prone. Skill contracts are unreliable.
+- **Per-file code linting** — that's what ESLint/Ruff/Clippy are for.
+
+---
+
+## Future Work
+
+| Feature                     | Status        | Notes                                                                       |
+| --------------------------- | ------------- | --------------------------------------------------------------------------- |
+| `vigiles discover`          | Not started   | Scan linter configs, report coverage gaps, suggest rules to document        |
+| `vigiles adopt`             | Not started   | Detect manual edits via hash, merge changes back into spec                  |
+| `vigiles.config.ts` loading | Not started   | Needs jiti or tsx for TS config evaluation                                  |
+| Convention Genome           | Research only | Extract conventions from AST, encode as types. High potential, large scope. |
+| Real tokenizer              | Not started   | Replace ~4 chars/token heuristic with BPE (tiktoken/gpt-tokenizer)          |