vigiles 2.0.0 → 2.2.0

package/dist/types.d.ts

@@ -44,16 +44,44 @@ export interface ValidatePathsResult {
 /** Toggleable rule settings. */
 /** Rule severity: "warn" prints but exits 0, "error" fails, false disables. */
 export type RuleSeverity = "warn" | "error" | false;
-/** Freshness detection mode for the `freshness` rule. */
-export type FreshnessMode = "strict" | "input-hash" | "output-hash";
+/** Rule with options: severity alone or [severity, options] tuple. */
+export type RuleWithOptions<T> = RuleSeverity | [Exclude<RuleSeverity, false>, T];
+/** Options for the coverage rule. */
+export interface CoverageThresholds {
+    /** Min % of enabled linter rules with enforce() declarations. */
+    linterRules?: number;
+    /** Min % of npm scripts documented in spec commands. */
+    scripts?: number;
+}
+/** Options for the orphan-docs check. */
+export interface OrphansConfig {
+    /**
+     * Glob patterns of `.md` files to scan for orphans. A doc is "orphaned"
+     * when no other markdown file references it. Defaults to vigiles-repo
+     * convention: `["docs/**\/*.md", "research/**\/*.md"]`. Set to `[]` to
+     * disable orphan detection entirely.
+     */
+    include?: readonly string[];
+    /**
+     * Glob patterns to exclude within the include scope. Same shape as
+     * `tsconfig.json#exclude`.
+     */
+    exclude?: readonly string[];
+}
 export interface RulesConfig {
     /** Require .spec.ts for CLAUDE.md / AGENTS.md. Default: "warn". */
     "require-spec"?: RuleSeverity;
     /** Require .spec.ts for SKILL.md files. Default: false. */
     "require-skill-spec"?: RuleSeverity;
-    /** Detect stale compiled output. Default: "warn". */
-    freshness?: RuleSeverity;
+    /** Detect hand-edits to compiled markdown via SHA-256 hash. Default: "warn". */
+    integrity?: RuleSeverity;
+    /** Enforce minimum spec coverage thresholds. Default: false. ESLint-style: ["warn", { scripts: 50 }]. */
+    coverage?: RuleWithOptions<CoverageThresholds>;
 }
+/** Extract severity from a rule value (handles both simple and tuple forms). */
+export declare function ruleSeverity<T>(rule: RuleWithOptions<T> | undefined): RuleSeverity;
+/** Extract options from a rule value (returns undefined for simple severity). */
+export declare function ruleOptions<T>(rule: RuleWithOptions<T> | undefined): T | undefined;
 /** Full vigiles configuration. Loaded from .vigilesrc.json. */
 export interface VigilesConfig {
     ruleMarkers: MarkerType[];
@@ -71,10 +99,8 @@ export interface VigilesConfig {
     linters?: Record<string, {
         rulesDir?: string | string[];
     }>;
-    /** How to detect staleness. Default: "strict" (recompile and diff). */
-    freshnessMode?: FreshnessMode;
-    /** Extra files to track in input-hash mode (e.g., monorepo root lock file). */
-    freshnessInputs?: string[];
+    /** Orphan-docs check configuration. Include/exclude globs, tsconfig-style. */
+    orphans?: OrphansConfig;
 }
 /** Valid marker types for rule detection. */
 export type MarkerType = "headings" | "checkboxes";

package/dist/types.js

@@ -1,3 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ruleSeverity = ruleSeverity;
+exports.ruleOptions = ruleOptions;
+// ---------------------------------------------------------------------------
+// Rule parsing helpers
+// ---------------------------------------------------------------------------
+/** Extract severity from a rule value (handles both simple and tuple forms). */
+function ruleSeverity(rule) {
+    if (rule === undefined)
+        return false;
+    if (Array.isArray(rule))
+        return rule[0];
+    return rule;
+}
+/** Extract options from a rule value (returns undefined for simple severity). */
+function ruleOptions(rule) {
+    if (Array.isArray(rule))
+        return rule[1];
+    return undefined;
+}
 //# sourceMappingURL=types.js.map

package/dist/validate.js

@@ -12,6 +12,7 @@ const glob_1 = require("glob");
 const node_path_1 = require("node:path");
 const cosmiconfig_1 = require("cosmiconfig");
 const inline_js_1 = require("./inline.js");
+const frontmatter_js_1 = require("./frontmatter.js");
 // ---------------------------------------------------------------------------
 // Constants & regex
 // ---------------------------------------------------------------------------
@@ -27,7 +28,8 @@ const DEFAULT_FILES = ["CLAUDE.md"];
 const DEFAULT_RULES = {
     "require-spec": "warn",
     "require-skill-spec": "warn",
-    freshness: "warn",
+    integrity: "warn",
+    coverage: false,
 };
 const DEFAULT_CONFIG = {
     ruleMarkers: ["headings", "checkboxes"],
@@ -150,11 +152,11 @@ function validate(content, { ruleMarkers, rules: rulesConfig, filePath } = {}) {
             // verified on `vigiles audit` even without a .spec.ts sibling.
             // Delegate to the real parser so a malformed marker can't
             // satisfy require-spec with a rule that audit can't verify.
-            const hasInline = (0, inline_js_1.hasInlineRules)(content);
+            const hasInline = (0, inline_js_1.hasInlineRules)(content) || (0, frontmatter_js_1.hasFrontmatterRules)(content);
             if (!(0, node_fs_1.existsSync)(specPath) && !hasInline) {
                 const msg = {
                     rule: "require-spec",
-                    message: `No spec file found for "${filePath}". Expected "${specPath}". Run \`npx vigiles init --target=${filePath}\` to create one, add inline \`<!-- vigiles:enforce ... -->\` comments, or disable with <!-- vigiles-disable require-spec -->.`,
+                    message: `No spec file found for "${filePath}". Expected "${specPath}". Run \`npx vigiles init --target=${filePath}\` to create one, add inline \`<!-- vigiles:enforce ... -->\` comments or a \`vigiles:\` frontmatter block, or disable with <!-- vigiles-disable require-spec -->.`,
                     line: 1,
                 };
                 if (specSeverity === "error") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Compile .spec.ts files to instruction files (CLAUDE.md, AGENTS.md) with linter cross-referencing",
   "bin": {
     "vigiles": "dist/cli.js"
@@ -11,17 +11,32 @@
     ".": "./dist/spec.js",
     "./spec": "./dist/spec.js",
     "./compile": "./dist/compile.js",
-    "./linters": "./dist/linters.js"
+    "./linters": "./dist/linters.js",
+    "./eval": "./dist/eval.js",
+    "./harness-test": "./dist/harness-test.js",
+    "./mock-model": "./dist/mock-model.js"
   },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "action.yml",
+    ".claude-plugin",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
     "build": "tsc",
-    "test": "npm run build && node --test dist/spec.test.js dist/validate.test.js dist/cli.test.js dist/proofs.test.js dist/inline.test.js",
+    "test": "npm run build && node --test dist/spec.test.js dist/validate.test.js dist/cli.test.js dist/proofs.test.js dist/inline.test.js dist/sidecar.test.js dist/coverage.test.js dist/session.test.js dist/orphans.test.js dist/cedar.test.js dist/doc-refs.test.js dist/frontmatter.test.js dist/skill-pipeline.test.js dist/skill-runtime.test.js dist/skill-driver.test.js dist/skill-test.test.js dist/compile-generator.test.js dist/community-skills.test.js dist/action-gate.test.js dist/symbols.test.js dist/refs.test.js dist/harness-test.test.js dist/eval.test.js",
     "lint": "eslint src/",
     "fmt": "prettier --write .",
-    "fmt:check": "prettier --check ."
+    "fmt:check": "prettier --check .",
+    "test:e2e": "bash test/e2e/run.sh"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@types/js-yaml": "^4.0.9",
     "@types/minimatch": "^5.1.2",
     "@types/node": "^20.19.39",
     "@typescript-eslint/eslint-plugin": "^8.58.0",
@@ -34,9 +49,15 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
+    "@ast-grep/lang-python": "^0.0.6",
+    "@ast-grep/lang-ruby": "^0.0.7",
+    "@ast-grep/lang-rust": "^0.0.7",
+    "@ast-grep/napi": "^0.43.0",
     "@jackchuka/mdschema": "^0.12.8",
     "cosmiconfig": "^9.0.1",
     "glob": "^13.0.6",
-    "minimatch": "^10.0.1"
+    "js-yaml": "^4.1.0",
+    "minimatch": "^10.0.1",
+    "typescript": "^5.9.3"
   }
 }

package/.claude/settings.json

@@ -1,46 +0,0 @@
-{
-  "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

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

package/.github/workflows/ci.yml

@@ -1,81 +0,0 @@
-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

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

package/.vigiles/generated.d.ts

@@ -1,205 +0,0 @@
-/**
- * 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

@@ -1,95 +0,0 @@
-<!-- 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.