vigiles 17.0.1 → 18.0.0

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,57 +4452,110 @@ 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
  * looked at and WHY it found nothing, because the commonest cause is that the
  * target isn't the directory the operator thinks it is.
+ *
+ * Two causes are named apart from the generic one, because they are the two the
+ * generic wording actively MISDESCRIBES:
+ *
+ *   - the path does not exist — "no surface was found there" reads as a verdict
+ *     on a real directory, so a typo'd dir in a multi-dir leaderboard run looked
+ *     like a legitimately empty repo. One `existsSync` separates them.
+ *   - the path is a CURATED marketplace — it has members, they are all external,
+ *     and the useful next step is to clone one. This advice used to live in a
+ *     branch that pre-empted the audit entirely (see the `audit` case); it
+ *     belongs here, where the directory has genuinely been looked at first.
  */
-function formatNothingToAudit(root, harness) {
-    return [
+function formatNothingToAudit(root, harness, market) {
+    if (!(0, node_fs_1.existsSync)(root)) {
+        return [
+            `✗ vigiles audit: ${root} does not exist`,
+            "  Nothing was scanned — this is NOT a grade, and NOT an empty repo.",
+            "  Check the path, and that a flag didn't swallow it",
+            "  (flags take values with `=`: `--out=dir`, never `--out dir`).",
+        ].join("\n");
+    }
+    const lines = [
         `✗ vigiles audit: nothing to audit in ${root}`,
         `  No instruction file and no ${harness} surface (skills / subagents / hooks / commands / MCP) was found there.`,
         "  This is NOT a grade — there was nothing to measure, so no score is reported.",
-        "  Check that the path is the repo you meant, and that a flag didn't swallow it",
-        "  (flags take values with `=`: `--out=dir`, never `--out dir`).",
-    ].join("\n");
+    ];
+    if (market && market.onDisk.length === 0 && market.total > 0) {
+        lines.push(`  It is the marketplace "${market.name}": ${String(market.total)} plugin(s), all external (url/git sources, not on disk).`, "  Clone a member plugin and scan that, or scan a marketplace that vendors its plugins in-tree.");
+    }
+    lines.push("  Check that the path is the repo you meant, and that a flag didn't swallow it", "  (flags take values with `=`: `--out=dir`, never `--out dir`).");
+    return lines.join("\n");
 }
 /** `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);
@@ -6151,26 +6238,36 @@ async function main() {
             // A single dir that's a marketplace (e.g. wshobson/agents' 80+ plugins
             // under one marketplace.json) expands into its members and ranks them.
             const market = dirs.length === 1 ? (0, scan_js_1.inspectMarketplace)((0, node_path_1.resolve)(dirs[0])) : null;
+            // A marketplace whose members are all EXTERNAL expands to nothing, and the
+            // fallback below already says what to do about that: the target is the
+            // directory itself.
+            //
+            // 🔴 THERE USED TO BE A BRANCH HERE that printed "nothing to scan" and
+            // returned at exit 0 whenever the expansion came back empty — before
+            // looking at the directory at all. A `marketplace.json` is a statement
+            // about OTHER directories; it says nothing about this one, and a directory
+            // is free to be a plugin AND ship a marketplace listing external members.
+            // Measured 2026-08-18 on `nyldn/claude-octopus` @ `57cfb9b0` (3,979 stars):
+            // the branch suppressed the whole audit — 59 skills, 50 subagents — because
+            // `.claude-plugin/` held a `marketplace.json` NEXT TO the `plugin.json`
+            // naming that same directory. It now grades D (60/100), and the check that
+            // this branch is really gone is that deleting the `marketplace.json` gives
+            // the byte-identical report: the file no longer changes the outcome at all.
+            //
+            // (An earlier journal recorded that delete-one-file experiment as B (85/100).
+            // That was measured before `agents/` was read recursively, when all 50 of
+            // this plugin's subagents lived in subdirectories and none were visible. Both
+            // numbers are real; they differ by the other fix, not by this one.)
+            //
+            // Exit 0 was the other half: a repo that was never scanned exited
+            // byte-identically to a repo that was scanned and found clean, so an
+            // automated leaderboard dropped it silently and CI went green. A genuinely
+            // curated marketplace now reaches the `score.empty` branch below, which
+            // carries `market` into its explanation and exits 2 — this repo's own rule
+            // that 1 is "I measured, and it's bad" and 2 is "I could not do what you
+            // asked". Nothing was measured here, so it is a 2.
             const targets = market && market.onDisk.length > 0 ? [...market.onDisk] : dirs;
-            if (market && market.onDisk.length === 0 && market.total > 0) {
-                // A CURATED marketplace — every member is an external git/url plugin, so
-                // there's nothing on disk to scan. Say so honestly instead of falling
-                // through to a misleading "empty machine / no structural issues" report
-                // (obra/superpowers-marketplace, anthropics/claude-plugins-community).
-                if (json) {
-                    console.log(JSON.stringify((0, audit_report_js_1.buildMarketplaceReport)(market, {
-                        vigilesVersion: getVersion(),
-                        dir: (0, node_path_1.resolve)(dirs[0]),
-                    }), null, 2));
-                }
-                else {
-                    console.log(`Marketplace "${market.name}": ${String(market.total)} plugin(s), all external ` +
-                        `(url/git sources, not on disk).\n` +
-                        `Nothing to scan here — clone a member plugin and scan that, or scan a ` +
-                        `marketplace that vendors its plugins in-tree.`);
-                }
-            }
-            else if (targets.length > 1) {
+            if (targets.length > 1) {
                 // Multiple targets → rank them (the leaderboard engine). `--md` emits the
                 // publishable Markdown table (a README / gist / the leaderboard site).
                 const scores = (0, leaderboard_js_1.rankPlugins)(targets);
@@ -6304,9 +6401,20 @@ async function main() {
                 // `score.empty: true`), so a machine consumer keeps its contract; the
                 // human-readable explanation goes to stderr either way.
                 if (sc.empty) {
+                    // A curated marketplace lands here now that the early return is gone:
+                    // it really has nothing of its own to audit, which is what this branch
+                    // is for. `--json` keeps emitting the `kind:"marketplace"` envelope for
+                    // exactly that case, so the discriminant still describes what it always
+                    // described — a marketplace with no on-disk members — and no longer
+                    // doubles as "a directory we declined to look at".
                     if (json)
-                        console.log(JSON.stringify(auditReportBase, null, 2));
-                    console.error(formatNothingToAudit(root, adapter.name));
+                        console.log(JSON.stringify(market && market.onDisk.length === 0 && market.total > 0
+                            ? (0, audit_report_js_1.buildMarketplaceReport)(market, {
+                                vigilesVersion: getVersion(),
+                                dir: root,
+                            })
+                            : auditReportBase, null, 2));
+                    console.error(formatNothingToAudit(root, adapter.name, market));
                     process.exit(2);
                 }
                 const plan = (0, optimize_js_1.optimize)(report);

package/dist/core/layout.d.ts

@@ -42,7 +42,12 @@ export interface PluginLayout {
     readonly userSurfaceRoot?: string;
     /** Skills dir, holding the nested `<dir>/<name>/SKILL.md`, e.g. `skills`. */
     readonly skillDir: string;
-    /** Subagents dir, holding flat `<dir>/<name>.md`, e.g. `agents` (`""` = none). */
+    /**
+     * Subagents dir, holding `<dir>/<name>.md` at ANY depth, e.g. `agents`
+     * (`""` = none). The depth rule, and the identifier that depth implies, are
+     * stated once in {@link AGENT_FILE_LEAF_RE} and {@link agentSurfaceName} —
+     * read those before writing a fourth thing that walks this dir.
+     */
     readonly agentDir: string;
     /** Slash-commands dir, holding flat `<dir>/<name>.md`, e.g. `commands`. */
     readonly commandDir: string;
@@ -70,4 +75,52 @@ export interface PluginLayout {
     /** Dirs scanned for dangling intra-plugin file references. */
     readonly intraRefDirs: readonly string[];
 }
+/**
+ * How DEEP a harness reads its {@link PluginLayout.agentDir} — the one statement
+ * of that rule, as a RegExp source fragment matching the part of a path AFTER
+ * `<agentDir>/`. Anchor-free on purpose, so each caller can bound it its own way
+ * (`(?:^|/)agents/` + this + `$` in the scan classifier; `^<prefix>/` + this +
+ * `$` in the coverage discoverers).
+ *
+ * 🔴 IT USED TO SAY `[^/]+`, in THREE independent places, and the vendor
+ * documents the opposite. Verbatim from `https://code.claude.com/docs/en/sub-agents`:
+ *
+ * > Claude Code scans `.claude/agents/` and `~/.claude/agents/` **recursively**,
+ * > so you can organize definitions into subfolders such as `agents/review/` or
+ * > `agents/research/`.
+ *
+ * > **Plugin `agents/` directories are also scanned recursively.** Unlike project
+ * > and user scopes, a subfolder inside a plugin's `agents/` directory becomes
+ * > part of the scoped identifier: a file at `agents/review/security.md` in
+ * > plugin `my-plugin` registers as `my-plugin:review:security`.
+ *
+ * Measured 2026-08-18 on `rsmdt/the-startup` @ `88d447c7`: 16 agent files under
+ * `plugins/team/agents/`, 2 read. The plugin was still GRADED — B (80/100) over
+ * 12.5% of its subagents — so the number was not merely incomplete, it was
+ * flattering. Twelve real malformed-frontmatter defects sat in the unread 87.5%.
+ *
+ * The three readers are the scan classifier (`makeClassifier`, scan-core.ts) and
+ * the two coverage discoverers (`test-coverage.ts`, `test-coverage-files.ts`).
+ * They disagreed silently because each spelled the rule itself; they now quote
+ * this. A fourth reader that hard-codes a depth is the defect coming back.
+ */
+export declare const AGENT_FILE_LEAF_RE = "(?:.+/)?[^/]+\\.md";
+/**
+ * A subagent's identity, per the same docs paragraph: the path under
+ * `<agentDir>/` with `/` → `:` and the `.md` dropped, so plugin
+ * `agents/review/security.md` is `review:security` (the scoped identifier minus
+ * its plugin prefix, which the scan of a single plugin dir does not know).
+ *
+ * 🔴 NOT COSMETIC — it is what keeps recursion from introducing a defect of its
+ * own. A basename cannot be unique once the dir is read recursively:
+ * `agents/a/review.md` and `agents/b/review.md` would both be "review", and the
+ * delegation graph keys agents BY NAME (`pathByName`, `delegatesTo`), so one
+ * would silently swallow the other's path and neither would delegate to its
+ * namesake. A path-derived name is unique by construction, so that collision has
+ * nowhere to live. Degenerates to today's basename for a top-level agent, which
+ * is why no existing report changes.
+ *
+ * Returns null when `path` holds no `<agentDir>/` segment (not an agent file).
+ */
+export declare function agentSurfaceName(path: string, agentDir: string): string | null;
 //# sourceMappingURL=layout.d.ts.map

package/dist/core/layout.js

@@ -1,3 +1,78 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_FILE_LEAF_RE = void 0;
+exports.agentSurfaceName = agentSurfaceName;
+/**
+ * How DEEP a harness reads its {@link PluginLayout.agentDir} — the one statement
+ * of that rule, as a RegExp source fragment matching the part of a path AFTER
+ * `<agentDir>/`. Anchor-free on purpose, so each caller can bound it its own way
+ * (`(?:^|/)agents/` + this + `$` in the scan classifier; `^<prefix>/` + this +
+ * `$` in the coverage discoverers).
+ *
+ * 🔴 IT USED TO SAY `[^/]+`, in THREE independent places, and the vendor
+ * documents the opposite. Verbatim from `https://code.claude.com/docs/en/sub-agents`:
+ *
+ * > Claude Code scans `.claude/agents/` and `~/.claude/agents/` **recursively**,
+ * > so you can organize definitions into subfolders such as `agents/review/` or
+ * > `agents/research/`.
+ *
+ * > **Plugin `agents/` directories are also scanned recursively.** Unlike project
+ * > and user scopes, a subfolder inside a plugin's `agents/` directory becomes
+ * > part of the scoped identifier: a file at `agents/review/security.md` in
+ * > plugin `my-plugin` registers as `my-plugin:review:security`.
+ *
+ * Measured 2026-08-18 on `rsmdt/the-startup` @ `88d447c7`: 16 agent files under
+ * `plugins/team/agents/`, 2 read. The plugin was still GRADED — B (80/100) over
+ * 12.5% of its subagents — so the number was not merely incomplete, it was
+ * flattering. Twelve real malformed-frontmatter defects sat in the unread 87.5%.
+ *
+ * The three readers are the scan classifier (`makeClassifier`, scan-core.ts) and
+ * the two coverage discoverers (`test-coverage.ts`, `test-coverage-files.ts`).
+ * They disagreed silently because each spelled the rule itself; they now quote
+ * this. A fourth reader that hard-codes a depth is the defect coming back.
+ */
+exports.AGENT_FILE_LEAF_RE = "(?:.+/)?[^/]+\\.md";
+/**
+ * A subagent's identity, per the same docs paragraph: the path under
+ * `<agentDir>/` with `/` → `:` and the `.md` dropped, so plugin
+ * `agents/review/security.md` is `review:security` (the scoped identifier minus
+ * its plugin prefix, which the scan of a single plugin dir does not know).
+ *
+ * 🔴 NOT COSMETIC — it is what keeps recursion from introducing a defect of its
+ * own. A basename cannot be unique once the dir is read recursively:
+ * `agents/a/review.md` and `agents/b/review.md` would both be "review", and the
+ * delegation graph keys agents BY NAME (`pathByName`, `delegatesTo`), so one
+ * would silently swallow the other's path and neither would delegate to its
+ * namesake. A path-derived name is unique by construction, so that collision has
+ * nowhere to live. Degenerates to today's basename for a top-level agent, which
+ * is why no existing report changes.
+ *
+ * Returns null when `path` holds no `<agentDir>/` segment (not an agent file).
+ */
+function agentSurfaceName(path, agentDir) {
+    if (!agentDir)
+        return null;
+    const marker = `${agentDir}/`;
+    // The FIRST occurrence sitting at a real path boundary — start-of-path or just
+    // after a `/`. Both halves matter and one of them is easy to get wrong:
+    // requiring the boundary stops `my-agents/x.md` being read as `agents/x.md`,
+    // and CONTINUING the search past a non-boundary hit is what keeps this
+    // agreeing with the classifier, whose `(?:^|/)agents/` skips the same way.
+    // Taking `indexOf` once and rejecting it would return null for
+    // `myagents/x/agents/y.md` — a path the classifier calls an agent — so the two
+    // would disagree about the very file they are both looking at.
+    let at = -1;
+    for (let i = path.indexOf(marker); i !== -1; i = path.indexOf(marker, i + 1)) {
+        if (i === 0 || path[i - 1] === "/") {
+            at = i;
+            break;
+        }
+    }
+    if (at === -1)
+        return null;
+    const tail = path.slice(at + marker.length);
+    if (tail === "" || !tail.endsWith(".md"))
+        return null;
+    return tail.slice(0, -".md".length).split("/").join(":");
+}
 //# sourceMappingURL=layout.js.map

package/dist/scan-core.d.ts

@@ -2,7 +2,7 @@ import type { HookEventIssue } from "./core/hook-events.js";
 import { type DescriptionOverlap } from "./core/description-overlap.js";
 import { type DescriptionBudgetIssue } from "./core/skill-description-budget.js";
 import type { SkillRefSource } from "./skill-refs.js";
-import type { PluginLayout } from "./core/layout.js";
+import { type PluginLayout } from "./core/layout.js";
 import type { HarnessDialect } from "./core/dialect.js";
 import type { HookRegistration } from "./core/hook-normalize.js";
 import type { HookScriptEntry } from "./core/hook-block-ineffective.js";
@@ -22,6 +22,14 @@ export interface SurfaceClassifier {
     readonly isSkill: (f: string) => boolean;
     readonly isAgent: (f: string) => boolean;
     readonly isCommand: (f: string) => boolean;
+    /**
+     * The subagent identity for a path `isAgent` accepts — the layout-scoped name
+     * from {@link agentSurfaceName}. Lives here because the classifier is already
+     * the one thing holding the layout's surface dirs; a caller deriving the name
+     * itself would need the layout too, and would be free to derive a different
+     * one. Null for a path this classifier does not call an agent.
+     */
+    readonly agentName: (f: string) => string | null;
 }
 export declare function makeClassifier(layout: PluginLayout): SurfaceClassifier;
 /** The plugin-root + materialize-root + dialect context skill scanning needs. */

package/dist/scan-core.js

@@ -52,6 +52,7 @@ const skill_missing_fence_js_1 = require("./core/skill-missing-fence.js");
 const delegation_trifecta_js_1 = require("./core/delegation-trifecta.js");
 const effects_js_1 = require("./core/effects.js");
 const agent_tools_js_1 = require("./adapters/claude-code/agent-tools.js");
+const layout_js_1 = require("./core/layout.js");
 // A script-path token, matched against a WHOLE shell WORD. The token class is
 // `\S` MINUS the glob metacharacters `*` and `?` (dogfood D1): a real, resolvable
 // hook path never contains them, but a command that merely MENTIONS a glob — e.g.
@@ -146,18 +147,21 @@ function makeClassifier(layout) {
     const agent = at(layout.agentDir);
     const command = at(layout.commandDir);
     const skillRe = skill ? new RegExp(`${skill}[^/]+/SKILL\\.md$`) : null;
-    const agentRe = agent ? new RegExp(`${agent}[^/]+\\.md$`) : null;
+    const agentRe = agent ? new RegExp(`${agent}${layout_js_1.AGENT_FILE_LEAF_RE}$`) : null;
     const commandRe = command ? new RegExp(`${command}.+\\.md$`) : null;
-    // A subagent lives at the plugin's TOP-LEVEL `agents/` dir (e.g. `agents/foo.md`
-    // or `.claude/agents/foo.md`), never recursively under ANOTHER surface dir. Two
-    // real-world nesting traps are excluded as false positives:
+    // A subagent lives under the plugin's `agents/` dir AT ANY DEPTH (the harness
+    // reads it recursively — see AGENT_FILE_LEAF_RE for the vendor's wording and
+    // the measurement), but never under ANOTHER surface dir. Two real-world
+    // nesting traps are excluded as false positives:
     //   - `skills/<x>/agents/…` — skill-internal worker docs (Anthropic's skill-creator)
     //   - `commands/agents/…`   — a COMMAND namespaced `/agents:…` (ruvnet/claude-flow),
     //     incl. a `README.md`; these are commands, not dispatchable subagents.
     // Flagging either as a subagent missing frontmatter is a false positive (it
-    // mis-graded a real plugin F). A genuine top-level `agents/foo.md` still
-    // matches. Both excluded dirs are read from the layout (adapter-agnostic). See
-    // scan.test.ts for the regressions.
+    // mis-graded a real plugin F). A genuine `agents/foo.md` — or `agents/x/foo.md`
+    // — still matches. Both excluded dirs are read from the layout
+    // (adapter-agnostic), and both patterns already tolerate depth on BOTH sides of
+    // the `agents/` segment, so the recursion above does not leak through them.
+    // See scan.test.ts for the regressions.
     const nestedUnder = [
         layout.skillDir &&
             `${escapeRe(layout.skillDir)}/.+/${escapeRe(layout.agentDir)}/`,
@@ -170,10 +174,24 @@ function makeClassifier(layout) {
     const isAgent = (f) => (agentRe?.test(f) ?? false) &&
         !f.endsWith(".spec.ts") &&
         !(nestedAgentRe?.test(f) ?? false);
+    // The MIRROR of the rule above, and it exists because reading `agents/`
+    // recursively made a new shape reachable: `agents/<x>/skills/<y>/SKILL.md` now
+    // matches the agent pattern, and it always matched the skill pattern, so the
+    // one file would be counted as BOTH — inflating two surface counts and grading
+    // it twice. The harness resolves this the same way the existing exclusion
+    // does: it reads skills from the plugin's OWN `skills/` dir, and reads every
+    // `.md` under `agents/` recursively — so this file is a subagent, and is not a
+    // skill. Excluding it here (rather than excluding it from agents) is what keeps
+    // the two classifiers disjoint AND agreeing with the harness.
+    const nestedSkillRe = layout.skillDir && layout.agentDir
+        ? new RegExp(`(?:^|/)${escapeRe(layout.agentDir)}/(?:.+/)?${escapeRe(layout.skillDir)}/`)
+        : null;
+    const isSkill = (f) => (skillRe?.test(f) ?? false) && !(nestedSkillRe?.test(f) ?? false);
     return {
-        isSkill: (f) => skillRe?.test(f) ?? false,
+        isSkill,
         isAgent,
         isCommand: (f) => commandRe?.test(f) ?? false,
+        agentName: (f) => isAgent(f) ? (0, layout_js_1.agentSurfaceName)(f, layout.agentDir) : null,
     };
 }
 function skillName(path) {
@@ -443,7 +461,10 @@ ctx) {
         // so they cannot disagree about what the vocabulary said.
         const vocabIssues = tools ? (0, tool_contract_js_1.verifyToolContract)(tools, dialect) : [];
         out.push({
-            name: (0, posix_path_js_1.basename)(path, ".md"),
+            // The layout-scoped identity, NOT the basename — see `agentSurfaceName`
+            // for why recursion makes a basename unsafe here. Identical to the
+            // basename for a top-level agent, so no existing report moves.
+            name: cls.agentName(path) ?? (0, posix_path_js_1.basename)(path, ".md"),
             path: ctx
                 ? reportedSurfacePath(path, ctx.sources?.[path], ctx.root)
                 : path,

package/dist/test-coverage-files.d.ts

@@ -1,4 +1,4 @@
-import type { PluginLayout } from "./core/layout.js";
+import { type PluginLayout } from "./core/layout.js";
 import type { CoverageDecision, CoverageTier, Surface } from "./test-coverage.js";
 /**
  * The untested harness surfaces (skills / agents / hooks) in a file map — the

package/dist/test-coverage-files.js

@@ -32,6 +32,7 @@ exports.findUntestedSurfacesInFiles = findUntestedSurfacesInFiles;
  * would report a measurement nobody in this process made.
  */
 const posix_path_js_1 = require("./posix-path.js");
+const layout_js_1 = require("./core/layout.js");
 const coverage_evidence_js_1 = require("./coverage-evidence.js");
 // Mirrors src/test-coverage.ts constants. VALUES are re-declared, never imported
 // — test-coverage.ts pulls in node:fs/glob, and this twin must stay browser-safe.
@@ -123,11 +124,15 @@ function discoverAgents(files, layout) {
     if (!layout.agentDir)
         return out;
     const prefixes = surfacePrefixes(layout.agentDir, layout.materializeRoot);
-    for (const path of matchSurface(files, prefixes, "[^/]+\\.md")) {
+    // Same depth rule as the scan classifier — quoted from AGENT_FILE_LEAF_RE, not
+    // respelled. This discoverer feeds the `Tested` metric; when it disagreed with
+    // the classifier, `audit` printed a subagent count and an untested-surface
+    // count derived from two different sets of files.
+    for (const path of matchSurface(files, prefixes, layout_js_1.AGENT_FILE_LEAF_RE)) {
         if (path.endsWith(".spec.ts"))
             continue;
         const content = files[path];
-        const name = (0, posix_path_js_1.basename)(path, ".md");
+        const name = (0, layout_js_1.agentSurfaceName)(path, layout.agentDir) ?? (0, posix_path_js_1.basename)(path, ".md");
         const dir = (0, posix_path_js_1.dirname)(path);
         out.push({
             kind: "agent",

package/dist/test-coverage.d.ts

@@ -60,7 +60,7 @@
  * magnitude in cost without saying which. {@link UntestedReport} therefore carries
  * a per-tier {@link CoverageTier} alongside the (unchanged) union fields.
  */
-import type { PluginLayout } from "./core/layout.js";
+import { type PluginLayout } from "./core/layout.js";
 import { type CoverageEvidence, type EvidenceCounts } from "./coverage-evidence.js";
 export type SurfaceKind = "skill" | "agent" | "hook";
 export interface Surface {

package/dist/test-coverage.js

@@ -75,7 +75,8 @@ const test_file_ext_js_1 = require("./core/test-file-ext.js");
 const assert_never_js_1 = require("./core/assert-never.js");
 const ts_runner_caps_js_1 = require("./ts-runner-caps.js");
 const glob_1 = require("glob");
-const layout_js_1 = require("./adapters/claude-code/layout.js");
+const layout_js_1 = require("./core/layout.js");
+const layout_js_2 = require("./adapters/claude-code/layout.js");
 const coverage_evidence_js_1 = require("./coverage-evidence.js");
 const coverage_artifact_js_1 = require("./coverage-artifact.js");
 /**
@@ -193,12 +194,33 @@ function discoverSkills(basePath, ignore, layout) {
 const LEGACY_COVERS = "vigiles:covers";
 function discoverAgents(basePath, ignore, layout) {
     const out = [];
-    const found = (0, glob_1.globSync)(surfaceGlobs(layout.agentDir, "*.md", layout.materializeRoot), { cwd: basePath, ignore });
+    // The glob is a COARSE FETCH — deliberately wider than the rule — and
+    // AGENT_FILE_LEAF_RE decides. Spelling the depth rule a second time in glob
+    // dialect is exactly how these two discoverers drifted from the scan
+    // classifier in the first place, so only one dialect is authoritative and the
+    // other is allowed to over-match.
+    const found = (0, glob_1.globSync)(surfaceGlobs(layout.agentDir, "**/*.md", layout.materializeRoot), { cwd: basePath, ignore });
+    const prefixes = layout.materializeRoot
+        ? [layout.agentDir, `${layout.materializeRoot}/${layout.agentDir}`]
+        : [layout.agentDir];
+    const isAgentFile = layout.agentDir
+        ? new RegExp(`^(?:${[...new Set(prefixes)]
+            .map((p) => p.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+            .join("|")})/${layout_js_1.AGENT_FILE_LEAF_RE}$`)
+        : null;
     for (const path of found.sort()) {
         if (path.endsWith(".spec.ts"))
             continue;
+        // Both the depth rule and the scoped name are written in POSIX (`/`), so
+        // normalize ONCE and derive both from the same string. Normalizing for one
+        // and not the other is how a Windows checkout would match the pattern and
+        // then fail to find `agents/` when naming — silently falling back to a
+        // basename, re-introducing the collision the scoped name exists to prevent.
+        const rel = path.split(node_path_1.sep).join("/");
+        if (isAgentFile && !isAgentFile.test(rel))
+            continue;
         const content = read((0, node_path_1.join)(basePath, path));
-        const name = (0, node_path_1.basename)(path, ".md");
+        const name = (0, layout_js_1.agentSurfaceName)(rel, layout.agentDir) ?? (0, node_path_1.basename)(rel, ".md");
         const dir = (0, node_path_1.dirname)(path);
         out.push({
             kind: "agent",
@@ -381,7 +403,7 @@ function tierOf(considered, tests, index, tier) {
  */
 function findUntestedSurfaces(options = {}) {
     const basePath = options.basePath ?? process.cwd();
-    const layout = options.layout ?? layout_js_1.claudeCodeLayout;
+    const layout = options.layout ?? layout_js_2.claudeCodeLayout;
     const ignore = [...DEFAULT_IGNORE, ...(options.exclude ?? [])];
     const globs = options.testGlobs ?? DEFAULT_TEST_GLOBS;
     const surfaces = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "17.0.1",
+  "version": "18.0.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