vigiles 22.0.0 → 24.0.0

package/dist/cli.js

@@ -12,8 +12,11 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.specLoadFailureReason = specLoadFailureReason;
+exports.lintTotals = lintTotals;
+exports.discoverNestedBundles = discoverNestedBundles;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const minimatch_1 = require("minimatch");
 const node_child_process_1 = require("node:child_process");
 const glob_1 = require("glob");
 const generate_types_js_1 = require("./core/generate-types.js");
@@ -316,7 +319,20 @@ function compileClaudeToFile(spec, specPath, config, dialect) {
     if (errors.length > 0) {
         console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
         printErrors(specPath, errors);
-        (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, primaryOutput), markdown);
+        // 🔴 NOTHING IS WRITTEN ON A FAILED COMPILE (#173).
+        //
+        // It used to write the artifact anyway, and the result was the exact
+        // false-confidence object this tool exists to prevent: a `CLAUDE.md`
+        // carrying refs already KNOWN to be dead, stamped with a VALID integrity
+        // hash. `lint` then verified the hash, found it intact, and exited 0 — so
+        // the command the README calls "the CI gate … broken refs" went green over
+        // breakage `compile` had printed minutes earlier. Compile locally, get
+        // distracted, commit: CI never mentions it again.
+        //
+        // Not writing leaves the LAST GOOD artifact in place, which is strictly
+        // better than replacing it with a broken one: the error is on screen, the
+        // exit code is 1, and no green hash is minted over a known-bad file.
+        console.log(`  → ${primaryOutput} was NOT written; the previous version is left in place.`);
         return false;
     }
     (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, primaryOutput), markdown);
@@ -788,6 +804,55 @@ async function verifyMarkdownMcpRefs(files, silent) {
     return errors;
 }
 /** Exit codes: 0 clean, 1 warnings only, 2 hard errors. */
+/**
+ * The run's totals, derived from the report itself.
+ *
+ * 🔴 ONE SOURCE, because the two numbers disagreeing IS the bug (#183). The
+ * human-readable log had no total, and counting its `⚠` lines gave a different
+ * number from the JSON — 21 against 88 on a real repo — because some checks print
+ * one line per finding and others one line carrying a count. Both numbers were
+ * right and nothing said why they differed, so "vigiles reports 21 warnings" and
+ * "88 warnings" were equally defensible readings of one run.
+ *
+ * Counted GENERICALLY off the `*Issues` / `*Errors` / count keys rather than a
+ * hand-maintained list, so a rule added later is included by existing, not by
+ * somebody remembering. `orphanCount` and `duplicatePairs` are named explicitly
+ * only because they predate the `*Issues` convention (#181).
+ */
+function lintTotals(report) {
+    let errors = 0;
+    let findings = 0;
+    for (const [key, value] of Object.entries(report)) {
+        if (typeof value !== "number" || value === 0)
+            continue;
+        if (key === "files")
+            continue;
+        // Informational counters: not findings, they describe the corpus.
+        if (key === "inlineRules" ||
+            key === "frontmatterRules" ||
+            key === "coverageEnabled" ||
+            key === "coverageDocumented" ||
+            key === "strengthenSuggestions")
+            continue;
+        if (key.endsWith("Errors")) {
+            errors += value;
+            findings += value;
+            continue;
+        }
+        // `*Issues` counts EVERY finding of that rule; when the rule is at "error"
+        // the same findings are also in `*Errors`, so they must not be counted twice.
+        if (key.endsWith("Issues")) {
+            const paired = report[`${key.slice(0, -"Issues".length)}Errors`];
+            findings += paired && paired > 0 ? 0 : value;
+            continue;
+        }
+        if (key === "orphanCount" ||
+            key === "duplicatePairs" ||
+            key === "untestedSurfaces")
+            findings += value;
+    }
+    return { findings, errors, warnings: findings - errors };
+}
 function lintExitCode(report) {
     if (report.hashErrors > 0 ||
         report.validationErrors > 0 ||
@@ -822,9 +887,15 @@ function lintExitCode(report) {
         // it to "error", so it belongs in the hard tier with every other explicit
         // error — it used to sit at exit 1 because it fired unasked and could not be
         // turned off.
-        report.docRefErrors > 0)
+        report.docRefErrors > 0 ||
+        report.specRefErrors > 0)
         return 2;
-    if (report.duplicatePairs > 0 || report.orphanCount > 0)
+    // Tierable now: a `warn` orphan/duplicate finding is reported and does NOT
+    // change the exit code. Both used to feed the exit directly, which is what
+    // made them the only untierable findings in the tool.
+    if (report.orphanCount > 0 && report.orphanSeverity === "error")
+        return 1;
+    if (report.duplicatePairs > 0 && report.duplicateSeverity === "error")
         return 1;
     // Guidance counts are informational, not failures
     return 0;
@@ -1072,6 +1143,157 @@ function sharedDirsRootFor(scanTarget) {
     const underCwd = rel === "" || (!rel.startsWith("..") && !(0, node_path_1.isAbsolute)(rel));
     return underCwd ? cwd : target;
 }
+/**
+ * Nested plugin bundles under a lint root — a directory that is itself a harness
+ * (its own `.claude-plugin/plugin.json`, or its own skills dir) and is NOT the
+ * root being linted.
+ *
+ * 🔴 WHY THIS EXISTS. Every per-surface check reads ONE root, so in a monorepo
+ * holding `skills/` plus `plugins/  * /skills/` the nested skills were never scored
+ * and nothing said so. Measured on a fixture: 4 skills over the description
+ * budget, `lint .` reported 2, exit 0 — a repo reads that as green-with-2 while
+ * the other 2 carry the same defect (#185). The failure is silent, which is the
+ * shape this repo treats as worse than a loud one.
+ *
+ * Deliberately shallow (one level under a container dir): deep recursion would
+ * sweep vendored corpora — this repo's own `test/dogfood/` holds real pinned
+ * third-party plugins — and scoring someone else's vendored plugin as if it were
+ * yours is the false-positive that gets a gate switched off.
+ */
+function discoverNestedBundles(root, exclude = []) {
+    const out = [];
+    const skip = new Set([
+        "node_modules",
+        ".git",
+        "dist",
+        "coverage",
+        ".vigiles",
+    ]);
+    const isBundle = (dir) => (0, node_fs_1.existsSync)((0, node_path_1.join)(dir, ".claude-plugin", "plugin.json")) ||
+        (0, node_fs_1.existsSync)((0, node_path_1.join)(dir, "skills"));
+    const excluded = (rel) => exclude.some((pattern) => rel === pattern ||
+        rel.startsWith(`${pattern}/`) ||
+        (0, minimatch_1.minimatch)(rel, pattern) ||
+        (0, minimatch_1.minimatch)(rel, `${pattern}/**`));
+    let entries;
+    try {
+        entries = (0, node_fs_1.readdirSync)(root, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && !skip.has(e.name) && !e.name.startsWith("."))
+            .map((e) => e.name);
+    }
+    catch {
+        return out;
+    }
+    for (const name of entries) {
+        const dir = (0, node_path_1.join)(root, name);
+        if (excluded(name))
+            continue;
+        // A container (`plugins/`) holds bundles; a bundle may also sit directly.
+        if (isBundle(dir)) {
+            out.push(dir);
+            continue;
+        }
+        let inner;
+        try {
+            inner = (0, node_fs_1.readdirSync)(dir, { withFileTypes: true })
+                .filter((e) => e.isDirectory() && !e.name.startsWith("."))
+                .map((e) => e.name);
+        }
+        catch {
+            continue;
+        }
+        for (const child of inner) {
+            const sub = (0, node_path_1.join)(dir, child);
+            if (excluded(`${name}/${child}`))
+                continue;
+            if (isBundle(sub))
+                out.push(sub);
+        }
+    }
+    return out.sort();
+}
+/**
+ * Run one per-surface check over EVERY root and sum its counters.
+ *
+ * The checks all share `(config, silent, adapter, root)` and return a small
+ * record of numbers, so one wrapper covers all twenty rather than twenty edits —
+ * and a check added later is swept in by using it, not by remembering to.
+ */
+function overBundles(fn, config, silent, adapter, roots) {
+    const [first, ...rest] = roots;
+    const total = { ...fn(config, silent, adapter, first) };
+    for (const root of rest) {
+        const next = fn(config, silent, adapter, root);
+        for (const key of Object.keys(next))
+            total[key] =
+                (total[key] ?? 0) + (next[key] ?? 0);
+    }
+    return total;
+}
+/**
+ * Re-derive a compiled artifact's references from its SPEC, and report the dead
+ * ones — the half of #173 that deleting the write-on-error did not close.
+ *
+ * 🔴 THE HOLE. `lint` verifies the integrity HASH, which answers "is this file
+ * still what the spec compiled to" and says nothing about whether the things it
+ * NAMES still exist. So a `CLAUDE.md` committed while its refs were live stays
+ * green forever after the referenced file is deleted: `compile` errors, `lint`
+ * prints "hash valid — All compiled files intact" and exits 0. Reproduced:
+ *
+ *     $ vigiles compile CLAUDE.md.spec.ts
+ *     ✗ [stale-file] File not found: "docs/guide.md"
+ *     $ vigiles lint .
+ *     ✓ CLAUDE.md — hash valid       # exit 0
+ *
+ * The reporter named this residue himself when filing #173 and I deferred it;
+ * it is the gap between what `README.md` promises of `lint` ("the CI gate …
+ * broken refs") and what it checked. A hash is an integrity claim, not a
+ * reference claim, and the two were being read as one.
+ *
+ * Cost is bounded: only specs whose compiled target actually EXISTS are loaded,
+ * so a repo with no specs does no extra work at all.
+ */
+async function checkSpecRefs(config, silent, dialect) {
+    const sev = (0, types_js_1.ruleSeverity)(config?.rules?.["spec-refs"]) ?? "error";
+    if (!sev)
+        return { issues: 0, errors: 0 };
+    const found = [];
+    for (const specPath of findSpecs()) {
+        const target = specPath.replace(/\.spec\.ts$/, "");
+        if (!(0, node_fs_1.existsSync)(target))
+            continue; // never compiled — `compile` reports it
+        const spec = await loadSpec(specPath);
+        if (!spec || spec._specType !== "claude")
+            continue;
+        try {
+            const { errors } = (0, compile_js_1.compileClaude)(spec, {
+                basePath: process.cwd(),
+                specFile: specPath,
+                dialect,
+                maxRules: config?.maxRules,
+                maxTokens: config?.maxTokens,
+                maxSectionLines: config?.maxSectionLines,
+                catalogOnly: config?.catalogOnly,
+                linters: config?.linters,
+            });
+            for (const e of errors)
+                found.push(`${target}: ${e.message} (from ${specPath})`);
+        }
+        catch {
+            // A spec that will not load is `compile`'s finding, not this one's —
+            // reporting it here would double-report and blame the wrong command.
+            continue;
+        }
+    }
+    if (found.length > 0 && !silent) {
+        console.log("\nSpec reference check:\n");
+        for (const msg of found) {
+            console.log(`  ${sev === "error" ? "✗" : "⚠"} ${msg}`);
+            ghAnnotate(sev === "error" ? "error" : "warning", msg);
+        }
+    }
+    return { issues: found.length, errors: sev === "error" ? found.length : 0 };
+}
 async function runLint(restArgs, flags, config) {
     const summary = flags.includes("--summary");
     const json = flags.includes("--json");
@@ -1104,6 +1326,30 @@ async function runLint(restArgs, flags, config) {
         configHarness: (0, adapter_registry_js_1.normalizeHarnessList)(config?.harness),
     });
     const adapter = lintSelection.adapter;
+    // 🔴 WHICH ROOTS GET SCORED, and saying so either way (#185).
+    //
+    // Every per-surface check reads ONE root, so a monorepo with `skills/` plus
+    // `plugins/*/skills/` scored only the first and said nothing — measured at 2
+    // findings reported against 4 real ones, exit 0. A skipped surface that is not
+    // announced reads as a clean surface.
+    //
+    // Default stays ROOT-ONLY on purpose: descending by default would start
+    // scoring vendored third-party corpora (this repo's own `test/dogfood/` holds
+    // pinned real plugins), and scoring someone else's plugin as if it were yours
+    // is the false positive that gets a gate turned off. So the DEFAULT fixes the
+    // SILENCE, and `bundles: "all"` fixes the COVERAGE — one exit code over the
+    // whole repo, which is what a CI gate needs.
+    const nestedBundles = discoverNestedBundles(scanRoot, config?.exclude ?? []);
+    const scoreAll = flags.includes("--bundles=all") || config?.bundles === "all";
+    const lintRoots = scoreAll ? [scanRoot, ...nestedBundles] : [scanRoot];
+    if (!silent && nestedBundles.length > 0) {
+        const rel = nestedBundles.map((b) => (0, node_path_1.relative)(scanRoot, b) || b);
+        console.log(scoreAll
+            ? `\nScoring ${String(lintRoots.length)} bundles: the root + ${rel.join(", ")}`
+            : `\n⚠ ${String(nestedBundles.length)} nested bundle(s) discovered but NOT scored: ${rel.join(", ")}\n` +
+                `  Their skills/agents/hooks are not in the counters below. Add \`"bundles": "all"\` to ` +
+                `.vigilesrc.json (or pass --bundles=all) to score them in this run.`);
+    }
     // Discover the compiled files whose integrity is verified. Include the active
     // harness's subagent dir (dogfood E2): a compiled `agents/<name>.md` carries a
     // vigiles hash, but the default glob only matched CLAUDE/AGENTS/SKILL, so a
@@ -1157,7 +1403,14 @@ async function runLint(restArgs, flags, config) {
     // declares the block; its `include` defaults to docs/ (research/ etc. are
     // opted into explicitly). `enforce("vigiles/orphan-docs")` in a spec only
     // validates the rule NAME — the block is what drives the scan.
-    const orphansCfg = config?.orphans;
+    // 🔴 SEVERITY IS READ, not just the block's presence (#181). `orphan-docs` had
+    // a RULE_META entry and a documented severity, and nothing ever read it: both
+    // `"warn"` and `"off"` still exited 1, so a repo could only choose between an
+    // always-blocking check and deleting the `orphans` block. `warn` now reports
+    // without touching the exit code and `false`/`"off"` skips the scan, exactly
+    // like every other rule.
+    const orphanSeverity = (0, types_js_1.ruleSeverity)(config?.rules?.["orphan-docs"]) ?? "warn";
+    const orphansCfg = orphanSeverity ? config?.orphans : undefined;
     if (!silent)
         console.log("\nOrphan docs check:\n");
     let orphanReport = {
@@ -1188,72 +1441,75 @@ async function runLint(restArgs, flags, config) {
     // 7b. Untested-surface check — skills/agents/hooks shipping without a test or
     // eval. Warning by default (a nudge, exit 0); set rules.untested-{skill,agent,
     // hook} to "error" to gate CI. See src/test-coverage.ts and docs/rules/.
-    const untested = checkUntestedSurfaces(config, silent, adapter, scanRoot);
+    // A compiled artifact's refs, re-derived from its spec — the hash says the file
+    // is unchanged, not that what it names still exists (#173).
+    const specRefs = await checkSpecRefs(config, silent, adapter.dialect);
+    const untested = overBundles(checkUntestedSurfaces, config, silent, adapter, lintRoots);
     // 7c. Subagent tool-contract check — cross-reference each subagent's `tools:`
     // rail against the harness catalog (the moat). n/a on a harness with no
     // subagents. Off by default unless a severity is configured; warning surfaces
     // a typo/never-available tool, error gates CI.
-    const toolContract = checkSubagentToolContracts(config, silent, adapter, scanRoot);
+    const toolContract = overBundles(checkSubagentToolContracts, config, silent, adapter, lintRoots);
     // 7d. Hook-event check — a hook registered under an event the harness doesn't
     // define never fires. High-precision (close typos only). Off unless configured.
-    const hookEvents = checkHookEvents(config, silent, adapter, scanRoot);
+    const hookEvents = overBundles(checkHookEvents, config, silent, adapter, lintRoots);
     // 7e. Subagent-frontmatter check — a subagent missing required frontmatter
     // (name + description) won't register. n/a on a harness with no subagents.
-    const frontmatter = checkFrontmatterSchema(config, silent, adapter, scanRoot);
+    const frontmatter = overBundles(checkFrontmatterSchema, config, silent, adapter, lintRoots);
     // 7f. MCP-config check — a declared MCP server with no command/url can't start.
-    const mcpConfig = checkMcpConfig(config, silent, adapter, scanRoot);
+    const mcpConfig = overBundles(checkMcpConfig, config, silent, adapter, lintRoots);
     // 7g. Skill-frontmatter — RECOMMEND explicit name/description on skills (a
     // reliable trigger surface). Best-practice nudge; skills load without it.
-    const skillFm = checkSkillFrontmatter(config, silent, adapter, scanRoot);
+    const skillFm = overBundles(checkSkillFrontmatter, config, silent, adapter, lintRoots);
     // 7h. MCP tool-resolution — an `mcp__server__tool` in a contract whose server
     // the plugin doesn't declare can't resolve (the MCP half of the tool moat).
-    const mcpToolResolves = checkMcpToolResolves(config, silent, adapter, scanRoot);
+    const mcpToolResolves = overBundles(checkMcpToolResolves, config, silent, adapter, lintRoots);
     // 7i. Hook-script existence — a hook command referencing a missing script file
     // never runs (matches Anthropic's own `claude plugin validate`).
-    const hookScripts = checkHookScriptExists(config, silent, adapter, scanRoot);
+    const hookScripts = overBundles(checkHookScriptExists, config, silent, adapter, lintRoots);
     // 7j. Disallowed-tools — a `disallowedTools:` block-list typo blocks nothing
     // (the deny-side mirror of subagent-tool-contract; close-typo only).
-    const disallowedTools = checkDisallowedTools(config, silent, adapter, scanRoot);
+    const disallowedTools = overBundles(checkDisallowedTools, config, silent, adapter, lintRoots);
     // 7k. Description-overlap — two model-invocable skills with near-identical
     // descriptions collide in the selector (deterministic NCD precision proxy).
-    const descriptionOverlap = checkDescriptionOverlap(config, silent, adapter, scanRoot);
+    const descriptionOverlap = overBundles(checkDescriptionOverlap, config, silent, adapter, lintRoots);
     // 7k². Skill-description-budget — a model-invocable skill whose description is
     // so long the trigger signal is buried (heuristic proxy; degrades recall +
     // precision). Generous 500-char budget; warn-tier, never gates.
-    const descriptionBudget = checkDescriptionBudget(config, silent, adapter, scanRoot);
+    const descriptionBudget = overBundles(checkDescriptionBudget, config, silent, adapter, lintRoots);
     // 7l. Frontmatter-valid — a `---` block that isn't valid YAML (warn; js-yaml is
     // stricter than some loaders, so verify before enforcing).
-    const frontmatterValid = checkFrontmatterValid(config, silent, adapter, scanRoot);
+    const frontmatterValid = overBundles(checkFrontmatterValid, config, silent, adapter, lintRoots);
     // 7m. MCP hook-target — a `type: mcp_tool` hook action that's incomplete or
     // targets an undeclared server (the moat applied to the hook surface).
-    const mcpHookTargets = checkMcpHookTargets(config, silent, adapter, scanRoot);
+    const mcpHookTargets = overBundles(checkMcpHookTargets, config, silent, adapter, lintRoots);
     // 7n. Prefer-compiled-hooks — ONE discovery nudge (not per-hook) toward
     // compiled `vigiles/hook` artifacts when hand-written hooks ship. Recommendation.
-    const preferCompiledHooks = checkPreferCompiledHooks(config, silent, adapter, scanRoot);
+    const preferCompiledHooks = overBundles(checkPreferCompiledHooks, config, silent, adapter, lintRoots);
     // 7o. Lethal-trifecta — a unit (subagent / model-invocable skill) whose tools
     // hold all three legs (read-private + ingest-untrusted + exfiltrate) is a
     // prompt-injection exfil path (Rule of Two). Capability SET-intersection.
-    const lethalTrifecta = checkLethalTrifecta(config, silent, adapter, scanRoot);
+    const lethalTrifecta = overBundles(checkLethalTrifecta, config, silent, adapter, lintRoots);
     // 7p. Skill-resource — a SKILL.md body referencing a bundled file that doesn't
     // exist on disk under the skill dir (the agent gets nothing). FP-safe.
-    const skillResources = checkSkillResourceResolves(config, silent, adapter, scanRoot);
+    const skillResources = overBundles(checkSkillResourceResolves, config, silent, adapter, lintRoots);
     // 7q. Skill-missing-fence — a SKILL.md opening with `name:`/`description:` but no
     // `---` fence loads as plain body (invisible — no name/description/trigger).
-    const skillFence = checkSkillMissingFence(config, silent, adapter, scanRoot);
+    const skillFence = overBundles(checkSkillMissingFence, config, silent, adapter, lintRoots);
     // 7r. Plugin-dir-layout — functional surface dirs (skills/agents/commands) nested
     // inside the `.claude-plugin/` manifest dir where the harness can't see them.
-    const pluginLayout = checkPluginDirLayout(config, silent, adapter, scanRoot);
+    const pluginLayout = overBundles(checkPluginDirLayout, config, silent, adapter, lintRoots);
     // 7s. Delegation-trifecta — a lethal trifecta that emerges across a delegation
     // edge (a subagent's own ∪ delegated-to capability) though no single unit trips it.
-    const delegationTrifecta = checkDelegationTrifecta(config, silent, adapter, scanRoot);
+    const delegationTrifecta = overBundles(checkDelegationTrifecta, config, silent, adapter, lintRoots);
     // 7t. Hook-block-ineffective — a hook that looks like it blocks but silently
     // doesn't (block decision on a non-blocking event, or the legacy `decision`
     // field on a permission-gated event). The #1 verified hook pain (#19009).
-    const hookBlock = checkHookBlockIneffective(config, silent, adapter, scanRoot);
+    const hookBlock = overBundles(checkHookBlockIneffective, config, silent, adapter, lintRoots);
     // 7u. Hook-matcher — a hook `matcher` that doesn't fire as written (tool-name
     // typo, an uncompilable or unreachable MCP pattern, one too narrow for real
     // server naming, or an undeclared MCP server).
-    const hookMatcher = checkHookMatcher(config, silent, adapter, scanRoot);
+    const hookMatcher = overBundles(checkHookMatcher, config, silent, adapter, lintRoots);
     // 8. Validate vigiles builder calls inside markdown code blocks — the
     // `doc-refs` rule, DEFAULT OFF. Illustrative blocks opt out via
     // `<!-- vigiles:ignore -->` (single block) or `<!-- vigiles:ignore-file -->`
@@ -1329,13 +1585,17 @@ async function runLint(restArgs, flags, config) {
         inlineRules,
         frontmatterErrors,
         frontmatterRules,
+        specRefIssues: specRefs.issues,
+        specRefErrors: specRefs.errors,
         duplicatePairs: dups.pairCount,
+        duplicateSeverity: (0, types_js_1.ruleSeverity)(config?.rules?.["duplicate-rules"]) ?? "warn",
         coverageEnabled: coverage.enabled,
         coverageDocumented: coverage.documented,
         strengthenSuggestions: guidanceCount,
         integrityErrors,
         coverageErrors,
         orphanCount: orphanReport.orphans.length,
+        orphanSeverity: orphanSeverity,
         untestedSurfaces: untested.untested,
         untestedErrors: untested.errors,
         toolContractIssues: toolContract.issues,
@@ -1386,13 +1646,41 @@ async function runLint(restArgs, flags, config) {
         mcpRefErrors,
         files,
     };
+    // The totals both surfaces quote, computed ONCE (#183). Attaching them to the
+    // report is what makes the log line and `--json` incapable of disagreeing —
+    // the previous gap was not a wrong number, it was two right numbers with
+    // nothing explaining the difference.
+    const totals = lintTotals(report);
+    const reported = { ...report, totals };
+    // `--json-out=<file>` writes the JSON to disk while stdout keeps the
+    // human-readable run — one scan, both artefacts (#182). A CI job needed both
+    // (the log is what a human opens; the JSON is what the PR comment is built
+    // from) and had to scan the repo TWICE to get them, which is the same work
+    // done twice and grows with the corpus.
+    const jsonOutFlag = flags.find((f) => f.startsWith("--json-out="));
+    if (jsonOutFlag) {
+        const dest = (0, node_path_1.resolve)(jsonOutFlag.slice("--json-out=".length));
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(dest), { recursive: true });
+        (0, node_fs_1.writeFileSync)(dest, `${JSON.stringify(reported, null, 2)}\n`);
+        if (!silent)
+            console.log(`\n✓ JSON report written to ${dest}`);
+    }
     if (summary) {
-        printLintSummary(report);
+        printLintSummary(reported);
     }
     else if (json) {
-        console.log(JSON.stringify(report, null, 2));
+        console.log(JSON.stringify(reported, null, 2));
+    }
+    else {
+        // The one number a reader can quote. Counting `⚠` lines gives a DIFFERENT
+        // number, because some checks print one line per finding and others one line
+        // carrying a count — so the log now states the finding total outright rather
+        // than leaving the reader to infer it from line shapes.
+        const code = lintExitCode(reported);
+        console.log(`\n${String(totals.findings)} finding(s): ${String(totals.errors)} error, ` +
+            `${String(totals.warnings)} warning — exit ${String(code)}`);
     }
-    return report;
+    return reported;
 }
 /** Single-line lint summary for SessionStart hooks — minimal token cost. */
 function printLintSummary(report) {
@@ -1937,6 +2225,15 @@ function scaffoldSpec(args) {
             (0, node_fs_1.writeFileSync)(specAbs, source);
             console.log(`Adopted ${target} → ${specPath} (${tier}, ${String(sectionCount)} section${sectionCount === 1 ? "" : "s"}). ` +
                 `Run \`vigiles compile\` and review the diff; the \`/strengthen\` skill upgrades prose to verified rules.`);
+            // Adoption is faithful by design: it infers NO rules and extracts NO refs,
+            // so a raw adoption verifies nothing on its own. Saying so is the whole
+            // fix — the cost (the file becomes a build artifact, edits move into TS)
+            // lands immediately, and without this line the benefit reads as zero
+            // rather than as not-yet-claimed. Deliberately not a heuristic extractor:
+            // guessing refs out of prose is what got `doc-refs` disabled.
+            if (tier === "raw")
+                console.log(`  ℹ 0 refs extracted — this spec verifies nothing yet. Wrap paths in \`file()\` ` +
+                    `and commands in \`cmd()\` to make \`compile\` check them.`);
         }
         return;
     }
@@ -3566,7 +3863,12 @@ function checkSkillResourceResolves(config, silent, adapter, scanRoot) {
     if (found.length > 0 && !silent) {
         console.log("\nSkill-resource check:\n");
         for (const s of found) {
-            const msg = `${s.name}: bundled resource "${s.finding.ref}" (line ${String(s.finding.line)}) is referenced but missing — the agent reads the instruction and gets nothing.`;
+            const msg = `${s.name}: bundled resource "${s.finding.ref}" (line ${String(s.finding.line)}) is referenced but missing — the agent reads the instruction and gets nothing.` +
+                // The main false-positive source in a skills monorepo, where a SKILL.md
+                // legitimately names a repo-root path. The fix already exists and works;
+                // it was documented only in docs/skills-monorepo.md, so a CI log gave no
+                // hint and the rule read as broken rather than misconfigured.
+                ` If it resolves from the repo root instead, add its directory to \`sharedDirs\` in .vigilesrc.json.`;
             console.log(`  ${sev === "error" ? "✗" : "⚠"} ${s.path}: ${msg}`);
             ghAnnotate(sev === "error" ? "error" : "warning", msg, s.path);
         }
@@ -4587,6 +4889,7 @@ const COMMAND_HELP = {
         usage: "  vigiles audit [dir...]     Grade it on your machine. Reports everything, fails nothing.",
         detail: [
             "  2+ dirs → a leaderboard. Writes vigiles-report.html + .json (auto-gitignored).",
+            "  --single                   audit this dir as ONE harness, even if it holds many bundles",
             "  The executing checks (run your hooks · live MCP · do skills fire?) run only",
             "  interactively — audit asks once and remembers; automation uses the testing API.",
         ],
@@ -4721,7 +5024,12 @@ function printUsage(command) {
     console.log("New here? Start with `vigiles audit .`");
     if (command && command !== "--help") {
         console.log(`\nUnknown command: "${command}"`);
-        process.exit(1);
+        // 2, not 1 — `docs/cli.md` fixes the contract as 1 = "I ran, and what you
+        // asked about is bad", 2 = "I could not do what you asked". A typo'd verb is
+        // the second, and the unknown-FLAG path (cli-flag-check.ts) already exits 2.
+        // A script telling "found problems" from "could not start" by exit code read
+        // a mistyped command as a finding.
+        process.exit(2);
     }
 }
 // ---------------------------------------------------------------------------
@@ -5914,6 +6222,14 @@ async function runHookProgramCommand(file) {
 function ensureReportGitignored(cwd, entries) {
     if (entries.length === 0)
         return;
+    // An `--out` outside the repo produced entries like
+    // `../../../../private/tmp/x/vigiles-report.json`, which ignore NOTHING —
+    // .gitignore does not reach outside its own tree — and accumulate one dead
+    // block per output path. Worse in principle than in practice: `audit` is
+    // documented as a read-only report, and this made it edit a tracked file for
+    // no benefit at all. Inside the repo the write is expected and documented.
+    if (entries.some((e) => e.startsWith("..") || (0, node_path_1.isAbsolute)(e)))
+        return;
     const gi = (0, node_path_1.resolve)(cwd, ".gitignore");
     try {
         if (!(0, node_fs_1.existsSync)(gi)) {
@@ -6429,10 +6745,37 @@ async function main() {
             // 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 (targets.length > 1) {
+            // `--single` pins the SINGLE-harness reading of the given directory, whatever
+            // is nested inside it. Without it, a repo holding many bundles auto-switches
+            // to the leaderboard and there is no way back — so the full ring report for
+            // the ROOT was simply unreachable, and the reported workaround was a CI job
+            // looping `audit` over 29 directories. The mode branch already existed; this
+            // only stops it being decided for you.
+            const single = args.includes("--single");
+            // `--single` names ONE harness, so more than one explicit directory is a
+            // contradiction. Refuse it (exit 2 = "could not do what you asked") rather
+            // than auditing the first and dropping the rest — silently honouring half
+            // an argument list is the same defect class as the ignored `--out` above.
+            if (single && dirs.length > 1) {
+                console.error(`--single audits ONE directory as one harness, but ${String(dirs.length)} were given. ` +
+                    `Drop --single for a leaderboard, or pass a single directory.`);
+                process.exit(2);
+            }
+            const targets = !single && market && market.onDisk.length > 0
+                ? [...market.onDisk]
+                : dirs;
+            if (!single && targets.length > 1) {
                 // Multiple targets → rank them (the leaderboard engine). `--md` emits the
                 // publishable Markdown table (a README / gist / the leaderboard site).
+                //
+                // `--out` writes nothing here: the per-bundle HTML/JSON report is built
+                // in the single-target branch below, and this one only prints a table.
+                // SAY SO. A silent no-op is how a CI job ships an empty artifact and
+                // stays green — which is exactly how this was found, and the same
+                // never-fail-silently shape as the rest of this file.
+                if (args.some((a) => a.startsWith("--out=")) && !json)
+                    console.log(`⚠ --out is ignored here: ${String(targets.length)} bundles → leaderboard mode, ` +
+                        `which produces no per-bundle report. Run audit per directory to write one.`);
                 const scores = (0, leaderboard_js_1.rankPlugins)(targets);
                 const text = args.includes("--md")
                     ? (0, leaderboard_js_1.formatLeaderboardMarkdown)(scores)

package/dist/core/hook-block-ineffective.js

@@ -79,6 +79,24 @@ const DECISION_BLOCK = /"decision"\s*:\s*"(block|deny)"/;
  * (Both require a structured response, as opposed to the legacy field.)
  */
 const PERMISSION_DENY = /"permissionDecision"\s*:\s*"(deny|ask)"/;
+/**
+ * A `"continue": false` halt — the OTHER documented way a Claude Code hook stops
+ * an action (it ends the turn and returns `stopReason` to the agent).
+ *
+ * Read ONLY as a SUPPRESSOR of `wrong-field`, never as a block ATTEMPT, and the
+ * asymmetry is the whole point. #174 proposed adding it alongside the three
+ * mechanisms above; doing that would have made `wrong-event` fire on a hook that
+ * works, because a halt is NOT event-scoped — it stops the turn from
+ * `SessionStart` just as it does from `PreToolUse`, which is precisely the set
+ * `wrong-event` flags. For a rule that can be wired at `error`, a false positive
+ * costs more than a miss: it fails a correct build, and a rule that fails
+ * correct builds gets switched off rather than fixed.
+ *
+ * What it legitimately fixes is the reverse: a hook on a permission-gated event
+ * that pairs a legacy `"decision":"block"` with a real halt was told "nothing is
+ * blocked" while it blocked.
+ */
+const CONTINUE_FALSE = /"continue"\s*:\s*false/;
 // ---------------------------------------------------------------------------
 // Detector
 // ---------------------------------------------------------------------------
@@ -125,6 +143,8 @@ function hookBlockIssues(entries, opts) {
         const hasExit2 = EXIT_2.test(text) || EXIT_2_CODE.test(text);
         const hasDecisionBlock = DECISION_BLOCK.test(text);
         const hasPermissionDeny = PERMISSION_DENY.test(text);
+        const hasContinueFalse = CONTINUE_FALSE.test(text);
+        // Deliberately NOT `|| hasContinueFalse` — see CONTINUE_FALSE.
         const triesBlock = hasExit2 || hasDecisionBlock || hasPermissionDeny;
         if (!triesBlock)
             continue;
@@ -143,7 +163,10 @@ function hookBlockIssues(entries, opts) {
         }
         else if (permissionDecisionEvents.has(entry.event) &&
             hasDecisionBlock &&
-            !hasPermissionDeny) {
+            !hasPermissionDeny &&
+            // A halt alongside the legacy field DOES stop the action, so the legacy
+            // field being ignored costs nothing. Flagging it would be a false alarm.
+            !hasContinueFalse) {
             // wrong-field: on a permission-gated event, uses the legacy field.
             kind = "wrong-field";
             message =

package/dist/core/hook-protocol.d.ts

@@ -46,5 +46,19 @@ export interface HookProtocol {
      * shell-hook harness declares a non-empty set.
      */
     readonly injectableEvents: readonly string[];
+    /**
+     * The boolean stdout field whose `false` value HALTS THE WHOLE TURN, if the
+     * harness has one (Claude Code: `"continue"`). Distinct from a deny: a deny
+     * refuses one tool call, this stops the iteration and hands `stopReason` back
+     * to the agent as text — so authors reach for it exactly when they want to
+     * explain themselves, and a guard written that way still prevents the action.
+     *
+     * Optional (additive, non-breaking) and per-harness on purpose. It is
+     * DOCUMENTED for Claude Code and UNVERIFIED for Codex, whose protocol notes
+     * only record the shared exit-2 / `decision` / `permissionDecision` model — so
+     * Codex leaves it unset rather than inheriting a claim nobody measured. Read
+     * by `decideHook`; absent ⇒ no field halts the turn on this harness.
+     */
+    readonly haltsTurnField?: string;
 }
 //# sourceMappingURL=hook-protocol.d.ts.map