vigiles 4.0.1 → 4.0.2

package/dist/cli.js

@@ -54,7 +54,7 @@ function findSpecs(pattern) {
     return (0, glob_1.globSync)(glob, {
         // `dot: true` so specs that live in a sync tool's source slot (e.g.
         // `.ruler/AGENTS.md.spec.ts`, the redirect target) are discovered by
-        // compile/audit/the recompile hook — not just root-level specs.
+        // compile/lint/the recompile hook — not just root-level specs.
         dot: true,
         ignore: [...IGNORE_NODE_MODULES, "dist/**", ".git/**"],
         cwd: process.cwd(),
@@ -310,7 +310,7 @@ function verifyHashes(filePaths, silent = false) {
         const fullPath = (0, node_path_1.resolve)(process.cwd(), filePath);
         // If the file doesn't exist at all (typo, deleted), that's an error —
         // not a "no hash" informational message. Without this check, a scoped
-        // audit like `vigiles audit typo.md` would silently exit clean.
+        // lint like `vigiles lint typo.md` would silently exit clean.
         if (!(0, node_fs_1.existsSync)(fullPath)) {
             log(`\n✗ ${filePath} — file not found`);
             if (!silent) {
@@ -387,7 +387,7 @@ function check(filePaths, silent = false) {
         hashErrors: hashes.errorCount,
         // `validateSpecs` only returns a boolean today, so we collapse
         // failures to 1 until it starts reporting counts. Kept in its own
-        // counter so audit's "stale hash — run vigiles compile" remediation
+        // counter so lint's "stale hash — run vigiles compile" remediation
         // doesn't misreport a require-spec / other validation failure.
         validationErrors: specsValid ? 0 : 1,
     };
@@ -403,7 +403,7 @@ async function findDuplicateRules(threshold = 0.3, silent = false, scopeFiles) {
             console.log(msg);
     };
     const allSpecs = findSpecs();
-    // If audit was invoked with explicit file arguments, only scan the specs
+    // If lint was invoked with explicit file arguments, only scan the specs
     // for those files — otherwise an unrelated duplicate elsewhere in the
     // repo would fail a targeted CI check (e.g. `vigiles lint path/foo.md`).
     //
@@ -551,7 +551,7 @@ async function verifyMarkdownMcpRefs(files, silent) {
     return errors;
 }
 /** Exit codes: 0 clean, 1 warnings only, 2 hard errors. */
-function auditExitCode(report) {
+function lintExitCode(report) {
     if (report.hashErrors > 0 ||
         report.validationErrors > 0 ||
         report.inlineErrors > 0 ||
@@ -718,7 +718,7 @@ function verifyFrontmatterRules(filePath, silent, exclude, linterOptions) {
  *
  * Spec mode is the source of truth when it exists, so a literal
  * `<!-- vigiles:enforce ... -->` snippet that survived into compiled
- * markdown (or an example in a spec-managed file) must not trip audit. A
+ * markdown (or an example in a spec-managed file) must not trip lint. A
  * file is spec-managed iff it has a sibling `<file>.spec.ts` OR its own
  * `<!-- vigiles:sha256:... compiled from <spec> -->` header. A rule
  * declared both inline and in frontmatter is verified once (inline wins as
@@ -768,14 +768,14 @@ function verifyMarkdownModeRules(files, silent, config) {
     return totals;
 }
 /**
- * Unified audit command: verify hashes, report coverage gaps, detect duplicates,
+ * Unified lint command: verify hashes, report coverage gaps, detect duplicates,
  * suggest improvements.
  *
  * Flags:
  *   --summary   Print a single-line summary (for SessionStart hooks)
  *   --json      Print structured JSON report (for CI integration)
  */
-async function audit(restArgs, flags, config) {
+async function runLint(restArgs, flags, config) {
     const summary = flags.includes("--summary");
     const json = flags.includes("--json");
     const silent = summary || json;
@@ -801,7 +801,7 @@ async function audit(restArgs, flags, config) {
         console.log("\nLinter rule coverage:\n");
     const coverage = discover(silent);
     // 3. Duplicate rule detection (NCD). Scope to the requested files when
-    // audit was invoked with explicit paths, so targeted CI checks don't
+    // lint was invoked with explicit paths, so targeted CI checks don't
     // fail on unrelated duplicates elsewhere in the repo.
     if (!silent)
         console.log("\nDuplicate rule detection:\n");
@@ -878,15 +878,15 @@ async function audit(restArgs, flags, config) {
         files,
     };
     if (summary) {
-        printAuditSummary(report);
+        printLintSummary(report);
     }
     else if (json) {
         console.log(JSON.stringify(report, null, 2));
     }
     return report;
 }
-/** Single-line audit summary for SessionStart hooks — minimal token cost. */
-function printAuditSummary(report) {
+/** Single-line lint summary for SessionStart hooks — minimal token cost. */
+function printLintSummary(report) {
     const parts = [];
     if (report.hashErrors > 0)
         parts.push(`${String(report.hashErrors)} stale`);
@@ -1036,7 +1036,14 @@ function init(args) {
     // `.ruler/AGENTS.md.spec.ts` source slot → target "AGENTS.md").
     const targetName = (0, node_path_1.basename)(target);
     const targetLine = targetName !== "CLAUDE.md" ? `\n  target: "${targetName}",` : "";
-    const template = `import { claude, enforce, guidance } from "vigiles/spec";
+    // Import ONLY what the scaffold uses (`claude`) — a strict ESLint with
+    // \`no-unused-vars\` + \`--max-warnings=0\` (common in CI) would otherwise fail
+    // the moment this is committed, because the enforce()/guidance() examples
+    // below are commented out. The commented import shows what to add when you
+    // write a real rule.
+    const template = `import { claude } from "vigiles/spec";
+// When you add rules below, import the builders you use, e.g.:
+// import { claude, enforce, guidance } from "vigiles/spec";
 
 export default claude({${targetLine}
   sections: {
@@ -1124,7 +1131,7 @@ ${harness}`;
 /**
  * Detect a workflow that drives vigiles through an OLD API — a bare `npx vigiles`
  * (a no-op help screen in v2+) rather than the `zernie/vigiles@` Action or a real
- * subcommand (`audit`/`test`/…). Upgrading users whose workflow predates the
+ * subcommand (`lint`/`test`/…). Upgrading users whose workflow predates the
  * subcommand split silently lose CI validation, so we flag it loudly.
  */
 function workflowUsesStaleApi(content) {
@@ -1135,24 +1142,69 @@ function workflowUsesStaleApi(content) {
     const hasModernCmd = /vigiles\s+(lint|test|eval|compile|scan|generate-types|generate-schema|init)\b/.test(content);
     return !hasModernCmd;
 }
+/**
+ * Subcommands removed/renamed across majors → the replacement to suggest. A
+ * workflow that still calls one is a silently-broken CI step (the removed
+ * subcommand exits non-zero / no-ops), and this stays true even when the file
+ * ALSO uses the Action or a modern command — so it is checked independently of
+ * the bare-API heuristic above, which an Action reference short-circuits.
+ */
+const REMOVED_SUBCOMMANDS = {
+    audit: "lint", // v3 → v4 rename
+};
+/** The first removed/renamed `vigiles <sub>` a workflow still calls, if any. */
+function workflowRemovedSubcommand(content) {
+    for (const [sub, replacement] of Object.entries(REMOVED_SUBCOMMANDS)) {
+        if (new RegExp(`vigiles\\s+${sub}\\b`).test(content))
+            return { sub, replacement };
+    }
+    return null;
+}
+/** Rewrite removed/renamed `vigiles <sub>` invocations in place (audit → lint).
+ * Surgical — preserves the rest of the user's workflow. */
+function rewriteRemovedSubcommands(content) {
+    let out = content;
+    for (const [sub, replacement] of Object.entries(REMOVED_SUBCOMMANDS)) {
+        out = out.replace(new RegExp(`(vigiles\\s+)${sub}\\b`, "g"), `$1${replacement}`);
+    }
+    return out;
+}
 /** Create `.github/workflows/vigiles.yml`. Returns the files it wrote (for the
- * commit hint). An existing workflow is never clobbered, but a STALE one (old
- * bare-`npx vigiles` API) is reported loudly instead of silently skipped. */
+ * commit hint). An existing workflow is never clobbered unless `--force`, but a
+ * STALE one (old bare-`npx vigiles` API, or a removed subcommand) is reported
+ * loudly instead of silently skipped — and rewritten in place with `--force`. */
 function wireGha(plan) {
     const dir = (0, node_path_1.resolve)(process.cwd(), ".github", "workflows");
     const path = (0, node_path_1.resolve)(dir, "vigiles.yml");
+    const rel = ".github/workflows/vigiles.yml";
     if ((0, node_fs_1.existsSync)(path)) {
         const content = (0, node_fs_1.readFileSync)(path, "utf-8");
-        if (workflowUsesStaleApi(content)) {
-            console.log("⚠ .github/workflows/vigiles.yml is STALE — it runs a bare `npx vigiles`,\n" +
-                "  which is a no-op help screen now. Replace its run step with the Action +\n" +
-                "  the test job (CI is otherwise silently not validating anything):\n" +
-                "    - uses: zernie/vigiles@v1   # lint pillar — verify references\n" +
-                "    - run: npx vigiles test     # pillar 2 — harness tests\n" +
-                "  Or delete the file and re-run `vigiles init` to regenerate it.");
+        const removed = workflowRemovedSubcommand(content);
+        if (removed) {
+            if (plan.force) {
+                (0, node_fs_1.writeFileSync)(path, rewriteRemovedSubcommands(content));
+                console.log(`✓ Rewrote ${rel} (vigiles ${removed.sub} → ${removed.replacement})`);
+                return [rel];
+            }
+            console.log(`⚠ ${rel} is STALE — it runs \`vigiles ${removed.sub}\`,\n` +
+                `  which was removed/renamed (now \`vigiles ${removed.replacement}\`). That CI\n` +
+                "  step is silently broken. Fix it:\n" +
+                `    - re-run \`vigiles init --force\` to rewrite it in place (vigiles ${removed.sub} → ${removed.replacement}), or\n` +
+                "    - switch the run step to `uses: zernie/vigiles@v1` (the composite Action).");
+        }
+        else if (workflowUsesStaleApi(content)) {
+            if (plan.force) {
+                (0, node_fs_1.writeFileSync)(path, vigilesWorkflow(plan));
+                console.log(`✓ Regenerated ${rel} (was a stale bare \`npx vigiles\`)`);
+                return [rel];
+            }
+            console.log(`⚠ ${rel} is STALE — it runs a bare \`npx vigiles\`,\n` +
+                "  which is a no-op help screen now. CI is silently not validating anything. Fix it:\n" +
+                "    - re-run `vigiles init --force` to regenerate the workflow, or\n" +
+                "    - replace its run step with `uses: zernie/vigiles@v1` + `run: npx vigiles test`.");
         }
         else {
-            console.log("✓ .github/workflows/vigiles.yml already exists (up to date)");
+            console.log(`✓ ${rel} already exists (up to date)`);
         }
         return [];
     }
@@ -1461,6 +1513,51 @@ function harnessBinaryPresent(bin) {
         return false;
     }
 }
+/** Run a plan's auto-install commands; classify the result. */
+function runInstall(plan, exec) {
+    if (plan.commands.length === 0)
+        return "no-cli";
+    try {
+        for (const cmd of plan.commands) {
+            exec(cmd, { stdio: ["ignore", "pipe", "pipe"], timeout: 120000 });
+        }
+        return "ok";
+    }
+    catch {
+        return "failed";
+    }
+}
+/**
+ * Report a plan's outcome. On anything but success, be LOUD — when an AGENT runs
+ * `init` (no human at the TTY), a quiet "Install vigiles:" hint followed by
+ * `/plugin` slash commands is a trap: the agent can't run a TUI slash command,
+ * so the plugin silently never installs. Surface the failure as a warning AND
+ * lead with the shell-runnable CLI form (which an agent CAN run), keeping the
+ * slash commands clearly labelled as the in-TUI alternative for a human.
+ */
+function reportInstall(plan, outcome) {
+    if (outcome === "ok") {
+        console.log(plan.successMessage);
+        for (const note of plan.notes)
+            console.log(`  ${note}`);
+        return;
+    }
+    console.log(outcome === "failed"
+        ? `⚠ vigiles plugin auto-install for ${plan.harness} FAILED — the plugin (hooks + skills) is NOT installed.`
+        : `⚠ vigiles plugin for ${plan.harness} was NOT installed (the ${plan.harness} CLI isn't on PATH here).`);
+    if (plan.commands.length > 0) {
+        console.log("  Finish from a shell (an agent can run these):");
+        for (const cmd of plan.commands)
+            console.log(`    ${cmd}`);
+    }
+    if (plan.manualSteps.length > 0) {
+        console.log("  Or inside the Claude Code TUI (a human, not an agent):");
+        for (const step of plan.manualSteps)
+            console.log(`    ${step}`);
+    }
+    for (const note of plan.notes)
+        console.log(`  ${note}`);
+}
 /**
  * Install vigiles's skills/hooks for the chosen harness(es) via the per-harness
  * `planPluginInstall` decision — Claude Code through the GLOBAL plugin
@@ -1474,26 +1571,7 @@ function installPlugins(harnesses) {
     });
     for (const plan of plans) {
         console.log("");
-        let installed = false;
-        if (plan.commands.length > 0) {
-            try {
-                for (const cmd of plan.commands) {
-                    exec(cmd, { stdio: ["ignore", "pipe", "pipe"], timeout: 120000 });
-                }
-                console.log(plan.successMessage);
-                installed = true;
-            }
-            catch {
-                // Fall through to the manual instructions below.
-            }
-        }
-        if (!installed) {
-            console.log(`Install vigiles for ${plan.harness}:`);
-            for (const step of plan.manualSteps)
-                console.log(`    ${step}`);
-        }
-        for (const note of plan.notes)
-            console.log(`  ${note}`);
+        reportInstall(plan, runInstall(plan, exec));
     }
 }
 /** Add/upgrade `vigiles` in the project's `devDependencies` (and move it out of
@@ -1725,7 +1803,7 @@ function checkUntestedSurfaces(config, silent) {
 }
 /**
  * Apply the configured coverage thresholds. Returns the number of failing
- * thresholds (so the audit can fail CI when severity is "error").
+ * thresholds (so the lint can fail CI when severity is "error").
  *
  * Loads specs directly via loadSpec() when the scripts threshold is set —
  * avoids depending on a pre-built `dist/` tree, which the setup-generated
@@ -1934,7 +2012,7 @@ function printUsage(command) {
     console.log("vigiles — compile typed specs to instruction files");
     console.log("");
     console.log("Commands:");
-    console.log("  vigiles init [flags]           Setup project (--lint, --test, --harness=, --strict, --no-gha)");
+    console.log("  vigiles init [flags]           Setup project (--lint, --test, --harness=, --strict, --no-gha, --force)");
     console.log("  vigiles compile [files...]     Compile .spec.ts → .md");
     console.log("  vigiles lint [files...]        Verify references, find gaps in instruction files");
     console.log("  vigiles test [files...]        Run *.harness.mjs deterministic harness tests");
@@ -1960,11 +2038,11 @@ function printUsage(command) {
 // Main
 // ---------------------------------------------------------------------------
 /**
- * Emit GitHub Actions annotations for an audit report. Skipped when --json or
+ * Emit GitHub Actions annotations for an lint report. Skipped when --json or
  * --summary is active — those modes promise clean machine-readable stdout, and
  * ::error/::warning lines would contaminate output parsed as JSON.
  */
-function annotateAuditForGitHub(report, flags) {
+function annotateLintForGitHub(report, flags) {
     const structuredOutput = flags.includes("--json") || flags.includes("--summary");
     if (!isGitHubActions() || structuredOutput)
         return;
@@ -1972,7 +2050,7 @@ function annotateAuditForGitHub(report, flags) {
         ghAnnotate("error", `${String(report.hashErrors)} compiled file(s) with stale hash — run vigiles compile`);
     }
     if (report.validationErrors > 0) {
-        ghAnnotate("error", `${String(report.validationErrors)} spec validation failure(s) — see audit output`);
+        ghAnnotate("error", `${String(report.validationErrors)} spec validation failure(s) — see lint output`);
     }
     if (report.duplicatePairs > 0) {
         ghAnnotate("warning", `${String(report.duplicatePairs)} near-duplicate rule pair(s) detected — consider merging`);
@@ -2303,9 +2381,9 @@ async function main() {
         case "lint": {
             // lint = verify references + discover + guidance count
             const flags = args.slice(1).filter((a) => a.startsWith("--"));
-            const report = await audit(restArgs, flags, config);
-            annotateAuditForGitHub(report, flags);
-            const exitCode = auditExitCode(report);
+            const report = await runLint(restArgs, flags, config);
+            annotateLintForGitHub(report, flags);
+            const exitCode = lintExitCode(report);
             if (exitCode !== 0) {
                 process.exit(exitCode);
             }

package/dist/core/compile.d.ts

@@ -92,7 +92,7 @@ export interface CompileAgentResult {
 /**
  * Compile an AgentSpec into a subagent markdown file with YAML frontmatter.
  * Verifies the tool contract and the body's references; the marks the body
- * carries (`vigiles:symbol`, file/cmd refs) are the same ones `audit` re-checks.
+ * carries (`vigiles:symbol`, file/cmd refs) are the same ones `lint` re-checks.
  */
 export declare function compileAgent(spec: AgentSpec, options: {
     basePath?: string;

package/dist/core/compile.js

@@ -802,7 +802,7 @@ function renderAgentRules(rules) {
 /**
  * Compile an AgentSpec into a subagent markdown file with YAML frontmatter.
  * Verifies the tool contract and the body's references; the marks the body
- * carries (`vigiles:symbol`, file/cmd refs) are the same ones `audit` re-checks.
+ * carries (`vigiles:symbol`, file/cmd refs) are the same ones `lint` re-checks.
  */
 function compileAgent(spec, options) {
     const basePath = options.basePath ?? process.cwd();

package/dist/core/compose.d.ts

@@ -13,7 +13,7 @@
  * This detector is pure filesystem inspection — the same deterministic-detector
  * shape as `orphans.ts` / `test-coverage.ts`. It reports which tools are present
  * and any target that collides with a file the tool regenerates, so `vigiles
- * audit` can warn before the integrity guarantee is lost.
+ * lint` can warn before the integrity guarantee is lost.
  */
 /** A rule-sync tool vigiles should compose with rather than reimplement. */
 export type SyncToolName = "ruler" | "rulesync";

package/dist/core/compose.js

@@ -14,7 +14,7 @@
  * This detector is pure filesystem inspection — the same deterministic-detector
  * shape as `orphans.ts` / `test-coverage.ts`. It reports which tools are present
  * and any target that collides with a file the tool regenerates, so `vigiles
- * audit` can warn before the integrity guarantee is lost.
+ * lint` can warn before the integrity guarantee is lost.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectSyncTools = detectSyncTools;

package/dist/core/generate-schema.d.ts

@@ -20,7 +20,7 @@ export interface GenerateSchemaOptions {
     basePath?: string;
     /**
      * Custom linters from `.vigilesrc.json` (`rulesDir`-backed). These aren't
-     * auto-discovered by `generate-types`, but `vigiles audit` resolves their
+     * auto-discovered by `generate-types`, but `vigiles lint` resolves their
      * rules via `checkLinterRule`, so the schema enum must include them too —
      * otherwise the YAML LSP false-flags a rule that CI accepts.
      */

package/dist/core/generate-schema.js

@@ -26,7 +26,7 @@ const generate_types_js_1 = require("./generate-types.js");
 /**
  * Rule references for config-declared custom linters. Mirrors
  * `checkLinterRule`'s rulesDir lookup (any file `<rule>.*` is a rule) so the
- * enum matches what `vigiles audit` accepts for these linters.
+ * enum matches what `vigiles lint` accepts for these linters.
  */
 function customRuleRefs(basePath, linters) {
     const refs = [];
@@ -84,7 +84,7 @@ function generateSchema(options = {}) {
                 properties: {
                     enforce: {
                         type: "array",
-                        description: "Linter rules to enforce, verified by `vigiles audit`.",
+                        description: "Linter rules to enforce, verified by `vigiles lint`.",
                         items: {
                             type: "object",
                             additionalProperties: false,
@@ -103,12 +103,12 @@ function generateSchema(options = {}) {
                     },
                     files: {
                         type: "array",
-                        description: "File paths referenced by this instruction file, verified to exist by `vigiles audit`.",
+                        description: "File paths referenced by this instruction file, verified to exist by `vigiles lint`.",
                         items: { type: "string" },
                     },
                     commands: {
                         type: "array",
-                        description: "Commands (npm scripts / script-runner invocations) referenced here, verified by `vigiles audit`.",
+                        description: "Commands (npm scripts / script-runner invocations) referenced here, verified by `vigiles lint`.",
                         items: { type: "string" },
                     },
                 },

package/dist/core/linters.js

@@ -461,7 +461,7 @@ function isEslintPluginRule(ruleName, basePath) {
 /**
  * Enumerate all rules for a CLI-based linter so `tryCliCheck` can emit
  * closest-match suggestions on typos. Result is cached per (linter,
- * basePath) so each linter's discovery CLI runs at most once per audit.
+ * basePath) so each linter's discovery CLI runs at most once per lint.
  */
 const CLI_RULE_SET_CACHE = new Map();
 function getCliRuleSet(linterName, basePath) {
@@ -561,7 +561,7 @@ function getCliRuleSet(linterName, basePath) {
 // The `vigiles/<id>` namespace lets specs declare mechanical checks that
 // vigiles itself runs (orphan docs, integrity, etc.) without delegating to
 // an external linter. Existence is verified at compile time against this
-// fixed catalog; the actual check runs at audit time.
+// fixed catalog; the actual check runs at lint time.
 // ---------------------------------------------------------------------------
 const VIGILES_INTERNAL_RULES = new Set(["orphan-docs"]);
 /** @internal */ function tryVigilesInternal(ctx) {

package/dist/core/orphans.js

@@ -28,6 +28,13 @@ const DEFAULT_IGNORE = [
     ".vigiles/**",
     ".git/**",
 ];
+/**
+ * A doc carrying this marker opts out of orphan detection — the inline escape
+ * hatch, mirroring `vigiles-disable require-spec` and `vigiles:ignore-test`.
+ * Use it for an intentionally-unreferenced doc (a changelog, a top-level index)
+ * that nothing else links to but is not rot.
+ */
+const DISABLE_RE = /<!--\s*vigiles-disable\s+orphan-docs\s*-->/;
 // Match markdown links ](path.md) or ](path.md#anchor)
 const LINK_RE = /\]\(([^)\s]+\.md)(?:#[^)]*)?\)/g;
 // Match backtick code spans wrapping a path ending in .md
@@ -35,6 +42,27 @@ const BACKTICK_RE = /`([^`\s]+\.md)`/g;
 function normalizePath(p) {
     return p.replace(/^\.\//, "").replace(/\\/g, "/");
 }
+/** True when a doc opts out of orphan detection via the inline disable marker. */
+function isOrphanExempt(absPath) {
+    try {
+        return DISABLE_RE.test((0, node_fs_1.readFileSync)(absPath, "utf-8"));
+    }
+    catch {
+        return false; // unreadable — treat like any other doc
+    }
+}
+/** Discover docs under `include`, dropping any that carry the inline opt-out. */
+function collectDocs(basePath, include, ignore) {
+    const docs = new Set();
+    for (const pattern of include) {
+        for (const p of (0, glob_1.globSync)(pattern, { cwd: basePath, ignore: [...ignore] })) {
+            if (isOrphanExempt((0, node_path_1.resolve)(basePath, p)))
+                continue;
+            docs.add(normalizePath(p));
+        }
+    }
+    return docs;
+}
 function extractRefs(content) {
     const refs = [];
     for (const m of content.matchAll(LINK_RE))
@@ -43,6 +71,23 @@ function extractRefs(content) {
         refs.push(normalizePath(m[1]));
     return refs;
 }
+/**
+ * Repo-root-relative targets a reference could mean, from a given source file.
+ * Markdown links are conventionally **file-relative** (a `[x](foo.md)` in
+ * `research/README.md` points at `research/foo.md`, and `../docs/x.md` walks up),
+ * but docs also write **root-relative** paths (`research/foo.md` from anywhere).
+ * We credit both so a real link is never miscounted as an orphan.
+ */
+function refTargets(sourcePath, ref) {
+    const targets = new Set([ref]); // root-relative reading
+    const dir = sourcePath.includes("/")
+        ? sourcePath.slice(0, sourcePath.lastIndexOf("/"))
+        : "";
+    // file-relative reading: resolve against the source's directory.
+    const resolved = normalizePath(node_path_1.posix.normalize(dir ? `${dir}/${ref}` : ref));
+    targets.add(resolved);
+    return [...targets];
+}
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -63,12 +108,7 @@ function findOrphanDocs(options = {}) {
     const include = options.include ?? DEFAULT_INCLUDE;
     const userExclude = options.exclude ?? [];
     const ignore = [...DEFAULT_IGNORE, ...userExclude];
-    const allDocs = new Set();
-    for (const pattern of include) {
-        const found = (0, glob_1.globSync)(pattern, { cwd: basePath, ignore });
-        for (const p of found)
-            allDocs.add(normalizePath(p));
-    }
+    const allDocs = collectDocs(basePath, include, ignore);
     const allMarkdown = (0, glob_1.globSync)("**/*.md", {
         cwd: basePath,
         ignore: [...DEFAULT_IGNORE],
@@ -83,15 +123,17 @@ function findOrphanDocs(options = {}) {
         catch {
             continue;
         }
-        for (const target of extractRefs(content)) {
-            if (target === source)
-                continue;
-            let sources = referencedBy.get(target);
-            if (!sources) {
-                sources = new Set();
-                referencedBy.set(target, sources);
+        for (const rawRef of extractRefs(content)) {
+            for (const target of refTargets(source, rawRef)) {
+                if (target === source)
+                    continue;
+                let sources = referencedBy.get(target);
+                if (!sources) {
+                    sources = new Set();
+                    referencedBy.set(target, sources);
+                }
+                sources.add(source);
             }
-            sources.add(source);
         }
     }
     const orphans = [];
@@ -119,6 +161,7 @@ function formatOrphanReport(report) {
     ];
     for (const o of report.orphans)
         lines.push(`    ${o}`);
+    lines.push("  Fix: link each from another .md (README, a spec's Key Files, or a doc).", "  To silence: add `<!-- vigiles-disable orphan-docs -->` to the doc, or", "  exclude it via .vigilesrc.json → `orphans.exclude` (or narrow `orphans.include`).");
     return lines.join("\n");
 }
 //# sourceMappingURL=orphans.js.map

package/dist/core/proofs.js

@@ -188,7 +188,7 @@ function findSimilarRules(rules, threshold = 0.5) {
  *
  * Throws a structured error on unknown rule kinds so that the caller (e.g.
  * runProofSuite) can surface a clear proof failure rather than letting an
- * `undefined` propagate into compressedSize and crash the audit.
+ * `undefined` propagate into compressedSize and crash the computation.
  */
 function ruleToText(rule) {
     switch (rule._kind) {

package/dist/core/refs.d.ts

@@ -29,7 +29,7 @@ export declare function symbolRefs(markdown: string): SymbolRef[];
 export declare function verifySymbolRefs(markdown: string, basePath: string): SymbolRefError[];
 /**
  * Whether a span is a **linter-rule reference** that ought to be marked
- * (`enforce()` / inline `<!-- vigiles:enforce -->`) so the audit can verify the
+ * (`enforce()` / inline `<!-- vigiles:enforce -->`) so the lint can verify the
  * rule exists AND is enabled. High-signal only: a slash-scoped name with no file
  * extension. A function-call form `` `foo(args)` `` is reduced to its callee.
  *

package/dist/core/refs.js

@@ -109,7 +109,7 @@ const IGNORE_FILE = /<!--\s*vigiles:ignore-file\s*-->/;
 const IGNORE_LINE = /<!--\s*vigiles:ignore\s*-->/;
 /**
  * Whether a span is a **linter-rule reference** that ought to be marked
- * (`enforce()` / inline `<!-- vigiles:enforce -->`) so the audit can verify the
+ * (`enforce()` / inline `<!-- vigiles:enforce -->`) so the lint can verify the
  * rule exists AND is enabled. High-signal only: a slash-scoped name with no file
  * extension. A function-call form `` `foo(args)` `` is reduced to its callee.
  *
@@ -152,7 +152,7 @@ function collectRefIssues(markdown, basePath) {
     for (const u of unmarkedCodeRefs(markdown)) {
         out.push(`line ${String(u.line)}: \`${u.text}\` is an unmarked linter-rule ` +
             `reference — mark it as \`enforce("${u.text}")\` (typed spec) or ` +
-            `\`<!-- vigiles:enforce ${u.text} -->\` (markdown) so audit can verify ` +
+            `\`<!-- vigiles:enforce ${u.text} -->\` (markdown) so lint can verify ` +
             `it exists and is enabled, or add <!-- vigiles:ignore --> if it is prose`);
     }
     return out;

package/dist/core/sidecar.d.ts

@@ -4,7 +4,7 @@
  * Used by the post-session audit to know which targets exist and which
  * spec source / inputs each one tracks. The compile pipeline writes
  * these whenever a spec is built; readers (currently only session.ts)
- * consume them at audit time.
+ * consume them at verification time.
  *
  * This module is the ONLY place sidecars live now — the freshness rule
  * doesn't depend on them anymore.

package/dist/core/sidecar.js

@@ -5,7 +5,7 @@
  * Used by the post-session audit to know which targets exist and which
  * spec source / inputs each one tracks. The compile pipeline writes
  * these whenever a spec is built; readers (currently only session.ts)
- * consume them at audit time.
+ * consume them at verification time.
  *
  * This module is the ONLY place sidecars live now — the freshness rule
  * doesn't depend on them anymore.

package/dist/core/spec.d.ts

@@ -156,7 +156,7 @@ export declare function cmd(command: NoInfer<StrictCmd>): CmdRef;
  * Reference a symbol defined in a file — verified at compile time that the
  * named file exists AND defines the named symbol (via ast-grep, cross-language).
  * Compiles to the file-qualified inline form `` `file#symbol` `` so the markdown
- * `audit` / `refs-hook` re-verify the same reference.
+ * `lint` / `refs-hook` re-verify the same reference.
  */
 export declare function symbol(file: NoInfer<StrictFile>, name: string): SymbolRef;
 /**

package/dist/core/spec.js

@@ -93,7 +93,7 @@ function cmd(command) {
  * Reference a symbol defined in a file — verified at compile time that the
  * named file exists AND defines the named symbol (via ast-grep, cross-language).
  * Compiles to the file-qualified inline form `` `file#symbol` `` so the markdown
- * `audit` / `refs-hook` re-verify the same reference.
+ * `lint` / `refs-hook` re-verify the same reference.
  */
 function symbol(file, name) {
     return { _ref: "symbol", file: file, symbol: name };

package/dist/core/types.d.ts

@@ -97,7 +97,7 @@ export interface RulesConfig {
     "untested-surface"?: RuleWithOptions<TestCoverageConfig>;
     /**
      * Nudge (or block) when an instruction file has code-shaped references that
-     * aren't expressed as vigiles marks (so the audit can't verify them), or a
+     * aren't expressed as vigiles marks (so the lint can't verify them), or a
      * `vigiles:symbol` mark that points at a missing symbol. Drives the
      * PostToolUse refs-hook: "warn" (default) → a non-blocking nudge, "error" →
      * block the edit, false → off.