vigiles 12.7.0 → 13.0.0

package/README.md

@@ -40,8 +40,10 @@
   SPINE = proof/demo-led. Real, screenshotable catches on shipped plugins, THEN
   mechanism. Every proof traces to a real dogfood run (research/dogfood/) — NEVER
   fabricate one. Order = most-RELATABLE first (broken tool ref → skill collision →
-  secrets-exfil gotcha last as the bite). The intro triplet maps 1:1 to the 3
-  proofs. Security is ONE dev-native GOTCHA proof, never the brand. Add a repro
+  rules-not-enforced → secrets-exfil gotcha LAST as the bite). The intro triplet
+  maps to the three "vibes break silently" proofs (1, 2, 4); Proof 3 (your rules →
+  enforced) pays off the TAGLINE's rule-follows-half-the-time pain. Security is ONE
+  dev-native GOTCHA proof, never the brand. Add a repro
   line ("run `npx vigiles audit <any-repo>` for your own") + a one-line note that
   examples use CC subagents but the checks run on Codex too. FALSE CONFIDENCE is
   the coined term (a guard that looks like it works and silently doesn't), defined
@@ -59,8 +61,11 @@
   block; ONE idea per sentence; NO internal vocabulary (moat/flywheel) / NO
   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 REAL current report (a community plugin as "my-plugin"),
-  C 72, five rings — re-render via headless Chromium if the UI changes.
+  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.
 -->
 
 <p align="center">
@@ -102,10 +107,10 @@ 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 scoring my-plugin C (72/100): five categories scored A–F — Truthfulness, Triggering, Structure, Safety, Tested — with an inline fix card for a subagent declaring a tool that doesn't exist" />
+  <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" />
 </p>
 
-**Like Google's Lighthouse, but for your agent harness.** One command grades it A–F across five categories, every fix shown inline:
+**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:
 
 - **Truthfulness** — do the references resolve?
 - **Triggering** — do skills fire, without colliding?
@@ -113,6 +118,8 @@ It's free and open-source, runs entirely on your machine, and never bills per to
 - **Safety** — any way for the agent to leak your data?
 - **Tested** — does the harness ship tests?
 
+And it closes the loop from prose to enforcement: **your rules → enforced** maps each rule you wrote to the lint rule that actually enforces it — already on, one config line away, or silently turned off (below).
+
 These are real scans of public plugins — run `npx vigiles audit <any-repo>` for your own. The examples below use Claude Code subagents; the same checks run on Codex `AGENTS.md`, skills, and hooks. ↓
 
 ## Proof 1 — a tool your agent thinks it has and doesn't
@@ -132,10 +139,23 @@ This subagent — a helper your main agent hands work to — lists a tool that d
       apart, so the wrong one fires  (e.g. "agent-coder" ↔ "agent-tester", 83% alike)
 ```
 
-One popular plugin ships **45 pairs of skills** with near-identical descriptions. Your agent picks which skill to run by _reading_ those descriptions, so when two match it fires the wrong one. Still perfectly valid markdown.
+One popular plugin ships **45 pairs** of near-identical skill descriptions. Your agent picks a skill by _reading_ them — so when two match, it fires the wrong one. Still perfectly valid markdown.
 **[How triggering works →](docs/measuring-skills.md)**
 
-## Proof 3 — it can quietly read your secrets and send them out
+## Proof 3 — a rule you wrote that nothing enforces
+
+Point vigiles at your own repo and the rules section maps each prose rule to the lint rule that enforces it — then checks your config. Representative output:
+
+```text
+Your rules → enforced   1 of 4 enforced · 2 one line away · 1 contradicted by config
+    └ "always use ===" → eqeqeq is set to "off" in your ESLint config
+       your CLAUDE.md says enforce it; your config quietly turns it off
+```
+
+You wrote the rule. Your agent treats it as gospel and follows it — until it doesn't, and nothing tells you which time. vigiles checks each mapped rule three ways: enforced, **one line away**, or — the one people screenshot — documented but silently **turned off**. Deterministic, no model. Want the rest compiled — a custom rule for a rule no linter ships, a hook for `git push`, the judgment calls honestly left alone? That's the opt-in `compile` tier (one model pass, then CI is plain lint).
+**[How enforcement works →](docs/verifying-instruction-files.md)**
+
+## Proof 4 — it can quietly read your secrets and send them out
 
 ```text
 ◑ Safety   80  (80/100)
@@ -144,7 +164,7 @@ One popular plugin ships **45 pairs of skills** with near-identical descriptions
         · can send data out (Bash, WebFetch)
 ```
 
-Hand one subagent all three powers and a poisoned web page can tell it to read your `.env` and POST it anywhere — no exploit code, just the tools it was given. The **80 still looks like a B** — that's the point: a healthy-looking grade can hide a single subagent that's a data-leak waiting to happen. vigiles spots it from the tool list alone, free, no model.
+Hand one subagent all three powers and a poisoned web page can make it read your `.env` and POST it anywhere — no exploit code, just the tools it was given. The **80 looks like a B** — and that's the trap: a healthy grade hiding a subagent that's a data-leak waiting to happen. vigiles spots it from the tool list alone, free, no model.
 
 That's the whole idea: it checks your harness against **reality, not style**. Every tool, hook, file, script, and skill you reference is verified to actually resolve — and where you name a linter rule, it's checked to exist _and_ be enabled (ESLint, Ruff, Clippy, and more).
 **[Everything it catches →](docs/what-vigiles-catches.md)** · point `audit` at a whole marketplace and it ranks every plugin the same way.
@@ -160,7 +180,7 @@ 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                |
 
-`audit` and `lint` share one engine. **`lint` is the CI gate** — it fails the build on broken references, bad tool contracts, dead hooks, and skill collisions (Proofs 1 and 2). **`audit`** runs those same checks, adds the Safety ring, renders the graded report, and can also run two opt-in _live_ checks (does your MCP server connect, do your skills fire). `test` and `eval` go 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 spec layer underneath — you rarely run them by hand.)
 
 ### 🔎 Lint — your instructions stop lying
 
@@ -172,7 +192,7 @@ Every path, script, symbol, and rule verified against reality — plus tool cont
 A hook that blocks nothing, a skill that hijacks unrelated prompts, context that never reaches the model — each passes a naive "did it run?" check. That gap is **false confidence**: a guard that looks like it works and silently doesn't. vigiles tests the real thing — hooks block, skills fire, subagents finish what they promised, a stray `git push` is caught before it happens. It drives a scripted stand-in for the model, not a live call, so it needs no key and runs on every commit.
 **[How testing works →](docs/harness-testing.md)**
 
-### 📊 Eval — does a skill help, or just cost more?
+### 📊 Eval — the only way to put a real number on cost
 
 _"Caveman Mode cuts 65% of your tokens." Says who?_ vigiles A/Bs the claim on real coding tasks and hands you three numbers: the **token bill**, whether it hit its **target**, and whether your code still **works**.
 
@@ -237,18 +257,26 @@ 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)).
-- **Is it stable enough to adopt?** Yes — the CLI is stable; only the library API is still evolving ([details](STABILITY.md)).
+- **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).
 
 **[Full FAQ →](docs/faq.md)**
 
 **Not for you if** you want a model/capability benchmark or runtime guardrails in the request path — vigiles is build-/CI-time.
 
-## More
+## Docs
+
+The **[docs index](docs/README.md)** is the full map, grouped by what you're doing:
+
+- **Guides** — [verify instruction files](docs/verifying-instruction-files.md) · [test your harness](docs/harness-testing.md) · [measure a skill](docs/measuring-skills.md) · [ship a plugin](docs/for-plugin-authors.md) · [Codex & other harnesses](docs/harnesses.md)
+- **Reference** — [CLI](docs/cli.md) · [rules matrix](docs/verifying-instruction-files.md#the-validation-rules--the-full-matrix) · [testing API](docs/testing-api.md) · [full API](https://zernie.github.io/vigiles/)
+- **Explanation** — [what it catches](docs/what-vigiles-catches.md) · [how it compares](docs/comparison.md) · [FAQ](docs/faq.md)
 
-**Docs** — **[What it catches and prevents →](docs/what-vigiles-catches.md)** · **[Verifying instruction files →](docs/verifying-instruction-files.md)** ([rules matrix](docs/verifying-instruction-files.md#the-validation-rules--the-full-matrix)) · **[Harness testing →](docs/harness-testing.md)** · **[Measuring skills →](docs/measuring-skills.md)** · **[CLI →](docs/cli.md)** · **[GitHub Action →](docs/github-action.md)** · **[Skills →](docs/skills.md)** · **[Plugin-author guide →](docs/for-plugin-authors.md)** · **[Docs index →](docs/README.md)** · **[API reference →](https://zernie.github.io/vigiles/)**
+**Project** — [Stability](STABILITY.md) · [Related tools](docs/comparison.md#what-vigiles-composes-with)
 
-**Project** — **[Stability →](STABILITY.md)** · **[Related tools →](docs/related-tools.md)** · companion to [Feedback Loop Is All You Need](https://zernie.com/blog/feedback-loop-is-all-you-need).
+<!-- The "companion to [Feedback Loop Is All You Need](https://zernie.com/blog/feedback-loop-is-all-you-need)"
+     link is temporarily removed while AgenticDev paper #1 is under blind review: repo → blog is a
+     deanonymization path (the reviewer-offer email links this repo). RESTORE after notification (2026-08-21). -->
 
 ## License
 

package/dist/audit-report.d.ts

@@ -13,10 +13,13 @@
  */
 import { type AuditScore } from "./audit-score.js";
 import { type Recommendation } from "./optimize.js";
+import { type Verdict } from "./audit-verdict.js";
 import type { LedgerSummary } from "./observe.js";
 import type { AdoptabilityResult } from "./adoptability.js";
 import type { ScanReport, MarketplaceInfo } from "./scan.js";
 import type { PluginScore } from "./leaderboard.js";
+import type { RuleInventoryItem } from "./rule-inventory.js";
+import type { RuleRouting } from "./rule-routing.js";
 /** The current schema version. Bump only on a BREAKING change to the shape. */
 export declare const AUDIT_SCHEMA_VERSION = 1;
 export interface AuditReportMeta {
@@ -80,6 +83,13 @@ export interface AuditReport {
     readonly meta: AuditReportMeta;
     /** The five deterministic category rings + the weighted overall + grade. */
     readonly score: AuditScore;
+    /**
+     * The one-line verdict + per-recommendation `pointsIfFixed`, both derived by
+     * RE-SCORING (never a hardcoded number). Drives the report's verdict-led header
+     * ("Two one-line fixes away from a B.") and the `+N pts` badges on fix cards.
+     * Pure/deterministic — always present.
+     */
+    readonly verdict: Verdict;
     /** The deterministic, ranked fixes (the inline recommendations). */
     readonly recommendations: readonly Recommendation[];
     readonly inventory: AuditInventory;
@@ -104,6 +114,24 @@ export interface AuditReport {
      * the pure builder stays fs-free.
      */
     readonly observations?: LedgerSummary;
+    /**
+     * The deterministic rule-inventory teaser — prose rules in the harness that
+     * map to an off-the-shelf lint rule + whether that rule is already in the
+     * config (the one-line-config-fix nudge). No model, no config execution. The
+     * CLI computes it (reads the instruction + config text, calls
+     * `buildRuleInventory`) and passes it in, so the pure builder stays fs-free.
+     * Present only when at least one intent resolves. Additive/optional — schema
+     * version unchanged. See `research/audit-rule-compile-tier.md`.
+     */
+    readonly rulesInventory?: readonly RuleInventoryItem[];
+    /**
+     * The deterministic State-B routing PREVIEW — the instruction file segmented
+     * into atomic rules, each routed (reuse / hook / semantic / unrouted) to how
+     * it would be enforced, with per-category counts. No model, fs-only. Grounds
+     * the report's "compile" upsell in real numbers instead of generic copy.
+     * Present only when at least one atomic rule was segmented. Additive/optional.
+     */
+    readonly ruleRouting?: RuleRouting;
 }
 export interface BuildAuditReportOptions {
     readonly harness: string;
@@ -117,6 +145,16 @@ export interface BuildAuditReportOptions {
      * when there's nothing to adopt.
      */
     readonly adoptableSurfaces?: readonly string[];
+    /**
+     * The rule-inventory items the CLI computed via `buildRuleInventory` (reading
+     * the instruction + config text). Omit/empty when nothing resolved.
+     */
+    readonly rulesInventory?: readonly RuleInventoryItem[];
+    /**
+     * The State-B routing preview the CLI computed via `routeRules`. Omit when
+     * nothing segmented.
+     */
+    readonly ruleRouting?: RuleRouting;
 }
 /**
  * Assemble the versioned {@link AuditReport} from a scan report — pure, no clock.

package/dist/audit-report.js

@@ -19,6 +19,7 @@ exports.buildMarketplaceReport = buildMarketplaceReport;
  */
 const audit_score_js_1 = require("./audit-score.js");
 const optimize_js_1 = require("./optimize.js");
+const audit_verdict_js_1 = require("./audit-verdict.js");
 /** The current schema version. Bump only on a BREAKING change to the shape. */
 exports.AUDIT_SCHEMA_VERSION = 1;
 /** The one command that adopts every un-spec'd surface (bare `init`). */
@@ -47,6 +48,9 @@ function buildAdoptable(surfaces) {
  */
 function buildAuditReport(report, opts) {
     const adoptable = buildAdoptable(opts.adoptableSurfaces);
+    const score = (0, audit_score_js_1.auditScore)(report);
+    const recommendations = (0, optimize_js_1.optimize)(report).recommendations;
+    const verdict = (0, audit_verdict_js_1.computeVerdict)({ report, score, recommendations });
     return {
         meta: {
             schemaVersion: exports.AUDIT_SCHEMA_VERSION,
@@ -56,8 +60,9 @@ function buildAuditReport(report, opts) {
             harness: opts.harness,
             dir: report.dir,
         },
-        score: (0, audit_score_js_1.auditScore)(report),
-        recommendations: (0, optimize_js_1.optimize)(report).recommendations,
+        score,
+        verdict,
+        recommendations,
         inventory: {
             skills: report.skills.length,
             agents: report.agents.length,
@@ -71,6 +76,12 @@ function buildAuditReport(report, opts) {
         },
         ...(adoptable ? { adoptable } : {}),
         ...(opts.observations ? { observations: opts.observations } : {}),
+        ...(opts.rulesInventory && opts.rulesInventory.length
+            ? { rulesInventory: opts.rulesInventory }
+            : {}),
+        ...(opts.ruleRouting && opts.ruleRouting.segmented > 0
+            ? { ruleRouting: opts.ruleRouting }
+            : {}),
     };
 }
 /** Assemble the versioned {@link LeaderboardReport} — pure, no clock. */