@codyswann/lisa 4.49.0 → 4.50.1

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