vigiles 29.1.0 → 30.0.1

package/dist/adapters/claude-code/instruction-chain.js

@@ -0,0 +1,626 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localSiblingOf = localSiblingOf;
+exports.claudeCodeInstructionChain = claudeCodeInstructionChain;
+const Minimatch = () => require("minimatch").Minimatch;
+const instruction_chain_js_1 = require("../../core/instruction-chain.js");
+const frontmatter_read_js_1 = require("../../core/frontmatter-read.js");
+const markdown_js_1 = require("../../core/markdown.js");
+/**
+ * The settings key that removes files from the chain, and the frontmatter key
+ * that makes a rule load ON DEMAND instead of at launch. Both are Claude Code's
+ * own words; they live here and nowhere in the core, which is the boundary the
+ * `no-harness-names` lint polices.
+ */
+const EXCLUDES_KEY = "claudeMdExcludes";
+const PATH_SCOPE_KEY = "paths";
+/**
+ * The cross-tool instruction filename Claude Code now reads natively — "Claude
+ * Code can read `AGENTS.md` as your project instructions".
+ *
+ * 🔴 IT IS A LITERAL HERE, AND DELIBERATELY NOT A FIELD ON `PluginLayout`.
+ * `layout.instructionFile` answers "which file does this harness WRITE and
+ * own"; the answer is still `CLAUDE.md` — that is what `vigiles init` compiles
+ * into and what `detect` scores on. `AGENTS.md` is a file this harness READS
+ * and another harness owns, which is a different question, and putting it in
+ * the layout would make `layoutClaims` say Claude Code claims `AGENTS.md` —
+ * i.e. two registered adapters claiming the same path, which is the collision
+ * `claims` exists to prevent. So it lives beside {@link EXCLUDES_KEY} and
+ * {@link PATH_SCOPE_KEY}: Claude Code's own words, in Claude Code's adapter,
+ * and nowhere in the core.
+ */
+const AGENTS_FILE = "AGENTS.md";
+/** The directory the vendor names in its "Not read" list. */
+const AGENTS_DIR = ".agents";
+/**
+ * The two cross-tool per-machine siblings, DERIVED through the one
+ * `siblingNamed` spelling rather than written out: Claude Code names its
+ * per-machine file with `local`, Codex with `override`, and both spellings of
+ * the `AGENTS.md` family are gitignored by convention.
+ *
+ * 🔴 USED FOR TWO DIFFERENT THINGS, and that is the point of it being a set
+ * rather than two comparisons inside {@link isNeverRead}. It answers "does this
+ * harness ever go looking for this name" (no), and it answers "is this file one
+ * machine's" — which is what {@link takeImportsOf} needs, because an imported
+ * file inherits the IMPORTER's scope, and a committed `AGENTS.md` importing
+ * `@AGENTS.local.md` would otherwise put a gitignored file into a published
+ * `committedTotal`. That is the very defect {@link InstructionScope} exists to
+ * prevent: the browser twin reads a GitHub tree and can never see the file.
+ *
+ * ⚠️ THE SECOND USE IS A CONVENTION, NOT A VENDOR RULE, and it is the SAME
+ * convention this module already applies to `CLAUDE.local.md` by name — the
+ * `.local.` / `.override.` infix means "one machine's", for both vendors. So
+ * this is the cross-tool family catching up with the rule its twin already
+ * follows, not a new one. What it costs if the convention is wrong in some
+ * repository — a committed `AGENTS.local.md` — is that the file leaves
+ * `committedTotal`; it stays in `effectiveTotal` and on its own breakdown row,
+ * so it is moved rather than dropped. Identical to the cost already accepted
+ * for `CLAUDE.local.md`.
+ */
+const CROSS_TOOL_LOCAL_LEAVES = new Set([
+    (0, instruction_chain_js_1.siblingNamed)(AGENTS_FILE, "local"),
+    (0, instruction_chain_js_1.siblingNamed)(AGENTS_FILE, "override"),
+]);
+/** Is this path one machine's file by NAME — `X.local.md` / `X.override.md`? */
+function isPerMachineName(path) {
+    return CROSS_TOOL_LOCAL_LEAVES.has(path.slice(path.lastIndexOf("/") + 1));
+}
+/**
+ * Cross-tool instruction files Claude Code NEVER reads, at any depth. Vendor:
+ *
+ * > **Not read**: `AGENTS.local.md`, `AGENTS.override.md`, or anything under a
+ * > `.agents/` directory.
+ *
+ * 🔴 A NAMED PREDICATE BECAUSE THE DEFAULT IS WRONG FOR THIS FAMILY, and it is
+ * wrong QUIETLY. {@link takeSubdirectories} recognises an instruction file by
+ * its LEAF NAME, so `.agents/AGENTS.md` — which the domain's bound really does
+ * enumerate, it is dot-directory markdown — would come out classified
+ * "on-demand". The number is the same either way (an on-demand file weighs
+ * nothing), so no total would move and nothing would go red; only the printed
+ * REASON would be a confident wrong answer about a file the harness will never
+ * open. That is the class this whole module exists to remove.
+ *
+ * The two sibling names come from {@link CROSS_TOOL_LOCAL_LEAVES}, which
+ * derives them through the one `siblingNamed` spelling rather than writing them
+ * out, for the reason {@link localSiblingOf} is derived: a second literal is a
+ * second thing to keep in step.
+ *
+ * ⚠️ WHAT THIS DOES NOT DO, stated rather than discovered later: a file it
+ * refuses is named by NOTHING — it appears in neither `loaded` nor `unloaded`.
+ * `NotLoadedReason` has no member for "this harness never reads this name", and
+ * inventing one for a single vendor sentence would put a branch into every
+ * consumer of the union for a file that weighs nothing. Silence here is the
+ * same answer the bound already gives every non-instruction file.
+ *
+ * ⏳ AND AN EXPLICIT `@` TOKEN NAMING ONE OF THESE FILES IS AN OPEN QUESTION,
+ * raised by the corpus rather than imagined: of the three real imports in the
+ * 214-file `AGENTS.md` sample (`core/instruction-chain.ts#resolveImports`), ONE
+ * is `@AGENTS.local.md` — a name this predicate refuses, written on purpose by
+ * the file beside it. The vendor's two sentences are peers in one bulleted
+ * list and neither qualifies the other:
+ *
+ * > **Inside each `AGENTS.md`**: `@path` imports are expanded …
+ * > **Not read**: `AGENTS.local.md`, `AGENTS.override.md`, or anything under a
+ * > `.agents/` directory
+ *
+ * Read as DISCOVERY, the second says where the loader goes looking and the
+ * token still loads the file. Read FLATLY, the name is never opened at all and
+ * the token resolves to nothing. {@link takeImportsOf} does not consult this
+ * predicate, so today the token IS honoured — but that is the behaviour that
+ * was already there, not a verdict reached here, and it is left alone rather
+ * than changed on a coin-flip. Settled by the same instrument as the exclusion
+ * question at {@link supersederOf}: one session, the documented `AGENTS.md
+ * loaded` line, or an `InstructionsLoaded` hook transcript.
+ *
+ * 🔴 WHAT IS DECIDED, BECAUSE IT IS RIGHT UNDER BOTH READINGS, is the SCOPE
+ * such a file gets if it is counted at all — see {@link isPerMachineName} and
+ * {@link takeImportsOf}. Under the flat reading the file is never taken and
+ * that code is simply unreachable; under the discovery reading it is taken, and
+ * scoring a `.local.` file as `repo` would put a gitignored file into a
+ * published `committedTotal`. Neither answer to the open question makes `repo`
+ * correct, which is what makes this one safe to take now.
+ */
+function isNeverRead(path) {
+    const leaf = path.slice(path.lastIndexOf("/") + 1);
+    return path.startsWith(`${AGENTS_DIR}/`) || CROSS_TOOL_LOCAL_LEAVES.has(leaf);
+}
+/**
+ * `@path/to/file.md` — how Claude Code names another file from inside an
+ * instruction file.
+ *
+ * 🔴 THIS IS A MODEL OF A LOADER, NOT A PARSE OF A FORMAT, and a reader who
+ * misses that will "fix" it in the wrong direction. `@path` is not in CommonMark
+ * or in any other specification, so there is no authority to parse against:
+ * markdown-it hands back `@AGENTS.md` as ordinary TEXT, correctly, because to
+ * markdown it is ordinary text. What we assume, stated so it can be argued with:
+ * a leading `@` followed by a path, written in PROSE (never inside a code fence
+ * or a code span), naming a markdown file. Anything beyond that — how the real
+ * loader treats a path relative to the importing file, a `~` reference, a
+ * recursive import — is inferred from the vendor documentation and from a
+ * 198-file corpus of public `CLAUDE.md`s, and a divergence from the real loader
+ * is discoverable only by OBSERVING it, never by reading a grammar.
+ *
+ * The narrowness is measured rather than cautious. A loose `@` pattern over that
+ * corpus matches Python decorators, Blade templates, npm scopes and CSS at-rules
+ * — all of them inside fenced code blocks, which {@link proseLines} removes
+ * before this pattern ever runs. Requiring a `.md` tail on top keeps
+ * `email me @ foo` and a prose `@dataclass` out. A token this refuses is simply
+ * not reported, which under-reports by that file's size; a token it wrongly
+ * accepted would make vigiles open a path the repo did not mean to name, and
+ * only one of those two is a safety question.
+ */
+const IMPORT_TOKEN = /(?:^|\s)(@[A-Za-z0-9_.][^\s]*\.md)\b/g;
+/** A prose line that is NOTHING BUT one import token — the redirect shape. */
+const ONLY_IMPORT = /^@[A-Za-z0-9_.][^\s]*\.md$/;
+/**
+ * The author's own prose, with the frontmatter, the code and the comments gone.
+ *
+ * Both halves come from the modules that own them — `frontmatterBody` from the
+ * frontmatter reader, {@link proseLines} from the ONE markdown-structure helper
+ * — rather than from a line-splitting loop here. The helper's own header records
+ * why: the hand-rolled fence toggle it replaced had been copy-pasted into five
+ * detectors and is wrong on nested and unbalanced fences, which is exactly the
+ * `@dataclass`-inside-a-code-block case this has to get right.
+ *
+ * Indentation, CRLF, trailing whitespace, trailing blank lines and a UTF-8 BOM
+ * are all handled THERE, measured; `instruction-chain.test.ts` names each of
+ * those spellings as its own case anyway, because they are the ratchet that
+ * proves this path still goes through the parser after the next edit.
+ */
+function contentLines(text) {
+    return (0, markdown_js_1.proseLines)((0, frontmatter_read_js_1.frontmatterBody)(text));
+}
+/** Every `@import` token in one file, deduplicated, in first-seen order. */
+function importTokens(text) {
+    const out = [];
+    for (const line of contentLines(text)) {
+        for (const m of line.matchAll(IMPORT_TOKEN)) {
+            const token = m[1];
+            if (token !== undefined && !out.includes(token))
+                out.push(token);
+        }
+    }
+    return out;
+}
+/**
+ * Is this file NOTHING BUT imports — a redirect rather than instructions?
+ *
+ * Binary, never a threshold: every prose line is a bare import token, and there
+ * is at least one. "Mostly imports" would be a number nobody can defend, and an
+ * empty file is empty rather than a redirect.
+ */
+function isPureRedirect(text) {
+    const lines = contentLines(text);
+    return lines.length > 0 && lines.every((line) => ONLY_IMPORT.test(line));
+}
+/**
+ * The `claudeMdExcludes` patterns this chain can APPLY, compiled.
+ *
+ * ⚠️ THE VENDOR MATCHES THESE AGAINST ABSOLUTE PATHS and the chain is handed
+ * repo-relative keys, so a pattern anchored at the filesystem root cannot be
+ * applied here at all. Rather than guess a root, only the `**\/`-prefixed form
+ * is applied — that leading segment matches zero or more directories, so such a
+ * pattern means the same thing against an absolute path and against a
+ * repo-relative one, which is exactly the subset that needs no root. Every other
+ * pattern is left UNAPPLIED, which counts a file that would not have loaded.
+ * That over-reports, and over-reporting is the safe direction: an under-report
+ * reads as "you are fine", which is the failure this feature exists to prevent.
+ *
+ * Matching is `minimatch`, the parser the rest of this repo's exclusion policy
+ * already uses (`src/exclude.ts`) — a glob is a LANGUAGE, and hand-rolling a
+ * second interpreter for it is precisely the defect being removed here.
+ */
+function compileExcludes(settings) {
+    if (settings.length === 0)
+        return [];
+    const ctor = Minimatch();
+    return settings
+        .filter((p) => p.startsWith("**/"))
+        .map((p) => new ctor(p, { dot: true }));
+}
+/** `claudeMdExcludes` from one settings file's text, or `[]` if it says nothing. */
+function excludesIn(text, parse) {
+    if (text === undefined)
+        return [];
+    let value;
+    try {
+        value = parse(text);
+    }
+    catch {
+        // A settings file mid-merge or mid-edit must not decide which instructions
+        // load. Reporting "nothing is excluded" over-reports, the safe direction.
+        return [];
+    }
+    const raw = value[EXCLUDES_KEY];
+    return Array.isArray(raw)
+        ? raw.filter((p) => typeof p === "string")
+        : [];
+}
+/** Does this rule file declare a `paths:` scope — i.e. load only on demand? */
+function isPathScoped(text) {
+    const { data } = (0, frontmatter_read_js_1.readFrontmatter)(text);
+    return data !== null && Object.hasOwn(data, PATH_SCOPE_KEY);
+}
+/**
+ * `CLAUDE.md` → `CLAUDE.local.md`: the per-machine sibling, DERIVED so the two
+ * names cannot drift apart the way a second constant would.
+ */
+function localSiblingOf(instructionFile) {
+    return (0, instruction_chain_js_1.siblingNamed)(instructionFile, "local");
+}
+/** Into `loaded`, or into `unloaded` with the settings reason; absent → nothing. */
+function take(b, path, entry) {
+    if (b.files[path] === undefined)
+        return;
+    const excluder = b.excluderOf(path);
+    if (excluder !== undefined) {
+        b.unloaded.push({
+            path,
+            ...entry,
+            reason: {
+                kind: "excluded-by-settings",
+                key: EXCLUDES_KEY,
+                by: excluder.path,
+                byScope: excluder.scope,
+            },
+        });
+        return;
+    }
+    b.loaded.push({ path, ...entry });
+}
+/**
+ * Every file under the rules dir: loaded, unless it declares a `paths:` scope.
+ *
+ * 🔴 THE CLAUDE CODE OVER-REPORT, FIXED HERE. A `paths:`-scoped rule is included
+ * when Claude reads a matching file, not at launch, so counting it as
+ * always-loaded inflated the one number this whole feature reports. Sorted by
+ * path for determinism; the vendor states that the files are concatenated, not
+ * in which order the project-scope ones arrive.
+ */
+function takeRules(b, ruleRe) {
+    for (const path of Object.keys(b.files).sort()) {
+        if (!ruleRe.test(path))
+            continue;
+        const text = b.files[path];
+        if (text === undefined)
+            continue;
+        if (isPathScoped(text)) {
+            b.unloaded.push({
+                path,
+                role: "rule",
+                scope: "repo",
+                reason: { kind: "on-demand", when: "path-scoped" },
+            });
+            continue;
+        }
+        take(b, path, { role: "rule", scope: "repo" });
+    }
+}
+/**
+ * A subdirectory's own instruction file, IF the caller handed one over.
+ *
+ * The domain's bound never enumerates one ({@link INSTRUCTION_SHAPES}), so this
+ * is reached only by a caller holding a wider map — and then the honest answer
+ * is "included when Claude reads files in those subdirectories", not "always".
+ *
+ * 🔴 `AGENTS.md` GETS THE SAME TREATMENT AS A `paths:`-SCOPED RULE, and the
+ * vendor puts the two in the same list for the same reason — neither is read at
+ * launch: "As Claude works in subdirectories: a subdirectory's `AGENTS.md`,
+ * when Claude opens a file there with the Read tool". Counting one would inflate
+ * the single number this feature exists to report, which is the over-report
+ * `alwaysLoaded` shipped.
+ *
+ * 🔴 THE VENDOR'S EXTRA CONDITION IS NOT MODELLED, AND THE REASON IS A
+ * MEASUREMENT RATHER THAN A PREFERENCE. "…when Claude opens a file there with
+ * the Read tool AND THAT SUBDIRECTORY HAS NONE OF THE THREE `CLAUDE.md` FILES
+ * OF ITS OWN": with one of them beside it, a nested `AGENTS.md` is never read
+ * at all rather than read on demand. Both answers weigh zero, so the only thing
+ * at stake is the printed REASON — which is worth getting right, since "same
+ * number, confident wrong reason" is the class {@link isNeverRead} exists for.
+ *
+ * ⚠️ IT CANNOT BE ANSWERED FROM THE MAP THIS METHOD IS HANDED. Measured over
+ * both engines, which are the only two callers: `boundedInstructionFiles`
+ * (`surface-discovery-fs.ts`) and the browser twin (`scan-files.ts:700`) each
+ * build the map as `instructionCandidatePaths(...)` UNION the paths the imports
+ * pass resolved — nothing else. `instructionCandidatePaths` keeps
+ * `^[^/]+\\.md$` and `^\\.[^/]+\\/[^/]+\\.md$`, so NO `<dir>/…` path is ever a
+ * candidate. A subdirectory `AGENTS.md` therefore reaches this loop only
+ * because something IMPORTED it, and its sibling `<dir>/CLAUDE.md` is in the
+ * map only if something imported that too. Absence of the sibling carries no
+ * information at all, so a supersede verdict built on it would be a guess
+ * wearing a vendor quote.
+ *
+ * 🔴 AND WIDENING THE BOUND TO GET IT WOULD BE THE WRONG TRADE. The bound is
+ * what stops registering an adapter from widening the read in someone else's
+ * repository — the construction this whole port rests on. Enumerating every
+ * directory's `CLAUDE.md` family to decide a printed reason on a file that
+ * weighs nothing spends the load-bearing thing on a cosmetic one. So the
+ * condition is declared here, unmodelled, and the file keeps the honest
+ * "on-demand": it says what this chain knows, not what the loader would do.
+ *
+ * ⏳ WHAT WOULD CLOSE IT: a caller that legitimately holds a per-directory map —
+ * a future `vigiles audit <subpackage>` run, where that directory IS the
+ * working directory and its files are in the bound by construction. Then the
+ * question is the ROOT question, already answered by {@link supersederOf}, and
+ * no widening is needed.
+ *
+ * ⚠️ AND THE CONDITION IS MOOT FOR AN IMPORTED FILE, WHICH IS WHY THIS PASS NOW
+ * RUNS LAST. A `<dir>/CLAUDE.md` that something `@`-imports is taken by the
+ * imports pass before this loop sees it, so the only paths reaching here are
+ * the ones nothing imported — the ones the condition was always about. The
+ * ordering, and the bug that came from the other order, are stated at the call.
+ *
+ * `reserved` holds the paths this chain owns at the root level. Without it, a
+ * `.claude/AGENTS.md` that the supersede pass has not yet classified would be
+ * read as a SUBDIRECTORY file, because it has a slash and the right basename —
+ * and the dot-directory is not a subdirectory of the project in the vendor's
+ * sense. It is empty-set-safe: every root candidate is already in `named` on
+ * the paths that reach this today.
+ */
+function takeSubdirectories(b, leafNames, reserved) {
+    const named = new Set([...b.loaded, ...b.unloaded].map((e) => e.path));
+    for (const path of Object.keys(b.files).sort()) {
+        if (named.has(path) || reserved.has(path) || !path.includes("/"))
+            continue;
+        if (isNeverRead(path))
+            continue;
+        if (!leafNames.has(path.slice(path.lastIndexOf("/") + 1)))
+            continue;
+        b.unloaded.push({
+            path,
+            role: "root",
+            scope: "repo",
+            reason: { kind: "on-demand", when: "subdirectory" },
+        });
+    }
+}
+/**
+ * Which file, if any, stops this repository's `AGENTS.md` being read — vendor:
+ * "a `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` in your working
+ * directory or any directory above it".
+ *
+ * 🔴 AN EXCLUDED `CLAUDE.md` DOES NOT SUPERSEDE, AND THAT IS A MEASUREMENT.
+ * Two vendor rules meet here and the vendor composes neither: the supersede
+ * rule is phrased about files you HAVE ("look for a `CLAUDE.md`… if you find
+ * one"), while `claudeMdExcludes` takes a file out of the chain without taking
+ * it off the disk. The page answers neither way, so this was run rather than
+ * argued — Claude Code **2.1.278**, fixtures and runner under
+ * `test/fixtures/instruction-chain-vendor/`, each file holding a codeword the
+ * model is then asked to recite with the file-reading tools denied:
+ *
+ *   c0  both files, no settings                  → ALPHA only. Supersede happens at all.
+ *   c1  `claudeMdExcludes` hides the CLAUDE.md   → **BETA, and no ALPHA**. The AGENTS.md LOADS.
+ *   c3  root hidden, `.claude/CLAUDE.md` kept    → GAMMA only. A SURVIVING candidate still supersedes.
+ *
+ * c0 is the control: without it, c1 is a reading of an instrument nobody
+ * checked. c3 is what fixes the SHAPE of the fix — the answer is not "ignore
+ * exclusions", it is "the first candidate that is present AND not excluded",
+ * and the survivor is what gets named in `by`. Hence the predicate below
+ * rather than a boolean bypass.
+ *
+ * 🔴 AND THE OBVIOUS INSTRUMENT IS THE WRONG ONE, which is worth a line here
+ * because it nearly reversed this conclusion. An `InstructionsLoaded` hook
+ * looks like the exact tool for the job and is BLIND TO `AGENTS.md`: case c2 —
+ * a repository holding only an `AGENTS.md` — recites BETA (so the file
+ * plainly loaded) while the hook logs NOTHING. Read on the hook alone, c1's
+ * silence says "nothing loaded" and this whole function stays as it was. The
+ * silence is a fact about the hook. Both instruments are in the runner, with
+ * c2 as the case that tells them apart.
+ *
+ * ⚠️ WHAT THE MEASUREMENT DOES NOT COVER: it was taken on ONE build, and the
+ * vendor has already reversed a neighbouring fact once (`AGENTS.md` auto-load,
+ * v2.1.277). So the build number is part of the claim, not decoration. Re-run
+ * the fixtures before trusting this on a much later version.
+ *
+ * 🔴 A COMMITTED SUPERSEDER WINS OVER THE PER-MACHINE ONE, and the order of
+ * this array is the whole of that rule. Both can be present; picking the local
+ * file then would put `AGENTS.md` into `committedTotal`, claiming a teammate
+ * loads it — but that teammate has the `CLAUDE.md`, so they do not. The
+ * per-machine file is therefore last, and only answers when nothing committed
+ * did.
+ *
+ * ⚠️ THIS ASSUMES THE DEFAULT MODE, AND THE REPOSITORY CANNOT CONFIRM IT. The
+ * vendor's `claude-md-or-agents-md` (default) is what supersedes at all;
+ * `claude-md-and-agents-md` loads both families and supersedes nothing, and
+ * `managed-only` loads neither. The setting is read only from user-level, a
+ * `--settings` file or managed settings — "Claude Code ignores it in project
+ * and local settings files" — so a repo scan cannot see it, and the same
+ * commit therefore loads a different instruction set for two different people
+ * with no file in the tree saying which. Nothing in this function can close
+ * that; it is the module header's limit 1, restated at the line that assumes.
+ *
+ * ⚠️ AND THE THREE NON-COUNTING FILES ARE ABSENT BY CONSTRUCTION, not by an
+ * omission: `~/.claude/CLAUDE.md` and a managed `CLAUDE.md` are outside a
+ * repository audit entirely (reading `~` for a grade is wrong on its face), and
+ * `.claude/rules/` files "keep loading alongside `AGENTS.md`" — they are taken
+ * by {@link takeRules} in both modes and are not consulted here. Stated because
+ * a reader who adds the rules dir to this array would turn `AGENTS.md` off in
+ * every repository that has one.
+ */
+function supersederOf(files, input, isExcluded) {
+    const candidates = [
+        { path: input.instructionFile, scope: "repo" },
+        {
+            path: `${input.userSurfaceRoot}/${input.instructionFile}`,
+            scope: "repo",
+        },
+        { path: localSiblingOf(input.instructionFile), scope: "local" },
+    ];
+    // PRESENT AND NOT EXCLUDED — c3 is why both halves are here. A bypass that
+    // just skipped the check when anything was excluded would name the wrong
+    // file in `by`, or none at all, in a repo that excludes one candidate and
+    // keeps another.
+    return candidates.find((c) => files[c.path] !== undefined && !isExcluded(c.path));
+}
+/** One loaded file's `@import` tokens: reported, and TAKEN when already present. */
+function takeImportsOf(b, entry) {
+    const text = b.files[entry.path];
+    if (text === undefined)
+        return;
+    const known = new Set([...b.loaded, ...b.unloaded].map((e) => e.path));
+    for (const token of importTokens(text)) {
+        // The token as WRITTEN carries the `@`; the path is what it resolves to —
+        // against the IMPORTING FILE's directory, measured, see `resolveImportPath`.
+        const written = token.slice(1);
+        if (!(0, instruction_chain_js_1.isRepoRootedImport)(written))
+            continue;
+        const path = (0, instruction_chain_js_1.resolveImportPath)(entry.path, written);
+        if (!b.imports.some((n) => n.path === path && n.from === entry.path)) {
+            b.imports.push({ path, token, from: entry.path });
+        }
+        if (b.files[path] === undefined || known.has(path))
+            continue;
+        // The importer's scope is INHERITED: a committed file pulled in only by
+        // `CLAUDE.local.md` does not load for a teammate, so it must not be in the
+        // committed total either. And `via` travels with it, so the report can say
+        // WHY a file nobody expected is in the count.
+        //
+        // 🔴 EXCEPT WHEN THE IMPORTED FILE IS ONE MACHINE'S BY NAME, which is not a
+        // hypothetical: `@AGENTS.local.md` is one of the three real imports in the
+        // measured 214-file corpus. Inheriting `repo` there would put a gitignored
+        // file into a published `committedTotal` — the browser twin reads a GitHub
+        // tree and can never see it, so the CLI and the browser would disagree
+        // about the same commit. That is the defect `InstructionScope` exists to
+        // prevent, and a token in a committed file does not make the target
+        // committed. Inheritance still applies in the other direction: a `local`
+        // importer keeps `local`, because `"local"` is the narrower answer.
+        //
+        // ⏳ THIS LINE DOES NOT DECIDE WHETHER THE TOKEN SHOULD LOAD AT ALL — that
+        // is the open question at `isNeverRead`, and this predicate is right under
+        // either of its answers. See the note there before "simplifying" this.
+        take(b, path, {
+            role: "import",
+            scope: isPerMachineName(path) ? "local" : entry.scope,
+            via: { from: entry.path, token },
+        });
+    }
+}
+function claudeCodeInstructionChain(files, input) {
+    // PER SOURCE, not flattened. Flattening lost which file a pattern came from,
+    // and that is the whole fact `byScope` needs — see the measurement on
+    // `excluded-by-settings` in core.
+    const excluders = input.settingsSources.map((source) => ({
+        source,
+        matchers: compileExcludes(excludesIn(files[source.path], input.parseSettings)),
+    }));
+    const b = {
+        files,
+        loaded: [],
+        unloaded: [],
+        imports: [],
+        excluderOf: (path) => excluders.find((e) => e.matchers.some((m) => m.match(path)))?.source,
+    };
+    // ORDER. The one ordering fact the vendor states is that the local file is
+    // LAST — "the last thing Claude reads at that level" — so it is taken after
+    // the rules rather than beside the root file it is named for.
+    take(b, input.instructionFile, { role: "root", scope: "repo" });
+    take(b, `${input.userSurfaceRoot}/${input.instructionFile}`, {
+        role: "root",
+        scope: "repo",
+    });
+    // THE CROSS-FAMILY SWITCH. "At session start: every `AGENTS.md` and
+    // `.claude/AGENTS.md` in your working directory" — but only "when you have no
+    // CLAUDE.md in your working directory or above it". Both spellings, in the
+    // same root-then-dot-directory order as the two takes above; the vendor states
+    // no order BETWEEN them, and it cannot matter to a sum.
+    const superseder = supersederOf(files, input, (p) => b.excluderOf(p) !== undefined);
+    const crossToolPaths = [
+        AGENTS_FILE,
+        `${input.userSurfaceRoot}/${AGENTS_FILE}`,
+    ];
+    if (superseder === undefined) {
+        for (const path of crossToolPaths) {
+            take(b, path, { role: "root", scope: "repo" });
+        }
+    }
+    takeRules(b, input.ruleRe);
+    take(b, localSiblingOf(input.instructionFile), {
+        role: "root-local",
+        scope: "local",
+    });
+    // THE IMPORTS PASS, ONE LEVEL. It reads a SNAPSHOT of what is loaded so far,
+    // so a file pulled in by an import is not itself scanned for imports — see
+    // `resolveImports` in the core for the corpus measurement behind that, and for
+    // what it costs. Every path reported literally occurs in the file that names
+    // it, which is the property that keeps this from being a widening the ADAPTER
+    // chose rather than one the repo owner wrote.
+    //
+    // 🔴 IT RUNS BEFORE THE SUPERSEDE VERDICT, AND THAT ORDER IS A VENDOR ROW
+    // RATHER THAN A CONVENIENCE. The third row of the vendor's own table reads:
+    // "A `CLAUDE.md` that already imports `AGENTS.md`" → "Your `CLAUDE.md`, with
+    // `AGENTS.md` included through the import". So the idiom four of the six real
+    // imports in the measured corpus use — a `CLAUDE.md` holding `@AGENTS.md` —
+    // still LOADS that file, and marking it superseded first would have deleted
+    // the whole redirect finding. Both passes see `known`, so whichever gets there
+    // first owns the entry; this one is meant to.
+    //
+    // It also settles the two vendor sentences about what happens INSIDE an
+    // `AGENTS.md` at no extra cost, because both passes are role-blind: "`@path`
+    // imports are expanded" is this loop over any loaded entry, and
+    // "`claudeMdExcludes` patterns apply" is `take` above. Asserted rather than
+    // assumed — `instruction-chain.test.ts` runs each against an `AGENTS.md` that
+    // got in as a ROOT file, since a role-keyed version of either would pass every
+    // `CLAUDE.md` case and fail exactly those two.
+    for (const entry of [...b.loaded])
+        takeImportsOf(b, entry);
+    // THE SUBDIRECTORY PASS, AFTER THE IMPORTS AND NOT BEFORE THEM. Order is the
+    // whole of a fixed bug: this pass claims ANY slash path whose leaf is an
+    // instruction name, and `takeImportsOf` skips a path already `known`. Running
+    // it first therefore swallowed `@pkg/CLAUDE.md` and `@pkg/AGENTS.md` — a
+    // file the root instruction file literally imports, which the loader expands
+    // at session start (measured on 2.1.278, case `q2-import`: an `InstructionsLoaded` entry reading
+    // `pkg/CLAUDE.md | load_reason: include | parent_file_path: CLAUDE.md`) — and
+    // filed it `on-demand/subdirectory`, dropping its bytes from BOTH totals. Only
+    // the leaf name decided it, so `@pkg/style.md` was counted and `@pkg/CLAUDE.md`
+    // was not: the same import, reported two ways.
+    //
+    // 🔴 THE FIX IS THE ORDER, NOT A CONDITION, and that is why it is cheap. A
+    // sibling test — "is there a `pkg/CLAUDE.md` next to this `pkg/AGENTS.md`" —
+    // is the shape this pass CANNOT answer (see its own header: no `<dir>/…` path
+    // is ever a candidate, so absence carries no information). Letting the imports
+    // pass go first makes the question moot BY CONSTRUCTION: an imported file is
+    // taken because a token names it, and what this pass then sees is exactly the
+    // set nothing imported. The bound is untouched — no new path is read.
+    takeSubdirectories(b, new Set([input.instructionFile, AGENTS_FILE]), new Set(crossToolPaths));
+    // THE VERDICT, LAST: anything cross-tool that the passes above did not claim
+    // is present, unread, and the reason is a file rather than a setting. `scope`
+    // stays `"repo"` — this IS a committed file — and `byScope` carries whether
+    // the thing that silenced it is committed too, which is what decides whether a
+    // teammate loads it. See `weighInstructions`.
+    if (superseder !== undefined) {
+        const named = new Set([...b.loaded, ...b.unloaded].map((e) => e.path));
+        for (const path of crossToolPaths) {
+            if (b.files[path] === undefined || named.has(path))
+                continue;
+            b.unloaded.push({
+                path,
+                role: "root",
+                scope: "repo",
+                reason: {
+                    kind: "superseded",
+                    by: superseder.path,
+                    byScope: superseder.scope,
+                },
+            });
+        }
+    }
+    return {
+        loaded: b.loaded,
+        unloaded: b.unloaded,
+        imports: b.imports,
+        patterns: [],
+        // A loaded file that is NOTHING BUT imports is a redirect, not instructions
+        // — reported as a shape so the report can say so instead of printing the
+        // reassuring size of a fourteen-byte pointer.
+        redirects: b.loaded.flatMap((entry) => {
+            const text = files[entry.path];
+            if (text === undefined || !isPureRedirect(text))
+                return [];
+            const to = b.imports
+                .filter((i) => i.from === entry.path)
+                .map((i) => i.path);
+            return to.length === 0 ? [] : [{ path: entry.path, to }];
+        }),
+    };
+}
+//# sourceMappingURL=instruction-chain.js.map

package/dist/adapters/claude-code/layout.d.ts

@@ -3,11 +3,11 @@
  * port's reference implementation). `loadPlugin` defaults to it; a Codex adapter
  * defines a sibling `codexLayout` and passes it to the same loader.
  * 🔴 THE PATHS BELOW ARE DOCUMENTED IN `docs/configuration.md`. Change any of
- * them — `instructionFile`, `surfaceDirs`, `userSurfaceRoot`, `rulesDir` — and
+ * them — `instructionFile`, `surfaces`, `userSurfaceRoot`, `rulesDir` — and
  * that page is wrong until you edit it too. The page marks this symbol with
  * `vigiles:symbol`, so RENAMING it turns `vigiles lint` red and forces the
  * edit; changing a VALUE in place does not, and nothing today catches that.
  */
-import type { PluginLayout } from "../../core/layout.js";
+import { type PluginLayout } from "../../core/layout.js";
 export declare const claudeCodeLayout: PluginLayout;
 //# sourceMappingURL=layout.d.ts.map