vigiles 2.0.0

package/.claude/settings.json

@@ -0,0 +1,46 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npm install && npm run build && pip install ruff pylint && gem install rubocop 2>/dev/null; true"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "FILE=$(cat | jq -r '.tool_input.file_path // empty') && case \"$(basename \"$FILE\")\" in eslint.config.*|.eslintrc*|package.json|pyproject.toml|Cargo.toml) npx vigiles generate-types 2>&1 || true ;; esac && case \"$FILE\" in *.spec.ts) npx vigiles compile 2>&1 || true ;; esac"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx prettier --check ."
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "FILE=$(cat | jq -r '.tool_input.file_path // empty') && case \"$FILE\" in *.md) [ -f \"$FILE\" ] && head -1 \"$FILE\" | grep -q 'vigiles:sha256:' && { SPEC=$(head -1 \"$FILE\" | sed -n 's/.*compiled from \\(.*\\) -->/\\1/p'); echo \"BLOCKED: Edit $SPEC instead.\" >&2; exit 2; } ;; esac; exit 0"
+          }
+        ]
+      }
+    ]
+  }
+}

package/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm whoami:*)",
+      "Bash(npm publish:*)"
+    ]
+  }
+}

package/.claude-plugin/hooks/post-edit.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# PostToolUse hook — keep generated types and compiled specs fresh.
+#
+# Reads stdin JSON from Claude Code to determine which file was edited,
+# then conditionally runs generate-types or compile.
+
+set -euo pipefail
+
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+
+if [ -z "$FILE" ]; then
+  exit 0
+fi
+
+BASENAME=$(basename "$FILE")
+
+# Linter config or package.json changed → regenerate types
+case "$BASENAME" in
+  eslint.config.*|.eslintrc*|.stylelintrc*|.rubocop.yml|pyproject.toml|Cargo.toml|package.json)
+    if command -v npx &>/dev/null && [ -f "package.json" ]; then
+      npx vigiles generate-types 2>&1 || true
+    fi
+    ;;
+esac
+
+# Spec file changed → recompile
+case "$FILE" in
+  *.spec.ts)
+    if command -v npx &>/dev/null && [ -f "package.json" ]; then
+      npx vigiles compile 2>&1 || true
+    fi
+    ;;
+esac

package/.claude-plugin/hooks/pre-edit.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# PreToolUse hook — redirect edits from compiled files to their specs.
+#
+# If a file has a vigiles hash comment, it's a build artifact.
+# Exit 2 = block the tool call in Claude Code.
+# The message tells the agent exactly what to do instead.
+
+set -euo pipefail
+
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+
+if [ -z "$FILE" ]; then
+  exit 0
+fi
+
+# Only check .md files
+case "$FILE" in
+  *.md) ;;
+  *) exit 0 ;;
+esac
+
+# Check if the file exists and has a vigiles hash
+if [ -f "$FILE" ] && head -1 "$FILE" | grep -q "<!-- vigiles:sha256:"; then
+  SPEC=$(head -1 "$FILE" | sed -n 's/.*compiled from \(.*\) -->/\1/p')
+  SPEC_FILE="${SPEC:-$(basename "$FILE").spec.ts}"
+
+  cat >&2 <<MSG
+BLOCKED: ${FILE} is a compiled build artifact — do not edit it directly.
+
+Instead:
+1. Read ${SPEC_FILE} to understand the spec structure
+2. Edit ${SPEC_FILE} to make your changes (add/modify rules, sections, keyFiles, commands)
+3. Run: npx vigiles compile
+4. The compiled ${FILE} will be regenerated automatically
+
+Use the edit-spec skill if you need guidance on the spec format.
+MSG
+  exit 2
+fi

package/.claude-plugin/hooks/session-start.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# SessionStart hook — inject a one-line vigiles audit summary into
+# Claude's context at session start and after compaction.
+#
+# Uses `vigiles audit --summary` which is designed for this: it
+# silences all per-stage output and prints a single line like
+#   vigiles: 3 stale / 2 validation errors / 1 duplicate
+# (or "vigiles: clean") so the injection costs a handful of tokens.
+#
+# Hook runs on the `startup` and `compact` matchers — the latter is
+# effectively free on token budget because it fires every time
+# context is compacted, so the agent re-notices drift without any
+# manual command.
+
+set -euo pipefail
+
+# Only run in projects that actually use vigiles — otherwise stay silent.
+if [ ! -f "package.json" ]; then
+  exit 0
+fi
+if ! grep -q '"vigiles"' package.json 2>/dev/null; then
+  exit 0
+fi
+
+# Prefer local install, fall back to npx.
+if command -v npx &>/dev/null; then
+  SUMMARY=$(npx --no-install vigiles audit --summary 2>/dev/null || true)
+else
+  exit 0
+fi
+
+if [ -z "$SUMMARY" ]; then
+  exit 0
+fi
+
+# Inject the summary line as hook output. Claude Code prepends hook
+# stdout to the session context for SessionStart hooks.
+echo "$SUMMARY"

package/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "vigiles",
+  "metadata": {
+    "description": "Tools for AI-assisted development feedback loops"
+  },
+  "plugins": [
+    {
+      "name": "vigiles",
+      "source": "./",
+      "description": "Validate CLAUDE.md, audit feedback loops, and generate lint rules from PR comments",
+      "version": "1.0.0"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,47 @@
+{
+  "name": "vigiles",
+  "version": "1.0.0",
+  "description": "Validate CLAUDE.md, audit feedback loops, and generate lint rules from PR comments",
+  "author": {
+    "name": "zernie"
+  },
+  "repository": "https://github.com/zernie/vigiles",
+  "license": "MIT",
+  "keywords": ["linting", "claude-md", "feedback-loops", "code-review"],
+  "skills": "./skills/",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/pre-edit.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/post-edit.sh"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "startup|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/.github/workflows/ci.yml

@@ -0,0 +1,81 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+
+      - name: Cache pip packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: pip-${{ runner.os }}-ruff-pylint
+
+      - name: Cache gem packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.local/share/gem
+          key: gem-${{ runner.os }}-rubocop
+
+      - run: npm ci
+
+      - name: Install linter CLIs for tests
+        run: |
+          pip install ruff pylint
+          gem install rubocop
+          rustup component add clippy
+
+      - name: Build
+        run: npm run build
+
+      - name: Run tests
+        run: npm test
+
+      - name: Type check
+        run: npx tsc --noEmit
+
+      - name: Check generated types compile
+        run: node dist/cli.js generate-types && npx tsc --noEmit
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Check formatting
+        run: npm run fmt:check
+
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Audit compiled files
+        run: node dist/cli.js audit

package/.prettierignore

@@ -0,0 +1 @@
+.vigiles/generated.d.ts

package/.vigiles/generated.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Auto-generated by `vigiles generate-types`.
+ * DO NOT EDIT — re-run `vigiles generate-types` to update.
+ */
+
+declare module "vigiles/generated" {
+
+  /** 64 enabled eslint rules (via flat config). */
+  export type EslintRule = 
+    | "constructor-super"
+    | "for-direction"
+    | "getter-return"
+    | "no-async-promise-executor"
+    | "no-case-declarations"
+    | "no-class-assign"
+    | "no-compare-neg-zero"
+    | "no-cond-assign"
+    | "no-const-assign"
+    | "no-constant-binary-expression"
+    | "no-constant-condition"
+    | "no-control-regex"
+    | "no-debugger"
+    | "no-delete-var"
+    | "no-dupe-args"
+    | "no-dupe-class-members"
+    | "no-dupe-else-if"
+    | "no-dupe-keys"
+    | "no-duplicate-case"
+    | "no-empty"
+    | "no-empty-character-class"
+    | "no-empty-pattern"
+    | "no-empty-static-block"
+    | "no-ex-assign"
+    | "no-extra-boolean-cast"
+    | "no-fallthrough"
+    | "no-func-assign"
+    | "no-global-assign"
+    | "no-import-assign"
+    | "no-invalid-regexp"
+    | "no-irregular-whitespace"
+    | "no-loss-of-precision"
+    | "no-misleading-character-class"
+    | "no-new-native-nonconstructor"
+    | "no-nonoctal-decimal-escape"
+    | "no-obj-calls"
+    | "no-octal"
+    | "no-prototype-builtins"
+    | "no-redeclare"
+    | "no-regex-spaces"
+    | "no-self-assign"
+    | "no-setter-return"
+    | "no-shadow-restricted-names"
+    | "no-sparse-arrays"
+    | "no-this-before-super"
+    | "no-unassigned-vars"
+    | "no-undef"
+    | "no-unexpected-multiline"
+    | "no-unreachable"
+    | "no-unsafe-finally"
+    | "no-unsafe-negation"
+    | "no-unsafe-optional-chaining"
+    | "no-unused-labels"
+    | "no-unused-private-class-members"
+    | "no-unused-vars"
+    | "no-useless-assignment"
+    | "no-useless-backreference"
+    | "no-useless-catch"
+    | "no-useless-escape"
+    | "no-with"
+    | "preserve-caught-error"
+    | "require-yield"
+    | "use-isnan"
+    | "valid-typeof";
+
+  /** All enabled linter rules across all detected linters. */
+  export type LinterRule = EslintRule;
+
+  /** 5 npm scripts from package.json. */
+  export type NpmScript = 
+    | "build"
+    | "test"
+    | "lint"
+    | "fmt"
+    | "fmt:check";
+
+  /** 18 project files. */
+  export type ProjectFile = 
+    | "src/action.ts"
+    | "src/cli.test.ts"
+    | "src/cli.ts"
+    | "src/compile.ts"
+    | "src/evolve.ts"
+    | "src/freshness.test.ts"
+    | "src/freshness.ts"
+    | "src/generate-types.ts"
+    | "src/inline.test.ts"
+    | "src/inline.ts"
+    | "src/linters.ts"
+    | "src/proofs.test.ts"
+    | "src/proofs.ts"
+    | "src/spec.test.ts"
+    | "src/spec.ts"
+    | "src/types.ts"
+    | "src/validate.test.ts"
+    | "src/validate.ts";
+}
+
+declare module "vigiles/spec" {
+  interface KnownLinterRules {
+    "eslint": 
+      | "constructor-super"
+      | "for-direction"
+      | "getter-return"
+      | "no-async-promise-executor"
+      | "no-case-declarations"
+      | "no-class-assign"
+      | "no-compare-neg-zero"
+      | "no-cond-assign"
+      | "no-const-assign"
+      | "no-constant-binary-expression"
+      | "no-constant-condition"
+      | "no-control-regex"
+      | "no-debugger"
+      | "no-delete-var"
+      | "no-dupe-args"
+      | "no-dupe-class-members"
+      | "no-dupe-else-if"
+      | "no-dupe-keys"
+      | "no-duplicate-case"
+      | "no-empty"
+      | "no-empty-character-class"
+      | "no-empty-pattern"
+      | "no-empty-static-block"
+      | "no-ex-assign"
+      | "no-extra-boolean-cast"
+      | "no-fallthrough"
+      | "no-func-assign"
+      | "no-global-assign"
+      | "no-import-assign"
+      | "no-invalid-regexp"
+      | "no-irregular-whitespace"
+      | "no-loss-of-precision"
+      | "no-misleading-character-class"
+      | "no-new-native-nonconstructor"
+      | "no-nonoctal-decimal-escape"
+      | "no-obj-calls"
+      | "no-octal"
+      | "no-prototype-builtins"
+      | "no-redeclare"
+      | "no-regex-spaces"
+      | "no-self-assign"
+      | "no-setter-return"
+      | "no-shadow-restricted-names"
+      | "no-sparse-arrays"
+      | "no-this-before-super"
+      | "no-unassigned-vars"
+      | "no-undef"
+      | "no-unexpected-multiline"
+      | "no-unreachable"
+      | "no-unsafe-finally"
+      | "no-unsafe-negation"
+      | "no-unsafe-optional-chaining"
+      | "no-unused-labels"
+      | "no-unused-private-class-members"
+      | "no-unused-vars"
+      | "no-useless-assignment"
+      | "no-useless-backreference"
+      | "no-useless-catch"
+      | "no-useless-escape"
+      | "no-with"
+      | "preserve-caught-error"
+      | "require-yield"
+      | "use-isnan"
+      | "valid-typeof";
+  }
+  interface KnownProjectFiles {
+    files: 
+      | "src/action.ts"
+      | "src/cli.test.ts"
+      | "src/cli.ts"
+      | "src/compile.ts"
+      | "src/evolve.ts"
+      | "src/freshness.test.ts"
+      | "src/freshness.ts"
+      | "src/generate-types.ts"
+      | "src/inline.test.ts"
+      | "src/inline.ts"
+      | "src/linters.ts"
+      | "src/proofs.test.ts"
+      | "src/proofs.ts"
+      | "src/spec.test.ts"
+      | "src/spec.ts"
+      | "src/types.ts"
+      | "src/validate.test.ts"
+      | "src/validate.ts";
+  }
+  interface KnownNpmScripts {
+    scripts: 
+      | "build"
+      | "test"
+      | "lint"
+      | "fmt"
+      | "fmt:check";
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,95 @@
+<!-- vigiles:sha256:2a0c0efd642c787a compiled from CLAUDE.md.spec.ts -->
+
+# CLAUDE.md
+
+## 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).
+
+## Key Files
+
+- `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/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)
+- `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/inline-mode.md` — Inline mode: `<!-- vigiles:enforce ... -->` comments for gradual adoption without a .spec.ts
+
+## 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 only** — 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 only** — `vigiles compile` should work with just a .spec.ts file. Config exists only for overrides (maxRules, maxTokens).
+
+### Dont Reimplement Linters
+
+**Guidance only** — 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 only** — `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 only** — Run `npm run fmt:check` before committing. Inline code spans in markdown need surrounding spaces to render correctly.
+
+### Progressive Adoption
+
+**Guidance only** — 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 only** — This is a public repo. Claude Code session URLs are private and must not appear in commits or PRs.