vigiles 23.0.0 → 25.0.0

package/dist/cli.js

@@ -12,8 +12,12 @@
  */
 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 repo_path_js_1 = require("./core/repo-path.js");
 const node_child_process_1 = require("node:child_process");
 const glob_1 = require("glob");
 const generate_types_js_1 = require("./core/generate-types.js");
@@ -285,11 +289,14 @@ function printWarnings(specFile, warnings) {
 /** Compile a generator-skill spec from source → SKILL.md. Returns validity. */
 function compileGeneratorSkillToFile(specPath, source) {
     const outputPath = specPath.replace(/\.spec\.ts$/, "");
-    const { markdown, errors } = (0, compile_generator_js_1.compileGeneratorSkill)(source, {
+    const { artifact, errors } = (0, compile_generator_js_1.compileGeneratorSkill)(source, {
         basePath: process.cwd(),
         specFile: specPath,
     });
-    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
+    // Written only when the compile is clean: `artifact` is null otherwise, and
+    // `writeArtifact` takes nothing else.
+    if (artifact)
+        writeArtifact(outputPath, artifact);
     if (errors.length === 0) {
         console.log(`\n✓ ${specPath} → ${outputPath} (generator skill)`);
         return true;
@@ -390,14 +397,17 @@ function writeInstructionMirrors(primaryOutput, harnesses) {
 /** Compile a declarative SkillSpec → SKILL.md. */
 function compileSkillToFile(spec, specPath, dialect) {
     const outputPath = specPath.replace(/\.spec\.ts$/, "");
-    const { markdown, errors, warnings } = (0, compile_js_1.compileSkill)(spec, {
+    const { artifact, errors, warnings } = (0, compile_js_1.compileSkill)(spec, {
         basePath: process.cwd(),
         specFile: specPath,
         // The SKILL.md frontmatter profile comes from the resolved harness — a Codex
         // repo gets a minimal (name + description) SKILL.md; CC gets the full set.
         dialect,
     });
-    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
+    // Written only when the compile is clean: `artifact` is null otherwise, and
+    // `writeArtifact` takes nothing else.
+    if (artifact)
+        writeArtifact(outputPath, artifact);
     if (errors.length === 0) {
         console.log(`\n✓ ${specPath} → ${outputPath}`);
         printWarnings(specPath, warnings);
@@ -411,12 +421,15 @@ function compileSkillToFile(spec, specPath, dialect) {
 /** Compile a subagent spec → agents/<name>.md (with its result-contract section). */
 function compileAgentToFile(spec, specPath, dialect) {
     const outputPath = specPath.replace(/\.spec\.ts$/, "");
-    const { markdown, errors, warnings } = (0, compile_js_1.compileAgent)(spec, {
+    const { artifact, errors, warnings } = (0, compile_js_1.compileAgent)(spec, {
         basePath: process.cwd(),
         specFile: specPath,
         dialect,
     });
-    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
+    // Written only when the compile is clean: `artifact` is null otherwise, and
+    // `writeArtifact` takes nothing else.
+    if (artifact)
+        writeArtifact(outputPath, artifact);
     if (errors.length === 0) {
         console.log(`\n✓ ${specPath} → ${outputPath}`);
         printWarnings(specPath, warnings);
@@ -434,11 +447,14 @@ function compileAgentToFile(spec, specPath, dialect) {
  */
 function compileRailwayToFile(spec, specPath, knownAgents) {
     const outputPath = specPath.replace(/\.spec\.ts$/, "");
-    const { markdown, errors } = (0, compile_js_1.compileRailway)(spec, {
+    const { artifact, errors } = (0, compile_js_1.compileRailway)(spec, {
         specFile: specPath,
         knownAgents,
     });
-    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
+    // Written only when the compile is clean: `artifact` is null otherwise, and
+    // `writeArtifact` takes nothing else.
+    if (artifact)
+        writeArtifact(outputPath, artifact);
     if (errors.length === 0) {
         console.log(`\n✓ ${specPath} → ${outputPath}`);
         return true;
@@ -801,6 +817,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 ||
@@ -835,9 +900,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;
@@ -1085,6 +1156,169 @@ 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 };
+}
+/**
+ * Write a compiled artifact. Accepts ONLY a {@link StampedMarkdown}, so a body
+ * that failed to compile cannot reach the disk — there is no stamp to pass.
+ *
+ * This replaces four copies of `writeFileSync(path, markdown)` that ran BEFORE
+ * their error check (#173, reproduced in the skill/subagent/railway/generator
+ * compilers after the CLAUDE.md one was fixed). Guarding four call sites would
+ * have left the fifth writable; the type leaves nothing to remember.
+ */
+function writeArtifact(outputPath, artifact) {
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), artifact);
+}
 async function runLint(restArgs, flags, config) {
     const summary = flags.includes("--summary");
     const json = flags.includes("--json");
@@ -1117,6 +1351,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
@@ -1170,7 +1428,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 = {
@@ -1201,72 +1466,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 -->`
@@ -1342,13 +1610,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,
@@ -1399,13 +1671,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));
     }
-    return report;
+    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 reported;
 }
 /** Single-line lint summary for SessionStart hooks — minimal token cost. */
 function printLintSummary(report) {
@@ -5947,14 +6247,12 @@ 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;
+    // 🔴 THE GUARD THAT USED TO BE HERE IS GONE, and its absence is the point.
+    // It checked at the write site that no entry escaped the repo (#176.8) — which
+    // worked, and left the bug writable: the next caller to build an entry list
+    // still got a bare `string[]`. `RepoRelativePath` moves the check into the
+    // TYPE, so an escaping path cannot be handed to this function at all. One
+    // place mints them (`repoRelative`), and it returns null instead.
     const gi = (0, node_path_1.resolve)(cwd, ".gitignore");
     try {
         if (!(0, node_fs_1.existsSync)(gi)) {
@@ -6860,10 +7158,17 @@ async function main() {
                 // backslashes (`relative()` yields `reports\x` on Windows, which would
                 // never match `reports/x`).
                 if (wroteReports.length > 0) {
-                    const rel = wroteReports.map((f) => {
-                        const r = (0, node_path_1.relative)(process.cwd(), (0, node_path_1.resolve)(outDir, f)) || f;
-                        return node_path_1.sep === "/" ? r : r.split(node_path_1.sep).join("/");
-                    });
+                    // Only paths that PROVABLY sit inside the repo can be minted, so an
+                    // `--out` pointing elsewhere yields nothing to write rather than a
+                    // dead `../../..` entry.
+                    const rel = wroteReports
+                        .map((f) => (0, repo_path_js_1.repoRelative)(process.cwd(), (0, node_path_1.resolve)(outDir, f), {
+                        relative: node_path_1.relative,
+                        resolve: node_path_1.resolve,
+                        isAbsolute: node_path_1.isAbsolute,
+                        sep: node_path_1.sep,
+                    }))
+                        .filter((p) => p !== null);
                     ensureReportGitignored(process.cwd(), rel);
                 }
                 // A shareable deep-link for a public GitHub repo: the in-browser demo

package/dist/core/compile-generator.d.ts

@@ -25,6 +25,7 @@
  * Gate references (`cmd`/`file`/`project`) are collected and verified, so the
  * cross-referencing moat works on generators too (literal args only).
  */
+import { type StampedMarkdown } from "./compile.js";
 export interface GeneratorError {
     type: "stale-file" | "stale-command";
     message: string;
@@ -34,6 +35,11 @@ export interface CompileGeneratorResult {
     errors: GeneratorError[];
 }
 export interface CompileGeneratorSkillResult {
+    /**
+     * The stamped artifact — present ONLY when `errors` is empty. `null` is what
+     * makes a failed compile unwritable: `writeArtifact` accepts nothing else.
+     */
+    artifact: StampedMarkdown | null;
     markdown: string;
     errors: GeneratorError[];
 }

package/dist/core/compile-generator.js

@@ -278,6 +278,9 @@ function compileGeneratorSkill(source, options = {}) {
         !genArg.body) {
         return {
             markdown: "",
+            // No stamp for a spec that did not compile — the error branch has nothing
+            // to write, which is the whole point of the field.
+            artifact: null,
             errors: [
                 {
                     type: "stale-command",
@@ -300,7 +303,7 @@ function compileGeneratorSkill(source, options = {}) {
     }
     fm.push("", "---");
     const content = `${fm.join("\n")}\n\n${body.trim()}\n`;
-    return { markdown: (0, compile_js_1.addHash)(content, specFile), errors };
+    return { ...(0, compile_js_1.seal)(content, errors, specFile), errors };
 }
 /**
  * Compile a generator's SOURCE text to SKILL.md markdown + verified-ref