vigiles 12.8.0 → 13.0.0

package/dist/cli.js

@@ -1011,23 +1011,42 @@ async function runLint(restArgs, flags, config) {
     }
     // 6. Coverage thresholds (gates CI when severity is "error")
     const coverageErrors = await checkCoverageThresholds(coverage, config, silent);
-    // 7. Orphan docs check — find .md files no other markdown references.
-    // Enforces the `vigiles/orphan-docs` built-in rule when declared in a
-    // spec. Include/exclude come from .vigilesrc.json#orphans (tsconfig-
-    // style globs); default include is docs/ + research/ for the
-    // vigiles-repo convention.
+    // 7. Orphan docs check — OPT-IN (the `orphans` block in .vigilesrc.json is
+    // the on-switch). "Unreferenced" only means "rot" for a hand-cross-linked
+    // corpus; on a nav-managed doc site (Docusaurus/MkDocs) the page graph lives
+    // in config, not inline links, so an unconditional scan is ~all false
+    // positives there (an OSS sweep confirmed it). So we scan only when the repo
+    // 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;
     if (!silent)
         console.log("\nOrphan docs check:\n");
-    const orphanReport = (0, orphans_js_1.findOrphanDocs)({
-        basePath: process.cwd(),
-        include: config?.orphans?.include,
-        exclude: config?.orphans?.exclude,
-    });
-    if (!silent) {
-        for (const line of (0, orphans_js_1.formatOrphanReport)(orphanReport).split("\n")) {
-            console.log(`  ${line}`);
+    let orphanReport = {
+        include: [],
+        totalDocs: 0,
+        referencedDocs: [],
+        orphans: [],
+    };
+    if (orphansCfg) {
+        orphanReport = (0, orphans_js_1.findOrphanDocs)({
+            basePath: process.cwd(),
+            include: orphansCfg.include,
+            exclude: orphansCfg.exclude,
+            // Exempt every registered harness's surface files (instruction file,
+            // SKILL.md, subagents, commands) as orphan candidates — layout-driven so
+            // core carries no harness literal (see src/core/orphans.ts).
+            layouts: adapter_registry_js_1.ADAPTERS.map((a) => a.layout),
+        });
+        if (!silent) {
+            for (const line of (0, orphans_js_1.formatOrphanReport)(orphanReport).split("\n")) {
+                console.log(`  ${line}`);
+            }
         }
     }
+    else if (!silent) {
+        console.log("  ⊘ not enabled — add an `orphans` block to .vigilesrc.json to opt in (scans docs/ by default)");
+    }
     // 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/.

package/dist/core/orphans.d.ts

@@ -11,6 +11,7 @@
  * references (markdown links and backtick paths). Works against source
  * README plus compiled CLAUDE.md — no spec loading required.
  */
+import type { PluginLayout } from "./layout.js";
 export interface OrphanReport {
     /** Include globs that were scanned. */
     readonly include: readonly string[];
@@ -25,14 +26,22 @@ export interface FindOrphansOptions {
     /** Repository root. Defaults to `process.cwd()`. */
     readonly basePath?: string;
     /**
-     * Glob patterns of `.md` files to scan. Defaults to
-     * `["docs/**\/*.md", "research/**\/*.md"]` — vigiles-repo convention.
-     * Set to `[]` to disable scanning entirely. Set to your project's
-     * doc directory globs (e.g. `["wiki/**\/*.md"]`) to override.
+     * Glob patterns of `.md` files to scan. Defaults to `["docs/**\/*.md"]`
+     * (`docs/` is the near-universal convention; a vigiles-specific dir like
+     * `research/` is opted into explicitly). Set to `[]` to disable scanning,
+     * or to your project's doc globs (e.g. `["wiki/**\/*.md"]`) to override.
      */
     readonly include?: readonly string[];
     /** Glob patterns to exclude within the include scope. */
     readonly exclude?: readonly string[];
+    /**
+     * Harnesses whose surface files (instruction file, `SKILL.md`, subagents,
+     * commands) are load-bearing by location and thus never orphan CANDIDATES
+     * (still counted as referencers). Injected by the CLI from the registered
+     * adapters so core stays harness-agnostic; a direct caller passes its own.
+     * Omitted ⇒ only the universal `SKILL.md` convention is exempt.
+     */
+    readonly layouts?: readonly PluginLayout[];
 }
 /**
  * Find docs under `include` globs that no other markdown file references.
@@ -43,8 +52,9 @@ export interface FindOrphansOptions {
  * links to itself is still an orphan.
  *
  * `include` and `exclude` are tsconfig-style glob arrays. Default include
- * is the vigiles-repo convention `["docs/**\/*.md", "research/**\/*.md"]`;
- * override per-project via `.vigilesrc.json` → `orphans.include`.
+ * is `["docs/**\/*.md"]` (the common convention); override per-project via
+ * `.vigilesrc.json` → `orphans.include` (whose presence also opts the repo
+ * into the scan — see the CLI gate in `vigiles lint`).
  */
 export declare function findOrphanDocs(options?: FindOrphansOptions): OrphanReport;
 /** Format an orphan report as human-readable text. */

package/dist/core/orphans.js

@@ -21,7 +21,7 @@ const glob_1 = require("glob");
 // ---------------------------------------------------------------------------
 // Internals
 // ---------------------------------------------------------------------------
-const DEFAULT_INCLUDE = ["docs/**/*.md", "research/**/*.md"];
+const DEFAULT_INCLUDE = ["docs/**/*.md"];
 const DEFAULT_IGNORE = [
     "node_modules/**",
     "dist/**",
@@ -35,24 +35,48 @@ const DEFAULT_IGNORE = [
  * that nothing else links to but is not rot.
  */
 const DISABLE_RE = /<!--\s*vigiles-disable\s+orphan-docs\s*-->/;
+/** The one universal cross-harness skill-entry filename (CC + Codex). */
+const SKILL_FILE = "SKILL.md";
 /**
- * Files the HARNESS loads directly — an instruction file (`CLAUDE.md` /
- * `AGENTS.md`), a skill (`SKILL.md`), a subagent (`agents/*.md`), or a slash
- * command (`commands/*.md`) — are load-bearing by their NAME/LOCATION, not
- * because another `.md` links to them. They are categorically NOT docs, so they
- * are never orphans, even if a project broadens `orphans.include` to scan the
- * whole repo. (They are still scanned as REFERENCERS, so a real doc that only
- * a CLAUDE.md links to is still credited — this exemption only removes them from
- * the orphan-CANDIDATE set.)
+ * Files the HARNESS loads directly — its instruction file
+ * (`layout.instructionFile`, e.g. `CLAUDE.md` / `AGENTS.md`), a skill
+ * (`SKILL.md`), a subagent (`<agentDir>/*.md`), or a slash command
+ * (`<commandDir>/*.md`) — are load-bearing by their NAME/LOCATION, not because
+ * another `.md` links to them. They are categorically NOT docs, so they are
+ * never orphans even when `orphans.include` broadens to the whole repo.
+ *
+ * The surface names come from the INJECTED layouts, so core stays
+ * harness-agnostic — no Claude Code literal here; the CLI passes every
+ * registered adapter's layout, and `SKILL.md` is the one universal convention.
+ * (They are still scanned as REFERENCERS, so a real doc that only a `CLAUDE.md`
+ * links to is still credited — this exemption only removes them from the
+ * orphan-CANDIDATE set.)
  */
-function isHarnessLoadedFile(path) {
+function isHarnessLoadedFile(path, layouts) {
     const norm = normalizePath(path);
     const base = norm.slice(norm.lastIndexOf("/") + 1);
-    if (base === "CLAUDE.md" || base === "AGENTS.md" || base === "SKILL.md") {
+    if (base === SKILL_FILE)
         return true;
+    for (const layout of layouts) {
+        if (base === layout.instructionFile)
+            return true;
+        // Subagent / slash-command surfaces live at a REAL surface root — the repo
+        // root, the user-surface root (e.g. `.claude/`), or the materialize root —
+        // NOT any nested dir that merely shares the name. A doc under `docs/prompts/`
+        // is documentation, not Codex's `prompts` command surface.
+        const roots = [
+            "",
+            ...[layout.userSurfaceRoot, layout.materializeRoot]
+                .filter((r) => !!r)
+                .map((r) => `${r}/`),
+        ];
+        for (const dir of [layout.agentDir, layout.commandDir]) {
+            if (dir && roots.some((r) => norm.startsWith(`${r}${dir}/`))) {
+                return true;
+            }
+        }
     }
-    // Subagent / slash-command surfaces the harness enumerates by directory.
-    return /(^|\/)(agents|commands)\//.test(norm);
+    return false;
 }
 // Match markdown links ](path.md) or ](path.md#anchor)
 const LINK_RE = /\]\(([^)\s]+\.md)(?:#[^)]*)?\)/g;
@@ -71,12 +95,12 @@ function isOrphanExempt(absPath) {
     }
 }
 /** Discover docs under `include`, dropping any that carry the inline opt-out. */
-function collectDocs(basePath, include, ignore) {
+function collectDocs(basePath, include, ignore, layouts) {
     const docs = new Set();
     for (const pattern of include) {
         for (const p of (0, glob_1.globSync)(pattern, { cwd: basePath, ignore: [...ignore] })) {
-            if (isHarnessLoadedFile(p))
-                continue; // instruction files are never orphans
+            if (isHarnessLoadedFile(p, layouts))
+                continue; // harness files are never orphans
             if (isOrphanExempt((0, node_path_1.resolve)(basePath, p)))
                 continue;
             docs.add(normalizePath(p));
@@ -121,15 +145,17 @@ function refTargets(sourcePath, ref) {
  * links to itself is still an orphan.
  *
  * `include` and `exclude` are tsconfig-style glob arrays. Default include
- * is the vigiles-repo convention `["docs/**\/*.md", "research/**\/*.md"]`;
- * override per-project via `.vigilesrc.json` → `orphans.include`.
+ * is `["docs/**\/*.md"]` (the common convention); override per-project via
+ * `.vigilesrc.json` → `orphans.include` (whose presence also opts the repo
+ * into the scan — see the CLI gate in `vigiles lint`).
  */
 function findOrphanDocs(options = {}) {
     const basePath = options.basePath ?? process.cwd();
     const include = options.include ?? DEFAULT_INCLUDE;
     const userExclude = options.exclude ?? [];
     const ignore = [...DEFAULT_IGNORE, ...userExclude];
-    const allDocs = collectDocs(basePath, include, ignore);
+    const layouts = options.layouts ?? [];
+    const allDocs = collectDocs(basePath, include, ignore, layouts);
     const allMarkdown = (0, glob_1.globSync)("**/*.md", {
         cwd: basePath,
         ignore: [...DEFAULT_IGNORE],

package/dist/core/rule-meta.js

@@ -256,10 +256,10 @@ exports.RULE_META = {
     // --- Docs hygiene ---------------------------------------------------------
     "orphan-docs": {
         id: "orphan-docs",
-        bucket: "external-decidable",
+        bucket: "heuristic-behavioral",
         surface: ["docs"],
         defaultSeverity: "warn",
-        summary: "Every docs/ + research/ .md is referenced by another .md.",
+        summary: "Opt-in: a doc in a configured dir (default docs/) that no other .md references.",
         detector: "findOrphanDocs",
     },
 };

package/dist/core/types.d.ts

@@ -54,13 +54,19 @@ export interface CoverageThresholds {
     /** Min % of npm scripts documented in spec commands. */
     scripts?: number;
 }
-/** Options for the orphan-docs check. */
+/**
+ * Options for the orphan-docs check. The PRESENCE of this block in
+ * `.vigilesrc.json` OPTS THE REPO IN — the scan is off unless declared,
+ * because "unreferenced" only means "rot" for a hand-cross-linked corpus,
+ * not for a nav-managed doc site (Docusaurus/MkDocs) where the page graph
+ * lives in config. `include` is the optional dir override.
+ */
 export interface OrphansConfig {
     /**
      * Glob patterns of `.md` files to scan for orphans. A doc is "orphaned"
-     * when no other markdown file references it. Defaults to vigiles-repo
-     * convention: `["docs/**\/*.md", "research/**\/*.md"]`. Set to `[]` to
-     * disable orphan detection entirely.
+     * when no other markdown file references it. Omitted → `["docs/**\/*.md"]`
+     * (the common convention); add your own dirs (e.g. a `research/` notes
+     * tree) explicitly. Set to `[]` to opt in but scan nothing.
      */
     include?: readonly string[];
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "12.8.0",
+  "version": "13.0.0",
   "description": "Lint & test the harness your AI agent runs on — verify the references in your CLAUDE.md / AGENTS.md and test that your hooks and skills actually work.",
   "keywords": [
     "claude-code",