vigiles 9.1.0 → 11.0.0

package/README.md

@@ -6,18 +6,31 @@
   SPINE = CONCEPT 5 (proof/demo-led). Lead with REAL, screenshotable catches on
   plugins people actually ship, THEN explain the mechanism. The proofs are not
   illustrative — every block traces to a real dogfood run captured in
-  research/dogfood/. HYBRID proof source (decided 2026-06-28): Proofs 1-2 are
-  COMMUNITY catches, anonymized (a missing SKILL.md, an AskUserQuestion-never-
-  available tool) — official plugins don't have those silent-failure bugs. Proofs
-  3-4 are OFFICIAL + NAMED: pr-review-toolkit (malformed YAML + unrestricted review
-  agents) and the all-37 Anthropic-official leaderboard (A→F, LSP stubs excluded).
-  NEVER replace a real catch with a fabricated one.
+  research/dogfood/. THREE COMMUNITY catches, anonymized (2026-06-29: Proof 1 is now a
+  lethal-trifecta exfil path → Safety 80, from madappgang's `tester` shown as
+  "my-plugin" — added to pay off the new Safety-ring hero; Proof 2 a skill-description
+  collision → wrong-skill-fires (claude-flow, Triggering F); Proof 3 an
+  AskUserQuestion-never-available tool) — all real GRADED/structural defects that
+  REPRODUCE on current main. NEVER replace a real catch with a fabricated one. (The
+  earlier Proof 1 was a missing-SKILL.md/Truthfulness catch, swapped 2026-06-28: its
+  source (superpowers) is clean on current main and NO reproducible dead-file-ref
+  exists in popular OSS — those are an adopt+strengthen payoff, see
+  research/oss-audit-render-findings.md.)
+
+  WHY ONLY TWO (decided 2026-06-28): the earlier Proofs 3-4 leaned on
+  pr-review-toolkit's "review agents inherit all tools" as an official-plugin
+  defect. But inherit-all (a subagent with no `tools:` line) is now ADVISORY, not a
+  graded penalty — omitting the tool contract is a near-universal, legitimate
+  authoring style (an OSS sweep of 122 plugins found 109 whose only finding was
+  this), so penalizing it cried wolf. With that change the official plugins are all
+  a clean A, so a "even Anthropic has bugs" proof would be dishonest — Proofs 3-4
+  were DROPPED rather than reframed. The leaderboard feature still exists; it just
+  isn't a headline proof.
 
   DON'T SHAME OSS: community catches are real but ANONYMIZED in public copy (no
   obra/superpowers, madappgang by name) — real names live only in research/dogfood/.
-  Punch UP at official/vendor plugins (Anthropic's own are NAMED); never name a
-  volunteer's repo to show its bug. Proof 3/4 don't show pr-review-toolkit's audit-
-  RING score (88) — only the leaderboard score (52 F) — so the two never clash.
+  If an official/vendor proof returns, punch UP (name Anthropic's own); never name a
+  volunteer's repo to show its bug.
 
   1. LEAD WITH BENEFITS / the reader's CONCRETE PAIN, never an apology, caveat, or
      competitor. A bolded lead-in is the first thing read — make it the hook/win.
@@ -34,11 +47,33 @@
      Push depth into docs/ and LINK it.
   6. NO INTERNAL VOCABULARY (moat / measurement-authority / flywheel) and NO
      research/ links — name the user benefit.
-  7. ASSETS: the hero vigiles-audit.png must be REFRESHED from a real run
-     (research/dogfood/audit-superpowers.html) without the dialect drift banner
-     before launch. (vigiles-demo.gif was removed from Proof 1 — it rendered as a
-     frozen half-typed terminal and was redundant with the code block; if a lint
-     demo returns, it belongs in the Lint section with a non-frozen asset.)
+  7. ASSETS: the hero vigiles-audit.png is a REAL current report (a community
+     plugin rendered as "my-plugin" to anonymize) — C 72 with five rings, the
+     SAFETY ring (80) flagging a subagent holding all three lethal-trifecta legs
+     (a prompt-injection exfil path) + an inline subagent-tool-contract fix; the
+     dramatic Safety catch is the whole point of leading with this report (chose
+     the "bite" over a clean A 92 on 2026-06-29). No dialect-drift banner (HTML
+     report is terminal-banner-free by design). Re-render via headless Chromium on
+     the React report if the UI changes (recipe: copy a trifecta-bearing plugin to
+     my-plugin/, `node dist/cli.js audit my-plugin --no-json --no-serve`,
+     headless_shell `--window-size=820,1180 --force-device-scale-factor=2
+     --screenshot` on vigiles-report.html, then `rm -rf my-plugin
+     vigiles-report.html`). (vigiles-demo.gif was removed
+     from Proof 1 — it rendered as a frozen half-typed terminal and was redundant
+     with the code block; if a lint demo returns, it belongs in the Lint section
+     with a non-frozen asset.)
+
+  READABILITY (the 2026-06-29 pass — why this reads the way it does):
+  A. ONE bold per block, on the single phrase the eye should catch. Bold
+     everywhere = bold nowhere. Link CTAs may stay bold (they're navigation).
+  B. ONE idea per sentence. No em-dash clause-chains, no stacked parentheticals.
+     If a clause needs a paren, cut it or give it its own line.
+  C. PLAIN words in every LEAD; push jargon (rings, recall/precision,
+     interceptTools, selector, deterministic) into the linked docs. A skimmer who
+     lives in Claude Code still may not know the vocabulary.
+  D. SHOW via the proofs/code blocks; don't stack adjectives ("real, popular,
+     free, model-less") on top of what the block already proves.
+  E. SELL the outcome before the mechanism; the instruments come AFTER the proofs.
 -->
 
 <p align="center">
@@ -48,7 +83,7 @@
 <h1 align="center">vigiles</h1>
 
 <p align="center">
-  <strong>The tests your AI agent harness never had.</strong>
+  <strong>The tests your agent's skills and hooks never had.</strong>
 </p>
 
 <p align="center">
@@ -59,153 +94,133 @@
 
 ---
 
-**You installed a bunch of plugins and wrote a few skills — but do they actually work?**
-A skill that never fires, a subagent wired to a tool that doesn't exist, a CLAUDE.md
-full of dead references — your harness fails **silently**, and you find out mid-task.
+**You installed some plugins and wrote a few skills. Do they actually work?**
 
-**It's a library with no tests.** One command runs them — no key, no config, safe on
-any repo:
+Your skills, hooks, and instructions are your agent's **harness** — the half you wrote
+and own, and the half nothing checks. A skill that never fires. Two skills the agent
+confuses. A subagent wired to a tool that doesn't exist. It breaks silently, and you
+find out mid-task.
+
+It's a library with no tests. This runs them:
 
 ```bash
 npx vigiles audit
 ```
 
-Here's what it found on real, popular plugins. ↓
+No key, no config, safe on any repo. Here's what it caught on plugins people actually
+ship. ↓
 
-## The report
+## What it caught
 
 <p align="center">
-  <img src="vigiles-audit.png" width="760" alt="vigiles audit report: an overall score with four category rings — Truthfulness, Triggering, Structure, Tested — and fix cards" />
+  <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 the Safety category flagging a subagent that holds all three lethal-trifecta legs (a prompt-injection exfil path), plus an inline fix card for a subagent declaring a tool that doesn't exist" />
 </p>
-<!-- REFRESH before launch from research/dogfood/audit-superpowers.html (a real catch, no drift banner). -->
-
-Four deterministic rings, **each finding's fix inline**, and a shareable HTML report.
-Like Lighthouse, `audit` is a **local report you run on your machine** — safe on any
-repo (even one wired to prod), identical on every OS. **Not a CI step** (CI uses
-`lint`). **[Audit a harness →](docs/for-plugin-authors.md)**
-
-## Proof 1 — your CLAUDE.md is lying to your agent
-
-```text
-● Truthfulness   92
-    └ ✗ skills/using-debugging/SKILL.md  (referenced but MISSING)
-```
 
-A real, widely-installed plugin — its instructions send the agent to a skill file
-that **isn't there**. Valid markdown, but not _true_, and your agent trusts it anyway.
+**Like Google's Lighthouse, but for your agent harness.** Five categories, each scored
+A–F — Truthfulness, Triggering, Structure, Safety, Tested — with every fix shown inline.
 
-File paths, scripts, code symbols — plus linter rules across **7 linters** (ESLint,
-Ruff, Clippy + four more): each one **exists _and_ is enabled**. **[Full guide →](docs/verifying-instruction-files.md)**
+It runs locally and only reads, so it's safe on any repo and the same on every OS.
+For CI gating, use `vigiles lint` instead. **[Audit a harness →](docs/for-plugin-authors.md)**
 
-## Proof 2 — a tool your subagent silently can't call
+## Proof 1 — your agent can read your secrets and ship them out
 
 ```text
-✗ tester — Tool "AskUserQuestion" is never available to a subagent.
-    → remove or correct it — it's silently dropped from the contract.
+◑ Safety   80  (80/100)
+    └ subagent "tester" holds all three lethal-trifecta legs:
+        reads private data (Bash, Read) · takes in untrusted web content (WebFetch)
+        · can send data out (Bash, WebFetch)
 ```
 
-A real upstream subagent declares a tool the harness **silently drops**, so it loses
-a capability it thinks it has. vigiles flags it _and_ hands you the one-line fix —
-**free, no model.** That's the difference from a markdown linter: it checks your
-harness against **reality**, not style.
-
-## Proof 3 — even the official plugins
+Give one subagent all three powers and it's a **prompt-injection exfil path**: a poisoned
+web page can tell it to read your `.env` and POST it anywhere — no exploit code, just the
+tools it was handed. vigiles flags it from the tool list alone, free, no model.
+**[How the Safety check works →](docs/for-plugin-authors.md)**
 
-Not cherry-picked community repos — **Anthropic's own official `pr-review-toolkit`**:
+## Proof 2 — two skills your agent can't tell apart
 
 ```text
-✗ silent-failure-hunter.md — frontmatter isn't valid YAML (won't parse)
-⚠ 6 review agents inherit ALL tools — a code-reviewer with Write + Bash
+✗ Triggering   0  (0/100)
+    └ 45 pairs of near-identical skill descriptions — the agent can't tell them
+      apart, so the wrong one fires  (e.g. "agent-coder" ↔ "agent-tester", 83% alike)
 ```
 
-A subagent whose YAML doesn't parse, and six review agents holding far more power than
-a reviewer needs — real findings on a first-party plugin. _(We name Anthropic's own;
-the community plugins above stay anonymous — punch up, don't shame volunteers.)_
+One popular plugin ships **45 pairs of skills** with near-identical descriptions. The
+agent picks which skill to run by reading those descriptions, so when two match it
+fires the wrong one. The markdown is perfectly valid.
+**[How triggering works →](docs/measuring-skills.md)**
 
-## Proof 4 — rank a whole marketplace
-
-`audit` ranks a folder of plugins by what's actually **broken** — no key. Run across
-**all of Anthropic's official plugins**, it flags exactly **one** real outlier — no
-false-positive noise (untested surfaces are advisory):
+## Proof 3 — a tool your subagent silently can't call
 
 ```text
-  #   score  grade  plugin
-   1  100    A      code-review            ← 24 of 25 come back a clean A
-  25   70    C      pr-review-toolkit  — 6 agents inherit all tools (a reviewer with Write + Bash)
+✗ tester — Tool "AskUserQuestion" is never available to a subagent.
+    → remove or correct it — it's silently dropped from the contract.
 ```
 
-<sub>Real scores on Anthropic's own marketplace — a fair tool flags the one real issue, not noise (empty LSP stubs excluded).</sub>
+This subagent — a helper your main agent hands a task to — declares a tool that
+doesn't exist. The harness drops it silently, so the agent loses a capability it
+thinks it has. vigiles catches it and gives you the **one-line fix**.
 
-**[Plugin-author guide →](docs/for-plugin-authors.md)**
+That's the whole idea — it checks your harness against reality, not style. Every path,
+script, code symbol, and linter rule, verified to exist _and_ be enabled across 7
+catalogs (ESLint, Ruff, Clippy + four more).
+**[Full guide →](docs/verifying-instruction-files.md)**
 
-> **And it grades itself: 100/100, A, all four rings green.** vigiles runs `audit` on
-> its own harness in CI. We eat what we cook.
+All three catches are free and need no model — and vigiles **prevents** other whole
+classes of bug by construction (a typed spec or compiled hook just won't compile).
+**[Everything it catches and prevents →](docs/what-vigiles-catches.md)** · point `audit`
+at a whole marketplace and it ranks every plugin the same way.
+**[Audit a marketplace →](docs/for-plugin-authors.md)**
 
-## How it does it — three instruments
+## How it works
 
-`Agent = Model + Harness`[^name]. The model gets the headlines; the **harness** is the
-half you own. `audit` is the dashboard — these fix and prove what it finds.
+The model isn't yours to fix. Your harness is. `audit` shows you the problems — here's
+what fixes and proves each one, almost all of it with no model and no key.
 
 ### 🔎 Lint — your CLAUDE.md stops lying
 
-Every path, script, symbol & linter rule resolved against reality (the catches
-above). **You don't write any of it** — `npx vigiles init` **adopts your existing
-CLAUDE.md _and every skill and subagent_ into verified specs**, non-destructively
-(untouched until you `compile`; `eject` reverses). After that, plain-English asks
-edit them for you. Prefer zero new files? Plain markdown + one inline
-`<!-- vigiles:enforce -->` comment lints too — no TypeScript.
+Every path, script, symbol, and rule verified against reality — the catches above.
+You don't write the checks: `npx vigiles init` turns your CLAUDE.md, skills, and
+subagents into _specs_ (same content, plus a layer vigiles can verify). Non-destructive,
+edited by your agent in plain English, undone by `eject`.
 **[How →](docs/verifying-instruction-files.md)**
 
 ### 🧪 Test — does the harness actually do its job?
 
-A hook that blocks nothing, a skill that hijacks unrelated prompts, injected context
-that never reaches the model — all pass a naive "did it run?" check. Start at the
-cheapest tier: a hook, called directly. **No model, no key:**
-
-```typescript
-import { runHook } from "vigiles/testing";
-
-const r = runHook(guard, {
-  hook_event_name: "PreToolUse",
-  tool_name: "Bash",
-  tool_input: { command: "git commit --no-verify" },
-});
-assert(r.blocked); // a red ✗ means your guard silently lets it through
-```
-
-Hooks **block** · skills **trigger** (recall _and_ precision) · subagents **finish**
-in the outcome they promised (no LLM judge) · **safety holds** — `interceptTools`
-catches a push or paid-API call as an _attempt_, so the side effect never happens.
-Almost every tier runs with **no model and no key**, on every commit.
+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. vigiles tests the real
+thing: hooks **block**, skills **fire**, subagents **finish what they promised**, and a
+stray `git push` is caught before it happens. No model, no key, on every commit.
 **[How testing works →](docs/harness-testing.md)**
 
 ### 📊 Eval — does a skill help, or just cost more?
 
-_"65% fewer tokens." Says who?_ vigiles A/Bs the claim on real coding tasks and reports
-the **bill**, the **target it claims to move**, and the **blast radius** (did the code
-still work?).
-
-**The eval you can actually afford:** promptfoo / DeepEval hit a metered API and bill
-**per token, every run**. vigiles answers most questions with **no model at all**, and
-runs the rest on your own **Claude Pro/Max subscription — $0 extra.**
-**[Measure a skill →](docs/measuring-skills.md)**
+_"65% fewer tokens." Says who?_ vigiles[^name] A/Bs the claim on real coding tasks and reports
+the token bill, whether it hit its target, and whether the code still works. promptfoo
+and DeepEval bill **per token, every run**; vigiles runs on your own Claude Pro/Max
+subscription. **[Measure a skill →](docs/measuring-skills.md)**
 
 ## Quick start
 
-**Paste into Claude Code or Codex:**
+**1. See what's broken** — read-only, no setup:
+
+```bash
+npx vigiles audit
+```
+
+**2. Set it up** when you like what you see. Paste into Claude Code or Codex:
 
 ```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 install the dep, compile, and write + run one harness
-test for a hook or skill of mine. Don't enforce a spec-per-file or add a real-model
-eval without asking me first.
+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.
 ```
 
-Or do it yourself:
+Or run it yourself:
 
 ```bash
-npx vigiles init   # lint + test: spec + harness test + CI + plugin
+npx vigiles init   # adopts your files (non-destructive — eject reverses), adds CI,
+                   # installs the Claude Code plugin globally
 ```
 
 Interactive in a terminal, non-interactive for agents/CI (or `--yes`).
@@ -234,15 +249,14 @@ JS **or** TS (`*.harness.{mjs,ts}`) — run with `npx vigiles test`.
 ## FAQ
 
 - **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 into one). Prefer zero new files? Plain markdown lints too. Deeper compiler-grade guarantees are gradual and opt-in, like TS's `strict`.
-- **Does it overwrite my files?** No. `init` adopts an existing CLAUDE.md _non-destructively_ — untouched until you `compile`, and `eject` reverses it.
-- **Need an API key?** No for almost everything (free, every commit). Real-model evals run on your Claude Pro/Max subscription — $0 metered tokens.
+- **Do I have to write TypeScript?** No — your agent writes the spec (`init` adopts your CLAUDE.md into one), or plain markdown lints with zero new files. Compiler-grade guarantees are opt-in, like TS's `strict`.
 - **Non-JS repo?** `npx vigiles lint` verifies your CLAUDE.md with no install (Ruff/Clippy/Pylint/… too).
 
 **[Full FAQ →](docs/faq.md)**
 
 ## More
 
+- **[What vigiles catches and prevents →](docs/what-vigiles-catches.md)** — the full matrix of harness problems it handles, biggest first, marked prevent / catch / measure.
 - **[CLI →](docs/cli.md)** · **[GitHub Action →](docs/github-action.md)** · the full **[lint rules matrix →](docs/verifying-instruction-files.md#the-validation-rules--the-full-matrix)** lives with the linting guide.
 - **[Skills →](docs/skills.md)** — the skills `init` installs, and how the model-invocable ones trigger.
 - **[Ship plugins? The plugin-author guide →](docs/for-plugin-authors.md)** — scan a draft, make your skills fire, rank a whole marketplace — no key.

package/dist/adapters/claude-code/dialect.js

@@ -79,6 +79,21 @@ exports.claudeCodeDialect = {
         "SessionStart",
         "SessionEnd",
     ],
+    // Events where a block decision is silently ignored ENTIRELY — no veto AND no
+    // model feedback (exit 2 there writes stderr only to the user). These are the
+    // ONLY events hook-block-ineffective flags as wrong-event. PostToolUse is NOT
+    // here: its exit 2 feeds stderr back to the model (a legitimate nudge/feedback
+    // channel), so flagging it would cry wolf (e.g. vigiles's own refs-nudge.sh).
+    noEffectHookEvents: [
+        "SessionStart",
+        "SessionEnd",
+        "Notification",
+        "PreCompact",
+    ],
+    // PreToolUse is the one event whose deny needs the structured
+    // `hookSpecificOutput.permissionDecision:"deny"`; the legacy top-level
+    // `decision` field is ignored there.
+    permissionDecisionHookEvents: ["PreToolUse"],
     // Claude Code natively reads CLAUDE.md only — it does NOT auto-load AGENTS.md
     // (anthropics/claude-code#34235 is open; AGENTS.md works solely via an
     // `@AGENTS.md` import inside CLAUDE.md or a symlink). AGENTS.md is the

package/dist/audit-html.d.ts

@@ -5,16 +5,27 @@ import type { AuditReport } from "./audit-report.js";
  * we use `__dirname`, not `import.meta`.
  */
 export declare function templatePath(): string | null;
+/**
+ * Live-server info injected into the report when it's served by `audit --serve`
+ * (not a static file): the per-run token the report must send on every adopt
+ * POST. Absent for a plain static report — the buttons fall back to copy-command.
+ */
+export interface ServeInfo {
+    readonly token: string;
+}
 /**
  * Inject the report JSON into a template by replacing the quoted placeholder
  * string with the JSON object literal. Pure — the testable core. Throws if the
- * template is missing the placeholder.
+ * template is missing the placeholder. When `serve` is given (the `--serve`
+ * path), also sets `window.__VIGILES_SERVE__` so the report's adopt buttons POST
+ * to the local server instead of copying the command.
  */
-export declare function injectReportData(template: string, report: AuditReport): string;
+export declare function injectReportData(template: string, report: AuditReport, serve?: ServeInfo): string;
 /**
  * Render the self-contained HTML report (React template + injected data). Throws
  * if the template hasn't been built — the caller (writeAuditHtml) catches that and
- * skips the HTML, since the JSON + terminal report don't depend on it.
+ * skips the HTML, since the JSON + terminal report don't depend on it. Pass
+ * `serve` to render the live (`--serve`) variant whose buttons POST.
  */
-export declare function renderAuditHtml(report: AuditReport): string;
+export declare function renderAuditHtml(report: AuditReport, serve?: ServeInfo): string;
 //# sourceMappingURL=audit-html.d.ts.map

package/dist/audit-html.js

@@ -37,25 +37,34 @@ function escapeForScript(json) {
 /**
  * Inject the report JSON into a template by replacing the quoted placeholder
  * string with the JSON object literal. Pure — the testable core. Throws if the
- * template is missing the placeholder.
+ * template is missing the placeholder. When `serve` is given (the `--serve`
+ * path), also sets `window.__VIGILES_SERVE__` so the report's adopt buttons POST
+ * to the local server instead of copying the command.
  */
-function injectReportData(template, report) {
+function injectReportData(template, report, serve) {
     const re = new RegExp(`(["'])${PLACEHOLDER}\\1`);
     if (!re.test(template)) {
         throw new Error("audit report template is missing the data placeholder");
     }
-    return template.replace(re, escapeForScript(JSON.stringify(report)));
+    let out = template.replace(re, escapeForScript(JSON.stringify(report)));
+    if (serve) {
+        // Prepend the serve global onto the same statement that carries the data, so
+        // it's set before the app bundle reads it. The token is hex, but escape anyway.
+        out = out.replace("window.__VIGILES_DATA__", `window.__VIGILES_SERVE__=${escapeForScript(JSON.stringify(serve))};window.__VIGILES_DATA__`);
+    }
+    return out;
 }
 /**
  * Render the self-contained HTML report (React template + injected data). Throws
  * if the template hasn't been built — the caller (writeAuditHtml) catches that and
- * skips the HTML, since the JSON + terminal report don't depend on it.
+ * skips the HTML, since the JSON + terminal report don't depend on it. Pass
+ * `serve` to render the live (`--serve`) variant whose buttons POST.
  */
-function renderAuditHtml(report) {
+function renderAuditHtml(report, serve) {
     const p = templatePath();
     if (!p) {
         throw new Error("audit report template not built — run `npm run build` (builds report/), or use --json / --no-html");
     }
-    return injectReportData((0, node_fs_1.readFileSync)(p, "utf-8"), report);
+    return injectReportData((0, node_fs_1.readFileSync)(p, "utf-8"), report, serve);
 }
 //# sourceMappingURL=audit-html.js.map

package/dist/audit-report.d.ts

@@ -14,13 +14,22 @@
 import { type AuditScore } from "./audit-score.js";
 import { type Recommendation } from "./optimize.js";
 import type { AdoptabilityResult } from "./adoptability.js";
-import type { ScanReport } from "./scan.js";
+import type { ScanReport, MarketplaceInfo } from "./scan.js";
+import type { PluginScore } from "./leaderboard.js";
 /** The current schema version. Bump only on a BREAKING change to the shape. */
 export declare const AUDIT_SCHEMA_VERSION = 1;
 export interface AuditReportMeta {
     /** Wire-format version — consumers gate on this. */
     readonly schemaVersion: typeof AUDIT_SCHEMA_VERSION;
     readonly tool: "vigiles";
+    /**
+     * Discriminates the three `audit --json` shapes a consumer may receive:
+     * `audit` (one plugin → {@link AuditReport}), `leaderboard` (a marketplace /
+     * multiple dirs → {@link LeaderboardReport}), `marketplace` (a curated,
+     * all-external marketplace → {@link MarketplaceReport}). Always present so the
+     * JSON is self-describing.
+     */
+    readonly kind: "audit";
     /** The vigiles version that produced the report. */
     readonly vigilesVersion: string;
     /** The detected/selected harness (`claude-code`, `codex`, …). */
@@ -68,7 +77,7 @@ export interface Adoptable {
  */
 export interface AuditReport {
     readonly meta: AuditReportMeta;
-    /** The four deterministic category rings + the weighted overall + grade. */
+    /** The five deterministic category rings + the weighted overall + grade. */
     readonly score: AuditScore;
     /** The deterministic, ranked fixes (the inline recommendations). */
     readonly recommendations: readonly Recommendation[];
@@ -104,4 +113,51 @@ export interface BuildAuditReportOptions {
  * HTML-embedded form omits it so the rendered file stays deterministic.
  */
 export declare function buildAuditReport(report: ScanReport, opts: BuildAuditReportOptions): AuditReport;
+/**
+ * The versioned envelope for a `audit --json` run over MULTIPLE plugins (a
+ * marketplace expanded into its members, or several dirs) — the leaderboard.
+ * Shares the same `meta.schemaVersion`/`tool`/`kind` self-description as
+ * {@link AuditReport} so every `audit --json` shape is a versioned object, never
+ * a bare array. `kind:"leaderboard"` is the discriminant; `plugins` carries the
+ * ranked per-plugin scores.
+ */
+export interface LeaderboardReport {
+    readonly meta: {
+        readonly schemaVersion: typeof AUDIT_SCHEMA_VERSION;
+        readonly tool: "vigiles";
+        readonly kind: "leaderboard";
+        readonly vigilesVersion: string;
+        /** The marketplace / parent dir that was expanded and ranked. */
+        readonly dir: string;
+        readonly generatedAt?: string;
+    };
+    readonly plugins: readonly PluginScore[];
+}
+/** Assemble the versioned {@link LeaderboardReport} — pure, no clock. */
+export declare function buildLeaderboardReport(plugins: readonly PluginScore[], opts: {
+    vigilesVersion: string;
+    dir: string;
+}): LeaderboardReport;
+/**
+ * The versioned envelope for a `audit --json` run on a CURATED marketplace whose
+ * members are all external (git/url, nothing on disk to scan). Wraps the
+ * {@link MarketplaceInfo} inventory so this path, too, emits a versioned object
+ * rather than a raw, unversioned struct. `kind:"marketplace"` is the discriminant.
+ */
+export interface MarketplaceReport {
+    readonly meta: {
+        readonly schemaVersion: typeof AUDIT_SCHEMA_VERSION;
+        readonly tool: "vigiles";
+        readonly kind: "marketplace";
+        readonly vigilesVersion: string;
+        readonly dir: string;
+        readonly generatedAt?: string;
+    };
+    readonly marketplace: MarketplaceInfo;
+}
+/** Assemble the versioned {@link MarketplaceReport} — pure, no clock. */
+export declare function buildMarketplaceReport(marketplace: MarketplaceInfo, opts: {
+    vigilesVersion: string;
+    dir: string;
+}): MarketplaceReport;
 //# sourceMappingURL=audit-report.d.ts.map

package/dist/audit-report.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AUDIT_SCHEMA_VERSION = void 0;
 exports.buildAuditReport = buildAuditReport;
+exports.buildLeaderboardReport = buildLeaderboardReport;
+exports.buildMarketplaceReport = buildMarketplaceReport;
 /**
  * The `AuditReport` — the versioned JSON contract that IS the audit's product
  * boundary. Everything renders FROM it: the local self-contained HTML report,
@@ -49,6 +51,7 @@ function buildAuditReport(report, opts) {
         meta: {
             schemaVersion: exports.AUDIT_SCHEMA_VERSION,
             tool: "vigiles",
+            kind: "audit",
             vigilesVersion: opts.vigilesVersion,
             harness: opts.harness,
             dir: report.dir,
@@ -69,4 +72,30 @@ function buildAuditReport(report, opts) {
         ...(adoptable ? { adoptable } : {}),
     };
 }
+/** Assemble the versioned {@link LeaderboardReport} — pure, no clock. */
+function buildLeaderboardReport(plugins, opts) {
+    return {
+        meta: {
+            schemaVersion: exports.AUDIT_SCHEMA_VERSION,
+            tool: "vigiles",
+            kind: "leaderboard",
+            vigilesVersion: opts.vigilesVersion,
+            dir: opts.dir,
+        },
+        plugins,
+    };
+}
+/** Assemble the versioned {@link MarketplaceReport} — pure, no clock. */
+function buildMarketplaceReport(marketplace, opts) {
+    return {
+        meta: {
+            schemaVersion: exports.AUDIT_SCHEMA_VERSION,
+            tool: "vigiles",
+            kind: "marketplace",
+            vigilesVersion: opts.vigilesVersion,
+            dir: opts.dir,
+        },
+        marketplace,
+    };
+}
 //# sourceMappingURL=audit-report.js.map