vigiles 7.0.0 → 9.0.0

package/README.md

@@ -1,3 +1,46 @@
+<!--
+  README DIRECTION — read before editing; keep changes aligned.
+  This file is the FRONT DOOR + a marketing asset for someone who already lives
+  in Claude Code / Codex. Optimize for a phone-skimmer.
+
+  1. LEAD WITH BENEFITS, not mechanics or vocabulary. Say what the user GETS
+     (a guard that can't silently fail; a CLAUDE.md that stops lying) before how.
+  1b. NEVER OPEN WITH A NEGATIVE, APOLOGY, OR CAVEAT. A bolded lead-in is the
+     FIRST thing a skimmer reads, so it must be the benefit/on-ramp, never a
+     deficiency or competitor: write "Start in plain markdown", NOT "No
+     TypeScript?". Put the STRONGEST proof (e.g. 2/7→7/7) on its OWN line, never
+     buried mid-paragraph, and END a section on the win, not the caveat (demote
+     trade-offs to a trailing aside). Break run-on em-dash/semicolon chains — a
+     paragraph is ≤ ~3 lines, one idea.
+  1c. LEAD WITH THE CONCRETE PAIN the reader already feels — named in THEIR
+     situation, with the SPECIFIC silent failure, not an abstraction. "You
+     installed plugins and wrote skills — but do they actually work? A skill that
+     never fires, a hook that blocks nothing, a CLAUDE.md full of dead refs" beats
+     "reliability for your harness"; "a library with no tests" is the anchoring
+     analogy. This is NOT a 1b violation: a pain about the READER's situation is a
+     hook, not an apology — 1b bans opening with vigiles's OWN deficiency, a
+     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. 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") —
+     so the live set is Lint/Test/Eval ("three instruments"); re-add Guard post-HN.
+  4. SCANNABLE + SHORT — ~200-line cap; punchy table cells, bullets, runnable
+     blocks; benefits over jargon. Push depth into docs/ and LINK it.
+  5. NO INTERNAL VOCABULARY (moat / measurement-authority / flywheel) and NO
+     research/ links — name the user benefit (see public-vs-internal-docs +
+     readme-brevity in CLAUDE.md).
+-->
+
 <p align="center">
   <img src="logo.png" width="140" alt="vigiles logo" />
 </p>
@@ -8,10 +51,6 @@
   <strong>Make the harness your AI agent runs on reliable.</strong>
 </p>
 
-<p align="center">
-  Your CLAUDE.md, hooks, and skills steer the agent — but nothing checks they're <em>true</em>, nothing stops them entering a <em>bad state</em>, nothing tests they <em>work</em>, and nothing measures whether they actually <em>help</em>. vigiles does all four — deterministically, mostly with no API key.
-</p>
-
 <p align="center">
   <a href="https://www.npmjs.com/package/vigiles"><img src="https://img.shields.io/npm/v/vigiles?color=orange" alt="npm version" /></a>
   <a href="https://github.com/zernie/vigiles/actions"><img src="https://img.shields.io/github/actions/workflow/status/zernie/vigiles/ci.yml?branch=main" alt="CI" /></a>
@@ -20,47 +59,100 @@
 
 ---
 
-`Agent = Model + Harness`. The model gets the headlines; the **harness** — the
-instruction files, hooks, and skills you actually control — is the half that
-fails silently. vigiles[^name] turns that harness into a compilable, analyzable,
-testable object instead of vibes. Four instruments, adopt any:
+**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.
+
+**It's a library with no tests.**
+
+**One command shows you — like a Lighthouse report for your harness:**
+
+```bash
+npx vigiles audit          # no key, no config, safe to run anywhere
+```
 
-|              |                                                                                                                                                                                                                                                                                           |
-| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **🔎 Lint**  | Every file path, script, code symbol, and linter rule your CLAUDE.md cites is checked against reality — a lint that asks _is this **true**_, not just _well-formed_ — so a renamed file or a disabled rule can't silently mislead the agent. **[→](docs/verifying-instruction-files.md)** |
-| **🛡 Guard** | Author a hook as a pure typed function and vigiles compiles it — making **whole classes of hook bugs unrepresentable** (the guard that silently doesn't block). **[→](docs/compiled-hooks.md)**                                                                                           |
-| **🧪 Test**  | Hooks, skills, and subagents are code. vigiles tests they _do their job_ — and almost all of it is **deterministic, no API key**; the real-model evals run on your **Claude subscription**, not metered tokens. **[→](docs/harness-testing.md)**                                          |
-| **📊 Eval**  | Does that skill or plugin actually help — or just add cost? **A/B it on real tasks** and read the bill + correctness, not the vendor's headline — the eval you can afford. The same engine ranks the hyped ecosystem: **what works vs hype**. **[→](docs/measuring-skills.md)**           |
+It **reads** your harness deterministically — every reference checked, four categories
+scored, each finding's fix inline — and writes a shareable HTML report:
 
-Pick the one that hurts today. **Works with Claude Code and Codex**
-([`vigiles/codex`](docs/harnesses.md)), and you can
-[teach it your own harness](docs/authoring-an-adapter.md).
+<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 —
+
+|             |                                                                                                                                                 |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| **🔎 Lint** | Your CLAUDE.md stops lying — every path, script, symbol & linter rule checked against **reality**. **[→](docs/verifying-instruction-files.md)** |
+| **🧪 Test** | Prove your hooks, skills & subagents do their job — **free, no API key**. **[→](docs/harness-testing.md)**                                      |
+| **📊 Eval** | Know if a skill helps or just costs — **A/B on real tasks**, on your own subscription. **[→](docs/measuring-skills.md)**                        |
+
+<!-- PARKED FOR LAUNCH — Guard / compiled hooks. Re-add this row + the ④ section below post-HN. See research/roadmap.md "Launch readiness".
+| **🛡 Guard** | A safety hook that **can't silently fail open** — write a typed function, get a guard that blocks. **[→](docs/compiled-hooks.md)** |
+-->
+
+**Two ways in** — pick the pain that's yours:
+
+- **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.** 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
 
 **Paste into Claude Code or Codex:**
 
 ```text
-Set up vigiles in this repo with good defaults (lint + test, non-interactive).
-Verify my CLAUDE.md / AGENTS.md references and show me what's stale, then write
-and run a harness test for one of my hooks or skills. Ask me first before gating
-it in CI, adding a real-model eval, or enforcing strictly (--strict).
+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.
 ```
 
+The same prompt works in Codex.
+
 Or do it yourself:
 
 ```bash
 npx vigiles init   # sets up lint + test: spec + harness test + CI + plugin
 ```
 
-Interactive in a terminal, non-interactive for agents/CI (or `--yes`). It installs
-a model-invocable **`test-harness` skill** too, so you can then tell your agent
-_"test my skills"_ and it writes the test.
+Interactive in a terminal, non-interactive for agents/CI (or `--yes`).
+
+**You don't hand-write any of this — your agent does.** `init` installs
+model-invocable skills, so a plain-English ask does the work (it edits the source
+and recompiles on save; you never touch it by hand):
+
+- _"test my skills"_ → scaffolds **and runs** a trigger/behaviour test (`test-harness`)
+- _"harden my rules"_ → upgrades prose guidance into enforced linter rules (`strengthen`)
+- _"add a rule to my CLAUDE.md"_ → edits the source and recompiles (`edit-spec`)
 
 <details>
 <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? `init` adopts it** into a spec faithfully and **non-destructively** — your file is left untouched until you choose to `compile` (and `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 (a composite over the same CLI) that posts a sticky PR comment + a `valid` output.
 
@@ -71,10 +163,10 @@ Prefer to write tests yourself? They can be JS **or** TS
 
 ## ① Lint — your CLAUDE.md lies to your agent
 
-Your CLAUDE.md points the agent at `src/auth/login.ts` and says to run `npm run
-check`. But the file moved six commits ago and the script was renamed — the agent
-trusts the stale claim and acts on fiction. `npx vigiles lint` resolves every
-reference against reality:
+**Your CLAUDE.md drifts the moment you refactor.** It points the agent at
+`src/auth/login.ts` and says run `npm run check` — but the file moved six commits
+ago and the script was renamed. The agent trusts the stale claim and acts on
+fiction. `npx vigiles lint` resolves every reference against reality:
 
 ```text
 CLAUDE.md:
@@ -83,57 +175,33 @@ CLAUDE.md:
   ✓ @typescript-eslint/no-floating-promises — exists and enabled in eslint config
 ```
 
-File paths, scripts, and code symbols — plus linter rules across **7 catalogs**
-(the rule exists **and is enabled**). Start with one inline comment, no new files;
-step up to a typed `.spec.ts` (compiled to CLAUDE.md) when you want it.
-**[Full guide →](docs/verifying-instruction-files.md)**
-
-> **Markdown is prose; a typed spec is a _program_.** Opt in and an agent that
-> leaks or hands off mismatched data is a **type error** — your multi-agent
-> pipeline won't compile if the handoffs don't line up. Others lint prose; vigiles
-> is a **compiler for harnesses**, graduated like `strict`. **[The moat →](research/typed-spec-moat.md)**
-
-**Same cross-reference, any plugin.** `npx vigiles scan` checks a plugin's
-_contracts_ — every subagent tool, `mcp__server__tool`, `mcp_tool` hook, hook
-event, and script path actually **exists and resolves**, not just parses (valid
-YAML ≠ a real tool). A **superset of `claude plugin validate`**, no key. **[Audit any plugin →](docs/cli.md#scan-dir)**
-
-## ② Guard — author a hook that can't be wrong
+<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). -->
 
-A safety hook is the one place that can _stop_ the agent before something
-irreversible — yet hand-written hooks fail silently (`exit 1` not `2`, the wrong
-JSON field, a `grep` that misses `cd x && git push -f`): they look like a guard
-and block nothing. Write the hook as a pure typed function instead — vigiles
-compiles the protocol for you:
+File paths, scripts, code symbols — plus linter rules across **7 linters**
+(ESLint, Ruff, Clippy + four more): each rule exists **and is enabled**.
 
-```typescript
-import { defineHook, tool, deny, allow } from "vigiles/hook";
+**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)**
 
-export default defineHook({
-  on: "PreToolUse",
-  match: tool("Bash"),
-  decide: (e) =>
-    e.command.runs("git push", { force: true })
-      ? deny("no force-push to a protected branch")
-      : allow(),
-});
-```
+> **Want more? Bad states can stop compiling.** Opt in deeper and a broken
+> hand-off between agents becomes a build error instead of a runtime surprise —
+> graduated like TypeScript's `strict`, on only when you want it.
+> **[How →](docs/compiled-hooks.md)**
 
-This **eliminates an entire class of bugs**: you never write the exit code / JSON
-field (false confidence), the matcher is **AST-backed** (catches the compound
-bypass a glob misses), the only import allowed is `vigiles/hook` (capability = API
-surface), and the artifact is **stamped** (a later hand-edit is refused). A real,
-widely-copied OSS safety hook blocks **2/7** of the disaster battery; the compiled
-rewrite blocks **7/7**. Honest about the cons: this fixes a hook's _logic_, not
-the harness's _delivery_ — a subagent's tool calls still bypass any PreToolUse
-hook ([#34692](https://github.com/anthropics/claude-code/issues/34692)), so it's a
-strong default, not an unbypassable wall. **[Compiled hooks — bug classes + trade-offs →](docs/compiled-hooks.md)**
+## ② Test — does your harness do its job?
 
-## ③ Test — does your harness do its job?
+**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.
 
-A hook can be wired wrong; a skill's description can fail to trigger — or hijack
-unrelated prompts; injected context can never reach the model. All of it passes a
-naive "did it run?" check. vigiles tests the assembled harness for real:
+Start with the cheapest tier — a hook, called directly. No model, no key:
 
 ```typescript
 import { runHook } from "vigiles/testing";
@@ -150,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?
+## ③ Eval — does it actually help, or just cost more?
 
-A skill claims "65% fewer tokens." A plugin promises "3× faster." 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**:
+**"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 **three numbers**:
 
 ```typescript
 import { measureArms } from "vigiles/testing";
@@ -178,20 +247,70 @@ const r = await measureArms({
 - **The target** — whatever the skill claims to move (output tokens, latency, tool calls), verified on its own terms.
 - **The blast radius** — correctness, a deterministic 1/0. A token win that breaks the code is **not a win**.
 
-The kicker: every run is **your own `claude` CLI on your Pro/Max subscription**,
-so you can measure on every change — and the same engine powers the **ecosystem
-benchmark** ("what works vs hype"). **[Eval a skill →](docs/measuring-skills.md)** · **[Why it's affordable →](docs/eval-architecture.md)**
+**Safe to repeat.** Each real-model run is sandboxed (ephemeral dir, egress blocked
+or allow-listed), and `interceptTools` catches an irreversible external — a push, a
+paid API — as an _attempt_, never running it. **[Safety, sandboxing & FAQ →](docs/safety.md)**
+
+**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**. So
+you can measure on every change. **[Eval a skill →](docs/measuring-skills.md)** · **[Why it's affordable →](docs/eval-architecture.md)**
+
+<!-- PARKED FOR LAUNCH — Guard / compiled hooks. Re-add this whole section (and the table row above) post-HN. See research/roadmap.md "Launch readiness".
+
+## ④ Guard — a safety hook that can't silently fail open
+
+**Your safety hook looks like it blocks — and doesn't.** A guard is your last stop
+before something irreversible, but a hand-written one **fails open** without telling
+you. _(Already write safety hooks? This is the power tool.)_ Write a pure typed
+function instead; vigiles emits the exit code, the JSON, and an AST-backed matcher:
+
+```typescript
+import { defineHook, tool, deny, allow } from "vigiles/hook";
+
+export default defineHook({
+  on: "PreToolUse",
+  match: tool("Bash"),
+  decide: (e) =>
+    e.command.runs("git push", { force: true })
+      ? deny("no force-push to a protected branch")
+      : allow(),
+});
+```
+
+**The proof:** a widely-copied OSS safety hook blocks **2/7** of the disaster
+battery. The compiled rewrite blocks **7/7** — measured, not asserted.
+
+You never hand-write the exit code or JSON field (the usual false confidence), the
+matcher is **AST-backed** (it catches the `cd x && git push -f` a glob misses), and
+the artifact is **stamped** so a later hand-edit is refused.
+
+_Scope: this fixes a hook's logic, not the harness's delivery — a subagent's tool
+calls still bypass any PreToolUse hook
+([#34692](https://github.com/anthropics/claude-code/issues/34692)), so it's a strong
+default, not an unbypassable wall._
+**[Compiled hooks — bug classes + trade-offs →](docs/compiled-hooks.md)**
+
+-->
+
+## 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. 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).
 
-**The eval you can actually afford.** promptfoo / DeepEval / … hit a metered API
-SDK and bill **per token, every run**; vigiles answers most questions with **no
-model at all** and runs the rest on **your Claude Pro/Max subscription — $0 extra**.
+**[Full FAQ →](docs/faq.md)**
 
 ## More
 
-- **[Plugin health leaderboard →](docs/cli.md#scan-dir)** — point `scan` at a marketplace (e.g. `wshobson/agents`) and it ranks every plugin by structural health (0–100, A–F), worst issues first — **no key**. Add `--trigger` for the model-gated column: do the skills actually fire?
-- **[CLI & GitHub Action →](docs/cli.md)** — every command (incl. compiled hooks via `compile`), the Action, and the plugin. 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)** — consumer skills installed as a Claude Code plugin. The model-invocable ones (`test-harness`, `strengthen`, `edit-spec`) fire on their own — ask _"test my skills"_ and the agent reaches for them.
-- **[Docs index →](docs/README.md)** · **[Research →](research/README.md)** · **[API reference →](https://zernie.github.io/vigiles/)** (generated) · **[Related tools →](docs/related-tools.md)** (ast-grep, Dependency Cruiser, Ruler, rulesync).
+- **[CLI →](docs/cli.md)** — every command and the plugin · **[GitHub Action →](docs/github-action.md)** — run it in CI. 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 for structural health, make your skills fire for users, then rank a whole marketplace (0–100, A–F, worst issues first) — **no key**.
+- **[Docs index →](docs/README.md)** · **[API reference →](https://zernie.github.io/vigiles/)** · **[Related tools →](docs/related-tools.md)** (ast-grep, Dependency Cruiser, Ruler, rulesync).
+- **[Stability →](STABILITY.md)** — 0.x: the CLI is stable; the library API is still evolving; experimental surfaces are marked.
+- **Not for you if** you want a model/capability benchmark or runtime guardrails in the request path — vigiles is build-/CI-time.
 - Companion to [Feedback Loop Is All You Need](https://zernie.com/blog/feedback-loop-is-all-you-need).
 
 ## License

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