vigiles 17.0.2 → 18.1.0

package/dist/adapters/claude-code/agent-result.js

@@ -39,8 +39,17 @@ function fieldMatches(value, type) {
             return typeof value === "boolean";
         case "string[]":
             return Array.isArray(value) && value.every((v) => typeof v === "string");
+        default:
+            // An enum, declared as a readonly tuple of the permitted literals.
+            return typeof value === "string" && type.includes(value);
     }
 }
+/** How a field type reads in a message to a human: `string`, or `"CUT" | "MERGE"`. */
+function typeName(type) {
+    return typeof type === "string"
+        ? type
+        : type.map((v) => JSON.stringify(v)).join(" | ");
+}
 /**
  * Validate a parsed object against a contract track; null when it conforms.
  *
@@ -54,7 +63,9 @@ function shapeError(obj, shape) {
         if (!(field in obj))
             return `missing field "${field}"`;
         if (!fieldMatches(obj[field], type)) {
-            return `field "${field}" should be ${type}`;
+            // `typeName`, not `type`: an enum interpolated raw renders as `CUT,MERGE,KEEP`,
+            // which reads like a value rather than a choice among values.
+            return `field "${field}" should be ${typeName(type)}`;
         }
     }
     return null;

package/dist/audit-score.js

@@ -303,12 +303,45 @@ function tested(r) {
             "your own test setup detected — vigiles-native skill coverage is optional",
         ]
         : findings;
+    // 🔴 COVERED BY PLACEMENT ALONE — the execution tier, finally said out loud.
+    //
+    // `colocated` evidence means a test file NAMED after the surface sits BESIDE it. That is
+    // a claim about the filesystem, and the provenance line already admits it ("this says the
+    // file EXISTS, not that it ran"). Nobody reads a provenance line. When `executed` is zero
+    // across the whole corpus, EVERY surface counted here rests on a filename, and the number
+    // above reads as health it has not earned.
+    //
+    // Measured in a real consumer 2026-08-18: 26 colocated, 0 executed — while its CI invoked
+    // exactly those harnesses in a job that never installed the `claude` CLI, so each one
+    // called `skip()` and the step reported success. Coverage looked fine the entire time.
+    //
+    // Deliberately NOT "your CI does not run these": that needs parsing CI config, and the
+    // grep-shaped version accuses a healthy repo, because real workflows invoke harnesses by
+    // GLOB and name no file. This says only what the run records say, so it cannot be wrong
+    // about a repo it has not looked at.
+    //
+    // ⚠️ KNOWN LIMIT, stated rather than hidden: the threshold is CORPUS-WIDE, so ONE recorded
+    // run anywhere silences it for every surface. That is what the data supports — the evidence
+    // this receives is an aggregate tally, not a per-surface verdict — and the same consumer
+    // demonstrates the cost: it read 0 executed / 26 colocated in the morning and 16 / 26 by
+    // evening, after which twenty-six surfaces resting on a filename would no longer be named.
+    // Sharpening this means carrying evidence per surface, which is a change to the producer,
+    // not to this sentence. Until then it catches the state that actually shipped (a corpus
+    // where the tier is entirely absent) and stays quiet the moment the tier exists at all.
+    const ev = r.coverageEvidence;
+    const placementOnly = ev && ev.executed === 0 && ev.colocated > 0
+        ? [
+            ...contextualized,
+            `${String(ev.colocated)} surface(s) counted as covered by PLACEMENT only — ` +
+                `no run on record ever exercised one`,
+        ]
+        : contextualized;
     return {
         key: "Tested",
         score,
         weight: 1,
         advisory: true,
-        findings: contextualized,
+        findings: placementOnly,
     };
 }
 /**

package/dist/cli.d.ts

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 /**
- * vigiles CLI — compile typed specs to instruction files.
+ * vigiles CLI — verify your agent harness is real, and prove it works.
  *
- * Commands:
- *   vigiles init            — scaffold a spec from scratch
- *   vigiles compile         — compile .spec.ts → .md with linter verification
- *   vigiles lint            — verify hashes, report coverage, detect duplicates
- *   vigiles generate types  — emit .d.ts with types from project state
+ * The verbs and their one-liners live in ONE place, `COMMAND_HELP` + `HELP_GROUPS`
+ * near the bottom of this file, and `--help` prints from that table. A second list
+ * here would be a copy that rots — this docblock WAS that copy: it named four
+ * commands and omitted `audit`, `test`, `eval` and `eject`, four of the eight, and
+ * `self-command-refs.test.ts` did not catch it because it guards against refs to
+ * REMOVED commands, not against a list that merely stops growing.
  */
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * vigiles CLI — compile typed specs to instruction files.
+ * vigiles CLI — verify your agent harness is real, and prove it works.
  *
- * Commands:
- *   vigiles init            — scaffold a spec from scratch
- *   vigiles compile         — compile .spec.ts → .md with linter verification
- *   vigiles lint            — verify hashes, report coverage, detect duplicates
- *   vigiles generate types  — emit .d.ts with types from project state
+ * The verbs and their one-liners live in ONE place, `COMMAND_HELP` + `HELP_GROUPS`
+ * near the bottom of this file, and `--help` prints from that table. A second list
+ * here would be a copy that rots — this docblock WAS that copy: it named four
+ * commands and omitted `audit`, `test`, `eval` and `eject`, four of the eight, and
+ * `self-command-refs.test.ts` did not catch it because it guards against refs to
+ * REMOVED commands, not against a list that merely stops growing.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 const node_fs_1 = require("node:fs");
@@ -4291,6 +4292,32 @@ async function handleRunScripts(kind, args, restArgs) {
         process.exit(1);
     }
     if (files.length === 0) {
+        // 🔴 ASKING FOR SOMETHING AND GETTING NOTHING IS A FAILURE; FINDING NOTHING IS NOT.
+        // The two cases were collapsed into one silent exit 0, and the collapse cost a real
+        // repository three days of green CI verifying zero files: a named step ran
+        // `vigiles test .claude/pipeline/skills.harness.mjs` after that file had been split
+        // into one-per-skill, printed "No **/*.harness.* files found" and passed, right next
+        // to a step that was red for the same root cause.
+        //
+        // They are different states. A POSITIONAL argument is a claim that something is there —
+        // when nothing matches it, the path is stale, the glob is wrong, or the run never
+        // reached its target, and every one of those is a defect. Bare discovery finding
+        // nothing is just an empty repository, which is a legitimate place to stand and must
+        // stay quiet.
+        //
+        // This is the default the field settled on: Jest and Vitest FAIL on no tests found and
+        // make you opt in with `--passWithNoTests`; pytest exits 5. `--min=0` remains the
+        // explicit opt-out here, so no new flag is introduced by this change.
+        // `minFlag`, not `minRequired`: 0 is both the DEFAULT and the explicit opt-out, so the
+        // VALUE cannot tell them apart — only the flag's presence can. (Caught by a control:
+        // the first version read `minRequired === 0` and made `--min=0` do nothing.)
+        if (restArgs.length > 0 && minFlag === undefined) {
+            console.error(`✗ vigiles ${kind}: ${String(restArgs.length)} target(s) given and NOTHING matched — ` +
+                `${restArgs.join(", ")}\n` +
+                `  Nothing ran. A stale path, a wrong glob, or a moved file all look like this.\n` +
+                `  If an empty match is expected here, say so with --min=0.`);
+            process.exit(1);
+        }
         console.log(`No ${defaultGlob} files found.`);
         return;
     }
@@ -4380,35 +4407,42 @@ function capabilitiesOfReport(report, dialect) {
 }
 const COMMAND_HELP = {
     init: {
-        usage: "  vigiles init [flags]           Setup project (--ci-only for the CI gate only; --lint, --test, --harness=, --strict, --report-only, --no-gha, --force)",
+        usage: "  vigiles init [flags]       Set up this repo — specs, plugin, and CI.",
     },
-    compile: { usage: "  vigiles compile [files...]     Compile .spec.ts → .md" },
+    compile: { usage: "  vigiles compile [files...] Compile .spec.ts → .md" },
     eject: {
-        usage: "  vigiles eject [file]           Un-manage a compiled file → plain hand-owned markdown (--keep-spec)",
+        usage: "  vigiles eject [file]       Hand a compiled file back as plain markdown.",
     },
     lint: {
-        usage: "  vigiles lint [files...]        Verify references, find gaps in instruction files",
+        usage: "  vigiles lint  [files...]   Gate it in CI. The same checks — but a finding fails the build.",
     },
     audit: {
-        usage: "  vigiles audit [dir...]          Lighthouse for your harness — a LOCAL report: rings + what's broken + fixes (a deterministic read; 2+ dirs → leaderboard)",
+        // "Reports everything, fails nothing" states always-exit-0 as the FEATURE it is. The line
+        // it replaces had to end with "NOT a CI step — use `vigiles lint` in CI", and a help text
+        // that must say what a command ISN'T is a description that failed. Deleting that sentence
+        // was the checkable success criterion for this rewrite.
+        usage: "  vigiles audit [dir...]     Grade it on your machine. Reports everything, fails nothing.",
         detail: [
-            "                                 writes vigiles-report.html + .json (auto-gitignored; --out=<dir> · --no-html/--no-json · --no-open · --json for machine output). NOT a CI step — use `vigiles lint` in CI.",
-            "                                 the executing checks (run your hooks · live MCP · do skills fire?) run only interactively — `audit` asks once (remembered); automation uses the vigiles testing API",
-            "                                 --serve opens a LIVE local report whose buttons create specs in one click (own repo only; loopback + token-guarded) · --no-serve to skip the prompt",
+            "  2+ dirs → a leaderboard. Writes vigiles-report.html + .json (auto-gitignored).",
+            "  The executing checks (run your hooks · live MCP · do skills fire?) run only",
+            "  interactively — audit asks once and remembers; automation uses the testing API.",
         ],
     },
     test: {
-        usage: "  vigiles test [files...]        Run *.harness.mjs deterministic harness tests",
+        // "Free, no API key" is the CONSEQUENCE; "deterministic" was the mechanism, and a reader
+        // deciding whether to put this in CI needs the cost, not the implementation.
+        usage: "  vigiles test  [files...]   Against a scripted stand-in model. Free, no API key — every commit.",
     },
     eval: {
-        usage: "  vigiles eval [files...]        Run *.eval.mjs real-model harness evals (--trials=N, --min=N, --no-skip)",
+        usage: "  vigiles eval  [files...]   Against a real model. Spends your subscription — on demand.",
         detail: [
-            "                                 --update records each named eval's result to a committed lock (run locally on your subscription)",
-            "                                 --check verifies committed eval results against current inputs WITHOUT a model — the CI staleness gate",
+            "  --update records each named eval's result to a committed lock (run it locally).",
+            "  --check verifies those committed results against current inputs with NO model —",
+            "  the CI-safe half.",
         ],
     },
     generate: {
-        usage: "  vigiles generate <kind>       Emit a dev-toolchain artifact: types (.d.ts) · schema (JSON Schema) · harness (harness.gen.ts)",
+        usage: "  vigiles generate <kind>    Emit a dev-toolchain artifact: types · schema · harness",
         detail: [
             "  vigiles generate <kind> --check  Verify the generated file is up to date",
         ],
@@ -4418,19 +4452,39 @@ const COMMAND_HELP = {
     },
 };
 /** Display order of the human-facing verbs in the banner's "Commands:" block. */
-const HELP_ORDER = [
-    "init",
-    "compile",
-    "eject",
-    "lint",
-    "audit",
-    "test",
-    "eval",
+/**
+ * The top-level help, as GROUPS. One table, so the printer cannot drift from the
+ * grouping and a new verb cannot quietly land outside both.
+ */
+const HELP_GROUPS = [
+    {
+        heading: "Set up and manage your specs:",
+        verbs: ["init", "compile", "eject"],
+    },
+    {
+        heading: "Check your harness (reads your files — nothing is executed):",
+        verbs: ["audit", "lint"],
+    },
+    {
+        heading: "Run your harness (drives it and watches what happens):",
+        verbs: ["test", "eval"],
+    },
 ];
-function printHelpEntry(v) {
+/**
+ * One command's line. `detail` is the per-flag prose and appears ONLY in
+ * `vigiles <verb> --help`, never in the top-level list.
+ *
+ * That split is the second half of this rewrite. `audit`'s entry used to carry four
+ * wrapped lines naming nine flags inline, and that single entry was most of the felt
+ * crowding in a CLI whose verb count (8) is the smallest of every comparable tool
+ * measured — vitest ships 8 verbs and 164 flags, cargo 48 verbs, git 166. None of them
+ * thinned their surface by removing verbs; they tiered the help. This does the same.
+ */
+function printHelpEntry(v, opts = {}) {
     console.log(COMMAND_HELP[v].usage);
-    for (const line of COMMAND_HELP[v].detail ?? [])
-        console.log(line);
+    if (opts.detail)
+        for (const line of COMMAND_HELP[v].detail ?? [])
+            console.log(line);
 }
 /**
  * The loud "there is nothing here to audit" block. Deliberately says WHAT was
@@ -4470,27 +4524,38 @@ function formatNothingToAudit(root, harness, market) {
 }
 /** `vigiles <verb> --help` — that verb's entry plus its complete flag list. */
 function printCommandHelp(command) {
-    printHelpEntry(command);
+    printHelpEntry(command, { detail: true });
     const flags = (0, cli_flag_check_js_1.knownFlagsFor)(command);
     console.log("");
     console.log(`Flags: ${[...flags].sort().join(" ")}`);
     console.log("(`vigiles --help` lists every command.)");
 }
+/**
+ * The top-level help, grouped. The grouping is load-bearing, not cosmetic: four verbs
+ * (`audit`, `lint`, `test`, `eval`) all read as "check my stuff", and a flat list left the
+ * reader to work out the difference from four independent sentences. The headings state the
+ * shared trait, which frees each verb's own line to state only what makes it different, so
+ * the four form a 2x2 that survives one pass:
+ *
+ *                    no consequence          has a consequence
+ *   read the files   audit (fails nothing)   lint (fails the build)
+ *   run the harness  test  (free)            eval (spends money)
+ */
 function printUsage(command) {
-    console.log("vigiles — compile typed specs to instruction files");
-    console.log("");
-    console.log("Commands:");
-    for (const v of HELP_ORDER)
-        printHelpEntry(v);
-    console.log("");
-    console.log("Examples:");
-    console.log("  vigiles init                 Auto-detect project, create specs, wire CI");
-    console.log("  vigiles compile              Compile all .spec.ts files");
-    console.log("  vigiles lint                 Verify references, hashes, coverage + suggestions");
+    console.log("vigiles — verify your agent harness is real, and prove it works");
     console.log("");
+    for (const g of HELP_GROUPS) {
+        console.log(g.heading);
+        for (const v of g.verbs)
+            printHelpEntry(v);
+        console.log("");
+    }
     console.log("Plumbing:");
     printHelpEntry("generate");
-    console.log("  vigiles --version             Print the version number");
+    console.log("  vigiles --version          Print the version number");
+    console.log("");
+    console.log("Flags live in `vigiles <command> --help`.");
+    console.log("New here? Start with `vigiles audit .`");
     if (command && command !== "--help") {
         console.log(`\nUnknown command: "${command}"`);
         process.exit(1);

package/dist/core/compile.js

@@ -899,7 +899,9 @@ function renderAgentSections(sections, basePath) {
 /** Render a result-contract track shape as a compact `{ "f": type, … }` line. */
 function renderShape(shape) {
     const fields = Object.entries(shape)
-        .map(([k, t]) => `"${k}": ${t}`)
+        // An enum renders as the choice itself — `"verdict": "CUT" | "MERGE" | "KEEP"` — so
+        // the fenced rail shows a worker the same permitted values the tool schema shows.
+        .map(([k, t]) => `"${k}": ${typeof t === "string" ? t : t.map((v) => JSON.stringify(v)).join(" | ")}`)
         .join(", ");
     return fields ? `{ ${fields} }` : "{}";
 }

package/dist/core/spec.d.ts

@@ -695,8 +695,22 @@ export type OkOf<T> = T extends TypedOutcome<infer Ok, Shape> ? Ok : Shape;
  * erased `Shape`, and the value is still a plain `AgentSpec` — backwards-compatible.
  */
 export declare function agent<const P extends AuthoredPurity | undefined = undefined, V extends ToolVocabulary = OpenToolVocabulary, Ok extends Shape = Shape, Err extends Shape = Shape>(spec: AgentSpecInput<P, V, Ok, Err>): TypedAgentSpec<Ok, Err>;
-/** The field types a result contract can declare (kept tiny + dependency-free). */
-export type OutputFieldType = "string" | "number" | "boolean" | "string[]";
+/**
+ * The field types a result contract can declare (kept tiny + dependency-free).
+ *
+ * The literal-array member is an ENUM: `["CUT", "MERGE", "KEEP"] as const` declares a
+ * field whose value must be one of those strings. It is the ONLY extension to this union,
+ * and it was added because a measured failure had no other cure: across 14 real payloads
+ * a `verdict: "string"` field held 3 mutually incomparable invented categories over 3
+ * runs, and vocabulary compliance was 3/19 — 16%. `string` cannot express "one of these",
+ * so nothing downstream could notice.
+ *
+ * Nothing RELATIONAL follows it — no `object[]`, no tuples, no per-element enums.
+ * Declaring one throws rather than rendering an unsatisfiable schema, because the body of
+ * a result is prose by decision: on those same 14 payloads, 23 scalar values carried
+ * every assertion anyone made while 80,981 characters of prose carried none.
+ */
+export type OutputFieldType = "string" | "number" | "boolean" | "string[]" | readonly [string, ...string[]];
 /** A field SHAPE — a record of field-name → field-type, kept in the TYPE so a
  *  typed pipeline can cross-reference one agent's `ok` against the next agent's
  *  `needs`. The erased runtime form is `Record<string, OutputFieldType>`. */

package/dist/experimental-emit.d.ts

@@ -68,8 +68,11 @@ export type EmitFieldSchema = {
     readonly items: {
         readonly type: "string";
     };
+} | {
+    readonly type: "string";
+    readonly enum: readonly string[];
 };
-/** The `track` discriminator's schema — the only enum this surface emits. */
+/** The `track` discriminator's schema — the enum this module owns, not the author's. */
 export interface EmitTrackSchema {
     readonly type: "string";
     readonly enum: readonly ["ok", "err"];

package/dist/experimental-emit.js

@@ -62,6 +62,11 @@ const agent_result_js_1 = require("./adapters/claude-code/agent-result.js");
 /** The default tool name, when `options.name` is not given. */
 const DEFAULT_EMIT_TOOL = "emit_result";
 function fieldSchema(type) {
+    // An enum reaches the model as a JSON-Schema `enum`, which is the whole point: the
+    // permitted values travel WITH the tool definition instead of living in prose the
+    // model may or may not have read.
+    if (typeof type !== "string")
+        return { type: "string", enum: [...type] };
     switch (type) {
         case "string":
             return { type: "string" };
@@ -189,8 +194,41 @@ function isEmitCall(observed, name) {
  */
 function experimental_parseEmitted(toolCalls, contract, options = {}) {
     const name = options.name ?? DEFAULT_EMIT_TOOL;
-    const calls = toolCalls.filter((c) => isEmitCall(c.name, name));
+    const all = toolCalls.filter((c) => isEmitCall(c.name, name));
+    // 🔴 A CALL THAT ERRORED IS NOT AN EMISSION, AND USED TO PARSE AS ONE.
+    //
+    // Measured 2026-08-19: a permission-denied call carrying a perfectly valid payload
+    // returned `{"kind":"ok", …}`, because this function filtered by NAME and never looked
+    // at `ToolCall.isError` — a field that has been on the type all along. The call never
+    // reached the server; the reader reported success. That is the exact shape of defect
+    // this channel exists to remove from the fenced rail, reproduced inside the channel.
+    //
+    // Denial is not hypothetical: it is what a wrong `allowedTools` spelling produces, and
+    // MCP tool names mangle per host (`mcp__plugin_<plugin>_<server>__emit_result` on Claude
+    // Code, two segments on Codex), so mis-spelling it is the likely case, not the exotic one.
+    //
+    // The errored calls get their OWN branch rather than being dropped or counted, because
+    // all three collapses lie in a different direction:
+    //   - counting them → this defect, success for a call nobody received;
+    //   - dropping them silently → "no tool call in the run", which sends the reader to the
+    //     skill's instructions when the fault is in permissions;
+    //   - lumping them with "called twice" → a model that retries a denied call produces a
+    //     true signal under a false name. (Observed: two denials in one run.)
+    // A successful call ALONGSIDE a denied one is one successful emission; the denial is
+    // mentioned, not fatal, because the contract was in fact satisfied.
+    // `isError` is a required boolean on ToolCall, so truthiness is exact here.
+    const errored = all.filter((c) => c.isError);
+    const calls = all.filter((c) => !c.isError);
     if (calls.length === 0) {
+        if (errored.length > 0) {
+            return {
+                kind: "malformed",
+                reason: `the \`${name}\` call itself errored or was denied ` +
+                    `(${String(errored.length)} attempt${errored.length === 1 ? "" : "s"}); nothing reached the ` +
+                    `server, so nothing was emitted. Check the tool's permissions and the exact spelling ` +
+                    `in \`allowedTools\` — MCP names are host-mangled.`,
+            };
+        }
         return { kind: "malformed", reason: `no \`${name}\` tool call in the run` };
     }
     if (calls.length > 1) {

package/dist/scaffold-test.js

@@ -118,6 +118,10 @@ assertTriggerRate(report, { min: 0.8, maxFalsePositive: 0.3 });
 }
 /** A JSON value placeholder for an `OutputFieldType`, for the `vigiles:ok` block. */
 function placeholderFor(type) {
+    // An enum's placeholder must be a MEMBER, or the scaffolded test fails the moment it
+    // is run — a generated test that cannot pass teaches the author to distrust the tool.
+    if (Array.isArray(type) && type.length > 0)
+        return type[0];
     switch (type) {
         case "number":
             return 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "17.0.2",
+  "version": "18.1.0",
   "description": "Audit, test and measure the harness your AI agent runs on — grade your CLAUDE.md / AGENTS.md, skills, subagents and hooks, run them against a scripted model, and measure whether they actually fire.",
   "keywords": [
     "claude-code",

package/skills/test-harness/SKILL.md

@@ -326,6 +326,20 @@ We do **not** show "% of your subscription" — Anthropic doesn't expose a plan'
 quota, so any percentage would be invented. Tokens + API-equivalent `$` + the
 billed-to line is the honest, complete picture. Keep the user's cost visible, always.
 
+## CI — don't hand-write the steps
+
+These tiers belong in CI, and there is a published Action for it. Run `vigiles init`: it
+writes `.github/workflows/vigiles.yml`, wiring the Action (`zernie/vigiles@v1`) for the jobs
+that can use it plus a plain `npx vigiles test` job for this tier — that one needs
+repo-local `node_modules`, which the Action does not install, so it stays hand-rolled on
+purpose.
+
+If the repo already has a workflow, the Action's inputs are documented in
+[docs/github-action.md](../../docs/github-action.md). Read them there rather than guessing:
+the input list is defined in `action.yml`, and a copy of it here would be a second source of
+truth that goes stale without anything noticing — which is exactly what happened to this
+file's own sibling docs and to a consumer's CI comment, both measured on 2026-08-18.
+
 ## Step 5 — Lock the eval so CI stays honest (you do this automatically)
 
 Real-model evals run on the user's subscription — locally, never in CI. So **as