vigiles 8.0.0 → 9.0.0

package/README.md

@@ -22,12 +22,14 @@
      caveat, or a competitor, never the user's pain. SAME FOR THE SUBDOCS: open
      every guide with the concrete pain, THEN the "what this doc is" line + the
      README uplink (per docs-quality in CLAUDE.md).
-  2. COMPILED SPECS ARE EASY — reassure, never intimidate. You rarely hand-write
-     a .spec.ts: model-invocable skills (edit-spec / strengthen / test-harness)
-     author + edit it, and hooks auto-compile on save. Present the typed spec as
-     the SMOOTH, AUTO-ENFORCED next step you don't think about — the natural
-     evolution (JS→TS: gradual, strict opt-in), NEVER a wall. Markdown + inline
-     mode work with zero TS for anyone not there yet (progressive adoption).
+  2. SPEC-FIRST IS THE DEFAULT — but easy, never intimidating. `init` adopts your
+     existing CLAUDE.md INTO a spec, and model-invocable skills (edit-spec /
+     strengthen / test-harness) author + edit it, so you rarely hand-write a
+     .spec.ts and hooks auto-compile on save. Present the typed spec as the default
+     the agent manages for you, NOT an advanced opt-in or a "step up". Inline
+     markdown is the ZERO-TS FLOOR for anyone who skips `init` (progressive
+     adoption) — the on-ramp, not the default starting point. `eject` always
+     reverses. NEVER a wall.
   3. THE INSTRUMENTS stay first-class — including Eval (measuring whether a skill
      actually helps is core, not optional). NOTE: Guard / compiled hooks is PARKED
      FOR LAUNCH (commented out below; see research/roadmap.md "Launch readiness") —
@@ -58,17 +60,41 @@
 ---
 
 **You installed a bunch of plugins and wrote a few skills — but do they actually work?**
-A skill that never fires, a safety hook that blocks nothing, a CLAUDE.md full of dead
-references — your harness fails **silently**, and you find out mid-task.
+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.
 
 **It's a library with no tests.**
 
-`Agent = Model + Harness` — the model gets the headlines, the harness is the half you
-own. vigiles[^name] makes it prove itself **before the agent ever runs** — verify, test,
-measure. Mostly free, no API key — real-model checks run on your **Claude Pro/Max
-subscription, not metered tokens**.
+**One command shows you — like a Lighthouse report for your harness:**
+
+```bash
+npx vigiles audit          # no key, no config, safe to run anywhere
+```
+
+It **reads** your harness deterministically — every reference checked, four categories
+scored, each finding's fix inline — and writes a shareable HTML report:
 
-Three instruments, adopt any:
+<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" />
+</p>
+
+| Ring                | What it proves                                                        |
+| ------------------- | --------------------------------------------------------------------- |
+| **🔎 Truthfulness** | Every path / script / symbol / linter rule in your CLAUDE.md resolves |
+| **🎯 Triggering**   | Skills fire on the right prompts and don't collide                    |
+| **🔧 Structure**    | Tool contracts, MCP servers & frontmatter are sound                   |
+| **🧪 Tested**       | Every surface ships a test                                            |
+
+Like Lighthouse, `audit` is a **local report you run on your machine** — a
+deterministic read, safe on any repo (even one wired to prod), identical on every
+OS. **Not a CI step** (CI uses `lint`, the deterministic gate). The **executing
+checks** (resolve MCP live · **do your skills fire?** · **what would vigiles
+catch in your repo?**) run only when there's a human to consent: `audit` **asks
+once** at a terminal and remembers. **[Audit a harness →](docs/for-plugin-authors.md)**
+
+`Agent = Model + Harness` — the model gets the headlines, the harness is the half you
+own. vigiles[^name] is how you make it prove itself: `audit` is the dashboard, and
+**three instruments** fix and prove what it finds —
 
 |             |                                                                                                                                                 |
 | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -80,24 +106,17 @@ Three instruments, adopt any:
 | **🛡 Guard** | A safety hook that **can't silently fail open** — write a typed function, get a guard that blocks. **[→](docs/compiled-hooks.md)** |
 -->
 
-<p align="center">
-  <img src="vigiles-demo.gif" width="720" alt="vigiles lint catching a file that moved and a script that was renamed" />
-</p>
-<!-- Regenerate the GIF: `python3 scripts/make-demo-gif.py` (output is verbatim CLI; see scripts/demo.sh for a live asciinema recording). -->
-
 **Two ways in** — pick the pain that's yours:
 
-- **Run agents on your own repo?** Start with **Lint** below, or `npx vigiles init`.
-- **Ship plugins to a marketplace?** **[`vigiles scan`](docs/for-plugin-authors.md)**
-  ranks structural health with no key — see the **[plugin-author guide →](docs/for-plugin-authors.md)**.
+- **Run agents on your own repo?** `npx vigiles audit`, then `npx vigiles init`.
+- **Ship plugins to a marketplace?** `npx vigiles audit ./plugins/*/` ranks a whole
+  marketplace (0–100, A–F) — see the **[plugin-author guide →](docs/for-plugin-authors.md)**.
 
-**Your agent writes the spec — and you can always eject.** You rarely hand-write a
-`.spec.ts`: skills author it for you, **`init` adopts an existing CLAUDE.md
-non-destructively** (untouched until you compile), and plain markdown + inline
-`<!-- vigiles:enforce -->` comments work with zero TypeScript. **Claude Code and
-Codex** ([`vigiles/codex`](docs/harnesses.md)), or [your own
-harness](docs/authoring-an-adapter.md). _(New here? [the FAQ](docs/faq.md) covers the
-"do I write TypeScript / will it touch my files" questions.)_
+**Your agent writes the spec — and you can always eject.** Skills author the
+`.spec.ts` for you, **`init` adopts an existing CLAUDE.md non-destructively**
+(untouched until you compile), and plain markdown + inline `<!-- vigiles:enforce -->`
+comments work with zero TypeScript. Works with **Claude Code and Codex**
+([`vigiles/codex`](docs/harnesses.md)) or [your own harness](docs/authoring-an-adapter.md).
 
 ## Quick start
 
@@ -156,12 +175,18 @@ CLAUDE.md:
   ✓ @typescript-eslint/no-floating-promises — exists and enabled in eslint config
 ```
 
+<p align="center">
+  <img src="vigiles-demo.gif" width="720" alt="vigiles lint catching a file that moved and a script that was renamed" />
+</p>
+<!-- Regenerate the GIF: `python3 scripts/make-demo-gif.py` (output is verbatim CLI; see scripts/demo.sh for a live asciinema recording). -->
+
 File paths, scripts, code symbols — plus linter rules across **7 linters**
 (ESLint, Ruff, Clippy + four more): each rule exists **and is enabled**.
 
-**Start with one inline comment — no new files.** Step up to a typed `.spec.ts`
-(your agent writes it; it compiles to CLAUDE.md) when you want compiler-grade
-guarantees — and `vigiles eject` hands it back to plain markdown anytime.
+**Your agent writes the spec — `init` adopts your existing CLAUDE.md into one,
+faithfully and non-destructively.** Prefer zero new files? Plain markdown + one
+inline `<!-- vigiles:enforce -->` comment lints too — no spec, no TypeScript. And
+`vigiles eject` hands a spec back to markdown anytime.
 **[Full guide →](docs/verifying-instruction-files.md)**
 
 > **Want more? Bad states can stop compiling.** Opt in deeper and a broken
@@ -174,7 +199,9 @@ guarantees — and `vigiles eject` hands it back to plain markdown anytime.
 **You wired the hook — but does it actually block?** A skill's description can fail
 to trigger, or hijack unrelated prompts; injected context can silently never reach
 the model. All of it passes a naive "did it run?" check. vigiles tests the
-assembled harness for real:
+assembled harness for real.
+
+Start with the cheapest tier — a hook, called directly. No model, no key:
 
 ```typescript
 import { runHook } from "vigiles/testing";
@@ -191,18 +218,19 @@ It goes well past _"did it fire?"_:
 
 - **Hooks block** what they must — `runHook`, or the real agent CLI via `runHarnessTest`.
 - **Skills trigger** on the right prompts and stay quiet on the wrong ones — recall _and_ precision (`measureTriggerRate`).
+- **Subagents finish right** — assert a subagent ended in the success (or error) outcome it promised, with a plain check, no LLM judge (`assertAgentOk` / `assertAgentErr`).
 - **Behaviour is good** — score a skill's output, or A/B it on-vs-off for the real lift (`measure` / `runEval`, with significance testing).
 - **Safety holds** — the agent _didn't_ push to the wrong branch or hit a paid API; `interceptTools` catches the attempt so the side effect never happens.
 
 Almost every tier runs with **no model and no API key** — milliseconds, on every
-commit; only the real-model evals need a model, on your own `claude` CLI.
+commit; only the real-model tier needs a model, on your own `claude` CLI.
 **[How it works →](docs/harness-testing.md)**
 
 ## ③ Eval — does it actually help, or just cost more?
 
 **"65% fewer tokens." "3× faster." Says who?** A skill claims it, a plugin promises
 it — stars and vibes, **zero measurement**. vigiles A/Bs the claim on real coding
-tasks, the harness loaded exactly as it ships, and reports the **metric triple**:
+tasks, the harness loaded exactly as it ships, and reports **three numbers**:
 
 ```typescript
 import { measureArms } from "vigiles/testing";
@@ -268,7 +296,7 @@ default, not an unbypassable wall._
 ## 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. Lint your markdown with zero new files; when you want a spec, your agent writes it. It's gradual, like TS's `strict`.
+- **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. The deeper compiler-grade guarantees are the gradual, opt-in part — 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.
 - **Non-JS repo?** `npx vigiles lint` verifies your CLAUDE.md with no install (Ruff/Clippy/Pylint/… too).

package/dist/adoptability.d.ts

@@ -0,0 +1,55 @@
+import { type AgentRunner, type ModelOutputParser } from "./eval.js";
+/** A reference the model proposes as machine-verifiable. */
+export interface DraftedRef {
+    readonly kind: "enforce" | "file" | "cmd" | "dir";
+    readonly ref: string;
+}
+/** A drafted ref that failed verification — the value proof. */
+export interface BrokenRef {
+    readonly kind: DraftedRef["kind"];
+    readonly ref: string;
+    readonly issue: string;
+}
+export interface AdoptabilityResult {
+    /** Distinct verifiable references the model found (the surface a spec would protect). */
+    readonly total: number;
+    /** How many of those are broken in this repo right now. */
+    readonly broken: number;
+    readonly brokenRefs: readonly BrokenRef[];
+}
+/**
+ * Deterministic verdict over drafted refs — the "disposes" half. Dedupes
+ * (kind+ref), routes each to the real cross-ref/filesystem check, and counts the
+ * broken. Pure: a hallucinated rule resolves to broken, never trusted as a pass.
+ */
+export declare function verifyDraftedRefs(refs: readonly DraftedRef[], basePath: string): AdoptabilityResult;
+/**
+ * Tolerant parse of the model's draft output into `DraftedRef[]`. The model is
+ * asked for a bare JSON array, but tolerate prose-wrapped / fenced output by
+ * extracting the outermost `[...]`. Drops any entry with an unknown kind or a
+ * non-string ref (the verifier is the guard, but a malformed shape is just noise).
+ */
+export declare function parseDraftJson(text: string): DraftedRef[];
+/** Options for the real model draft (the one v8-ignored seam). */
+export interface DraftOptions {
+    readonly model?: string;
+    readonly cwd?: string;
+    readonly runner?: AgentRunner;
+    readonly parse?: ModelOutputParser;
+}
+/** Injectable drafter — the real one calls a model; tests pass a fake. */
+export type Drafter = (content: string) => Promise<DraftedRef[]>;
+export interface AdoptabilityTierOptions {
+    readonly instructionContent: string;
+    readonly basePath: string;
+    /** Injectable for tests; defaults to the real one-shot model draft. */
+    readonly draft?: Drafter;
+}
+/**
+ * Run the preview: draft refs from the instruction file (model), then verify them
+ * (deterministic). The composition root of "LLM proposes, deterministic disposes".
+ */
+export declare function runAdoptabilityTier(opts: AdoptabilityTierOptions): Promise<AdoptabilityResult>;
+/** Terminal section — the adoption invitation, not a graded ring. */
+export declare function formatAdoptability(r: AdoptabilityResult, instructionFile: string): string;
+//# sourceMappingURL=adoptability.d.ts.map

package/dist/adoptability.js

@@ -0,0 +1,196 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyDraftedRefs = verifyDraftedRefs;
+exports.parseDraftJson = parseDraftJson;
+exports.runAdoptabilityTier = runAdoptabilityTier;
+exports.formatAdoptability = formatAdoptability;
+/**
+ * Adoptability preview — "what would vigiles catch in YOUR repo?"
+ *
+ * The audit's adoption front door for a NON-adopter: instead of grading the hygiene
+ * of an already-adopted spec, it shows the concrete bugs a spec WOULD catch today.
+ *
+ * Architecture (research/adoption-gateway-preview.md): **LLM proposes, deterministic
+ * disposes.** A model DRAFTS the verifiable references in an instruction file (high
+ * recall, incl. prose intent a regex can't see — `draftRefs`); the deterministic
+ * cross-reference engine VERIFIES each one (`verifyDraftedRefs`, reusing
+ * `checkLinterRule` + the compile validators). The model never gets to assert a
+ * pass — only the verifier does — so the "M broken right now" number is trustworthy
+ * even though the extraction was probabilistic.
+ *
+ * The verifier + parser + formatter are pure and model-free (fully unit-tested); the
+ * single real model call (`defaultDraft`) is the only v8-ignored seam, injected so
+ * the orchestration is testable without a model.
+ */
+const linters_js_1 = require("./core/linters.js");
+const compile_js_1 = require("./core/compile.js");
+const hash_js_1 = require("./core/hash.js");
+const eval_js_1 = require("./eval.js");
+/** Verify ONE drafted ref against the real repo; null = resolves, else the breakage. */
+function verifyOne(r, basePath) {
+    switch (r.kind) {
+        case "enforce": {
+            const res = (0, linters_js_1.checkLinterRule)(r.ref, basePath);
+            if (!res.exists)
+                return {
+                    ...r,
+                    issue: res.error ?? `linter rule "${r.ref}" does not exist`,
+                };
+            if (res.enabled === "disabled")
+                return { ...r, issue: `rule "${r.ref}" exists but is not enabled` };
+            return null;
+        }
+        case "file": {
+            const e = (0, compile_js_1.validateFileRef)(r.ref, basePath);
+            return e ? { kind: r.kind, ref: r.ref, issue: e.message } : null;
+        }
+        case "cmd": {
+            const e = (0, compile_js_1.validateCommandRef)(r.ref, basePath);
+            return e ? { kind: r.kind, ref: r.ref, issue: e.message } : null;
+        }
+        case "dir": {
+            const e = (0, compile_js_1.validateDirRef)(r.ref, basePath);
+            return e ? { kind: r.kind, ref: r.ref, issue: e.message } : null;
+        }
+        default:
+            return (0, hash_js_1.assertNever)(r.kind);
+    }
+}
+/**
+ * Deterministic verdict over drafted refs — the "disposes" half. Dedupes
+ * (kind+ref), routes each to the real cross-ref/filesystem check, and counts the
+ * broken. Pure: a hallucinated rule resolves to broken, never trusted as a pass.
+ */
+function verifyDraftedRefs(refs, basePath) {
+    const seen = new Set();
+    const unique = [];
+    for (const r of refs) {
+        const key = `${r.kind}:${r.ref}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        unique.push(r);
+    }
+    const brokenRefs = unique
+        .map((r) => verifyOne(r, basePath))
+        .filter((b) => b !== null);
+    return { total: unique.length, broken: brokenRefs.length, brokenRefs };
+}
+const VALID_KINDS = new Set([
+    "enforce",
+    "file",
+    "cmd",
+    "dir",
+]);
+/**
+ * Tolerant parse of the model's draft output into `DraftedRef[]`. The model is
+ * asked for a bare JSON array, but tolerate prose-wrapped / fenced output by
+ * extracting the outermost `[...]`. Drops any entry with an unknown kind or a
+ * non-string ref (the verifier is the guard, but a malformed shape is just noise).
+ */
+function parseDraftJson(text) {
+    const raw = extractJsonArray(text);
+    if (raw === null)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const out = [];
+    for (const item of parsed) {
+        if (typeof item !== "object" || item === null)
+            continue;
+        const rec = item;
+        const kind = rec.kind;
+        const ref = rec.ref;
+        if (typeof kind === "string" &&
+            VALID_KINDS.has(kind) &&
+            typeof ref === "string" &&
+            ref.trim()) {
+            out.push({ kind: kind, ref: ref.trim() });
+        }
+    }
+    return out;
+}
+/** Pull the outermost `[...]` from a possibly prose/fence-wrapped string. */
+function extractJsonArray(text) {
+    const start = text.indexOf("[");
+    const end = text.lastIndexOf("]");
+    if (start === -1 || end === -1 || end < start)
+        return null;
+    return text.slice(start, end + 1);
+}
+/** The drafting prompt — reuse the strengthen/adopt-spec mapping intent. */
+function draftPrompt(content) {
+    return [
+        "You are evaluating whether a coding-agent instruction file's references can be",
+        "machine-verified. Read the instruction file and identify every reference to a",
+        "CONCRETE, VERIFIABLE artifact:",
+        '- a linter rule (kind "enforce", ref like "eslint/no-console" or',
+        '  "@typescript-eslint/no-floating-promises") — INCLUDING prose intent you can',
+        '  confidently map to a real rule (e.g. "always await promises" ->',
+        '  "@typescript-eslint/no-floating-promises", "no console.log" -> "eslint/no-console").',
+        '- a file path (kind "file", ref like "src/index.ts").',
+        '- an npm script (kind "cmd", ref like "npm run build" or "npm test").',
+        '- a directory (kind "dir", ref like "src/components").',
+        "",
+        'Output ONLY a JSON array of {"kind","ref"} objects — no markdown, no prose. If',
+        "none, output []. Do not invent references that aren't grounded in the text.",
+        "",
+        "Instruction file:",
+        "---",
+        content,
+        "---",
+    ].join("\n");
+}
+/* v8 ignore start — the single real model call; the orchestration is tested with a fake draft. */
+/** The "proposes" half: one model call drafting the verifiable refs from prose. */
+async function defaultDraft(content, opts = {}) {
+    const runner = opts.runner ?? eval_js_1.spawnAgent;
+    const parse = opts.parse ?? eval_js_1.parseClaudeRun;
+    const out = await runner({
+        task: draftPrompt(content),
+        cwd: opts.cwd ?? process.cwd(),
+        model: opts.model ?? "sonnet",
+        tools: [], // the content is inline — no file tools needed (deterministic-ish)
+        hasSettings: false,
+        pluginDir: undefined,
+        timeoutMs: 120000,
+        env: process.env,
+    });
+    return parseDraftJson(parse(out).output);
+}
+/**
+ * Run the preview: draft refs from the instruction file (model), then verify them
+ * (deterministic). The composition root of "LLM proposes, deterministic disposes".
+ */
+async function runAdoptabilityTier(opts) {
+    const draft = opts.draft ?? ((c) => defaultDraft(c));
+    const refs = await draft(opts.instructionContent);
+    return verifyDraftedRefs(refs, opts.basePath);
+}
+/** Terminal section — the adoption invitation, not a graded ring. */
+function formatAdoptability(r, instructionFile) {
+    const lines = ["Adoptability — what vigiles would lock in"];
+    if (r.total === 0) {
+        lines.push(`  no machine-verifiable references found in ${instructionFile}.`);
+        return lines.join("\n");
+    }
+    lines.push(`  vigiles drafted a spec from ${instructionFile}: ${String(r.total)} verifiable reference(s) found`);
+    if (r.broken === 0) {
+        lines.push("  ✓ all resolve right now — adopt a spec to keep it that way.");
+        return lines.join("\n");
+    }
+    lines.push(`  ${String(r.broken)} broken right now:`);
+    for (const b of r.brokenRefs) {
+        lines.push(`    ✗ ${b.issue}`);
+    }
+    lines.push("  → run `vigiles init` to adopt the spec and catch these at edit time.");
+    return lines.join("\n");
+}
+//# sourceMappingURL=adoptability.js.map

package/dist/audit-html.d.ts

@@ -0,0 +1,20 @@
+import type { AuditReport } from "./audit-report.js";
+/**
+ * Candidate locations for the built template, relative to this module (`__dirname`
+ * is the compiled `dist/` at runtime, or `src/` under vitest). CommonJS output, so
+ * we use `__dirname`, not `import.meta`.
+ */
+export declare function templatePath(): string | null;
+/**
+ * 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.
+ */
+export declare function injectReportData(template: string, report: AuditReport): 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.
+ */
+export declare function renderAuditHtml(report: AuditReport): string;
+//# sourceMappingURL=audit-html.d.ts.map

package/dist/audit-html.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.templatePath = templatePath;
+exports.injectReportData = injectReportData;
+exports.renderAuditHtml = renderAuditHtml;
+/**
+ * The shareable HTML audit report — the prebuilt **Vite + React + shadcn** template
+ * (`report/`, built to one self-contained file at `dist/audit-report.template.html`)
+ * with the {@link AuditReport} JSON injected. The React app runs in the reader's
+ * browser, so the CLI stays runtime-dependency-light and the output is still a
+ * single offline file. There is ONE renderer (pure shadcn/Tailwind) — no inline-CSS
+ * fallback; the build guarantees the template exists, and if it somehow doesn't the
+ * caller skips the HTML (the JSON + terminal report still work).
+ *
+ * `<`/`>`/`&` are escaped on injection so report text can never break out of the
+ * `<script>`. `injectReportData` is the pure, testable core.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const PLACEHOLDER = "__VIGILES_DATA_PLACEHOLDER__";
+/**
+ * Candidate locations for the built template, relative to this module (`__dirname`
+ * is the compiled `dist/` at runtime, or `src/` under vitest). CommonJS output, so
+ * we use `__dirname`, not `import.meta`.
+ */
+function templatePath() {
+    const candidates = [
+        (0, node_path_1.resolve)(__dirname, "audit-report.template.html"), // dist/ (shipped)
+        (0, node_path_1.resolve)(__dirname, "..", "dist", "audit-report.template.html"), // src/ under vitest
+    ];
+    return candidates.find((p) => (0, node_fs_1.existsSync)(p)) ?? null;
+}
+/** Escape `<`, `>`, `&` so report text can never break out of the `<script>`. */
+function escapeForScript(json) {
+    return json.replace(/[<>&]/g, (ch) => "\\u00" + ch.charCodeAt(0).toString(16).padStart(2, "0"));
+}
+/**
+ * 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.
+ */
+function injectReportData(template, report) {
+    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)));
+}
+/**
+ * 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.
+ */
+function renderAuditHtml(report) {
+    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);
+}
+//# sourceMappingURL=audit-html.js.map

package/dist/audit-prompts.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Auto-generated trigger probes for `vigiles audit`'s model trigger tier.
+ *
+ * The trigger-rate eval needs a per-skill prompt set (does the description FIRE?
+ * — recall + precision). Authoring that set by hand was the friction that made
+ * the eval un-wowable. The trigger tier removes it: derive a small, DIVERSE probe
+ * set from each skill's own description — zero setup. `--prompts=<file>` still
+ * overrides for a rigorous, curated benchmark.
+ *
+ * Deterministic by design (no model needed to AUTHOR the probes — the model is
+ * spent RUNNING them). The trick that clears the diversity gate: extract a SHORT
+ * topic from the description (so the shared text stays small relative to the
+ * frame) and wrap it in lexically-distant frames. Measured min pairwise NCD
+ * ~0.27 across short/long descriptions — comfortably above {@link AUTO_MIN_DISTANCE}.
+ */
+import type { TriggerPromptSet } from "./scan-behavioral.js";
+export interface PromptSkill {
+    readonly name: string;
+    readonly description: string;
+}
+/** How many recall probes we generate per skill (each a distinct frame). */
+export declare const AUTO_RECALL_COUNT = 6;
+/**
+ * The diversity floor for AUTO probes — relaxed from the default 0.3 because a
+ * templated-but-varied machine probe legitimately shares a topic phrase (the
+ * generator's measured min is ~0.27). Still well above 0 → genuine copy-paste
+ * is caught; the gate's "vary the phrasing" advice is for hand-authored sets.
+ */
+export declare const AUTO_MIN_DISTANCE = 0.2;
+/**
+ * Extract a short, action-shaped topic from a description: drop boilerplate
+ * lead-ins ("A skill that…", "Use this skill to…"), take the first clause, cap
+ * at 8 words. Capping is load-bearing — a long verbatim topic makes the frames
+ * too similar (NCD collapses below the gate).
+ */
+export declare function topicOf(description: string): string;
+/** Recall probes for one skill: distinct frames around its extracted topic. */
+export declare function recallPrompts(description: string, count?: number): string[];
+/**
+ * Build a {@link TriggerPromptSet} from skill descriptions — zero-setup trigger
+ * probes. Each skill gets `recallPrompts` derived from its description plus the
+ * shared irrelevant bank for precision. Skills with an empty description are
+ * skipped (nothing to derive a topic from).
+ */
+export declare function autoTriggerPrompts(skills: readonly PromptSkill[], count?: number): TriggerPromptSet;
+//# sourceMappingURL=audit-prompts.d.ts.map

package/dist/audit-prompts.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTO_MIN_DISTANCE = exports.AUTO_RECALL_COUNT = void 0;
+exports.topicOf = topicOf;
+exports.recallPrompts = recallPrompts;
+exports.autoTriggerPrompts = autoTriggerPrompts;
+/** How many recall probes we generate per skill (each a distinct frame). */
+exports.AUTO_RECALL_COUNT = 6;
+/**
+ * The diversity floor for AUTO probes — relaxed from the default 0.3 because a
+ * templated-but-varied machine probe legitimately shares a topic phrase (the
+ * generator's measured min is ~0.27). Still well above 0 → genuine copy-paste
+ * is caught; the gate's "vary the phrasing" advice is for hand-authored sets.
+ */
+exports.AUTO_MIN_DISTANCE = 0.2;
+// Lexically-distant frames around a short topic. Order matters: the first N are
+// used, and they're arranged so any prefix stays diverse (verified in the test).
+const RECALL_FRAMES = [
+    (t) => `I need help to ${t} in my project right now.`,
+    (t) => `How do I ${t}? Walk me through the steps.`,
+    (t) => `Please ${t} before I open this pull request.`,
+    (t) => `What's the recommended way to ${t} on a large team?`,
+    (t) => `Can you take a look and ${t} for me?`,
+    (t) => `My task today: ${t} across the whole repo.`,
+    (t) => `Is there a tool that will ${t} automatically?`,
+    (t) => `Give me a checklist to ${t} thoroughly.`,
+];
+// Unrelated requests for the precision arm — varied, clearly off-topic, so a
+// well-scoped skill should NOT fire on them (a too-broad description that hijacks
+// these fails precision). Generic on purpose, distant from any one skill's topic.
+// Count is load-bearing: the auto trigger tier applies the diversity gate's
+// `minPrompts` floor (= AUTO_RECALL_COUNT) to BOTH arms, so the bank must hold at
+// least AUTO_RECALL_COUNT entries or the precision arm fails preflight and every
+// skill reports "unmeasured" instead of running.
+const IRRELEVANT_BANK = [
+    "What's the weather forecast for Tokyo this weekend?",
+    "Summarize the plot of Hamlet in two sentences.",
+    "Convert 100 US dollars to euros at today's rate.",
+    "Recommend a good pasta recipe for dinner tonight.",
+    "Who won the most Olympic gold medals in swimming?",
+    "Explain how photosynthesis works in plants.",
+    "Suggest a weekend hiking trail near Seattle.",
+];
+// Boilerplate lead-in words that carry no topical signal (skill descriptions
+// open with a verb — "Reviews…", "Generate…" — so stripping these from the front
+// never eats the real action). Applied iteratively until a content word remains.
+const LEAD_WORD = /^(a|an|the|this|use|skill|agent|tool|command|helper|that|which|to|for|when|invoked?|invoke|used?|helps?|you|with)\b[\s,:-]*/i;
+/**
+ * Extract a short, action-shaped topic from a description: drop boilerplate
+ * lead-ins ("A skill that…", "Use this skill to…"), take the first clause, cap
+ * at 8 words. Capping is load-bearing — a long verbatim topic makes the frames
+ * too similar (NCD collapses below the gate).
+ */
+function topicOf(description) {
+    let t = description.trim().toLowerCase();
+    let prev = "";
+    while (t !== prev) {
+        prev = t;
+        t = t.replace(LEAD_WORD, "");
+    }
+    const firstClause = t.split(/[.,;:!?]/)[0].trim();
+    const words = firstClause.split(/\s+/).filter(Boolean).slice(0, 8);
+    const topic = words.join(" ");
+    // Fall back to the raw (capped, lowercased) description if stripping left nothing.
+    return (topic || description.trim().toLowerCase().split(/\s+/).slice(0, 8).join(" "));
+}
+/** Recall probes for one skill: distinct frames around its extracted topic. */
+function recallPrompts(description, count = exports.AUTO_RECALL_COUNT) {
+    const topic = topicOf(description);
+    return RECALL_FRAMES.slice(0, count).map((frame) => frame(topic));
+}
+/**
+ * Build a {@link TriggerPromptSet} from skill descriptions — zero-setup trigger
+ * probes. Each skill gets `recallPrompts` derived from its description plus the
+ * shared irrelevant bank for precision. Skills with an empty description are
+ * skipped (nothing to derive a topic from).
+ */
+function autoTriggerPrompts(skills, count = exports.AUTO_RECALL_COUNT) {
+    const set = {};
+    for (const s of skills) {
+        if (!s.description.trim())
+            continue;
+        set[s.name] = {
+            prompts: recallPrompts(s.description, count),
+            irrelevant: [...IRRELEVANT_BANK],
+        };
+    }
+    return set;
+}
+//# sourceMappingURL=audit-prompts.js.map