vigiles 29.0.0 → 30.0.0

package/dist/scan-trigger-suggest.d.ts

@@ -11,27 +11,6 @@
  * not through the report verb. The IO (prompt / run / remember) lives in the CLI;
  * this is the pure decision + helpers.
  */
-/** Only the env vars that signal a reachable model (parse, don't validate). */
-export interface ModelEnv {
-    readonly ANTHROPIC_API_KEY?: string;
-    readonly CLAUDECODE?: string;
-    readonly CLAUDE_CODE_ENTRYPOINT?: string;
-}
-/**
- * Is a real model reachable for the trigger tier? Either a metered API key
- * (`ANTHROPIC_API_KEY`), OR an authenticated Claude Code session (`CLAUDECODE=1`
- * / `CLAUDE_CODE_ENTRYPOINT`, web/desktop/CLI) — the latter drives the `claude`
- * CLI on the user's subscription, no key needed and $0 metered. A tiny env-only
- * predicate (not a live probe), so it never spends a token just to decide.
- */
-export declare function hasModelAccess(env: ModelEnv): boolean;
-/**
- * Is the reachable model METERED (a paid API key) rather than a subscription?
- * Only affects the consent DISCLOSURE wording (a metered key bills per token; a
- * subscription is $0 metered) — the run/skip decision itself is consent-driven,
- * not metered-driven.
- */
-export declare function isMeteredAccess(env: ModelEnv): boolean;
 /** Why the executing checks were skipped (drives the "not run" nudge). */
 export type ExecuteSkipReason = "nothing" | "headless" | "remembered-no";
 /**

package/dist/scan-trigger-suggest.js

@@ -13,32 +13,9 @@
  * this is the pure decision + helpers.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.hasModelAccess = hasModelAccess;
-exports.isMeteredAccess = isMeteredAccess;
 exports.decideExecute = decideExecute;
 exports.formatExecuteSkip = formatExecuteSkip;
 exports.scaffoldTriggerPrompts = scaffoldTriggerPrompts;
-/**
- * Is a real model reachable for the trigger tier? Either a metered API key
- * (`ANTHROPIC_API_KEY`), OR an authenticated Claude Code session (`CLAUDECODE=1`
- * / `CLAUDE_CODE_ENTRYPOINT`, web/desktop/CLI) — the latter drives the `claude`
- * CLI on the user's subscription, no key needed and $0 metered. A tiny env-only
- * predicate (not a live probe), so it never spends a token just to decide.
- */
-function hasModelAccess(env) {
-    return Boolean(env.ANTHROPIC_API_KEY ||
-        env.CLAUDECODE === "1" ||
-        env.CLAUDE_CODE_ENTRYPOINT);
-}
-/**
- * Is the reachable model METERED (a paid API key) rather than a subscription?
- * Only affects the consent DISCLOSURE wording (a metered key bills per token; a
- * subscription is $0 metered) — the run/skip decision itself is consent-driven,
- * not metered-driven.
- */
-function isMeteredAccess(env) {
-    return Boolean(env.ANTHROPIC_API_KEY);
-}
 /**
  * Decide what `audit` does with the executing checks. Total + pure; the first
  * matching rule wins. There is NO execution flag — `audit` is a local report, so

package/dist/scan.d.ts

@@ -11,7 +11,7 @@
  * need to RUN the plugin (observed egress under the sandbox, real trigger-rate)
  * stack on top later; this core stays pure so it runs anywhere in CI for free.
  */
-import type { PluginLayout } from "./core/layout.js";
+import { type PluginLayout } from "./core/layout.js";
 import type { ExcludeSet } from "./exclude.js";
 import type { HarnessDialect } from "./core/dialect.js";
 import type { ToolIssue } from "./core/tool-contract.js";
@@ -412,7 +412,7 @@ export interface ScanHarness {
     readonly roots: readonly string[];
 }
 /** Scan a plugin/repo directory and report its surfaces + structural issues. */
-export declare function scanPlugin(dir: string, layout?: PluginLayout, dialect?: HarnessDialect, opts?: {
+export declare function scanPlugin(dir: string, layout: PluginLayout, dialect: HarnessDialect, opts?: {
     sharedDirs?: readonly string[];
     sharedDirsRoot?: string;
     /**
@@ -492,7 +492,7 @@ export interface MarketplaceInfo {
  * marketplace. The source of truth behind {@link expandMarketplace} and the
  * curated-marketplace report in `vigiles audit`.
  */
-export declare function inspectMarketplace(dir: string, layout?: PluginLayout): MarketplaceInfo | null;
+export declare function inspectMarketplace(dir: string, layout: PluginLayout): MarketplaceInfo | null;
 /**
  * If `dir` is a plugin MARKETPLACE (a `marketplace.json` beside the layout's
  * plugin manifest, e.g. `.claude-plugin/marketplace.json`), expand it into the
@@ -501,6 +501,6 @@ export declare function inspectMarketplace(dir: string, layout?: PluginLayout):
  * on disk). Used by `vigiles audit` to rank a whole marketplace — wshobson/agents
  * alone ships 80+ plugins under one `marketplace.json`. See {@link inspectMarketplace}.
  */
-export declare function expandMarketplace(dir: string, layout?: PluginLayout): string[] | null;
+export declare function expandMarketplace(dir: string, layout: PluginLayout): string[] | null;
 export declare function formatScanReport(r: ScanReport): string;
 //# sourceMappingURL=scan.d.ts.map

package/dist/scan.js

@@ -40,11 +40,20 @@ const node_path_1 = require("node:path");
 // Claude Code default), and only the generic one takes the `ExcludeSet` that
 // makes `.vigilesrc.json#exclude` reach surface discovery.
 const plugin_loader_js_1 = require("./plugin-loader.js");
-const layout_js_1 = require("./adapters/claude-code/layout.js");
-const dialect_js_1 = require("./adapters/claude-code/dialect.js");
+// 🔴 THIS MODULE NO LONGER IMPORTS AN ADAPTER, and that is the point of the
+// change rather than tidiness. It is listed as a harness-agnostic detector and
+// it used to import `claudeCodeLayout` + `claudeCodeDialect` to DEFAULT five
+// parameters with. Neither of the other two fences could see it —
+// `boundaries/dependencies` deliberately leaves this file unclassified, and the
+// CC-literal rule's `\.claude` needs the dot while this path spells
+// `/claude-code/` — so it took a third rule to find, and two per-line disables
+// to live with. The default belongs to the CALLER: the CLI already resolves an
+// adapter before every one of these calls, and passing it is what removes the
+// import rather than hiding it.
 const plugin_loader_js_2 = require("./plugin-loader.js");
 const score_core_js_1 = require("./score-core.js");
 const skill_refs_js_1 = require("./skill-refs.js");
+const layout_js_1 = require("./core/layout.js");
 const hook_events_js_1 = require("./core/hook-events.js");
 const mcp_config_js_1 = require("./core/mcp-config.js");
 const agent_plugins_js_1 = require("./core/agent-plugins.js");
@@ -145,8 +154,8 @@ function ownTestSignalOnDisk(dir) {
     });
 }
 /** Scan a plugin/repo directory and report its surfaces + structural issues. */
-function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts = {}) {
-    const lay = layout ?? layout_js_1.claudeCodeLayout;
+function scanPlugin(dir, layout, dialect, opts = {}) {
+    const lay = layout;
     // The declared harnesses, or the single positional one — so every path below
     // is the multi-harness path and a one-entry list is not a second code path.
     const declared = opts.harnesses && opts.harnesses.length > 0
@@ -181,6 +190,12 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts
     const allHookEventIssues = (0, hook_events_js_1.verifyHookEvents)(eventNames, dialect);
     const hookEventIssues = (0, hook_events_js_1.scoredIssues)(allHookEventIssues);
     const instructionFile = instructionHarness.layout.instructionFile;
+    // The BOUNDED candidate set, read once and handed to the harness that owns
+    // the instruction file this repo has. It replaced `readAlwaysLoaded`, which
+    // expanded an ADAPTER's globs by walking the whole tree; the bound and the
+    // classification are now separate jobs held by separate modules, and only the
+    // second is the adapter's. See `core/instruction-chain.ts`.
+    const instructionFiles = (0, surface_discovery_fs_js_1.boundedInstructionFiles)((0, node_path_1.resolve)(dir), instructionHarness.layout, opts.excludes);
     const instructions = loaded.files[instructionFile] !== undefined
         ? {
             file: instructionFile,
@@ -195,7 +210,7 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts
     });
     const skills = (0, scan_core_js_1.scanSkills)(loaded.files, cls, {
         root: (0, node_path_1.resolve)(dir),
-        materializeRoot: lay.materializeRoot,
+        materializeRoot: (0, layout_js_1.materializePrefix)(lay),
         dialect,
         sources: loaded.sources,
         sharedDirs: opts.sharedDirs,
@@ -269,10 +284,14 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts
             roots: h.roots,
         }))),
         pluginLayoutIssues: (0, plugin_dir_layout_js_1.pluginDirLayoutIssues)((0, node_path_1.resolve)(dir, (0, node_path_1.dirname)(lay.manifestPath)), 
-        // The hooks dir is a misplaceable functional surface too, but it lives in
-        // the layout as a convention PATH (`hooks/hooks.json`), not in surfaceDirs
-        // — derive its first segment and dedupe so the detector watches it as well.
-        [...new Set([...lay.surfaceDirs, lay.hooksConventionPath.split("/")[0]])], { existsSync: node_fs_1.existsSync, isDirectory: nodeIsDirectory }),
+        // 🔴 THE HOOK SCRIPTS DIR IS NAMED, NOT DERIVED FROM A FILE PATH. This
+        // used to be `lay.hooksConventionPath.split("/")[0]`, copied here and into
+        // the twin: it reads `hooks` from `hooks/hooks.json`, but `.codex` from
+        // `.codex/hooks.json` — a REGISTRATION directory, not a scripts one, so
+        // for Codex the detector was watching the wrong directory entirely. The
+        // layout names it (`hookScriptsDir`) and `executableSourceDirs` joins it
+        // to the surfaces.
+        (0, layout_js_1.executableSourceDirs)(lay), { existsSync: node_fs_1.existsSync, isDirectory: nodeIsDirectory }),
         delegationTrifecta: (0, scan_core_js_1.collectDelegationTrifecta)(agents, dialect),
         hookBlockFindings: (0, event_capability_js_1.blockIneffectiveEventsOf)(dialect).length > 0
             ? (0, hook_block_ineffective_js_1.hookBlockIssues)((0, scan_core_js_1.collectHookBlockEntries)(hookRegs, (0, node_path_1.resolve)(dir), lay.pluginRootToken, node_fs_1.existsSync), {
@@ -302,7 +321,7 @@ function scanPlugin(dir, layout, dialect = dialect_js_1.claudeCodeDialect, opts
         // meaningful sum across two; reporting the one that owns the file that
         // exists is the only reading that is true of something.
         instructionWeight: instructionHarness.dialect.instructionBudget
-            ? (0, instruction_weight_js_1.weighInstructions)(readAlwaysLoaded(dir, instructionHarness.dialect.instructionBudget), instructionHarness.dialect.instructionBudget)
+            ? (0, instruction_weight_js_1.weighInstructions)(instructionHarness.layout.instructionChain(instructionFiles), instructionFiles, instructionHarness.dialect.instructionBudget)
             : null,
         untested: coverage.untested.length,
         untestedHarness: coverage.harness.untested.length,
@@ -351,7 +370,7 @@ function formatMcpContractReport(errors) {
  * marketplace. The source of truth behind {@link expandMarketplace} and the
  * curated-marketplace report in `vigiles audit`.
  */
-function inspectMarketplace(dir, layout = layout_js_1.claudeCodeLayout) {
+function inspectMarketplace(dir, layout) {
     const mpPath = (0, node_path_1.join)(dir, (0, node_path_1.dirname)(layout.manifestPath), "marketplace.json");
     if (!(0, node_fs_1.existsSync)(mpPath))
         return null;
@@ -404,7 +423,7 @@ function inspectMarketplace(dir, layout = layout_js_1.claudeCodeLayout) {
  * on disk). Used by `vigiles audit` to rank a whole marketplace — wshobson/agents
  * alone ships 80+ plugins under one `marketplace.json`. See {@link inspectMarketplace}.
  */
-function expandMarketplace(dir, layout = layout_js_1.claudeCodeLayout) {
+function expandMarketplace(dir, layout) {
     const mp = inspectMarketplace(dir, layout);
     return mp ? [...mp.onDisk] : null;
 }
@@ -497,63 +516,6 @@ function agentLines(a) {
     return lines;
 }
 /** Format a scan report as human-readable text. */
-/**
- * Read every unconditionally-loaded instruction file off disk.
- *
- * Separate from `loadPlugin` on purpose: that materializes the harness's
- * SURFACES (skills, agents, hooks), while this reads what the harness loads
- * before any surface is involved — including `.claude/rules/**`, which is
- * exactly the directory a repo relocates into when it wants the root file to
- * look smaller.
- */
-function readAlwaysLoaded(dir, budget) {
-    const out = {};
-    const walk = (rel) => {
-        const abs = (0, node_path_1.join)(dir, rel);
-        if (!(0, node_fs_1.existsSync)(abs) || !(0, node_fs_1.statSync)(abs).isDirectory())
-            return;
-        for (const entry of (0, node_fs_1.readdirSync)(abs)) {
-            const child = `${rel}/${entry}`;
-            if ((0, node_fs_1.statSync)((0, node_path_1.join)(dir, child)).isDirectory())
-                walk(child);
-            else
-                out[child] = (0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, child), "utf-8");
-        }
-    };
-    // `**/NAME` — Codex reads nested AGENTS.md root-to-leaf and they all pay into
-    // the SAME budget, so leaving them out under-reports in the one direction that
-    // matters: the harness truncates silently, and an under-report reads as "you
-    // are fine". Skipped dirs are the ones that are never the user's instructions
-    // and would dominate the walk.
-    const SKIP = new Set(["node_modules", ".git", "dist", "build", "vendor"]);
-    const findNested = (name, rel = "") => {
-        const abs = rel === "" ? dir : (0, node_path_1.join)(dir, rel);
-        if (!(0, node_fs_1.existsSync)(abs))
-            return;
-        for (const entry of (0, node_fs_1.readdirSync)(abs)) {
-            if (SKIP.has(entry) || entry.startsWith("."))
-                continue;
-            const child = rel === "" ? entry : `${rel}/${entry}`;
-            const childAbs = (0, node_path_1.join)(dir, child);
-            if ((0, node_fs_1.statSync)(childAbs).isDirectory())
-                findNested(name, child);
-            else if (entry === name && out[child] === undefined)
-                out[child] = (0, node_fs_1.readFileSync)(childAbs, "utf-8");
-        }
-    };
-    for (const glob of budget.alwaysLoaded) {
-        if (!glob.includes("*")) {
-            const abs = (0, node_path_1.join)(dir, glob);
-            if ((0, node_fs_1.existsSync)(abs) && (0, node_fs_1.statSync)(abs).isFile())
-                out[glob] = (0, node_fs_1.readFileSync)(abs, "utf-8");
-        }
-        else if (glob.endsWith("/**"))
-            walk(glob.slice(0, -3));
-        else if (glob.startsWith("**/"))
-            findNested(glob.slice(3));
-    }
-    return out;
-}
 /**
  * The weight report. States the SUM first and the per-file breakdown second,
  * because the sum is the number a reader can act on and the breakdown is only
@@ -565,20 +527,105 @@ function readAlwaysLoaded(dir, budget) {
  */
 function instructionWeightLines(w) {
     const g = (n) => String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
-    const head = `Always-loaded instructions: ${g(w.total)} ${w.unit} (budget ${g(w.limit)})`;
+    /** One breakdown row, with its provenance when it did not get in by location. */
+    const fileLine = (f) => `  ${g(f.size).padStart(9)}  ${f.path}` +
+        (f.via === undefined ? "" : `   via ${f.via.token} in ${f.via.from}`);
+    const head = `Always-loaded instructions: ${g(w.committedTotal)} ${w.unit} (budget ${g(w.limit)})`;
+    // 🔴 TWO NUMBERS, AND ONLY THE FIRST IS JUDGED. The committed total is what a
+    // teammate or CI loads from this commit; the effective total is what THIS
+    // working copy loads, per-machine files included. Scoring the second would
+    // make a published grade depend on a gitignored file and put the CLI and the
+    // browser engine — which reads a GitHub tree and can never see one —
+    // permanently out of agreement. Printing only the first would hide bytes the
+    // author is really paying for. See `core/instruction-chain.ts`.
+    const local = w.effectiveTotal - w.committedTotal;
+    // 🔴 A REDIRECT IS A FINDING, NOT A SIZE. A `CLAUDE.md` holding nothing but
+    // `@AGENTS.md` is fourteen bytes, and the repository it describes loads tens
+    // of kilobytes; printing the fourteen would be a confident wrong answer. The
+    // line says what the file IS and what it points at, above the number.
+    const redirectLines = w.redirects.map((r) => `  ↪ ${r.path} is a REDIRECT — its entire content is import(s): ${r.to.join(", ")}`);
+    // 🔴 AN IMPORTED FILE IS NAMED WHETHER OR NOT WE ARE OVER BUDGET. The
+    // breakdown below only prints when over, and an import is exactly the entry a
+    // reader cannot account for — `AGENTS.md` in a Claude Code weight reads as a
+    // bug until the line says which file asked for it.
+    const importedLines = w.overBy === null
+        ? w.files.filter((f) => f.via !== undefined).map(fileLine)
+        : [];
+    // 🔴 THE DELTA HAS A SIGN NOW, AND SUPPRESSING THE NEGATIVE ONE WAS THE WORST
+    // OF THE THREE OPTIONS. `local > 0` was written when a per-machine file could
+    // only ADD bytes; the supersede rule makes it subtract, and the model already
+    // reports that (`supersededLocallyBy`, `effectiveTotal` below `committedTotal`
+    // — see `core/instruction-weight.ts`). The printer was the last reader still
+    // assuming one direction, so the header announced the larger COMMITTED number
+    // as what is always loaded and nothing said this working copy loads a
+    // different, smaller chain. That is a confident over-report — the same
+    // undecomposable total the breakdown exists to prevent, pointing the other
+    // way. Both signs print; only exactly zero stays silent, because there is
+    // nothing to decompose.
+    const removedHere = w.files.filter((f) => f.notLoadedHere !== undefined);
+    const deltaLine = () => {
+        const here = `${g(w.effectiveTotal)} in this working copy, not scored`;
+        if (local > 0) {
+            return `  + ${g(local)} ${w.unit} from per-machine file(s) — ${here}`;
+        }
+        // NAMED, not just signed. A reader meeting "−93" has to be told which
+        // committed file stopped being loaded and what silenced it, or the number
+        // is an accusation with no defendant.
+        // The VERB comes off the entry, because the two doors to this state read
+        // very differently to someone deciding what to do about it: a superseding
+        // file is one they wrote, an exclusion is a pattern they set.
+        const by = removedHere
+            .map((f) => `${f.path} (${f.notLoadedHere?.why === "excluded" ? "excluded" : "silenced"} by ${String(f.notLoadedHere?.by)})`)
+            .join(", ");
+        return (`  − ${g(-local)} ${w.unit}: a per-machine file REMOVES committed instruction(s) — ${here}` +
+            (by === "" ? "" : `\n      not loaded here: ${by}`));
+    };
+    const tail = [
+        ...(local === 0 ? [] : [deltaLine()]),
+        // Named rather than silently dropped: a number that omits a file it knows
+        // about is the under-report this whole report exists to prevent.
+        ...(w.unreadImports.length > 0
+            ? [
+                `  + ${String(w.unreadImports.length)} named import(s) not read: ${w.unreadImports.join(", ")}`,
+            ]
+            : []),
+        ...(w.unweighedPatterns.length > 0
+            ? [
+                `  + ${String(w.unweighedPatterns.length)} pattern(s) not weighed: ${w.unweighedPatterns.join(", ")}`,
+            ]
+            : []),
+        // 🔴 THE NUMBER IS A FLOOR, AND SAYING SO IS THE WHOLE FIX. Both vendors
+        // load instruction files from OUTSIDE the repository ALONGSIDE the ones
+        // counted here — a home-directory file and an organization's managed one.
+        // The Claude Code page is explicit that those "don't count, and keep
+        // loading alongside `AGENTS.md`": they are ADDED to this sum in a real
+        // session, they are never subtracted from it.
+        //
+        // READING THEM WOULD BE THE WRONG FIX, not a better one. A grade that
+        // reached into `~` would depend on whose machine ran it, and the browser
+        // twin — which reads a GitHub tree — could never reproduce it; that is the
+        // same argument `scope: "local"` rests on, one directory further out. So
+        // the fix is this line: a total that silently omits files it KNOWS exist is
+        // the undecomposable number this whole report exists to prevent, and one
+        // line costs nothing and cannot be wrong. Unconditional, because the
+        // omission does not depend on anything in the repository.
+        `  ⌊ a FLOOR: a home-directory or organization-managed instruction file loads on top of this and is outside a repository audit`,
+    ];
     if (w.overBy === null)
-        return [head];
-    const factor = (w.total / w.limit).toFixed(1);
+        return [head, ...redirectLines, ...importedLines, ...tail];
+    const factor = (w.committedTotal / w.limit).toFixed(1);
     const consequence = w.onExceed === "truncates"
         ? "past the budget is SILENTLY TRUNCATED — those rules never reach the model"
         : "the harness warns; the rules still reach the model, you pay for them every request";
     return [
         `${head} — ${factor}x OVER by ${g(w.overBy)} ${w.unit}`,
         `  ${consequence}`,
-        ...w.files.slice(0, 5).map((f) => `  ${g(f.size).padStart(9)}  ${f.path}`),
+        ...redirectLines,
+        ...w.files.slice(0, 5).map(fileLine),
         ...(w.files.length > 5
             ? [`  …and ${String(w.files.length - 5)} more`]
             : []),
+        ...tail,
     ];
 }
 function formatScanReport(r) {

package/dist/skill-harness.d.ts

@@ -14,12 +14,28 @@
  * about another tool's parser tolerance.
  */
 import type { SkillSpec } from "./core/spec.js";
-/** The Claude-Code-only frontmatter keys a skill spec would emit. */
-export declare function claudeOnlyFrontmatterKeys(spec: SkillSpec): string[];
 /**
- * Warn for each declared harness whose `minimal` SKILL.md profile would DROP a
- * skill's Claude-Code-only frontmatter. Empty when the skill uses no such keys or
- * no declared harness is minimal-profile.
+ * The optional frontmatter keys a skill spec would emit that this check ranges
+ * over. `name` and `description` are excluded because conformance requires
+ * every dialect to read them, so they can never be dropped.
+ *
+ * ⚠️ NOT the whole optional set: `context`, `allowed-tools` and
+ * `disallowed-tools` are also droppable and are not listed here. That is the
+ * pre-existing scope of this warning, carried over unchanged when the profile
+ * enum became a key set — widening it is a behaviour change to argue
+ * separately, not a side effect of the rename.
+ */
+export declare function optionalFrontmatterKeys(spec: SkillSpec): string[];
+/**
+ * Warn for each declared harness that would DROP frontmatter keys this skill
+ * sets, because its dialect does not read them. Empty when the skill uses no
+ * optional keys, or when every declared harness reads the ones it uses.
+ *
+ * 🔴 THE KEYS THE WARNING NAMES ARE NOW THE KEYS ACTUALLY DROPPED. It used to
+ * test `dialect.skillFrontmatter === "minimal"` and then print every
+ * Claude-Code-only key the spec set — one bucket for every non-CC harness, and
+ * a message that could name a key the harness in fact reads. The set difference
+ * is both the condition and the message, so the two cannot disagree.
  */
 export declare function skillFrontmatterDropWarnings(spec: SkillSpec, harnessNames: readonly string[]): string[];
 //# sourceMappingURL=skill-harness.d.ts.map

package/dist/skill-harness.js

@@ -1,10 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.claudeOnlyFrontmatterKeys = claudeOnlyFrontmatterKeys;
+exports.optionalFrontmatterKeys = optionalFrontmatterKeys;
 exports.skillFrontmatterDropWarnings = skillFrontmatterDropWarnings;
 const adapter_registry_js_1 = require("./adapter-registry.js");
-/** The Claude-Code-only frontmatter keys a skill spec would emit. */
-function claudeOnlyFrontmatterKeys(spec) {
+/**
+ * The optional frontmatter keys a skill spec would emit that this check ranges
+ * over. `name` and `description` are excluded because conformance requires
+ * every dialect to read them, so they can never be dropped.
+ *
+ * ⚠️ NOT the whole optional set: `context`, `allowed-tools` and
+ * `disallowed-tools` are also droppable and are not listed here. That is the
+ * pre-existing scope of this warning, carried over unchanged when the profile
+ * enum became a key set — widening it is a behaviour change to argue
+ * separately, not a side effect of the rename.
+ */
+function optionalFrontmatterKeys(spec) {
     const keys = [];
     if (spec.disableModelInvocation !== undefined) {
         keys.push("disable-model-invocation");
@@ -15,13 +25,19 @@ function claudeOnlyFrontmatterKeys(spec) {
     return keys;
 }
 /**
- * Warn for each declared harness whose `minimal` SKILL.md profile would DROP a
- * skill's Claude-Code-only frontmatter. Empty when the skill uses no such keys or
- * no declared harness is minimal-profile.
+ * Warn for each declared harness that would DROP frontmatter keys this skill
+ * sets, because its dialect does not read them. Empty when the skill uses no
+ * optional keys, or when every declared harness reads the ones it uses.
+ *
+ * 🔴 THE KEYS THE WARNING NAMES ARE NOW THE KEYS ACTUALLY DROPPED. It used to
+ * test `dialect.skillFrontmatter === "minimal"` and then print every
+ * Claude-Code-only key the spec set — one bucket for every non-CC harness, and
+ * a message that could name a key the harness in fact reads. The set difference
+ * is both the condition and the message, so the two cannot disagree.
  */
 function skillFrontmatterDropWarnings(spec, harnessNames) {
-    const ccKeys = claudeOnlyFrontmatterKeys(spec);
-    if (ccKeys.length === 0)
+    const optionalKeys = optionalFrontmatterKeys(spec);
+    if (optionalKeys.length === 0)
         return [];
     const warnings = [];
     const seen = new Set();
@@ -30,9 +46,11 @@ function skillFrontmatterDropWarnings(spec, harnessNames) {
         if (!adapter || seen.has(adapter.name))
             continue;
         seen.add(adapter.name);
-        if (adapter.dialect.skillFrontmatter === "minimal") {
-            const one = ccKeys.length === 1;
-            warnings.push(`skill "${spec.name}": ${ccKeys.join(", ")} ${one ? "is" : "are"} Claude-Code-only — declared harness "${adapter.name}" drops ${one ? "it" : "them"}.`);
+        const read = adapter.dialect.skillFrontmatterKeys;
+        const dropped = optionalKeys.filter((key) => !read.includes(key));
+        if (dropped.length > 0) {
+            const one = dropped.length === 1;
+            warnings.push(`skill "${spec.name}": ${dropped.join(", ")} ${one ? "is" : "are"} not read by declared harness "${adapter.name}" — it drops ${one ? "it" : "them"}.`);
         }
     }
     return warnings;

package/dist/surface-discovery-fs.d.ts

@@ -1,3 +1,4 @@
+import type { PluginLayout } from "./core/layout.js";
 import { type DiscoveredSurface } from "./core/surface-discovery.js";
 import { type ExcludeSet } from "./exclude.js";
 /**
@@ -9,4 +10,5 @@ import { type ExcludeSet } from "./exclude.js";
 export declare function boundedSurfacePaths(root: string, excludes?: ExcludeSet): readonly string[];
 /** Every surface the bounded walk finds on disk under `root`, by shape. */
 export declare function discoverSurfacesOnDisk(root: string, excludes?: ExcludeSet): readonly DiscoveredSurface[];
+export declare function boundedInstructionFiles(root: string, layout: PluginLayout, excludes?: ExcludeSet): Record<string, string>;
 //# sourceMappingURL=surface-discovery-fs.d.ts.map

package/dist/surface-discovery-fs.js

@@ -2,14 +2,21 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.boundedSurfacePaths = boundedSurfacePaths;
 exports.discoverSurfacesOnDisk = discoverSurfacesOnDisk;
+exports.boundedInstructionFiles = boundedInstructionFiles;
 /**
- * The DISK half of surface discovery: enumerate the repo-relative paths inside
- * the bounded root set, so the pure classifier in `src/core/surface-discovery.ts`
- * can say which of them are surfaces.
+ * The DISK half of BOUNDED DISCOVERY: enumerate the repo-relative paths inside
+ * the bounded root set, so the pure classifiers in `src/core/surface-discovery.ts`
+ * and `src/core/instruction-chain.ts` can say what each of them is.
  *
- * Paths only — never contents. Discovery answers "is there a surface here that
- * nobody reads", which is a question about NAMES; reading a file nobody claims
- * would be doing the very work the finding says is not being done.
+ * Two enumerations, one bound. {@link boundedSurfacePaths} answers "is there a
+ * surface here that nobody reads" and returns PATHS ONLY — that is a question
+ * about NAMES, and reading a file nobody claims would be doing the very work the
+ * finding says is not being done. {@link boundedInstructionFiles} answers "what
+ * does this harness load without being asked" and must return CONTENTS, because
+ * the answer depends on them: a rule's own frontmatter decides whether it loads
+ * at launch, and the repository's settings decide which files are candidates at
+ * all. The header of `core/instruction-chain.ts` holds the reason that is a port
+ * method rather than a glob.
  *
  * 🔴 THE WALK IS BOUNDED BY CONSTRUCTION, NOT BY A DEPTH COUNTER. One `readdir`
  * of the repo root, one per DOT-DIRECTORY found there, and then descent ONLY
@@ -31,6 +38,8 @@ exports.discoverSurfacesOnDisk = discoverSurfacesOnDisk;
  */
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const instruction_chain_js_1 = require("./core/instruction-chain.js");
+const layout_js_1 = require("./core/layout.js");
 const surface_discovery_js_1 = require("./core/surface-discovery.js");
 const exclude_js_1 = require("./exclude.js");
 const fs_walk_js_1 = require("./fs-walk.js");
@@ -105,4 +114,97 @@ function openableSurfaceDir(root, rel, excluded) {
 function discoverSurfacesOnDisk(root, excludes) {
     return (0, surface_discovery_js_1.discoverSurfaces)(boundedSurfacePaths(root, excludes));
 }
+/** Read one repo-relative file, or `undefined` for anything that is not one. */
+function readIfFile(root, rel) {
+    const abs = (0, node_path_1.join)(root, rel);
+    if ((0, fs_walk_js_1.entryOf)(abs).kind !== "file")
+        return undefined;
+    try {
+        return (0, node_fs_1.readFileSync)(abs, "utf-8");
+    }
+    catch {
+        return undefined; // unreadable: the same silence the walk gives elsewhere
+    }
+}
+/** Repo-relative paths of the files directly inside one discovery root. */
+function filesDirectlyIn(root, base) {
+    const baseAbs = base === "" ? root : (0, node_path_1.join)(root, base);
+    return namesIn(baseAbs).map((n) => (base === "" ? n : `${base}/${n}`));
+}
+/**
+ * Every instruction CANDIDATE on disk, with its contents — the input a harness's
+ * `instructionChain` is allowed to classify.
+ *
+ * 🔴 BOUNDED BY THE SAME CONSTRUCTION AS THE SURFACE WALK, and for the same
+ * reason. One `readdir` of the repo root, one per dot-directory found there, and
+ * a recursive descent ONLY into a `rules` directory inside one of those. `src/`,
+ * `packages/` and `node_modules/` are never entered — which is exactly what the
+ * thing this replaced did do: `scan.ts:readAlwaysLoaded` expanded an ADAPTER's
+ * `"**\/AGENTS.md"` by recursing through the whole tree, so registering an
+ * adapter widened what vigiles read in everyone's repository.
+ *
+ * The one read outside that bound is the IMPORT PASS below, and the difference
+ * is who chose the path.
+ */
+/**
+ * The `rules` tree under one dot-directory, read RECURSIVELY.
+ *
+ * Recursive because the vendor documents it that way — and because the scan
+ * classifier now says the same through `RULE_FILE_LEAF_RE`; a rule the loader
+ * reads and the classifier ignores is a file that is never checked, counted or
+ * weighed. The entry point goes through the same symlink and exclude policy as
+ * a surface dir, `filesUnder` applies `exclude` per entry below it.
+ */
+function addRulesTree(root, rulesRel, excluded, out) {
+    if (rulesRel === null)
+        return;
+    // The same entry question `openableSurfaceDir` answers for a surface dir, so
+    // it is asked through that function rather than spelled a second time. The
+    // second spelling was `kind !== "dir"`, and `entryOf` says "skip" for a
+    // symlinked directory on purpose — so a `.claude/rules` linked to a shared
+    // policy directory was dropped whole, while the same link as `.claude/skills`
+    // was walked.
+    if (!openableSurfaceDir(root, rulesRel, excluded))
+        return;
+    filesUnder(root, rulesRel, excluded, out);
+}
+function boundedInstructionFiles(root, layout, excludes) {
+    const excluded = (0, exclude_js_1.excludedBy)(excludes);
+    const roots = ["", ...namesIn(root).filter((n) => (0, surface_discovery_js_1.isDiscoveryRoot)(n))].filter((b) => b === "" || !excluded((0, node_path_1.join)(root, b)));
+    // Every file directly inside a discovery root is a candidate PATH; the pure
+    // filter keeps the instruction-shaped ones plus the layout's own named files
+    // (`.codex/config.toml` is neither markdown nor an instruction — it is the
+    // settings source that decides WHICH files load, and is never weighed).
+    const candidates = [];
+    for (const base of roots) {
+        candidates.push(...filesDirectlyIn(root, base));
+    }
+    // 🔴 THE RULES TREE HAS ONE HOME, AND THE LAYOUT NAMES IT (#271).
+    //
+    // This used to run INSIDE the loop above, joining `<base>/<rulesDir>` for
+    // every discovery root and guarding the repository root out with
+    // `if (base !== "")`. Two wrong answers fell out of that, measured on layouts
+    // built from the type: a layout declaring `rulesDir` with no
+    // `userSurfaceRoot` had its tree skipped entirely, while `.github/rules` was
+    // walked for every layout, declared or not. `rulesHome` is the same answer
+    // `ruleFileRe` gives the classifier, so the walk and the filter can no longer
+    // disagree about which tree belongs to this harness.
+    addRulesTree(root, (0, layout_js_1.rulesHome)(layout), excluded, candidates);
+    const candidateFiles = {};
+    for (const rel of (0, instruction_chain_js_1.instructionCandidatePaths)(candidates, layout)) {
+        if (excluded((0, node_path_1.join)(root, rel)))
+            continue;
+        const text = readIfFile(root, rel);
+        if (text !== undefined)
+            candidateFiles[rel] = text;
+    }
+    // The import pass is the ONE read outside the bound, and the pure half of it
+    // lives in the core so the browser twin runs the identical loop over its file
+    // map. It is ONE concrete path per token, one level deep — the corpus
+    // measurement behind that is in `resolveImports`. `exclude` is deliberately
+    // NOT applied to it: the path was written by the repository owner in their own
+    // instruction file, and the harness really does load it, so hiding its size
+    // would under-report the one number this report exists to give.
+    return (0, instruction_chain_js_1.resolveImports)(layout, candidateFiles, (rel) => readIfFile(root, rel));
+}
 //# sourceMappingURL=surface-discovery-fs.js.map