vigiles 14.0.0 → 14.2.0

package/README.md

@@ -65,10 +65,13 @@
   research/ links / NO enterprise/national-interest framing — name the user
   benefit; ~220-line body cap; push depth into docs/ and LINK it. Assets: the hero
   vigiles-audit.png is a REPRESENTATIVE report ("my-plugin", C 77) — the verdict-
-  led header + ranked fixes + the "Your rules → enforced" section (the new rule-
-  compile capability). Re-render via headless Chromium if the UI changes: build
-  report/, screenshot report/dist/index.html (falls back to the sample fixture),
-  inject the dark :root tokens before </body> for the dark render.
+  led header + category strip + ranked fixes + broken references. The "Your rules →
+  enforced" preview is DEMOTED low + badged EXPERIMENTAL (the rule map is alpha —
+  research/rule-enforcer-design.md §8). Re-render if the UI changes: `npm run build`
+  (rebuilds report/dist/index.html from the SAMPLE fixture), then headless Chromium
+  (puppeteer-core, executablePath /opt/pw-browsers/chromium) with
+  prefers-color-scheme:dark emulated + a fullPage screenshot at deviceScaleFactor 2
+  → vigiles-audit.png (2200px wide).
 -->
 
 <p align="center">
@@ -110,7 +113,7 @@ It's free and open-source, runs entirely on your machine, and never bills per to
 ## What it caught
 
 <p align="center">
-  <img src="vigiles-audit.png" width="760" alt="vigiles audit report for my-plugin: a verdict header reading 'Two one-line fixes away from a B.' next to a C (77/100) grade, a five-category strip (Truthfulness, Triggering, Structure, Safety, Tested), ranked fix cards with '+N pts' impact badges, and a 'Your rules → enforced' section showing a prose rule the config silently turns off" />
+  <img src="vigiles-audit.png" width="760" alt="vigiles audit report for my-plugin: a verdict header reading 'Two one-line fixes away from a B.' next to a C (77/100) grade, a five-category strip (Truthfulness, Triggering, Structure, Safety, Tested), ranked fix cards with '+N pts' impact badges, broken-reference findings — and, lower down and badged experimental, a 'Your rules → enforced' preview mapping a prose rule the config silently turns off" />
 </p>
 
 **Like Google's Lighthouse, but for your agent harness.** One command grades it A–F across five categories, leads with a plain-English verdict — _"two one-line fixes away from a B"_ — and ranks every fix by the points it buys back:
@@ -186,11 +189,11 @@ That's the whole idea: it checks your harness against **reality, not style**. Ev
 | `test`  | Does the harness behave?       | No — a scripted stand-in | Every commit             |
 | `eval`  | Does a skill actually help?    | Yes — your subscription  | On demand                |
 
-**One engine, two doors.** `audit` is the local report; **`lint` is the CI gate** that fails the build on the same deterministic checks — broken refs, bad tool contracts, dead hooks, skill collisions (Proofs 1–2). `test` and `eval` go further: past _does it exist_ to _does it work_. (`init` / `compile` / `eject` manage the spec layer underneath — you rarely run them by hand.)
+**One engine, two doors.** `audit` is the local report; **`lint` is the CI gate** that fails the build on the same deterministic checks — broken refs, bad tool contracts, dead hooks, skill collisions (Proofs 1–2). `test` and `eval` go further: past _does it exist_ to _does it work_. (`init` / `compile` / `eject` manage the optional typed-spec layer for the structural rules no linter can express — a graduation step you rarely run by hand.)
 
 ### 🔎 Lint — your instructions stop lying
 
-Every path, script, symbol, and rule verified against reality — plus tool contracts, skill collisions, and dead hooks (the catches above). You don't write the checks. `npx vigiles init` writes a `CLAUDE.md.spec.ts` beside your file: the same rules, each reference now wrapped so vigiles can confirm it exists. `compile` turns that back into the `CLAUDE.md` (or `AGENTS.md`) your agent already reads. Your agent edits the spec in plain English; `eject` deletes it and leaves your original untouched.
+Every path, script, symbol, and rule verified against reality — plus tool contracts, skill collisions, and dead hooks (the catches above). You don't write the checks, and you don't port anything into a spec: `lint` reads the `CLAUDE.md` or `AGENTS.md` you already hand-edit and checks it as-is. Rules that map to a real linter rule run in your own config (ESLint, Ruff), not a shadow layer.
 **[How →](docs/verifying-instruction-files.md)**
 
 ### 🧪 Test — does the harness actually do its job?
@@ -223,15 +226,15 @@ npx vigiles audit
 
 ```text
 Set up vigiles in this repo: run `npx vigiles init` and accept the defaults. If I
-already have a CLAUDE.md or AGENTS.md, adopt it into a spec and show me which
-references are stale. Then compile and write + run one harness test for a hook or
-skill of mine. Don't run a real-model eval without asking me first.
+already have a CLAUDE.md or AGENTS.md, audit it and show me which references are
+stale and which of my rules aren't enforced. Then write + run one harness test for
+a hook or skill of mine. Don't run a real-model eval without asking me first.
 ```
 
 Or run it yourself:
 
 ```bash
-npx vigiles init   # adopts your files (non-destructive — eject reverses), adds CI,
+npx vigiles init   # sets up the typed spec for structural rules (non-destructive — eject reverses), adds CI,
                    # installs vigiles's skills + hooks as a Claude Code plugin (in
                    # ~/.claude/, not your repo). On Codex, skills install globally too.
 ```
@@ -250,7 +253,7 @@ The **hooks** keep it honest in-loop — nudging the agent to tag a linter-rule
 <summary>What <code>init</code> sets up</summary>
 
 - **Both lint and test** by default; scope with `--lint` / `--test`.
-- **Already have a CLAUDE.md / AGENTS.md, skills, or subagents? `init` adopts them all** into specs faithfully and **non-destructively** — untouched until you `compile` (and `eject` undoes it).
+- **Already have a CLAUDE.md / AGENTS.md, skills, or subagents? `audit` and `lint` read them as-is** — nothing is moved or rewritten. For the structural rules that want a typed spec, `init` sets one up **non-destructively** (`eject` undoes it).
 - Adds `vigiles` to `devDependencies`; installs the Claude Code plugin (skills + hooks) via the marketplace — globally, never vendored.
 - Wires CI as a `zernie/vigiles@v1` workflow (needs only read + PR-comment permissions) that posts a sticky PR comment + a `valid` output.
 
@@ -262,7 +265,7 @@ Targets Claude Code and Codex out of the box, or [your own harness](docs/authori
 
 - **Is this a framework I have to build around?** No. It's a tool you run — like ESLint, Lighthouse, or `npm audit`. One command, a report, an optional CI gate. There's a library API for automation, but you never touch it to get value.
 - **Isn't this just a markdown linter?** No — it checks whether your instruction file is _true_ (every path/script/symbol/rule exists and is enabled), then tests and measures your harness. A style linter can't do any of that.
-- **Do I have to write TypeScript?** No — your agent writes the spec (`init` adopts your CLAUDE.md or AGENTS.md into one), or plain markdown lints with zero new files. Compiler-grade guarantees are opt-in, like TS's `strict` ([why?](docs/faq.md#why-are-the-strongest-guarantees-opt-in-not-the-default)).
+- **Do I have to write TypeScript?** No — plain markdown works with zero new files, and rules run in your own linter config. The typed spec is opt-in, only for the structural checks a linter can't do — like TS's `strict` ([why?](docs/faq.md#why-are-the-strongest-guarantees-opt-in-not-the-default)).
 - **Is it stable enough to adopt?** The CLI you run is small and rarely changes; the library API still moves between releases. The high version number is release automation (a new major per breaking change), not age — see [Stability](STABILITY.md).
 - **Non-JS repo?** `npx vigiles lint` verifies your CLAUDE.md or AGENTS.md with no install (Ruff/Clippy/Pylint/… too).
 

package/dist/adapters/claude-code/dialect.d.ts

@@ -3,7 +3,7 @@
  * The concrete dialect is DEFINED here, in the adapter, symmetric with the other
  * four ports (`claudeCodeLayout`/`Runtime`/`HookProtocol`/`ModelMock`): the core
  * holds only the `HarnessDialect` interface and never a harness's vocabulary. The
- * compiler/validator receive this by injection (`compileAgent(spec, { dialect })`,
+ * rule-enforcer/validator receive this by injection (`compileAgent(spec, { dialect })`,
  * the CLI/composition root supplies it). A second harness defines its own dialect
  * in its adapter (e.g. `src/adapters/codex/dialect.ts` exporting `codexDialect`).
  */

package/dist/audit-report.js

@@ -84,7 +84,10 @@ function buildAuditReport(report, opts) {
         ...(opts.rulesInventory && opts.rulesInventory.length
             ? { rulesInventory: opts.rulesInventory }
             : {}),
-        ...(opts.ruleRouting && opts.ruleRouting.segmented > 0
+        ...(opts.ruleRouting &&
+            (opts.ruleRouting.segmented > 0 ||
+                opts.ruleRouting.possible.length > 0 ||
+                opts.ruleRouting.skipped.length > 0)
             ? { ruleRouting: opts.ruleRouting }
             : {}),
     };