@codyswann/lisa 4.48.0 → 4.50.0

package/plugins/src/base/scripts/intake-blocker-reprobe.mjs

@@ -37,6 +37,143 @@ function normalizeLabels(labels) {
     .filter(label => label.length > 0);
 }
 
+/**
+ * Decoration a declaration may sit behind, and nothing more.
+ *
+ * Whitespace, blockquote arrows, list bullets or numbers, emphasis, a comment
+ * hash, and an opening HTML comment. `#` is there on EVIDENCE rather than
+ * taste: a shell script declares a hold as `# <marker> reason=…` — a bare
+ * marker behind a SHELL comment, with no HTML comment anywhere — and that form
+ * is in this repository's own guard fixtures. A single character class plus two
+ * optional groups —
+ * deliberately not a nested-quantifier pattern, because this runs over
+ * untrusted work-item bodies and `sonarjs/slow-regex` is right about that
+ * shape.
+ */
+const LEADING_DECORATION =
+  /^[ \t>*_+#-]*(?:\d+[.)][ \t]*)?(?:<!--[ \t]*)?[ \t]*/u;
+
+/**
+ * The body with fenced blocks and inline code spans removed.
+ *
+ * Documentation of a declaration is not a declaration, and a fenced example is
+ * how the declaration form gets written ABOUT. The same move
+ * `pr-arming-sweep.mjs` makes for the auto-merge-off marker
+ * (CodySwannGT/lisa#3986), and the same one `block-direct-issue-create.sh`
+ * makes when it strips heredoc bodies before tokenising argv.
+ * @param {unknown} body - The raw item body
+ * @returns {string} The body with quoted and code regions blanked out
+ */
+function declarativeText(body) {
+  return String(body ?? "")
+    .replace(/```[\s\S]*?```/gu, "")
+    .replace(/`[^`\n]*`/gu, "");
+}
+
+/**
+ * Whether an HTML comment on this line carries the marker.
+ *
+ * The second declaration form, and it is not a concession: an HTML comment is
+ * invisible when the body is rendered, so nobody writes one to TALK about the
+ * marker — a quotation has to be visible to be a quotation. Prose about the
+ * marker is written in sentences, code spans and fenced examples, all of which
+ * this rule already excludes.
+ *
+ * Scanned rather than pattern-matched. A regular expression with two lazy
+ * `[^\n]*?` runs around a literal is the ambiguous shape this module avoids
+ * elsewhere, and an indexOf walk is both linear and easier to be sure about.
+ * @param {string} line - One line of the body
+ * @returns {boolean} True when a comment on this line contains the marker
+ */
+function commentCarriesMarker(line) {
+  const segments = line.split("<!--");
+  for (let index = 1; index < segments.length; index += 1) {
+    const close = segments[index].indexOf("-->");
+    const inside =
+      close === -1 ? segments[index] : segments[index].slice(0, close);
+    if (inside.includes(HUMAN_GATE_MARKER)) return true;
+  }
+  return false;
+}
+
+/**
+ * Whether one line DECLARES a hold rather than mentioning one.
+ *
+ * Two accepted forms, and the corpus says they cost nothing to combine:
+ * measured over this repository's 42 matching bodies, line-leading alone and
+ * line-leading-or-comment hold the SAME 29. The comment branch exists because
+ * the filing guard reads inputs that are not markdown documents — a one-line
+ * `--body` string and a shell script — where a declaration legitimately sits
+ * after other text on its line.
+ * @param {string} line - One line of the body
+ * @returns {boolean} True when the line declares a hold
+ */
+function declaresOnLine(line) {
+  if (line.replace(LEADING_DECORATION, "").startsWith(HUMAN_GATE_MARKER)) {
+    return true;
+  }
+  return commentCarriesMarker(line);
+}
+
+/**
+ * Count what a body says about the hold marker, split by what it MEANS.
+ *
+ * ## Why the substring test had to go
+ *
+ * `isHumanGated` asked one question — does the body contain the marker
+ * anywhere — and that form was deliberate, documented, and correct when it was
+ * written: *"it is a marker with no other meaning, so its presence IS the
+ * declaration."* The premise expired. The marker acquired a second meaning —
+ * **being discussed** — the moment the feature became something people file
+ * tickets about, so a sentence quoting it, a Gherkin line naming it, and a
+ * ticket about it all read as declared holds (CodySwannGT/lisa#3815).
+ *
+ * The consequence is not one skipped cycle. `planHumanGateReconciliation`
+ * removes the ready role and applies the human-needed label, so a false
+ * positive rewrites the item's own metadata and every later sweep agrees with
+ * the first. And the affected population GROWS with the documentation: 38
+ * matching bodies measured 2026-09-04, 42 on 2026-09-05.
+ *
+ * ## The rule
+ *
+ * A declaration is POSITIONAL — the marker leads its line, behind at most
+ * blockquote, list, emphasis or opening-comment decoration — evaluated after
+ * code regions are removed. Measured over this repository's 42 matching bodies:
+ * this holds 29 of them and correctly releases the two live ready-lane items
+ * that only discussed the marker.
+ *
+ * The stricter HTML-comment-only rule was measured and REJECTED: it holds only
+ * 18, dropping declarations that carry `human-needed` today. Losing a real hold
+ * is the unsafe direction and would need a retrofit of the tracker.
+ *
+ * ## Why it counts rather than answering yes or no
+ *
+ * A heuristic that silently drops candidates is indistinguishable from one that
+ * found none. Every occurrence this rule declines to honour is counted and
+ * reported, so "the rule demoted 33 mentions" is a fact an operator can read
+ * rather than an absence they must infer.
+ * @param {unknown} body - The item body
+ * @returns {{ total: number, declared: number, demoted: number }} Occurrences,
+ *   those that declare a hold, and those demoted to mentions
+ */
+export function humanGateMentions(body) {
+  const raw = String(body ?? "");
+  const total = raw.split(HUMAN_GATE_MARKER).length - 1;
+  const declared = declarativeText(raw)
+    .split("\n")
+    .filter(line => declaresOnLine(line)).length;
+  return { total, declared, demoted: total - declared };
+}
+
+/**
+ * Whether a body declares a hold, as opposed to discussing one.
+ * @param {unknown} body - The item body
+ * @returns {boolean} True when at least one line declares a hold
+ */
+export function bodyDeclaresHold(body) {
+  return humanGateMentions(body).declared > 0;
+}
+
 /**
  * Whether an item is held for a person, on either surface.
  *
@@ -64,7 +201,7 @@ export function isHumanGated(input) {
     return true;
   }
 
-  return String(input.body ?? "").includes(HUMAN_GATE_MARKER);
+  return bodyDeclaresHold(input.body);
 }
 
 /**
@@ -432,6 +569,26 @@ export function formatHumanGateNote() {
  * @param {readonly unknown[]} held - Item references held this cycle
  * @returns {string} One summary line
  */
+/**
+ * Render the cycle-summary line naming what the precision rule DEMOTED.
+ *
+ * The counterpart of {@link summarizeHumanGateHolds}, and it exists for the
+ * same reason: a mutation nobody can see afterwards is the problem this whole
+ * area keeps having. A rule that quietly declines to honour half the marker
+ * occurrences it sees reads exactly like a rule that saw none, so the count is
+ * printed even when it is zero — measured across this repository's matching
+ * bodies, 33 of 62 occurrences are mentions rather than declarations.
+ * @param {unknown} demoted - How many occurrences were mentions, not declarations
+ * @returns {string} One summary line
+ */
+export function summarizeHumanGateMentions(demoted = 0) {
+  const count = Number.isFinite(Number(demoted))
+    ? Math.trunc(Number(demoted))
+    : 0;
+  const shown = count > 0 ? String(count) : "none";
+  return `Marker mentions demoted (not declarations): ${shown}.`;
+}
+
 export function summarizeHumanGateHolds(held = []) {
   const names = (Array.isArray(held) ? held : [])
     .map(item => trimmedString(item))

package/plugins/src/base/skills/lisa-drive-pr-to-merge/SKILL.md

@@ -1136,10 +1136,26 @@ not there, and a lifecycle step performed by hand is one nothing can verify
 happened.
 
 **The backstop, for the ones that still slip:** `lisa-work-item.mjs sweep`
-reports every claimed item that already has a merged pull request, and
+reports every open item — in the **ready** lane as well as the **claimed** one —
+that a commit on a deploy branch DECLARES via its `Work-Item:` trailer, and
 `--apply` completes them. Reporting is the default deliberately — a sweep that
 closes things as a side effect of being run is not one anyone runs twice.
 
+You do not need to run it. The `🧹 Lifecycle Drift Sweep` workflow runs it
+daily and files a deduplicated issue when drift exists, because a report with
+no consumer and no report are the same thing with different amounts of code.
+
+Two properties worth knowing, because both were once the other way round:
+
+- **Credit requires a declaration, never a mention.** Evidence is a commit
+  reachable from a deploy branch whose own trailer names the item. It used to
+  be a timeline cross-reference, which any pull request that so much as *named*
+  `#N` created — so one merged land-stack pull request made every sibling in
+  its batch look shipped. Measured: 8 of 53 reported items had no commit
+  declaring them, and every one of the 8 had live work open against it.
+- **A clean result names the lanes it examined.** "No drift" over a subject
+  list that excluded the ready lane was true and unusable.
+
 ## 4. Terminal states
 
 Loop until one of:

package/plugins/src/base/skills/lisa-github-build-intake/SKILL.md

@@ -332,6 +332,10 @@ other gate's verdict — however conclusive — may promote an item a person par
 4. **Name it in the cycle summary** via `summarizeHumanGateHolds([...])`, so the record
    distinguishes "nothing was eligible" from "something eligible was held for a person". A lane
    mutation nobody can see afterwards is the same class of problem this gate exists to fix.
+   Report alongside it what the precision rule SKIPPED, via `summarizeHumanGateMentions(n)`
+   — the marker occurrences that were mentions rather than declarations (CodySwannGT/lisa#3815).
+   A rule that quietly declines to honour half the occurrences it sees reads exactly like a
+   rule that saw none, so the count is printed even when it is zero.
 5. **Continue to the next candidate.** A held item does not end the cycle.
 
 

package/plugins/src/base/skills/lisa-jira-build-intake/SKILL.md

@@ -237,6 +237,10 @@ other gate's verdict — however conclusive — may promote an item a person par
 4. **Name it in the cycle summary** via `summarizeHumanGateHolds([...])`, so the record
    distinguishes "nothing was eligible" from "something eligible was held for a person". A lane
    mutation nobody can see afterwards is the same class of problem this gate exists to fix.
+   Report alongside it what the precision rule SKIPPED, via `summarizeHumanGateMentions(n)`
+   — the marker occurrences that were mentions rather than declarations (CodySwannGT/lisa#3815).
+   A rule that quietly declines to honour half the occurrences it sees reads exactly like a
+   rule that saw none, so the count is printed even when it is zero.
 5. **Continue to the next candidate.** A held item does not end the cycle.
 
 

package/plugins/src/base/skills/lisa-linear-build-intake/SKILL.md

@@ -231,6 +231,10 @@ other gate's verdict — however conclusive — may promote an item a person par
 4. **Name it in the cycle summary** via `summarizeHumanGateHolds([...])`, so the record
    distinguishes "nothing was eligible" from "something eligible was held for a person". A lane
    mutation nobody can see afterwards is the same class of problem this gate exists to fix.
+   Report alongside it what the precision rule SKIPPED, via `summarizeHumanGateMentions(n)`
+   — the marker occurrences that were mentions rather than declarations (CodySwannGT/lisa#3815).
+   A rule that quietly declines to honour half the occurrences it sees reads exactly like a
+   rule that saw none, so the count is printed even when it is zero.
 5. **Continue to the next candidate.** A held item does not end the cycle.
 
 

package/plugins/src/base/skills/lisa-repair-intake/SKILL.md

@@ -994,7 +994,10 @@ with labels like `build-ready`, or with no Lisa status label at all, that are in
    instead — it says that nothing was changed and how a person resumes the item, which is the
    opposite of what the reconciliation note says and must not be substituted for it. A promotion
    declined silently is invisible, which is the quieter version of the failure this step exists to
-   prevent, so name every held item in the cycle summary via `summarizeHumanGateHolds([...])`.
+   prevent, so name every held item in the cycle summary via `summarizeHumanGateHolds([...])`. Report what the
+   precision rule skipped beside it via `summarizeHumanGateMentions(n)`: the marker
+   occurrences that were mentions rather than declarations (CodySwannGT/lisa#3815),
+   because a rule that silently drops candidates reads like one that found none.
 
 ### Ungated non-ready filing → surface as an incomplete handoff (read-only)
 

package/rails/copy-overwrite/ast-grep/rules/no-day-truncating-file-age-predicate.yml

@@ -0,0 +1,50 @@
+# This file is managed by Lisa and IS replaced on each `lisa` run.
+# Do not edit directly — durable changes belong upstream in Lisa.
+
+id: no-day-truncating-file-age-predicate
+language: bash
+severity: error
+message: |
+  `-mtime`, `-atime` and `-ctime` do NOT mean "older than N days".
+
+  `find` divides the file's age by 86400 and DISCARDS the remainder, so
+  `-mtime +N` matches only files older than N+1 days. Measured on this
+  repository's own platform with fixtures stamped at known ages:
+
+    age    -mtime +2   -mmin +2880
+    47h        no          no
+    49h        NO          yes   <- the whole disagreement
+    71h        NO          yes
+    73h        yes         yes
+
+  The 49h-71h band is silently dropped. The failure direction is what makes
+  this worth a rule: the under-selection reports "nothing to do", and nobody
+  questions an empty result from a cleanup predicate, so it prevents needed
+  work instead of causing visible harm. Reported once as a broken `find`; it
+  is not. `find` is answering a different question than the flag appears to
+  ask, which is exactly why it survives review.
+
+  Write the question you mean:
+
+    older than N days   ->  -mmin +$((N * 1440))
+    older than N days   ->  ! -newermt "<an ISO timestamp N days back>"
+    older than N hours  ->  -mmin +$((N * 60))
+
+  `-mmin` is minute-granularity and is not truncated to days, so it means
+  what it reads. `-newermt` is exact but needs a timestamp, and the two
+  `date` implementations disagree on how to produce one: `date -v-2d` is
+  BSD/macOS and `date -d '2 days ago'` is GNU/Linux. Prefer `-mmin` in any
+  script that runs on both.
+note: |
+  This rule matches the flag itself rather than a `find` invocation, so it
+  still fires through `/usr/bin/find`, `$FIND`, and `xargs find`. There are
+  no legitimate uses in this repository: every shipped age predicate already
+  uses `-mmin`, and this rule exists to keep it that way, because `-mtime` is
+  the form a maintainer reaches for by reflex and the shell hooks that carry
+  these predicates are copied across five per-agent plugin variants, so one
+  wrong edit lands in eight files at once.
+
+  See CodySwannGT/lisa#3905.
+rule:
+  kind: word
+  regex: ^-(mtime|atime|ctime)$

package/rails/copy-overwrite/scripts/threshold-ratchet-families.mjs

@@ -75,6 +75,18 @@ export const FAMILIES = [
     match: /(^|\/)\.github\/k6\/thresholds\/[^/]+\.json$/,
     kind: "k6",
   },
+  {
+    // #3992. The always-on eager rule tier is concatenated into every session
+    // AND every subagent start, so its byte ceiling is a quality threshold like
+    // any other. `max` because the number is a ceiling: lowering it tightens the
+    // gate and is free, raising it re-authorises context the cleanup removed and
+    // is the change a human has to see. The tier was cut to 26,540 bytes once
+    // and regrew to 201,083 in fourteen weeks with nothing watching it.
+    id: "eager-rules",
+    match: /(^|\/)eager-rules\.thresholds\.json$/,
+    kind: "json-num",
+    direction: "max",
+  },
   {
     id: "lisa-config",
     match: /(^|\/)\.lisa\.config\.json$/,

package/scripts/check-eager-rule-budget.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * CI gate on the total size of the always-on eager rule tier.
+ *
+ * WHY THIS EXISTS, AND WHY IT IS A GATE RATHER THAN A REPORT.
+ *
+ * `plugins/<plugin>/rules/eager/*.md` is concatenated into `additionalContext`
+ * by `inject-rules.sh` on **SessionStart and SubagentStart**, mirrored into
+ * `.codex/lisa-rules/eager/` and `.opencode/lisa-rules/`, and flattened to
+ * Cursor `.mdc` files with `alwaysApply: true`. Every session in every adopting
+ * project pays for it before its first tool call, and so does every subagent —
+ * a lead plus ten teammates pays it eleven times.
+ *
+ * This tier has already been cleaned up once and grown back. Measured from git:
+ *
+ *   pre-split (flat rules/)   12 files   190,237 bytes
+ *   2026-05-28 after a820527  13 files    26,540 bytes   ("~86% smaller")
+ *   2026-07-15                19 files    49,488 bytes
+ *   2026-07-30                36 files   105,198 bytes
+ *   2026-09-05                56 files   201,083 bytes
+ *
+ * Fourteen weeks took it to 7.6x the post-cleanup figure and 5.7% PAST the
+ * payload the cleanup was created to remove. Nothing measured it, so nobody saw
+ * it happen — every individual addition was defensible. A fix performed once
+ * and undone by accretion needs a guard, not a second tidy (#3992).
+ *
+ * TOTAL BYTES, NOT PER FILE. A per-file cap is defeated by splitting one rule
+ * into two, and the file count is exactly what already moved: 13 -> 56. The
+ * cost to a session is the sum, so the sum is what is measured.
+ *
+ * THE CEILING lives in `eager-rules.thresholds.json` (root, beside the other threshold files) and
+ * is registered as a `max`-direction family in `threshold-ratchet-families.mjs`,
+ * so it may only tighten: lowering it is free, raising it is a weakening that
+ * needs a `thresholdRatchet.allow` entry with a written reason. See
+ * `threshold-ratchet.mjs` for why an allow entry is read only from the baseline.
+ *
+ * ALL THREE ROOTS are checked, not just the source. `plugins/lisa/` and
+ * `plugins/lisa-copilot/` are generated copies that ship to Claude and Copilot;
+ * checking only `plugins/src/base` would gate the input to a generator while the
+ * artifacts that actually reach a session went unmeasured.
+ *
+ * It refuses to pass an inspection it did not perform: zero roots or zero rule
+ * files is exit 2, not a passing zero. Every gate in the `plugins-sync` job
+ * takes that stance, and it is why they are trustworthy — a scan that finds
+ * nothing and a tree that is clean otherwise print the same tick.
+ * @module scripts/check-eager-rule-budget
+ */
+import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPO_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  ".."
+);
+
+/** Plugin roots whose eager tier ships to a session. */
+const CHECKED_PLUGINS = ["src/base", "lisa", "lisa-copilot"];
+
+/** Committed ceiling, ratcheted by the `eager-rules` threshold family. */
+const THRESHOLDS_FILE = path.join(REPO_ROOT, "eager-rules.thresholds.json");
+
+/**
+ * Total the `.md` payload of one plugin's eager rules directory.
+ * @param {string} pluginRelPath - Plugin path relative to `plugins/`.
+ * @returns {{ root: string, files: number, bytes: number } | undefined} The
+ *   measurement, or undefined when the plugin has no eager directory.
+ */
+function measureEagerTier(pluginRelPath) {
+  const dir = path.join(REPO_ROOT, "plugins", pluginRelPath, "rules", "eager");
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return undefined;
+  const files = readdirSync(dir).filter(name => name.endsWith(".md"));
+  const bytes = files.reduce(
+    (total, name) =>
+      total + Buffer.byteLength(readFileSync(path.join(dir, name))),
+    0
+  );
+  return {
+    root: `plugins/${pluginRelPath}/rules/eager`,
+    files: files.length,
+    bytes,
+  };
+}
+
+/**
+ * Read the committed byte ceiling.
+ * @returns {number} The ceiling in bytes.
+ */
+function readCeiling() {
+  if (!existsSync(THRESHOLDS_FILE)) {
+    process.stderr.write(
+      `✗ Missing ${path.relative(REPO_ROOT, THRESHOLDS_FILE)} — the eager budget ` +
+        `cannot be checked without its committed ceiling.\n`
+    );
+    process.exit(2);
+  }
+  const parsed = JSON.parse(readFileSync(THRESHOLDS_FILE, "utf8"));
+  const ceiling = parsed.totalBytes;
+  if (
+    typeof ceiling !== "number" ||
+    !Number.isFinite(ceiling) ||
+    ceiling <= 0
+  ) {
+    process.stderr.write(
+      `✗ ${path.relative(REPO_ROOT, THRESHOLDS_FILE)} has no usable ` +
+        `"totalBytes" number; refusing to check against an unreadable ceiling.\n`
+    );
+    process.exit(2);
+  }
+  return ceiling;
+}
+
+const ceiling = readCeiling();
+const measured = CHECKED_PLUGINS.map(measureEagerTier).filter(Boolean);
+
+// VACUITY GUARD. A tree with no eager rules and a tree this script failed to
+// read produce the same zero, and the passing branch cannot tell them apart.
+// Exit 2 keeps "I could not measure" distinct from "it is within budget".
+if (measured.length === 0) {
+  process.stderr.write(
+    `✗ No eager rules directory found under any of ${CHECKED_PLUGINS.join(", ")}. ` +
+      `Refusing to report a passing zero for a measurement that did not happen.\n`
+  );
+  process.exit(2);
+}
+const empty = measured.filter(m => m.files === 0);
+if (empty.length > 0) {
+  process.stderr.write(
+    `✗ Eager rules directories with zero .md files: ${empty
+      .map(m => m.root)
+      .join(", ")}. Refusing to report a passing zero.\n`
+  );
+  process.exit(2);
+}
+
+const over = measured.filter(m => m.bytes > ceiling);
+for (const m of measured) {
+  const margin =
+    m.bytes > ceiling
+      ? `over by ${m.bytes - ceiling}`
+      : `${ceiling - m.bytes} to spare`;
+  process.stdout.write(
+    `${(m.bytes > ceiling ? "OVER" : "ok").padEnd(4)} ${m.root}: ${m.files} ` +
+      `files, ${m.bytes} bytes (ceiling ${ceiling}, ${margin})\n`
+  );
+}
+
+if (over.length > 0) {
+  process.stderr.write("\n");
+  for (const m of over) {
+    process.stderr.write(
+      `✗ ${m.root} is ${m.bytes - ceiling} bytes over the eager budget ` +
+        `(${m.bytes} measured, ceiling ${ceiling}).\n`
+    );
+  }
+  process.stderr.write(
+    "\n  Every session AND every subagent in every adopting project pays this " +
+      "payload\n  before its first tool call. Fix it by demoting, not by raising " +
+      "the ceiling:\n\n" +
+      "  1. Move the rule's body to plugins/src/base/rules/reference/<slug>.md\n" +
+      "  2. Add a one-line entry to plugins/src/base/rules/eager/00-rule-index.md\n" +
+      "  3. Delete the eager head and re-run this gate\n\n" +
+      "  A rule stays eager only when an agent behaves WRONGLY without it in a " +
+      "session\n  that never asks for it. Being true, well-argued, and cited by " +
+      "ten skills is not\n  that bar — those rules belong in the index.\n\n" +
+      "  Raising the ceiling in eager-rules.thresholds.json is a weakening: the " +
+      "threshold\n  ratchet refuses it without a thresholdRatchet.allow entry " +
+      "naming a reason.\n"
+  );
+  process.exit(1);
+}
+
+process.stdout.write(
+  `\n✓ Eager rule budget passed across ${measured.length} plugin roots ` +
+    `(ceiling ${ceiling} bytes).\n`
+);

package/scripts/check-generated-artifact-merge-coverage.mjs

@@ -106,6 +106,13 @@ export const GENERATED_ARTIFACTS = Object.freeze([
     reason:
       "nested: a contractVersion / packageVersions / provenances record under each digest, which the driver's flat one-level parser rejects",
   }),
+  Object.freeze({
+    path: "src/core/export-surface.json",
+    check: "check:export-surface",
+    disposition: DISPOSITION.UNSUPPORTED,
+    reason:
+      "nested: a `surface` sub-object mapping each module path to an array of exported names, which the driver's flat one-level parser rejects",
+  }),
 ]);
 
 /**

package/scripts/check-rules-pairing.sh

@@ -1,9 +1,15 @@
 #!/usr/bin/env bash
-# Fails if any plugin's rules/eager/X.md is missing its rules/reference/X.md
-# pair (or vice versa). The eager/reference split documents the contract that
-# every eager head points at a reference body for the long-form detail; an
-# unpaired file means either a head without a body (broken breadcrumb) or a
-# body without a head (orphaned, never injected).
+# Fails when a rule body is unreachable, in either direction.
+#
+# Forward (unchanged): every rules/eager/X.md must have its rules/reference/X.md,
+# because the head's breadcrumb points at that body and a broken pointer is a
+# defect.
+#
+# Reverse (#3992): every rules/reference/X.md must be pointed at by SOMETHING
+# eager — its own head, or a line in rules/eager/00-rule-index.md. This used to
+# demand a dedicated head, which made writing any long-form contract compel a
+# permanent per-session payload; the eager tier grew 7.6x on that incentive.
+# The property being protected is reachability, and an index line provides it.
 #
 # Bootstrap files are exempt: rules/eager/00-bootstrap.md (and any other file
 # matching rules/eager/00-*.md) is allowed to have no reference pair. The
@@ -35,6 +41,13 @@ check_plugin() {
     exempt_pattern="$(grep -v '^[[:space:]]*#' "$exempt_file" | grep -v '^[[:space:]]*$' || true)"
   fi
 
+  # The eager rule index, when this plugin has one. It is itself a 00-* file, so
+  # it is exempt from needing a body of its own.
+  local index_file=""
+  if [ -f "$eager_dir/00-rule-index.md" ]; then
+    index_file="$eager_dir/00-rule-index.md"
+  fi
+
   # Every eager/X.md (except 00-bootstrap-style files and explicit exemptions)
   # must have a reference/X.md pair.
   while IFS= read -r eager_file; do
@@ -55,8 +68,17 @@ check_plugin() {
     fi
   done < <(find "$eager_dir" -maxdepth 1 -type f -name '*.md' | sort)
 
-  # Every reference/X.md must have an eager/X.md pair (catch orphans on the
-  # other side: a reference body with no breadcrumb pointing to it is dead).
+  # Every reference/X.md must be POINTED AT by something eager — either its own
+  # eager/X.md head, or a line in the eager rule index. The invariant is
+  # reachability, not pairing: a body nothing names is dead, and that is what
+  # this arm has always been protecting.
+  #
+  # The index satisfies it because #3992 changed the mechanism. Requiring a
+  # dedicated head made authoring any long-form contract compel an always-on
+  # per-session payload, and the tier grew from 26,540 to 201,083 bytes on that
+  # incentive alone — `credential-substrate-precedence.md` was added purely to
+  # turn this check green. One index line carries the same pointer at ~1% of the
+  # context cost, so the cheap way to satisfy the gate is now also the right one.
   if [ -d "$reference_dir" ]; then
     while IFS= read -r ref_file; do
       local base
@@ -64,11 +86,19 @@ check_plugin() {
       if [ -n "$exempt_pattern" ] && echo "$exempt_pattern" | grep -qxF "$base"; then
         continue
       fi
-      if [ ! -f "$eager_dir/$base" ]; then
-        echo "✗ Orphaned reference body (no eager head): $ref_file" >&2
-        echo "  Expected: $eager_dir/$base" >&2
-        failed=1
+      if [ -f "$eager_dir/$base" ]; then
+        continue
+      fi
+      if [ -n "$index_file" ] && grep -qF "reference/$base" "$index_file"; then
+        continue
       fi
+      echo "✗ Unreachable reference body: $ref_file" >&2
+      echo "  Nothing eager points at it. Give it either:" >&2
+      echo "    - a paired head at $eager_dir/$base, or" >&2
+      echo "    - a line naming reference/$base in $eager_dir/00-rule-index.md" >&2
+      echo "  Prefer the index — a head is loaded into every session and every" >&2
+      echo "  subagent, whether or not anything asks for it." >&2
+      failed=1
     done < <(find "$reference_dir" -maxdepth 1 -type f -name '*.md' | sort)
   fi
 }
@@ -80,9 +110,10 @@ done < <(find "$ROOT_DIR/plugins" -type d -name rules | sort)
 
 if [ "$failed" -ne 0 ]; then
   echo "" >&2
-  echo "  Every rules/eager/X.md must have a paired rules/reference/X.md" >&2
-  echo "  (and vice versa) so the eager head's breadcrumb to the full" >&2
-  echo "  reference body resolves. To exempt a file, either name it" >&2
+  echo "  Every rules/eager/X.md must have a paired rules/reference/X.md so" >&2
+  echo "  its breadcrumb resolves, and every rules/reference/X.md must be" >&2
+  echo "  reachable from either its own head or the eager rule index." >&2
+  echo "  To exempt a file, either name it" >&2
   echo "  00-*.md (bootstrap convention) or list its basename in" >&2
   echo "  <plugin>/rules/.pair-exempt (one per line)." >&2
   exit 1