fix(audit): a pointer is not a rule document, so stop scoring it (0.1.0-alpha.12)

README.md

@@ -106,7 +106,7 @@ Relative `--target` paths resolve from your current shell cwd. If you are alread
 
 Choose the lane that matches your setup before your first run.
 
-If you are collecting the outside-user proof, stay on the exact pinned version and launcher from [First User Proof](docs/first-user-proof.md) instead of switching to the unpinned examples in this README. The current pinned `0.1.0-alpha.11` proof packet uses one repo-root `bunx` command with `--ci --output ./anvil-audit.md` so the saved report comes back from the first run.
+If you are collecting the outside-user proof, stay on the exact pinned version and launcher from [First User Proof](docs/first-user-proof.md) instead of switching to the unpinned examples in this README. The current pinned `0.1.0-alpha.12` proof packet uses one repo-root `bunx` command with `--ci --output ./anvil-audit.md` so the saved report comes back from the first run.
 
 ### Local-only first pass (no provider required)
 
@@ -151,7 +151,7 @@ bun run ./bin/anvil.ts --version
 Verified on the current alpha packet:
 
 - `--help` prints the four shipped entry commands: `audit`, `drift`, `bootstrap`, `mine-pr`
-- `--version` prints `0.1.0-alpha.11`
+- `--version` prints `0.1.0-alpha.12`
 
 Why you might choose this lane:
 
@@ -173,10 +173,10 @@ For first-run setup and CI/lint guidance, see:
 
 Lambda Curry maintains this project with internal automation behind it, but that machinery is secondary to the public product path above.
 
-- **Status:** Report as Decision Tool shipped; current charter follow-through is to collect outside-Lambda-Curry first-run proof on pinned `0.1.0-alpha.11`
+- **Status:** Report as Decision Tool shipped; current charter follow-through is to collect outside-Lambda-Curry first-run proof on pinned `0.1.0-alpha.12`
 - **Verification posture:** CI artifact (audit report) + downstream observed impact in rule quality
 - **Current checked-in self-audit:** `docs/audits/anvil-audit-2026-08-08.md` reports `98/100` Structural Lint, `35/35` Guardrail Readiness, `0` issues, and `0` remediation tasks on current `main`
-- **Current proof packet:** `docs/proofs/current-outside-tester-send-packet.md` keeps the external proof lane on one canonical repo-root command that saves `./anvil-audit.md`; the pinned packet stays on `@lambdacurry/anvil@0.1.0-alpha.11`
+- **Current proof packet:** `docs/proofs/current-outside-tester-send-packet.md` keeps the external proof lane on one canonical repo-root command that saves `./anvil-audit.md`; the pinned packet stays on `@lambdacurry/anvil@0.1.0-alpha.12`
 
 Anvil is not primarily a UI project. Its real proof surface is whether downstream outputs and consumers reflect the intended rule behavior correctly.
 

docs-site/public/llms-full.txt

@@ -745,7 +745,7 @@ anvil audit --target ./my-repo [options]
 
 Relative `--target` paths resolve from your current shell cwd.
 
-If you arrived here from the external first-user proof docs, use the exact pinned command from that packet. The current `0.1.0-alpha.11` packet uses the public `--ci` spelling; `--no-ai` remains only as a deprecated compatibility alias.
+If you arrived here from the external first-user proof docs, use the exact pinned command from that packet. The current `0.1.0-alpha.12` packet uses the public `--ci` spelling; `--no-ai` remains only as a deprecated compatibility alias.
 
 ## `anvil drift`
 

docs-site/src/content/docs/reference/cli.md

@@ -32,7 +32,7 @@ anvil audit --target ./my-repo [options]
 
 Relative `--target` paths resolve from your current shell cwd.
 
-If you arrived here from the external first-user proof docs, use the exact pinned command from that packet. The current `0.1.0-alpha.11` packet uses the public `--ci` spelling; `--no-ai` remains only as a deprecated compatibility alias.
+If you arrived here from the external first-user proof docs, use the exact pinned command from that packet. The current `0.1.0-alpha.12` packet uses the public `--ci` spelling; `--no-ai` remains only as a deprecated compatibility alias.
 
 ## `anvil drift`
 

docs/byok-trust-model.md

@@ -18,7 +18,7 @@ By default, Anvil scans your repo locally, then expects a working AI provider fo
 
 If you want the privacy-first path, run:
 
-> **Current alpha note:** The published `0.1.0-alpha.11` proof packet uses one canonical repo-root `bunx` command with `--ci --output ./anvil-audit.md`. Packaged relative `--target` and `--output` paths still resolve from your shell cwd, so normal repo-relative first-run commands are honest when you use the unpinned command (it tracks the latest published build).
+> **Current alpha note:** The published `0.1.0-alpha.12` proof packet uses one canonical repo-root `bunx` command with `--ci --output ./anvil-audit.md`. Packaged relative `--target` and `--output` paths still resolve from your shell cwd, so normal repo-relative first-run commands are honest when you use the unpinned command (it tracks the latest published build).
 
 ```bash
 # zero-install

docs/first-user-proof-packet.md

@@ -20,7 +20,7 @@ Send back whether it worked first try, the first useful fix the report pointed t
 bunx @lambdacurry/anvil@<exact-version> audit --target . --ci --output ./anvil-audit.md
 ```
 
-Replace `<exact-version>` with the specific published build you want validated. The current `0.1.0-alpha.11` proof packet sends only the repo-root saved-report command above so the artifact comes back from the same first run without asking the tester to choose between layouts.
+Replace `<exact-version>` with the specific published build you want validated. The current `0.1.0-alpha.12` proof packet sends only the repo-root saved-report command above so the artifact comes back from the same first run without asking the tester to choose between layouts.
 
 Helpful docs:
 - Getting started: https://lambda-curry.github.io/anvil/getting-started/first-audit
@@ -54,7 +54,7 @@ Before sending the note above, make sure:
 
 ## 3. Exact command blocks to send
 
-Pick one install path and one shell layout, then send only that exact command so the tester is not choosing between multiple moving parts. For the current `0.1.0-alpha.11` packet, the canonical layout is Bun zero-install from the target repo root.
+Pick one install path and one shell layout, then send only that exact command so the tester is not choosing between multiple moving parts. For the current `0.1.0-alpha.12` packet, the canonical layout is Bun zero-install from the target repo root.
 
 Replace `<exact-version>` before you send anything. Do not use the floating `@alpha` tag in the external proof packet.
 
@@ -128,7 +128,7 @@ bun run verify:first-user-proof -- docs/proofs/YYYY-MM-DD-<tester>-first-user-pr
 ```
 
 The validator returns a deterministic `counts` / `does-not-count` result and names the missing proof fields or contract mismatches directly.
-For the current pinned `0.1.0-alpha.11` proof lane, that includes checking that the retained audit command keeps the packet's `--ci` spelling.
+For the current pinned `0.1.0-alpha.12` proof lane, that includes checking that the retained audit command keeps the packet's `--ci` spelling.
 When the packet keeps a local report artifact, it also requires `Saved report path or screenshot link` to match the retained audit command's `--output` path.
 
 Save one small packet with these fields:

docs/first-user-proof.md

@@ -15,7 +15,7 @@ Capture one real outside-Lambda-Curry run that proves:
 
 Do this only after the exact published version you want to validate is live, and before Milestone 3 is called complete.
 
-Do not send this packet with the floating `@alpha` tag. Replace `<exact-version>` in the command below with the specific published build you are validating, for example `0.1.0-alpha.11`.
+Do not send this packet with the floating `@alpha` tag. Replace `<exact-version>` in the command below with the specific published build you are validating, for example `0.1.0-alpha.12`.
 
 ## Suggested tester profile
 
@@ -115,7 +115,7 @@ bun run verify:first-user-proof -- docs/proofs/YYYY-MM-DD-<tester>-first-user-pr
 ```
 
 That validator checks the outside-tester status, pinned CLI version, first-try success, returned artifact, and other minimum packet fields, then returns `counts` or `does-not-count` with explicit reasons.
-For the current pinned `0.1.0-alpha.11` proof lane, it requires the retained audit command to keep the exact `--ci` spelling from the packet.
+For the current pinned `0.1.0-alpha.12` proof lane, it requires the retained audit command to keep the exact `--ci` spelling from the packet.
 
 ## Done signal for Milestone 3 gate
 

docs/getting-started.md

@@ -64,7 +64,7 @@ anvil --version
 What you should see in the current alpha:
 
 - `--help` lists the four shipped commands: `audit`, `drift`, `bootstrap`, `mine-pr`
-- `--version` prints `0.1.0-alpha.11`
+- `--version` prints `0.1.0-alpha.12`
 
 If you are validating Anvil from a cloned checkout instead of a global install, run:
 
@@ -125,7 +125,7 @@ Top 5 improvements:
 
 ## Save the report to a file
 
-> **Current alpha note:** The published `0.1.0-alpha.11` proof packet uses one canonical repo-root `bunx` command with `--ci --output ./anvil-audit.md`, while the packaged CLI still resolves relative `--target` and `--output` paths from your shell cwd on `bunx`, `npx`, and Bun global install. Normal relative-path examples are honest when you use the unpinned command (it tracks the latest published build).
+> **Current alpha note:** The published `0.1.0-alpha.12` proof packet uses one canonical repo-root `bunx` command with `--ci --output ./anvil-audit.md`, while the packaged CLI still resolves relative `--target` and `--output` paths from your shell cwd on `bunx`, `npx`, and Bun global install. Normal relative-path examples are honest when you use the unpinned command (it tracks the latest published build).
 
 ```bash
 # zero-install with bunx
@@ -235,7 +235,7 @@ anvil audit \
 
 `--ci` keeps discovery, drift detection, coverage scoring, and markdown output local. The report headline becomes `Structural Lint Score`, and the improvement section is generated from repo-local heuristics instead of a provider.
 
-`--no-ai` still works as a deprecated compatibility alias for the same mode. The current external first-user proof packet stays pinned to `0.1.0-alpha.11` and uses `--ci` for the local-only lane.
+`--no-ai` still works as a deprecated compatibility alias for the same mode. The current external first-user proof packet stays pinned to `0.1.0-alpha.12` and uses `--ci` for the local-only lane.
 
 Privacy-first example artifact from the same example target:
 

docs/proofs/current-outside-tester-send-packet.md

@@ -2,7 +2,7 @@
 
 Use this packet to route one outside-Lambda-Curry tester through Anvil's remaining Milestone 3 proof lane.
 
-This packet stays pinned to `@lambdacurry/anvil@0.1.0-alpha.11`. Do not swap the tester onto the floating `@alpha` tag.
+This packet stays pinned to `@lambdacurry/anvil@0.1.0-alpha.12`. Do not swap the tester onto the floating `@alpha` tag.
 
 ## Three-line opener
 
@@ -15,7 +15,7 @@ Send back whether it worked first try, the first useful fix the report pointed t
 ## Exact command to send
 
 ```bash
-bunx @lambdacurry/anvil@0.1.0-alpha.11 audit --target . --ci --output ./anvil-audit.md
+bunx @lambdacurry/anvil@0.1.0-alpha.12 audit --target . --ci --output ./anvil-audit.md
 ```
 
 Send this as the only command. It assumes the tester is already in the target repo root, guarantees the saved report path, and keeps the local-only flag aligned with current public docs.
@@ -27,7 +27,7 @@ Could you try one first-run Anvil audit on a real repo of yours?
 Paste the single command below from that repo's root; it saves `./anvil-audit.md`, stays local, and does not require an AI provider.
 
 ```bash
-bunx @lambdacurry/anvil@0.1.0-alpha.11 audit --target . --ci --output ./anvil-audit.md
+bunx @lambdacurry/anvil@0.1.0-alpha.12 audit --target . --ci --output ./anvil-audit.md
 ```
 
 Helpful docs:
@@ -39,15 +39,15 @@ What I'd love back:
 1. Whether the exact command worked on the first try
 2. If it did not, what failed first
 3. If you changed the launcher or command, what you used instead
-   - If you switched to global `anvil`, keep both the pinned `bun add -g @lambdacurry/anvil@0.1.0-alpha.11` line and the `anvil audit ...` line together in `Exact command`.
+   - If you switched to global `anvil`, keep both the pinned `bun add -g @lambdacurry/anvil@0.1.0-alpha.12` line and the `anvil audit ...` line together in `Exact command`.
 4. Whether you ran it from the repo root or somewhere else
 5. The first useful fix the report pointed to, if any
 6. Anything that felt confusing, too internal, or too hand-wavy
 7. The saved `anvil-audit.md` file or one screenshot/report excerpt from the run
    - If you send back the saved report path itself, keep `./anvil-audit.md`, the exact path the retained command wrote with `--output`.
 
 If you want one extra cross-check, this should print the same pinned version:
-`bunx @lambdacurry/anvil@0.1.0-alpha.11 --version`
+`bunx @lambdacurry/anvil@0.1.0-alpha.12 --version`
 
 If you changed launchers before the successful run, use the matching `--version` command from that same install path instead of mixing launchers in the saved packet. Do not append `anvil --version` to a `bunx` or `npx` proof packet.
 
@@ -57,7 +57,7 @@ Count this as Milestone 3 proof only if all of these are true:
 
 - the tester is outside Lambda Curry
 - the tester completes a successful first run on a real repo
-- the retained audit command keeps the pinned `0.1.0-alpha.11` local-only `--ci` spelling
+- the retained audit command keeps the pinned `0.1.0-alpha.12` local-only `--ci` spelling
 - the exact command and returned artifact are retained in a saved proof packet
 - any rough edge found is captured as follow-up work
 
@@ -79,7 +79,7 @@ bun run verify:first-user-proof -- docs/proofs/YYYY-MM-DD-<tester>-first-user-pr
 ```
 
 Run that verifier from an Anvil repo checkout or an unpacked published Anvil package root; the verifier now ships with the same proof-doc bundle.
-It keys validation off the saved packet's `Pinned CLI version`, so this retained `0.1.0-alpha.11` packet can still be checked after current `main` advances to a later package version.
+It keys validation off the saved packet's `Pinned CLI version`, so this retained `0.1.0-alpha.12` packet can still be checked after current `main` advances to a later package version.
 
 Historical note: the original dated retained packet for this same pinned proof lane remains at `docs/proofs/2026-05-23-alpha4-outside-tester-send-packet.md`.
 

docs/rubric.md

@@ -170,6 +170,8 @@ Globs: [if glob-matched] / alwaysApply: [true/false] / on-demand: [how to pull]
 
 The two paths cover different genres, and short files depend on the first. A 35-line Cursor `.mdc` rule states its rationale in one dense paragraph, which rarely trips two separate prose families — the label is what carries it. Long-form instruction files usually pass on prose alone. **You need one of the two, not both.**
 
+*Pointers are not scored.* A `CLAUDE.md` whose body is an `@AGENTS.md` import is a redirect to the canonical document, not a rule document, so it leaves the Low-Yield denominator entirely rather than being counted and forgiven — requiring rationale and examples of a redirect would only invite padding it. The signal is the import, not the length: a genuinely thin rule document of the same size is still scored, and still fails. Such a file does still count toward Context Load Pressure, because Claude loads the shim in addition to the file it imports.
+
 **Examples are load-bearing.** A rule without examples is a hypothesis. Examples demonstrate the failure mode in a form the model can pattern-match against.
 
 **Imperative voice.** Rules give instructions. Use "Use X" not "X should be used." Use "Never modify Y" not "Y shouldn't be modified."

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lambdacurry/anvil",
-  "version": "0.1.0-alpha.11",
+  "version": "0.1.0-alpha.12",
   "description": "AI rules + engineering guardrails audit engine for AI-assisted codebases",
   "keywords": [
     "agents",

scripts/audit.ts

@@ -1313,11 +1313,9 @@ function classifyMirrorStatus(
  * the maintainer to "repair" a working cross-tool contract.
  */
 function importsItsMirrorSource(file: RuleFile): boolean {
-  try {
-    return /^\s*@AGENTS\.md\s*$/m.test(readFileSync(file.path, "utf8"));
-  } catch {
-    return false;
-  }
+  // Classified once at parse time; this used to re-read the file from disk with
+  // a second copy of the same regex.
+  return file.importsRootMirror;
 }
 
 function comparableMirrorFingerprint(file: RuleFile): string {
@@ -2143,10 +2141,19 @@ export function assessStageD(
 ): { stage: StageResult; metrics: OverkillMetrics } {
   const load = summarizeLoad(countableLoadFiles(scoringRuleFiles));
   const alwaysOnLines = load.alwaysOnLines;
-  const lowYieldRules = scoringRuleFiles.filter(
+  // A pointer redirects to the canonical document; it carries no rules, so
+  // asking it for rationale and examples asks the maintainer to pad a redirect.
+  // It leaves the denominator, not just the numerator — it was never a rule
+  // document to score. Note this is scoped to Low-Yield deliberately: the same
+  // file still counts toward Context Load Pressure, because Claude really does
+  // load the shim in addition to what it imports.
+  const lowYieldCandidates = scoringRuleFiles.filter(
+    (ruleFile) => !ruleFile.importsRootMirror,
+  );
+  const lowYieldRules = lowYieldCandidates.filter(
     (ruleFile) => !ruleFile.hasWhySection || !ruleFile.hasExamplesSection,
   ).length;
-  const lowYieldRatio = ratio(lowYieldRules, scoringRuleFiles.length);
+  const lowYieldRatio = ratio(lowYieldRules, lowYieldCandidates.length);
   const keywordConflicts = detectKeywordConflicts(scoringRuleFiles);
 
   const redundancyPressure = clamp01(inventory.accidentalDuplicationRate * 3);
@@ -2220,8 +2227,8 @@ export function assessStageD(
       label: "Low-Yield Rule Ratio",
       status: lowYieldStatus,
       detail: toolNativeAdvisoryLowYield
-        ? `${lowYieldRules}/${scoringRuleFiles.length || 0} scoring files miss Why or Examples; tool-native-first surface keeps this advisory while duplication/conflict/load stay healthy`
-        : `${lowYieldRules}/${scoringRuleFiles.length || 0} scoring files miss Why or Examples`,
+        ? `${lowYieldRules}/${lowYieldCandidates.length || 0} scoring files miss Why or Examples; tool-native-first surface keeps this advisory while duplication/conflict/load stay healthy`
+        : `${lowYieldRules}/${lowYieldCandidates.length || 0} scoring files miss Why or Examples`,
     },
   ];
 

scripts/lib/document-role.ts

@@ -0,0 +1,26 @@
+/**
+ * What *kind* of document a rule file is, as distinct from what any check does
+ * with it.
+ *
+ * Anvil has accumulated several "this file is not really a rule document"
+ * predicates — symlink aliases, agent-workspace personas, generated mirror
+ * twins, and pointers. They are not interchangeable, and deliberately do not
+ * live behind one shared policy: the same role earns opposite treatment in
+ * different checks. A pointer is *excluded* from Low-Yield because it is not a
+ * rule document, and simultaneously *included* in Context Load Pressure because
+ * Claude genuinely loads it in addition to the file it imports.
+ *
+ * So this module names roles. It does not decide what to do about them.
+ */
+
+/**
+ * A file whose body redirects to the canonical document rather than carrying
+ * rules itself — the sanctioned alternative to a symlink, used where Claude
+ * needs extras that Codex must not receive.
+ *
+ * Pointer-ness is about the import, not about length: a genuinely thin 11-line
+ * rule document is still a rule document and still has to earn its keep.
+ */
+export function isPointerDocument(content: string): boolean {
+  return /^\s*@AGENTS\.md\s*$/m.test(content);
+}