From dec78e89cc24f5258cabfbdfb0f7b2d4d4b3fc76 Mon Sep 17 00:00:00 2001
From: "basquin-bot[bot]" <307641014+basquin-bot[bot]@users.noreply.github.com>
Date: Fri, 31 Jul 2026 11:53:03 -0400
Subject: [PATCH 1/5] =?UTF-8?q?fix(dd045):=20item=202=20=E2=80=94=20a=20tr?=
 =?UTF-8?q?acked=20pointer=20file=20for=20the=20run=20of=20record?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

bench-results/RUN-OF-RECORD is a tracked pointer FILE (not a symlink — this
checkout has core.symlinks=false, on which a tracked symlink materialises as
a plain-text file naming its target rather than resolving) holding one
non-comment line naming the current run-of-record directory.

scripts/check-citations.py's resolve() now substitutes a cited
bench-results/RUN-OF-RECORD/... prefix with the directory the pointer names
before matching it against the tracked tree (resolve_run_of_record()),
reusing the existing FAILED/DEAD-PATH reporting path rather than adding a
parallel one. A dangling, missing, or malformed (0 or 2+ non-comment-line)
pointer is never a silent pass or a guess: each was proven empirically to
produce exit=1 with a DEAD PATH finding naming the reason, and restoring the
pointer returned exit=0 again every time.

Repointed all 14 occurrences across the 5 files that named
verify-20260730T215842Z (counted with grep -o | wc -l, not grep -c, per the
lesson 16da079 shipped) to bench-results/RUN-OF-RECORD/; check-citations.py's
disposition counts are byte-identical before and after. Removed the now-moot
"proposed, not yet built" allowlist exemption for the pointer path.
scripts/verify-dd043-pr3.sh was not touched and does not write this file —
promoting a run stays a deliberate, manual edit in the same commit that adds
the new run directory, per the pointer file's own comment header.

Closes DD-045 item 2 in TODO.md and docs/ROADMAP.md, describing what was
actually delivered.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LHBLwqfM1acog2bHRS8WCb
---
 TODO.md                                       | 32 +++++++---
 bench-results/RUN-OF-RECORD                   | 14 +++++
 .../README.md                                 |  4 +-
 docs/ROADMAP.md                               | 32 ++++++----
 .../2026-07-26-dd043-pr3-maven-injector.md    |  2 +-
 ...26-07-24-native-reactive-targets-design.md |  4 +-
 scripts/check-citations-allowlist.txt         |  1 -
 scripts/check-citations.py                    | 58 +++++++++++++++++++
 8 files changed, 121 insertions(+), 26 deletions(-)
 create mode 100644 bench-results/RUN-OF-RECORD

diff --git a/TODO.md b/TODO.md
index 3e8b5a1..398a2fb 100644
--- a/TODO.md
+++ b/TODO.md
@@ -1184,12 +1184,28 @@ the feature held in every one, and almost every finding was in the machinery tha
       but is gitignored — the citation resolved for its author and was dead on every fresh clone
       (fixed in the same pass that added this entry). Evidence for the scale that motivated building
       it: `bench-results/dd043-pr3-citation-audit-2026-07-30/`.
-- [ ] **2 — a stable pointer to the run of record.** Timestamped `verify-<UTC>/` names mean each new
-      run stales every citation to the previous one at once: **10, 10, 13 and 18** occurrences had to be
-      repointed by the four supersession commits, each figure read out of that commit's own message
-      (`16da079`, `865ba35`, `1c3ce88`, `572282a`) and counted as occurrences rather than matching lines
-      — `16da079` records `grep -c` reporting eight where there were ten. Add
-      `bench-results/RUN-OF-RECORD` and cite that.
+- [x] **2 — a stable pointer to the run of record. Delivered.** Timestamped `verify-<UTC>/` names meant
+      each new run staled every citation to the previous one at once: **10, 10, 13 and 18** occurrences
+      had to be repointed by the four supersession commits, each figure read out of that commit's own
+      message (`16da079`, `865ba35`, `1c3ce88`, `572282a`) and counted as occurrences rather than
+      matching lines — `16da079` records `grep -c` reporting eight where there were ten. Added
+      `bench-results/RUN-OF-RECORD`, a tracked pointer **file** — not a symlink: this checkout has
+      `core.symlinks=false`, on which a tracked symlink materialises as a plain-text file containing its
+      target path rather than resolving. Format: `#`-comment and blank lines ignored, then exactly one
+      line naming a `bench-results/` subdirectory by name only. `scripts/check-citations.py`'s
+      `resolve()` substitutes a cited `bench-results/RUN-OF-RECORD/...` prefix with the directory the
+      pointer names before matching the tracked tree (`resolve_run_of_record()`), reusing the existing
+      FAILED/DEAD-PATH reporting path rather than adding a parallel one. Repointed all **14** occurrences
+      across the **5** files that named `verify-20260730T215842Z` (counted with `grep -o … | wc -l`, not
+      `grep -c`, per the lesson above) to `bench-results/RUN-OF-RECORD/`; `python3
+      scripts/check-citations.py`'s disposition counts are byte-identical before and after the repoint,
+      both runs exit 0. The three failure modes a resolver like this must never silently pass were each
+      proven empirically, not asserted: a pointer naming an untracked directory, a missing pointer file,
+      and a pointer with 0 or 2 non-comment lines each produced a `DEAD PATH` finding and `exit=1`;
+      restoring the pointer returned `exit=0` again every time. `scripts/verify-dd043-pr3.sh` was not
+      touched and does not write this file — promoting a run to run-of-record stays a deliberate, manual
+      edit made in the same commit that adds the new run directory, stated in the pointer file's own
+      comment header.
 - [ ] **3 — mutation-test the harness, not only the guards.** The script proves each of the injector's
       8 guards fails when neutered; nothing proves the script's own rows do. Also: the guards stage
       mutates tracked source in place, so a commit during a run is unsafe — one was observed
@@ -1259,7 +1275,7 @@ were recorded nowhere — the same evaporation that #95 had to go back and fix.
       committed unexercised (the native mutex was held, and the `guards` stage mutates source a running
       build was compiling). **Resolved 2026-07-30**: both stages ran end-to-end in the run of record,
       stamped `20260730T215842Z` and made against `b980e1f` on a clean tree. All four figures come from
-      `bench-results/verify-20260730T215842Z/RESULTS.md`, read by label rather than by line number because
+      `bench-results/RUN-OF-RECORD/RESULTS.md`, read by label rather than by line number because
       that header gains lines: its title line carries the stamp, its `Commit:` line the SHA and
       `tree clean at run start`, its `Stages run:` line `unit jar guards jvm native`, and the line after
       that **27 passed, 0 failed, 0 skipped** — including the `jvm:build`, `jvm:banner`, `native:build` and
@@ -1274,7 +1290,7 @@ were recorded nowhere — the same evaporation that #95 had to go back and fix.
       `## What a pass here does and does not establish` heading, which states what a pass does and does not
       establish. (Cited by heading with no line range at all: the range given here was off by one at both
       ends, and a limitations list that gains a bullet invalidates any range.) Do not re-run the
-      native stage on the strength of this entry; check `bench-results/verify-20260730T215842Z/` first.
+      native stage on the strength of this entry; check `bench-results/RUN-OF-RECORD/` first.
       (An earlier run, `verify-20260729T153141Z`, was **deleted** in `8cadf8a` — its B1 and B2 checks could
       not fail, so it certified nothing. Do not cite it; it is not in the tree.)
 - [ ] **A repo-wide line-citation audit (PR #103 round 7) found 135 wrong citations out of 547
diff --git a/bench-results/RUN-OF-RECORD b/bench-results/RUN-OF-RECORD
new file mode 100644
index 0000000..b2e2855
--- /dev/null
+++ b/bench-results/RUN-OF-RECORD
@@ -0,0 +1,14 @@
+# bench-results/RUN-OF-RECORD — the certified run of record for DD-043 PR-3.
+#
+# scripts/check-citations.py resolves any cited path beginning
+# `bench-results/RUN-OF-RECORD/` against the directory named on the single non-comment line
+# below, so citations do not go stale every time evidence is regenerated (DD-045 item 2).
+# Format: exactly one non-comment, non-blank line, naming a bench-results/ subdirectory by
+# name only — no `bench-results/` prefix, no trailing slash. Zero or more than one such line
+# is a malformed pointer and the checker fails loudly rather than guessing.
+#
+# Promoting a run to run-of-record is a DELIBERATE, MANUAL step: scripts/verify-dd043-pr3.sh
+# never writes this file, so an ad hoc local run cannot silently become the cited evidence.
+# Whoever certifies a new run edits the line below to name it, in the SAME COMMIT that adds
+# the new bench-results/verify-<UTC>/ directory — never as a follow-up commit.
+verify-20260730T215842Z
diff --git a/bench-results/dd043-pr3-restvillains-2026-07-26/README.md b/bench-results/dd043-pr3-restvillains-2026-07-26/README.md
index 1219f95..6651484 100644
--- a/bench-results/dd043-pr3-restvillains-2026-07-26/README.md
+++ b/bench-results/dd043-pr3-restvillains-2026-07-26/README.md
@@ -14,7 +14,7 @@ is established separately, by `scripts/verify-dd043-pr3.sh`'s `jvm` stage — di
 the build (the preflight `git -C "$app" status --porcelain -- .`, whose non-zero `rc` `skip`s the whole
 stage as UNMEASURED) and `jvm:zero-edits` after it
 (`git status --porcelain=v2 --branch -- .` into `jvm-target-status-after.txt`), graded in
-`bench-results/verify-20260730T215842Z/RESULTS.md`'s `jvm:zero-edits` row. All three are cited by
+`bench-results/RUN-OF-RECORD/RESULTS.md`'s `jvm:zero-edits` row. All three are cited by
 command text and row key, not by line: the script's line numbers went stale twice while this very
 citation was being fixed, and any added guard row renumbers that table. The run *directory* is the part
 that still has to be re-checked by hand — the previous name here was superseded and deleted while this
@@ -32,7 +32,7 @@ by the Quarkus bootstrap resolver on its own. **JVM mode only — the native cel
 | 2 | Startup banner lists `basquin` under `Installed features` | `app-startup.log:25`, extracted to `banner.txt` |
 | 3 | The boundary works, not just loads: driven request returns a cost line, not `miss` | `result-poll.txt`: `X-Basquin-Req: pr3-accept-1` → `/__basquin/result?id=pr3-accept-1` → `787,-684,9|0||` |
 | 4 | `basquin-quarkus-deployment` fetched from the injected repo | `http-access.log` (4 GETs for it, all `200`); `build.log:31-36` (`Downloaded from basquin-injected`) |
-| 5 | App tree pristine, checked once, post-hoc | `pristine-proof.txt:6,11`: a single `git status --porcelain`, empty, taken after `clean package` and after the app container ran. The before-**and**-after property (not merely after) is established by the verify run, not this artifact — in `scripts/verify-dd043-pr3.sh`, the preflight `git -C "$app" status --porcelain -- .` (before; a non-zero `rc` `skip`s the stage as UNMEASURED) and `git status --porcelain=v2 --branch -- .` into `jvm-target-status-after.txt` (after). Each is that file's only occurrence, so it is cited by command text, not by a line number that edits keep invalidating. Graded `PASS` at `bench-results/verify-20260730T215842Z/RESULTS.md`'s `jvm:zero-edits` row (row key, not line — an added guard row renumbers the table), against the same clone commit `c9b46d74…` this directory used (that run's `jvm-target-status-after.txt:1`) |
+| 5 | App tree pristine, checked once, post-hoc | `pristine-proof.txt:6,11`: a single `git status --porcelain`, empty, taken after `clean package` and after the app container ran. The before-**and**-after property (not merely after) is established by the verify run, not this artifact — in `scripts/verify-dd043-pr3.sh`, the preflight `git -C "$app" status --porcelain -- .` (before; a non-zero `rc` `skip`s the stage as UNMEASURED) and `git status --porcelain=v2 --branch -- .` into `jvm-target-status-after.txt` (after). Each is that file's only occurrence, so it is cited by command text, not by a line number that edits keep invalidating. Graded `PASS` at `bench-results/RUN-OF-RECORD/RESULTS.md`'s `jvm:zero-edits` row (row key, not line — an added guard row renumbers the table), against the same clone commit `c9b46d74…` this directory used (that run's `jvm-target-status-after.txt:1`) |
 
 Build wall time 01:03 min (`build.log`, `Total time`). On check 3's numbers: 787 ms elapsed is a
 first-hit (Hibernate/Agroal warmup) figure, the −684 KB heap delta is the reactive-path GC-in-window
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index 87428bb..fa47395 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -45,7 +45,7 @@ work, not cleanup of this thread.
 | **DD-043** | Native + reactive targets — build-time instrumentation of a GraalVM-native Quarkus app | **Phase 0 done, gate PASSED** — **merged** as [#98](https://github.com/ianp94/basquin/pull/98) (2026-07-24). All four spikes resolved; S1 REFUTED as specified then CONFIRMED via S1b; 8 spec amendments forced, none voiding a section, plus a round-2 fix pass from the whole-branch review (spec ledger, "Round 2"). **PR-1 (#100), PR-2 (#102) merged; PR-3 open as
 [#103](https://github.com/ianp94/basquin/pull/103)** — build-time injection with zero edits to the
 target's tree, both halves of §5.2 passed (JVM on `rest-villains`, native on the fixture), 390 tests
-(`bench-results/verify-20260730T215842Z/suite-counts.txt:1`).
+(`bench-results/RUN-OF-RECORD/suite-counts.txt:1`).
 §8.1 **resolved**: Apicurio's server has no native build on the 3.x line, so row 5 needs a substitute —
 ranked Debezium Server (Quarkus 3.33.1.1) > Eclipse Hono HTTP adapter (3.27.4.1, reactive, heavier
 infra) > Apicurio 2.6.x, the last only behind a compatibility spike since `basquin-quarkus` is pinned to
@@ -99,7 +99,7 @@ extraction; scope under "Open PRs" below). Four threads are ready to pick up, in
    Spec §5.2's two-artifact bar passed both halves — JVM on the real `rest-villains` app
    (`bench-results/dd043-pr3-restvillains-2026-07-26/`) and native on the Phase-0 fixture
    (`bench-results/dd043-pr3-native-2026-07-26/`). 390 tests, 0 failures — that count comes from the
-   run of record, not from either acceptance directory: `bench-results/verify-20260730T215842Z/`
+   run of record, not from either acceptance directory: `bench-results/RUN-OF-RECORD/`
    (`suite-counts.txt:1` reads `390 0`; `RESULTS.md:10`).
 
    **Both acceptances are single-module, and no multi-module Maven reactor was ever built end-to-end
@@ -111,7 +111,7 @@ extraction; scope under "Open PRs" below). Four threads are ready to pick up, in
    targets are multi-module" (`docs/superpowers/specs/2026-07-24-native-reactive-targets-design.md`,
    the paragraph beginning "The injector must construct a fresh `Dependency` per `MavenProject`"). The
    run of record's own "What a pass here does and does not establish" section
-   (`bench-results/verify-20260730T215842Z/RESULTS.md`) omits this gap; that file is fixed evidence and
+   (`bench-results/RUN-OF-RECORD/RESULTS.md`) omits this gap; that file is fixed evidence and
    cannot be amended, so it is recorded here and in the spec instead.
 
    **What a fresh agent most needs to know about this branch.** Two mechanisms fail *silently* if
@@ -166,7 +166,7 @@ extraction; scope under "Open PRs" below). Four threads are ready to pick up, in
    `declaration-usability`, `sibling-scope`, `sibling-version` — seven, matching the seven
    `throw new MavenExecutionException` sites in `BasquinInjector.java`), plus `skip` for the operator
    opt-out, each proven able to fail when its own branch is neutered. All eight PASS in
-   `bench-results/verify-20260730T215842Z/RESULTS.md` as one `guards:<label>` row apiece, alongside
+   `bench-results/RUN-OF-RECORD/RESULTS.md` as one `guards:<label>` row apiece, alongside
    `guards:restored` recording the source restored and the module suite green. Cited by **row key, not
    line**: mid-table insertions in rounds 6 and 7 invalidated that line range twice, and any further
    guard renumbers it again. Mind the arithmetic when restating this — eight *shapes* are closed by
@@ -277,10 +277,18 @@ extraction; scope under "Open PRs" below). Four threads are ready to pick up, in
       not: a citation to agents.md in `docs/DESIGN-DECISIONS.md`'s DD-021 entry, a file that exists on
       the authoring machine but is gitignored, so it resolved for its author and was dead on a fresh
       clone (fixed in the same pass).
-   2. **A stable pointer to the run of record.** Timestamped directory names are why citations rot in
-      bulk. Add `bench-results/RUN-OF-RECORD` (a pointer file or symlink) and cite *that*, so
-      regenerating evidence does not invalidate every reference to it. This is the cheapest structural
-      fix on the list and it removes the cause rather than detecting the symptom.
+   2. **A stable pointer to the run of record. Delivered.** Timestamped directory names were why
+      citations rotted in bulk. Added `bench-results/RUN-OF-RECORD` — a tracked pointer **file**, not a
+      symlink (this checkout has `core.symlinks=false`, on which a tracked symlink materialises as a
+      plain-text file naming its target rather than resolving), holding one non-comment line naming the
+      run directory. `scripts/check-citations.py`'s `resolve()` substitutes a cited
+      `bench-results/RUN-OF-RECORD/...` prefix with the directory the pointer names before matching the
+      tracked tree, so a supersession now edits one file instead of repointing every citation; a
+      dangling, missing, or malformed (0 or 2+ non-comment-line) pointer fails the checker loudly
+      (`exit=1`, a `DEAD PATH` finding naming the reason) rather than passing silently — proved
+      empirically for all three modes. `scripts/verify-dd043-pr3.sh` never writes this file; promoting a
+      run is a deliberate, manual edit in the same commit that adds the new run directory. Full account
+      in `TODO.md`'s DD-045 item 2.
    3. **Mutation-test the harness, not only the guards.** The script mutation-tests the injector's guards
       (8 rows, each proven to fail when its own branch is neutered) but nothing mutation-tests the
       *script's own rows*. Neuter each assertion; require its row to go red. Every entry in row 1 of the
@@ -307,8 +315,8 @@ extraction; scope under "Open PRs" below). Four threads are ready to pick up, in
       it contains the pasted output of its own verification, and partial evidence is never committed.
 
    **Entry condition:** none — this is tooling over the existing tree, and it is independently useful
-   before PR-4 begins. 0 and 1 are now built; 2-3 are the remaining structural pieces. 4-6 are cheap
-   once those exist.
+   before PR-4 begins. 0, 1 and 2 are now built; 3 is the remaining structural piece. 4-6 are cheap once
+   that exists.
 
    **Also worth noting for whoever picks this up:** `scripts/verify-dd043-pr3.sh` is *inside*
    `ci.yml`'s path filters — `'scripts/**'` is in both lists
@@ -350,13 +358,13 @@ time, nothing CPU-heavy during a run.
 
 **[#103](https://github.com/ianp94/basquin/pull/103) — DD-043 PR-3, `basquin-maven-injector`.**
 Build-time injection with zero edits to the target's source; both halves of spec §5.2 passed; 390 tests,
-0 failures (`bench-results/verify-20260730T215842Z/suite-counts.txt:1`). Labelled `ready-for-approver`.
+0 failures (`bench-results/RUN-OF-RECORD/suite-counts.txt:1`). Labelled `ready-for-approver`.
 Six follow-ups are recorded in `TODO.md` under "DD-043 PR-3 follow-ups", of which **two** are now
 resolved and **four** remain open — count the `- [ ]`/`- [x]` boxes in that section rather than
 trusting this sentence, which has gone stale twice (round 7 added the sixth; round 9 closed the
 second). The two resolved: the verify script's `jvm` and `native` stages had never been executed —
 both now ran end-to-end in the run of record, stamped `20260730T215842Z`
-(`bench-results/verify-20260730T215842Z/RESULTS.md`, its `Stages run:` and
+(`bench-results/RUN-OF-RECORD/RESULTS.md`, its `Stages run:` and
 `27 passed, 0 failed, 0 skipped` header lines — cited by label, not line number, because the header
 gains lines) — and `jvm:boundary` no longer accepts an error page, since it now runs `curl -sf` and
 requires `ResultStore.format`'s CSV shape.
diff --git a/docs/superpowers/plans/2026-07-26-dd043-pr3-maven-injector.md b/docs/superpowers/plans/2026-07-26-dd043-pr3-maven-injector.md
index b34b212..20988bd 100644
--- a/docs/superpowers/plans/2026-07-26-dd043-pr3-maven-injector.md
+++ b/docs/superpowers/plans/2026-07-26-dd043-pr3-maven-injector.md
@@ -1480,7 +1480,7 @@ two-sided property is real, but is established by `scripts/verify-dd043-pr3.sh`,
 directory: dirty-tree refusal before the build (the preflight
 `git -C "$app" status --porcelain -- .`) and `jvm:zero-edits` after
 (`git status --porcelain=v2 --branch -- .`), surfaced in
-`bench-results/verify-20260730T215842Z/RESULTS.md`'s `jvm:zero-edits` row. All three are cited by
+`bench-results/RUN-OF-RECORD/RESULTS.md`'s `jvm:zero-edits` row. All three are cited by
 command text and row key rather than by line, because the line numbers here were wrong once and went
 stale again while being fixed. The current
 `bench-results/dd043-pr3-restvillains-2026-07-26/README.md` verdict and check-5 row carry the
diff --git a/docs/superpowers/specs/2026-07-24-native-reactive-targets-design.md b/docs/superpowers/specs/2026-07-24-native-reactive-targets-design.md
index dc4fe12..dfeacfa 100644
--- a/docs/superpowers/specs/2026-07-24-native-reactive-targets-design.md
+++ b/docs/superpowers/specs/2026-07-24-native-reactive-targets-design.md
@@ -1457,8 +1457,8 @@ history says this repo needs.
 | **PR-0** | Phase-0 spikes S1–S4 → `bench-results/dd043-spikes-2026-07-24/`, plus the spec amendments they forced. **No product code.** — **DONE, gate PASSED** | Gates everything below |
 | **PR-1** | `basquin-core` extraction (§4.1) — pure refactor, zero behaviour change, existing tests green, no Quarkus code — **DONE** (324 → 326 tests, 0 failures; branch `dd043-pr1-basquin-core`, not yet merged) | PR-0 — cleared |
 | **PR-2** | `basquin-quarkus` MVP — filter boundary, result store + a `/__basquin/{result,violations}` control surface sharing `ResultStore`'s wire format (§4.4a), control defect routes (§7.3); validated on `rest-villains` **JVM mode** | PR-1 · **entry requirement: §4.1** — `Invariants`, `evaluateAndMaybeFail`, `Result` (+ accessors) and `Violation`'s fields are all package-private and must be widened together before the boundary filter can call this artifact. The publishing half is resolved: `maven-publish` ships both a local and a Pages-served Maven repo |
-| **PR-3** | `basquin-maven-injector` + Gradle init stub; acceptance is §5.2's banner, zero pom edits — **DONE.** Shipped: the core extension injecting the dependency **and** the repository at both levels (§5), **8 operator guards** (grew from 7 in round 7, when review found a managed `<scope>` reaches `basquin-core` the same way a managed `<exclusions>` does — see `docs/ROADMAP.md` and `docs/THIRD-PARTY-APPS.md` for the current, checkable enumeration rather than trusting this snapshot), each mutation-checked by `scripts/verify-dd043-pr3.sh` — **all eight, no exception**: eight `_mutate` rows, one per item in the list below, each proven able to fail when its own branch is neutered, all PASS in `bench-results/verify-20260730T215842Z/RESULTS.md` as one `guards:<label>` row apiece, plus `guards:restored`. Cited by row key rather than line, because two mid-table insertions have already shifted that table's numbering twice: skip; conflicting managed version; conflicting managed exclusions; an unusable managed scope; conflicting declared version; an unusable declaration — wrong scope, `pom`/`test-jar` type, a classifier, or exclusions; and, on a *sibling* `com.basquin` artifact declared directly (`basquin-core` above all), an unusable sibling scope and a conflicting sibling version. **All but `skip` fail loudly per §5.1 — seven of the eight**; `skip` is the operator opt-out, not a guard. The scope, type/classifier, managed-exclusions, managed-scope and both sibling shapes were each found by review AFTER the preceding guard landed, so the declared-artifact check is written as a whitelist of what is usable rather than a list of known-bad values — while the sibling check enumerates the two fields measured to be hazards, `type`/`classifier`/`exclusions` having been measured harmless there. The eight live in **four** guard methods — `failOnUnusableDeclaration`, `failOnConflictingDeclaredVersion`, `failOnConflictingManagedVersion`, `failOnUnusableSiblingDeclaration` — read their javadoc in `BasquinInjector.java` for the shape-by-shape detail; this count and the line numbers below it move every time a guard is added, so a hand-typed number here is a snapshot, not a fact. And the Pages repo widened to all four artifacts (§3). **31 module tests** (23 in `BasquinInjectorGuardsTest.java` + 8 in `BasquinInjectorTest.java` — the two JUnit XMLs under
-`bench-results/verify-20260730T215842Z/guard-restore-junit/` report `tests="23"` and `tests="8"`; the `guards:restored` row of that run's `RESULTS.md` records the clean module suite as `31 tests, 0 failures`, derived from those XMLs); **390 repo-wide, 0 failures** (`bench-results/verify-20260730T215842Z/suite-counts.txt:1` reads `390 0`; `RESULTS.md:10`). §5.2's JVM half **PASSED on `rest-villains`** with zero edits to its tree (`bench-results/dd043-pr3-restvillains-2026-07-26/`, banner lists `basquin`); §5.2's native half **PASSED on the Phase-0 fixture, not rest-villains** (`bench-results/dd043-pr3-native-2026-07-26/`, banner `[basquin, cdi, rest, smallrye-context-propagation, vertx]`) — rest-villains' native buildability stays **unmeasured** and belongs to PR-4's native 2×2 cells (§7.2). **No multi-module Maven reactor was ever built end-to-end with the injector on `maven.ext.class.path`**: both acceptances are single-module — `rest-villains` is a standalone pom, so is the Phase-0 fixture — while `inject()` loops `session.getProjects()` and mutates a `MavenProject` instance per reactor member, which is exactly the shape this spec flags a hazard in ("The injector must construct a fresh `Dependency` per `MavenProject`", this file, the paragraph beginning with that sentence) and exactly the shape "the real targets are multi-module" a few lines below it refers to. The two unit tests that pin per-project freshness build a synthetic three-project list in memory, not a live Maven reactor; a real reactor build exercises paths — shared parent-pom inheritance into the effective model, Maven's own per-module lifecycle sequencing — that a synthetic list and a standalone pom cannot. The Gradle init script is a **stub**: it implements only the `skip` opt-out (`basquin-init.gradle:20,24`) — **none of the other seven operator guards have a Gradle counterpart**, so a conflicting version, an unusable declaration or an unusable sibling declaration on a Gradle target is resolved silently by Gradle's own defaults rather than failing loudly — and it was never exercised against a Gradle-built Quarkus target (§5). Both acceptances resolved over localhost HTTP; the real Pages HTTPS repository stays unexercised until the first `v*` tag (§3). The offline-JaCoCo plugin execution was **not** injected — §8.2 stands unmeasured, PR-4's entry gate | PR-2 — cleared |
+| **PR-3** | `basquin-maven-injector` + Gradle init stub; acceptance is §5.2's banner, zero pom edits — **DONE.** Shipped: the core extension injecting the dependency **and** the repository at both levels (§5), **8 operator guards** (grew from 7 in round 7, when review found a managed `<scope>` reaches `basquin-core` the same way a managed `<exclusions>` does — see `docs/ROADMAP.md` and `docs/THIRD-PARTY-APPS.md` for the current, checkable enumeration rather than trusting this snapshot), each mutation-checked by `scripts/verify-dd043-pr3.sh` — **all eight, no exception**: eight `_mutate` rows, one per item in the list below, each proven able to fail when its own branch is neutered, all PASS in `bench-results/RUN-OF-RECORD/RESULTS.md` as one `guards:<label>` row apiece, plus `guards:restored`. Cited by row key rather than line, because two mid-table insertions have already shifted that table's numbering twice: skip; conflicting managed version; conflicting managed exclusions; an unusable managed scope; conflicting declared version; an unusable declaration — wrong scope, `pom`/`test-jar` type, a classifier, or exclusions; and, on a *sibling* `com.basquin` artifact declared directly (`basquin-core` above all), an unusable sibling scope and a conflicting sibling version. **All but `skip` fail loudly per §5.1 — seven of the eight**; `skip` is the operator opt-out, not a guard. The scope, type/classifier, managed-exclusions, managed-scope and both sibling shapes were each found by review AFTER the preceding guard landed, so the declared-artifact check is written as a whitelist of what is usable rather than a list of known-bad values — while the sibling check enumerates the two fields measured to be hazards, `type`/`classifier`/`exclusions` having been measured harmless there. The eight live in **four** guard methods — `failOnUnusableDeclaration`, `failOnConflictingDeclaredVersion`, `failOnConflictingManagedVersion`, `failOnUnusableSiblingDeclaration` — read their javadoc in `BasquinInjector.java` for the shape-by-shape detail; this count and the line numbers below it move every time a guard is added, so a hand-typed number here is a snapshot, not a fact. And the Pages repo widened to all four artifacts (§3). **31 module tests** (23 in `BasquinInjectorGuardsTest.java` + 8 in `BasquinInjectorTest.java` — the two JUnit XMLs under
+`bench-results/RUN-OF-RECORD/guard-restore-junit/` report `tests="23"` and `tests="8"`; the `guards:restored` row of that run's `RESULTS.md` records the clean module suite as `31 tests, 0 failures`, derived from those XMLs); **390 repo-wide, 0 failures** (`bench-results/RUN-OF-RECORD/suite-counts.txt:1` reads `390 0`; `RESULTS.md:10`). §5.2's JVM half **PASSED on `rest-villains`** with zero edits to its tree (`bench-results/dd043-pr3-restvillains-2026-07-26/`, banner lists `basquin`); §5.2's native half **PASSED on the Phase-0 fixture, not rest-villains** (`bench-results/dd043-pr3-native-2026-07-26/`, banner `[basquin, cdi, rest, smallrye-context-propagation, vertx]`) — rest-villains' native buildability stays **unmeasured** and belongs to PR-4's native 2×2 cells (§7.2). **No multi-module Maven reactor was ever built end-to-end with the injector on `maven.ext.class.path`**: both acceptances are single-module — `rest-villains` is a standalone pom, so is the Phase-0 fixture — while `inject()` loops `session.getProjects()` and mutates a `MavenProject` instance per reactor member, which is exactly the shape this spec flags a hazard in ("The injector must construct a fresh `Dependency` per `MavenProject`", this file, the paragraph beginning with that sentence) and exactly the shape "the real targets are multi-module" a few lines below it refers to. The two unit tests that pin per-project freshness build a synthetic three-project list in memory, not a live Maven reactor; a real reactor build exercises paths — shared parent-pom inheritance into the effective model, Maven's own per-module lifecycle sequencing — that a synthetic list and a standalone pom cannot. The Gradle init script is a **stub**: it implements only the `skip` opt-out (`basquin-init.gradle:20,24`) — **none of the other seven operator guards have a Gradle counterpart**, so a conflicting version, an unusable declaration or an unusable sibling declaration on a Gradle target is resolved silently by Gradle's own defaults rather than failing loudly — and it was never exercised against a Gradle-built Quarkus target (§5). Both acceptances resolved over localhost HTTP; the real Pages HTTPS repository stays unexercised until the first `v*` tag (§3). The offline-JaCoCo plugin execution was **not** injected — §8.2 stands unmeasured, PR-4's entry gate | PR-2 — cleared |
 | **PR-4** | Coverage — offline-JaCoCo execution injection, `/__basquin/coverage`, `JacocoCoverageProvider` HTTP transport; the native 2×2 cells | PR-3 · **entry gate: §8.2** (plugin-execution injection is unmeasured); the native cells additionally carry §7.2's S3 re-check |
 | **PR-5** | Reactive invariant set (§6.3 watchdog), `render_page.py` per-target sets, benchmark rows, docs. **Entry condition:** §7.4's rule that the heap column, taint rate and `UNMEASURED` count render only when §7.3's firing controls passed is today **documented discipline, not enforced code** — nothing reads control-pass state, and it holds only because no renderer exists yet. PR-5 must make it a checkable gate in `render_page.py`, not a convention. **Also owns four gaps PR-2 measured:** the `UNMEASURED` disposition and §6.1's in-flight taint — both need a `ResultStore.Entry` field, and until they land §7.3's sub-quantum control **fails** and the heap invariant is **not publishable**; the watchdog, without which `block-loop`'s control cannot be claimed; **negative** heap deltas (measured `-16,456 KB` on `rest-villains`), which the in-flight counter structurally cannot detect because a GC is not a request; and **GC-contaminated positive** deltas, which the sign rule cannot see either — the general detector is a `GarbageCollectorMXBean.getCollectionCount()` delta across the window, whose SubstrateVM support is itself a PR-5 precondition | PR-4 · **entry gate: §6.2** — native JFR streaming and `com.sun.management`-on-SubstrateVM are both unverified; establish or demote before budgeting the cross-check |
 
diff --git a/scripts/check-citations-allowlist.txt b/scripts/check-citations-allowlist.txt
index 579bb95..705bab4 100644
--- a/scripts/check-citations-allowlist.txt
+++ b/scripts/check-citations-allowlist.txt
@@ -7,7 +7,6 @@
 #                                          other agents, reported 2026-07-30, pending their fix.
 
 # --- deliberately absent (proposed, not yet built) ---
-bench-results/RUN-OF-RECORD proposed in DD-045 item 2 (docs/ROADMAP.md); deliberately not built yet — forward-looking reference, not a broken one
 snap/snapcraft.yaml planned file — TODO.md's snap-packaging checklist item says "Write" it; deliberately not in the tree yet
 
 # --- upstream repos: files that live in the target application's tree, not ours ---
diff --git a/scripts/check-citations.py b/scripts/check-citations.py
index 9ce11c8..0cef0e0 100644
--- a/scripts/check-citations.py
+++ b/scripts/check-citations.py
@@ -66,6 +66,17 @@
 final OK line claims "verified clean" only for the verified count and names everything it did
 not verify: a zero in this tool's output means checked-and-clean, never unexamined.
 
+RUN-OF-RECORD POINTER (DD-045 item 2). `bench-results/RUN-OF-RECORD` is a tracked pointer FILE
+naming the current run-of-record directory (one non-comment line; not a symlink — this
+checkout has core.symlinks=false, so a tracked symlink would materialise as a plain-text file
+containing its target path). `resolve()` substitutes a cited `bench-results/RUN-OF-RECORD/...`
+prefix with that directory before matching against the tracked tree, so a supersession edits
+one file instead of repointing every citation. A missing pointer, a pointer with zero or more
+than one non-comment line, or a pointer naming a directory that is not tracked (dangling) is
+never a silent pass or a guess: `resolve_run_of_record()` reports it, and it is emitted as a
+FAILED DEAD PATH exactly like any other broken citation, so it fails the run (exit 1) whenever
+a RUN-OF-RECORD/ citation exists to need it.
+
 MECHANICS. Prose is grouped into logical units — markdown paragraphs (blank-line delimited;
 each table row its own unit) and contiguous comment blocks — because a wrapped sentence puts
 the quoted value and its citation on adjacent physical lines. A quoted value passes if it
@@ -165,6 +176,15 @@
 # never evidence FOR those figures. Round 11: two carried values under indictment briefly
 # "verified" against the allowlist entry written to report them. Excluded from value backing.
 SELF_FILES = {"scripts/check-citations.py", "scripts/check-citations-allowlist.txt"}
+# DD-045 item 2: bench-results/RUN-OF-RECORD is a tracked pointer FILE (not a symlink — this
+# checkout has core.symlinks=false, so a tracked symlink materialises as a plain-text file
+# containing its target path rather than resolving, on a clone with that setting) naming the
+# current run-of-record directory. A cited path beginning `bench-results/RUN-OF-RECORD/` is
+# resolved (see resolve()) against the directory it names, so a supersession edits one file
+# instead of repointing every citation. See resolve_run_of_record() for the three failure
+# modes this substitution must fail loudly on rather than silently pass or guess.
+RUN_OF_RECORD_FILE = "bench-results/RUN-OF-RECORD"
+RUN_OF_RECORD_PREFIX = RUN_OF_RECORD_FILE + "/"
 
 CITED_EXTS = (
     "md|txt|log|java|sh|py|go|gradle|xml|yml|yaml|json|csv|tsv|properties|html|svg|bat|kts|exec"
@@ -341,6 +361,27 @@ def emit(citing: str, msg: str) -> str:
     def cite_emit(citing: str, msg: str) -> None:
         stats[K_REP if emit(citing, msg) == "reported" else K_FAIL] += 1
 
+    def resolve_run_of_record():
+        """Resolve the bench-results/RUN-OF-RECORD pointer to the run directory it names.
+        -> (target_dir, None) on success, (None, reason) on any of the three failure modes
+        this pointer must not silently swallow: the pointer file is missing; it has zero or
+        more than one non-comment, non-blank line; or the directory it names is not in the
+        tracked tree (a dangling pointer). Called lazily, only when a citation actually needs
+        it, via resolve()'s RUN_OF_RECORD_PREFIX branch below — so a broken pointer with no
+        RUN-OF-RECORD/ citations in the tree does not, by itself, fail the run."""
+        lines = read_lines(RUN_OF_RECORD_FILE)
+        if lines is None:
+            return None, f"{RUN_OF_RECORD_FILE} is missing"
+        content = [ln.strip() for ln in lines
+                   if ln.strip() and not ln.strip().startswith("#")]
+        if len(content) != 1:
+            return None, (f"{RUN_OF_RECORD_FILE} has {len(content)} non-comment, non-blank "
+                          f"line(s) (expected exactly 1): {content!r}")
+        target_dir = f"bench-results/{content[0]}"
+        if target_dir not in tracked_dirs:
+            return None, f"{RUN_OF_RECORD_FILE} names {target_dir!r}, not a tracked directory"
+        return target_dir, None
+
     def resolve(citing: str, path: str):
         """-> (candidates, kind).
              exact — root-relative or citing-dir-relative (incl. ../ normalised): verified;
@@ -351,9 +392,21 @@ def resolve(citing: str, path: str):
                      multi-segment token (`env/build.sh`, `cmd/basquin/status.go`): the
                      written path names nothing, so this is reported UNCHECKED, not verified;
              ambiguous — several matches, target not mechanically decidable;
+             pointer-error — path is bench-results/RUN-OF-RECORD/<rest> but the pointer is
+                     missing, malformed, or dangling: reported as a FAILED DEAD PATH, never a
+                     guess (see resolve_run_of_record());
              none  — nothing matches anywhere."""
         if path in tracked_set or path in tracked_dirs:
             return [path], "exact"
+        if path.startswith(RUN_OF_RECORD_PREFIX):
+            target_dir, err = resolve_run_of_record()
+            if err is not None:
+                return [err], "pointer-error"
+            sub = target_dir + path[len(RUN_OF_RECORD_FILE):]
+            if sub in tracked_set or sub in tracked_dirs:
+                return [sub], "exact"
+            return ([f"{RUN_OF_RECORD_FILE} resolves to {target_dir!r}, but {sub!r} is not "
+                     f"tracked"], "pointer-error")
         cite_dir = citing.rsplit("/", 1)[0] if "/" in citing else ""
         if cite_dir:
             rel = posixpath.normpath(f"{cite_dir}/{path}")
@@ -569,6 +622,11 @@ def check_unit(citing: str, unit: list[tuple[int, str]]) -> None:
                 stats[K_GUESS] += 1
                 guess_rows.append((raw, cands[0], citing, lineno))
                 continue
+            if kind == "pointer-error":
+                # A dangling/missing/malformed RUN-OF-RECORD pointer is a FAILED DEAD PATH,
+                # never a guess or a silent pass — see resolve_run_of_record().
+                cite_emit(citing, f"{citing}:{lineno}: DEAD PATH `{raw}` — {cands[0]}")
+                continue
             if kind == "none":
                 window = [unit_text.get(lineno - 1, ""), unit_text[lineno],
                           unit_text.get(lineno + 1, "")]

From 3cfda2790bb865f7ffe4aeac14eb4548de110d0b Mon Sep 17 00:00:00 2001
From: "basquin-bot[bot]" <307641014+basquin-bot[bot]@users.noreply.github.com>
Date: Fri, 31 Jul 2026 11:56:06 -0400
Subject: [PATCH 2/5] docs(dd045): state the pointer resolver's scope boundary
 in the docstring
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

resolve() substitutes the RUN-OF-RECORD pointer; the separate pinned-row
resolver for */citations.txt does not. Moot as written — neither tracked
citations.txt names the run of record — and it fails closed rather than open.
Recording it because an undocumented gap in a gate reads as coverage, which is
the defect class this whole thread exists to remove; it surfaced in the
implementer's report and would otherwise have lived only there.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LHBLwqfM1acog2bHRS8WCb
---
 scripts/check-citations.py | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/scripts/check-citations.py b/scripts/check-citations.py
index 0cef0e0..945d279 100644
--- a/scripts/check-citations.py
+++ b/scripts/check-citations.py
@@ -76,6 +76,14 @@
 never a silent pass or a guess: `resolve_run_of_record()` reports it, and it is emitted as a
 FAILED DEAD PATH exactly like any other broken citation, so it fails the run (exit 1) whenever
 a RUN-OF-RECORD/ citation exists to need it.
+  Scope boundary, stated so it is not mistaken for coverage: only `resolve()` substitutes the
+pointer. The separate pinned-row resolver that reads `*/citations.txt` does NOT, so a
+`bench-results/RUN-OF-RECORD/...` path written into a citations.txt would be treated as a
+literal path and reported DEAD rather than resolved. That is moot as written — no tracked
+citations.txt names the run of record (both under bench-results/dd043-pr3-r4-guard-measurement-
+2026-07-29/ and bench-results/dd043-pr3-r7-managed-scope-2026-07-30/ contain zero such
+references) — and it fails closed rather than open, which is the safe direction. Teach the
+pinned resolver the same substitution before writing the first such citation.
 
 MECHANICS. Prose is grouped into logical units — markdown paragraphs (blank-line delimited;
 each table row its own unit) and contiguous comment blocks — because a wrapped sentence puts

From 793c18e03ee273d29e37f80a9cbaa354d6dd819c Mon Sep 17 00:00:00 2001
From: "basquin-bot[bot]" <307641014+basquin-bot[bot]@users.noreply.github.com>
Date: Fri, 31 Jul 2026 12:32:52 -0400
Subject: [PATCH 3/5] =?UTF-8?q?fix(dd045):=20resolve()=20checked=20the=20p?=
 =?UTF-8?q?ointer=20FILE's=20own=20tracked-ness=20before=20ever=20resolvin?=
 =?UTF-8?q?g=20it=20=E2=80=94=20a=20bare=20RUN-OF-RECORD/=20citation=20byp?=
 =?UTF-8?q?assed=20validation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review finding: `resolve()` matched `path in tracked_set` before the
RUN_OF_RECORD_PREFIX branch. bench-results/RUN-OF-RECORD is itself a tracked
FILE, and the caller strips a citation's trailing slash before calling
resolve() — so a bare `bench-results/RUN-OF-RECORD/` citation (nothing after
the slash) arrived as exactly that tracked path and returned "exact" on the
first line, never reaching resolve_run_of_record(). Three citations
(TODO.md:1200, TODO.md:1293, docs/ROADMAP.md:102) are written that way, and a
pointer deliberately pointed at a nonexistent directory verified clean for
all three while sub-path citations of the same pointer correctly failed.

Fix: check path == RUN_OF_RECORD_FILE (or the prefix) FIRST in resolve(),
ahead of the generic short-circuit. A bare citation now resolves to the
pointer's target DIRECTORY, not the pointer FILE, so file_cands is empty for
it exactly as for any other directory citation — a nearby quoted value has
nothing to check against, instead of silently matching the pointer's own
one-line text.

Proved empirically: all four break modes (dangling, missing, 0-line, 2-line
pointer) now produce a DEAD PATH FAILED finding and exit=1 for all three bare
citation sites; restoring the pointer returns exit=0. Corrected the
docstring's and TODO.md/ROADMAP.md's claims that a broken pointer "fails the
run whenever a RUN-OF-RECORD/ citation exists" / "proved empirically for all
three modes" — both were true only for the sub-path shape.

Sibling shape found, NOT fixed here (reported for a deliberate decision): the
citing-dir-relative branch of resolve() (`rel = normpath(cite_dir/path)`,
checked directly against tracked_set/tracked_dirs) has the same ordering bug.
A citation like `../RUN-OF-RECORD/` from a file one level under bench-results/
normalises to the bare pointer path and can match tracked_set there too,
bypassing resolve_run_of_record(). Not currently exploited (no tracked
citation is written that way), but structurally present.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LHBLwqfM1acog2bHRS8WCb
---
 TODO.md                    | 18 +++++++++-
 docs/ROADMAP.md            | 10 ++++--
 scripts/check-citations.py | 70 +++++++++++++++++++++++++++++++-------
 3 files changed, 83 insertions(+), 15 deletions(-)

diff --git a/TODO.md b/TODO.md
index 398a2fb..410c9e6 100644
--- a/TODO.md
+++ b/TODO.md
@@ -1205,7 +1205,23 @@ the feature held in every one, and almost every finding was in the machinery tha
       restoring the pointer returned `exit=0` again every time. `scripts/verify-dd043-pr3.sh` was not
       touched and does not write this file — promoting a run to run-of-record stays a deliberate, manual
       edit made in the same commit that adds the new run directory, stated in the pointer file's own
-      comment header.
+      comment header. **Review found a gap in that proof and it is now fixed.** The four-mode
+      empirical proof above only ever broke the pointer against a **sub-path** citation
+      (`bench-results/RUN-OF-RECORD/RESULTS.md`); it never exercised the **bare** form — this
+      bullet's own `bench-results/RUN-OF-RECORD/` citation two sentences up, one more citation
+      further down this file ("check `bench-results/RUN-OF-RECORD/` first"), and one in
+      `docs/ROADMAP.md` all cite the pointer that way, with nothing after the slash. In `resolve()`,
+      the generic `path in tracked_set` check ran BEFORE the RUN-OF-RECORD substitution, and
+      `bench-results/RUN-OF-RECORD` is itself a tracked file (the pointer) — so a bare citation
+      matched the pointer's own tracked-ness and verified clean without `resolve_run_of_record()`
+      ever running. All three bare citations verified clean against a pointer deliberately pointed
+      at a nonexistent directory. **Fixed**: the RUN-OF-RECORD branch in `resolve()` now runs first,
+      and a bare citation resolves to the pointer's target DIRECTORY rather than the pointer FILE
+      itself, so `file_cands` stays empty for it exactly as for any other directory citation instead
+      of accidentally matching a nearby quoted value against the pointer's own one-line text.
+      Re-verified against all four break modes (dangling, missing, 0-line, 2-line pointer) with all
+      three bare citations now each producing a `DEAD PATH` finding and `exit=1`; restoring the
+      pointer returns `exit=0` again.
 - [ ] **3 — mutation-test the harness, not only the guards.** The script proves each of the injector's
       8 guards fails when neutered; nothing proves the script's own rows do. Also: the guards stage
       mutates tracked source in place, so a commit during a run is unsafe — one was observed
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index fa47395..9ecdf08 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -287,8 +287,14 @@ extraction; scope under "Open PRs" below). Four threads are ready to pick up, in
       dangling, missing, or malformed (0 or 2+ non-comment-line) pointer fails the checker loudly
       (`exit=1`, a `DEAD PATH` finding naming the reason) rather than passing silently — proved
       empirically for all three modes. `scripts/verify-dd043-pr3.sh` never writes this file; promoting a
-      run is a deliberate, manual edit in the same commit that adds the new run directory. Full account
-      in `TODO.md`'s DD-045 item 2.
+      run is a deliberate, manual edit in the same commit that adds the new run directory. **Correction
+      (review found this):** that proof only ever exercised a **sub-path** citation
+      (`bench-results/RUN-OF-RECORD/RESULTS.md`); a **bare** `bench-results/RUN-OF-RECORD/` citation —
+      the exact form this file cites at `docs/ROADMAP.md:102`, and TODO.md cites twice — reached
+      "exact" via the generic tracked-path check before the substitution ever ran, because the pointer
+      is itself a tracked file, so all three bare citations verified clean against a deliberately
+      broken pointer. Fixed by checking the substitution first. Full account in `TODO.md`'s DD-045
+      item 2.
    3. **Mutation-test the harness, not only the guards.** The script mutation-tests the injector's guards
       (8 rows, each proven to fail when its own branch is neutered) but nothing mutation-tests the
       *script's own rows*. Neuter each assertion; require its row to go red. Every entry in row 1 of the
diff --git a/scripts/check-citations.py b/scripts/check-citations.py
index 945d279..0fabf15 100644
--- a/scripts/check-citations.py
+++ b/scripts/check-citations.py
@@ -70,12 +70,29 @@
 naming the current run-of-record directory (one non-comment line; not a symlink — this
 checkout has core.symlinks=false, so a tracked symlink would materialise as a plain-text file
 containing its target path). `resolve()` substitutes a cited `bench-results/RUN-OF-RECORD/...`
-prefix with that directory before matching against the tracked tree, so a supersession edits
-one file instead of repointing every citation. A missing pointer, a pointer with zero or more
-than one non-comment line, or a pointer naming a directory that is not tracked (dangling) is
-never a silent pass or a guess: `resolve_run_of_record()` reports it, and it is emitted as a
-FAILED DEAD PATH exactly like any other broken citation, so it fails the run (exit 1) whenever
-a RUN-OF-RECORD/ citation exists to need it.
+prefix — INCLUDING the bare form `bench-results/RUN-OF-RECORD/`, nothing after the slash,
+which names the directory itself rather than a sub-path within it — with that directory before
+matching against the tracked tree, so a supersession edits one file instead of repointing
+every citation. The substitution is checked FIRST in `resolve()`, ahead of the generic
+exact-path short-circuit (`path in tracked_set or path in tracked_dirs`), and it has to run
+first: the caller strips a citation's trailing slash before calling resolve(), so a bare
+citation's path is then IDENTICAL to `bench-results/RUN-OF-RECORD` — the pointer FILE's own
+tracked path. An earlier version of this tool checked the generic branch first; it matched the
+pointer's own tracked-ness and returned "exact" without `resolve_run_of_record()` ever running,
+so a dangling, missing, or malformed pointer verified clean for that one citation shape. That
+was a real, review-found gap: three citations (`TODO.md:1200`, `TODO.md:1293`,
+`docs/ROADMAP.md:102`) name only the bare form, and none of the three was flagged when the
+pointer was deliberately pointed at a nonexistent directory, while sub-path citations of the
+same broken pointer were. A bare citation now resolves to the target directory itself — a
+tracked DIRECTORY, never the pointer FILE — so the `file_cands` computed from it (candidates
+that are tracked FILES) is empty exactly as it is for any other directory citation: a quoted
+value beside a bare RUN-OF-RECORD/ citation has nothing to check against, rather than being
+silently checked against the pointer file's own one-line text. A missing pointer, a pointer
+with zero or more than one non-comment line, or a pointer naming a directory that is not
+tracked (dangling) is never a silent pass or a guess for any RUN-OF-RECORD/ citation
+`resolve()` reaches, bare or with a sub-path: `resolve_run_of_record()` reports it, and it is
+emitted as a FAILED DEAD PATH exactly like any other broken citation, so it fails the run
+(exit 1) whenever such a citation exists to need it.
   Scope boundary, stated so it is not mistaken for coverage: only `resolve()` substitutes the
 pointer. The separate pinned-row resolver that reads `*/citations.txt` does NOT, so a
 `bench-results/RUN-OF-RECORD/...` path written into a citations.txt would be treated as a
@@ -400,21 +417,50 @@ def resolve(citing: str, path: str):
                      multi-segment token (`env/build.sh`, `cmd/basquin/status.go`): the
                      written path names nothing, so this is reported UNCHECKED, not verified;
              ambiguous — several matches, target not mechanically decidable;
-             pointer-error — path is bench-results/RUN-OF-RECORD/<rest> but the pointer is
-                     missing, malformed, or dangling: reported as a FAILED DEAD PATH, never a
-                     guess (see resolve_run_of_record());
+             pointer-error — path is bench-results/RUN-OF-RECORD (bare) or
+                     bench-results/RUN-OF-RECORD/<rest> but the pointer is missing,
+                     malformed, or dangling: reported as a FAILED DEAD PATH, never a guess
+                     (see resolve_run_of_record());
              none  — nothing matches anywhere."""
-        if path in tracked_set or path in tracked_dirs:
-            return [path], "exact"
-        if path.startswith(RUN_OF_RECORD_PREFIX):
+        # Checked FIRST, ahead of the generic "path in tracked_set" short-circuit below —
+        # not after it. RUN_OF_RECORD_FILE is itself a tracked FILE (the pointer), and the
+        # caller has already stripped a bare citation's trailing slash before calling
+        # resolve(), so a bare `bench-results/RUN-OF-RECORD/` citation arrives here with
+        # path == RUN_OF_RECORD_FILE — identical to that tracked file's own path. Checking
+        # tracked_set first (an earlier version of this tool did) would match the pointer's
+        # own tracked-ness and return "exact" without resolve_run_of_record() ever running,
+        # so a dangling/missing/malformed pointer would verify clean for that citation shape
+        # specifically. That was not hypothetical: three citations (TODO.md:1200,
+        # TODO.md:1293, docs/ROADMAP.md:102) name only the bare `bench-results/RUN-OF-RECORD/`
+        # form, and none of the three was flagged when the pointer was deliberately pointed
+        # at a nonexistent directory, while sub-path citations of the same broken pointer
+        # were — because only the prefix branch (not the tracked_set short-circuit) called
+        # resolve_run_of_record(). Ordering this branch first closes that gap for every
+        # RUN-OF-RECORD/ citation shape, bare or with a sub-path.
+        if path == RUN_OF_RECORD_FILE or path.startswith(RUN_OF_RECORD_PREFIX):
             target_dir, err = resolve_run_of_record()
             if err is not None:
                 return [err], "pointer-error"
+            if path == RUN_OF_RECORD_FILE:
+                # A bare `RUN-OF-RECORD/` citation names the DIRECTORY the pointer points
+                # to, not the pointer file's own one-line text — the same reading a
+                # sub-path citation gets, just with an empty remainder. Resolve to
+                # target_dir itself: a tracked DIRECTORY, never the pointer FILE, so the
+                # caller's `file_cands = [c for c in cands if c in tracked_set]` comes back
+                # empty, exactly as it does for every other directory citation (directories
+                # are never in tracked_set). Deliberate, not incidental: the alternative —
+                # resolving to RUN_OF_RECORD_FILE itself so `cands` is non-empty — would put
+                # the pointer file back into file_cands, and a quoted value in the same
+                # prose unit would then be silently checked against the pointer's own
+                # one-line content instead of correctly having nothing to check against.
+                return [target_dir], "exact"
             sub = target_dir + path[len(RUN_OF_RECORD_FILE):]
             if sub in tracked_set or sub in tracked_dirs:
                 return [sub], "exact"
             return ([f"{RUN_OF_RECORD_FILE} resolves to {target_dir!r}, but {sub!r} is not "
                      f"tracked"], "pointer-error")
+        if path in tracked_set or path in tracked_dirs:
+            return [path], "exact"
         cite_dir = citing.rsplit("/", 1)[0] if "/" in citing else ""
         if cite_dir:
             rel = posixpath.normpath(f"{cite_dir}/{path}")

From 4a65bb363a937325c63e3259c6c4a7195292843c Mon Sep 17 00:00:00 2001
From: "basquin-bot[bot]" <307641014+basquin-bot[bot]@users.noreply.github.com>
Date: Fri, 31 Jul 2026 12:42:29 -0400
Subject: [PATCH 4/5] =?UTF-8?q?fix(dd045):=20resolve()=20checked=20the=20c?=
 =?UTF-8?q?iting-dir-relative=20path=20against=20tracked=5Fset=20before=20?=
 =?UTF-8?q?ever=20resolving=20the=20RUN-OF-RECORD=20pointer=20=E2=80=94=20?=
 =?UTF-8?q?same=20bug=20793c18e=20fixed,=20one=20branch=20further=20down?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

793c18e fixed resolve()'s literal-path short-circuit but explicitly deferred
the sibling: the citing-dir-relative branch (`rel = normpath(cite_dir/path)`)
still checked `rel in tracked_set or rel in tracked_dirs` directly, with no
pointer substitution. `bench-results/dd043-pr3-restvillains-2026-07-26/README.md`
sits one level under bench-results/ and already cites the run of record, so a
future edit there in relative form (`../RUN-OF-RECORD/`) would normalise to
`bench-results/RUN-OF-RECORD` — the pointer FILE's own tracked path — and
return "exact" without resolve_run_of_record() ever running. Not exploited
today (no citation is written that way), but structurally present and one
edit away.

Fix: fold both candidate shapes resolve() is willing to call an exact match —
the literal path and its citing-dir-relative normalisation — through one
shared helper, tracked_or_pointer(), which checks the pointer substitution
FIRST and the generic tracked-tree membership second, for whichever candidate
it is given. One place expresses the ordering instead of two copies that can
drift independently, so a third citation shape added later inherits the
correct order automatically. Verified no third "check tracked_set before
resolving the pointer" site exists in resolve(): the basename/tail-guess
branches never reach RUN-OF-RECORD by accident, because a bare `RUN-OF-RECORD`
token (no bench-results/ prefix, no extension) never matches TOKEN_RE or
DIR_TOKEN_RE and so is never extracted as a citation at all.

Proved empirically: added a temporary `../RUN-OF-RECORD/` citation to the
restvillains README (one level under bench-results/), broke the pointer four
ways (dangling, missing, 0-line, 2-line) — each produced a DEAD PATH FAILED
finding on that citation and exit=1; the intact pointer round-tripped exit=0
with byte-identical output to the pre-change baseline. Removed the scratch
citation before committing; git diff on that README is empty.

Updated the module docstring's RUN-OF-RECORD POINTER section and resolve()'s
own docstring to describe the guarantee across all three citation shapes
(literal, bare, citing-dir-relative) instead of the literal-only claim that
had grown wider than the check.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LHBLwqfM1acog2bHRS8WCb
---
 scripts/check-citations.py | 171 +++++++++++++++++++++++--------------
 1 file changed, 109 insertions(+), 62 deletions(-)

diff --git a/scripts/check-citations.py b/scripts/check-citations.py
index 0fabf15..61042e8 100644
--- a/scripts/check-citations.py
+++ b/scripts/check-citations.py
@@ -73,26 +73,45 @@
 prefix — INCLUDING the bare form `bench-results/RUN-OF-RECORD/`, nothing after the slash,
 which names the directory itself rather than a sub-path within it — with that directory before
 matching against the tracked tree, so a supersession edits one file instead of repointing
-every citation. The substitution is checked FIRST in `resolve()`, ahead of the generic
-exact-path short-circuit (`path in tracked_set or path in tracked_dirs`), and it has to run
-first: the caller strips a citation's trailing slash before calling resolve(), so a bare
-citation's path is then IDENTICAL to `bench-results/RUN-OF-RECORD` — the pointer FILE's own
-tracked path. An earlier version of this tool checked the generic branch first; it matched the
-pointer's own tracked-ness and returned "exact" without `resolve_run_of_record()` ever running,
-so a dangling, missing, or malformed pointer verified clean for that one citation shape. That
-was a real, review-found gap: three citations (`TODO.md:1200`, `TODO.md:1293`,
-`docs/ROADMAP.md:102`) name only the bare form, and none of the three was flagged when the
-pointer was deliberately pointed at a nonexistent directory, while sub-path citations of the
-same broken pointer were. A bare citation now resolves to the target directory itself — a
+every citation. `resolve()` checks the substitution FIRST, through a single helper —
+`tracked_or_pointer()` — shared by EVERY citation shape it is willing to call an exact match:
+the literal, root-relative path, AND its citing-dir-relative normalisation (`../RUN-OF-RECORD/`
+cited from a file one level under bench-results/, or bare `RUN-OF-RECORD/` cited from a file
+directly under it). Both go through that one helper, in that order, ahead of the generic
+exact-path short-circuit (`cand in tracked_set or cand in tracked_dirs`) inside it — for
+EITHER shape, not just the literal one — because the caller strips a citation's trailing slash
+before calling resolve(), so a bare citation's literal path, or its citing-dir-relative
+normalisation, is then IDENTICAL to `bench-results/RUN-OF-RECORD` — the pointer FILE's own
+tracked path. An earlier version of this tool checked the generic branch first for the literal
+path; it matched the pointer's own tracked-ness and returned "exact" without
+`resolve_run_of_record()` ever running, so a dangling, missing, or malformed pointer verified
+clean for that one citation shape (fixed in 793c18e). One round later, the citing-dir-relative
+branch a few lines further down still ran its own, separately-ordered copy of "check
+tracked_set first" — the identical bug, one branch later, because the two shapes were two
+independent copies of the ordering instead of one shared, correctly-ordered check; folding both
+through `tracked_or_pointer()` is the fix, so a third citation shape reaching the tracked tree
+by some future route gets the correct ordering for free rather than needing its own patch. That
+was a real, review-found gap for the literal shape: three citations (`TODO.md:1200`,
+`TODO.md:1293`, `docs/ROADMAP.md:102`) name only the bare form, and none of the three was
+flagged when the pointer was deliberately pointed at a nonexistent directory, while sub-path
+citations of the same broken pointer were. For the citing-dir-relative shape no citation was
+ever written that way — but `bench-results/dd043-pr3-restvillains-2026-07-26/README.md` already
+cites the run of record from one level under bench-results/, so it was one edit away. A bare
+citation (literal or citing-dir-relative) now resolves to the target directory itself — a
 tracked DIRECTORY, never the pointer FILE — so the `file_cands` computed from it (candidates
 that are tracked FILES) is empty exactly as it is for any other directory citation: a quoted
 value beside a bare RUN-OF-RECORD/ citation has nothing to check against, rather than being
 silently checked against the pointer file's own one-line text. A missing pointer, a pointer
 with zero or more than one non-comment line, or a pointer naming a directory that is not
 tracked (dangling) is never a silent pass or a guess for any RUN-OF-RECORD/ citation
-`resolve()` reaches, bare or with a sub-path: `resolve_run_of_record()` reports it, and it is
-emitted as a FAILED DEAD PATH exactly like any other broken citation, so it fails the run
-(exit 1) whenever such a citation exists to need it.
+`resolve()` treats as an exact match — literal or citing-dir-relative, bare or with a sub-path:
+`resolve_run_of_record()` reports it, and it is emitted as a FAILED DEAD PATH exactly like any
+other broken citation, so it fails the run (exit 1) whenever such a citation exists to need it.
+This does NOT cover every conceivable way a citation could name the pointer — a basename/tail
+GUESS match could in principle land on `bench-results/RUN-OF-RECORD` too, but never does in
+practice: those branches only fire for a path with no "/", and `RUN-OF-RECORD` alone, without
+`bench-results/` and without a recognised extension, never matches TOKEN_RE or DIR_TOKEN_RE, so
+it is never extracted as a citation token at all (see `check_unit()`/`parse_token()`).
   Scope boundary, stated so it is not mistaken for coverage: only `resolve()` substitutes the
 pointer. The separate pinned-row resolver that reads `*/citations.txt` does NOT, so a
 `bench-results/RUN-OF-RECORD/...` path written into a citations.txt would be treated as a
@@ -409,7 +428,9 @@ def resolve_run_of_record():
 
     def resolve(citing: str, path: str):
         """-> (candidates, kind).
-             exact — root-relative or citing-dir-relative (incl. ../ normalised): verified;
+             exact — the literal path, OR its citing-dir-relative normalisation (incl. ../
+                     normalised), is a tracked file/dir, OR the RUN-OF-RECORD pointer
+                     resolves either of them (see tracked_or_pointer()): verified;
              near  — unique basename/suffix match inside the citing file's own directory
                      subtree (an evidence README citing `driver-summary.txt` means the copy
                      in its run directory): verified;
@@ -417,55 +438,81 @@ def resolve(citing: str, path: str):
                      multi-segment token (`env/build.sh`, `cmd/basquin/status.go`): the
                      written path names nothing, so this is reported UNCHECKED, not verified;
              ambiguous — several matches, target not mechanically decidable;
-             pointer-error — path is bench-results/RUN-OF-RECORD (bare) or
-                     bench-results/RUN-OF-RECORD/<rest> but the pointer is missing,
-                     malformed, or dangling: reported as a FAILED DEAD PATH, never a guess
-                     (see resolve_run_of_record());
+             pointer-error — the literal path, or its citing-dir-relative normalisation, is
+                     bench-results/RUN-OF-RECORD (bare) or bench-results/RUN-OF-RECORD/<rest>
+                     but the pointer is missing, malformed, or dangling: reported as a FAILED
+                     DEAD PATH, never a guess (see resolve_run_of_record());
              none  — nothing matches anywhere."""
-        # Checked FIRST, ahead of the generic "path in tracked_set" short-circuit below —
-        # not after it. RUN_OF_RECORD_FILE is itself a tracked FILE (the pointer), and the
-        # caller has already stripped a bare citation's trailing slash before calling
-        # resolve(), so a bare `bench-results/RUN-OF-RECORD/` citation arrives here with
-        # path == RUN_OF_RECORD_FILE — identical to that tracked file's own path. Checking
-        # tracked_set first (an earlier version of this tool did) would match the pointer's
-        # own tracked-ness and return "exact" without resolve_run_of_record() ever running,
-        # so a dangling/missing/malformed pointer would verify clean for that citation shape
-        # specifically. That was not hypothetical: three citations (TODO.md:1200,
-        # TODO.md:1293, docs/ROADMAP.md:102) name only the bare `bench-results/RUN-OF-RECORD/`
-        # form, and none of the three was flagged when the pointer was deliberately pointed
-        # at a nonexistent directory, while sub-path citations of the same broken pointer
-        # were — because only the prefix branch (not the tracked_set short-circuit) called
-        # resolve_run_of_record(). Ordering this branch first closes that gap for every
-        # RUN-OF-RECORD/ citation shape, bare or with a sub-path.
-        if path == RUN_OF_RECORD_FILE or path.startswith(RUN_OF_RECORD_PREFIX):
-            target_dir, err = resolve_run_of_record()
-            if err is not None:
-                return [err], "pointer-error"
-            if path == RUN_OF_RECORD_FILE:
-                # A bare `RUN-OF-RECORD/` citation names the DIRECTORY the pointer points
-                # to, not the pointer file's own one-line text — the same reading a
-                # sub-path citation gets, just with an empty remainder. Resolve to
-                # target_dir itself: a tracked DIRECTORY, never the pointer FILE, so the
-                # caller's `file_cands = [c for c in cands if c in tracked_set]` comes back
-                # empty, exactly as it does for every other directory citation (directories
-                # are never in tracked_set). Deliberate, not incidental: the alternative —
-                # resolving to RUN_OF_RECORD_FILE itself so `cands` is non-empty — would put
-                # the pointer file back into file_cands, and a quoted value in the same
-                # prose unit would then be silently checked against the pointer's own
-                # one-line content instead of correctly having nothing to check against.
-                return [target_dir], "exact"
-            sub = target_dir + path[len(RUN_OF_RECORD_FILE):]
-            if sub in tracked_set or sub in tracked_dirs:
-                return [sub], "exact"
-            return ([f"{RUN_OF_RECORD_FILE} resolves to {target_dir!r}, but {sub!r} is not "
-                     f"tracked"], "pointer-error")
-        if path in tracked_set or path in tracked_dirs:
-            return [path], "exact"
         cite_dir = citing.rsplit("/", 1)[0] if "/" in citing else ""
-        if cite_dir:
-            rel = posixpath.normpath(f"{cite_dir}/{path}")
-            if rel in tracked_set or rel in tracked_dirs:
-                return [rel], "exact"
+        rel = posixpath.normpath(f"{cite_dir}/{path}") if cite_dir else None
+
+        def tracked_or_pointer(cand: str):
+            """Validate ONE candidate path — called once below for the literal `path` and
+            once for its citing-dir-relative normalisation `rel` — against the RUN-OF-RECORD
+            pointer substitution, checked FIRST, ahead of the generic "cand in tracked_set"
+            short-circuit. Not after it, for EITHER candidate: this is the one place that
+            ordering is expressed, so a citation shape added later gets it automatically
+            instead of needing its own copy that can fall out of sync. That already happened
+            once: 793c18e fixed this ordering for the literal path alone; the citing-dir-
+            relative branch a few lines below it, in the pre-refactor code, still ran
+            `rel in tracked_set` with no pointer check at all — the identical bug, one branch
+            further down, because the two shapes were two copies of "check tracked_set" that
+            drifted independently instead of one shared, correctly-ordered check.
+              RUN_OF_RECORD_FILE is itself a tracked FILE (the pointer), and the caller has
+            already stripped a bare citation's trailing slash before calling resolve(), so a
+            bare `bench-results/RUN-OF-RECORD/` citation — or, one level further, a citing-
+            dir-relative citation that NORMALISES to the same path (`../RUN-OF-RECORD/` cited
+            from a file one level under bench-results/, or bare `RUN-OF-RECORD/` cited from a
+            file directly under it) — arrives here with `cand == RUN_OF_RECORD_FILE`,
+            identical to that tracked file's own path. Checking tracked_set first would match
+            the pointer's own tracked-ness and return "exact" without
+            resolve_run_of_record() ever running, so a dangling/missing/malformed pointer
+            would verify clean for that citation shape specifically. That was not
+            hypothetical for the literal shape: three citations (TODO.md:1200, TODO.md:1293,
+            docs/ROADMAP.md:102) name only the bare `bench-results/RUN-OF-RECORD/` form, and
+            none of the three was flagged when the pointer was deliberately pointed at a
+            nonexistent directory, while sub-path citations of the same broken pointer were.
+            (The basename/tail-guess branches further down resolve() can never hit this same
+            trap by accident: they only fire for a `path` with no "/", and `RUN-OF-RECORD`
+            alone — without `bench-results/` and without a recognised extension — never
+            matches TOKEN_RE or DIR_TOKEN_RE, so it is never extracted as a citation token in
+            the first place; see check_unit().)
+            -> (candidates, kind) if `cand` resolves — pointer substitution or a plain
+               tracked-tree hit — else None, meaning `cand` isn't in the tracked tree at all
+               so the caller falls through to basename/tail matching."""
+            if cand == RUN_OF_RECORD_FILE or cand.startswith(RUN_OF_RECORD_PREFIX):
+                target_dir, err = resolve_run_of_record()
+                if err is not None:
+                    return [err], "pointer-error"
+                if cand == RUN_OF_RECORD_FILE:
+                    # A bare `RUN-OF-RECORD/` citation names the DIRECTORY the pointer points
+                    # to, not the pointer file's own one-line text — the same reading a
+                    # sub-path citation gets, just with an empty remainder. Resolve to
+                    # target_dir itself: a tracked DIRECTORY, never the pointer FILE, so the
+                    # caller's `file_cands = [c for c in cands if c in tracked_set]` comes back
+                    # empty, exactly as it does for every other directory citation (directories
+                    # are never in tracked_set). Deliberate, not incidental: the alternative —
+                    # resolving to RUN_OF_RECORD_FILE itself so `cands` is non-empty — would put
+                    # the pointer file back into file_cands, and a quoted value in the same
+                    # prose unit would then be silently checked against the pointer's own
+                    # one-line content instead of correctly having nothing to check against.
+                    return [target_dir], "exact"
+                sub = target_dir + cand[len(RUN_OF_RECORD_FILE):]
+                if sub in tracked_set or sub in tracked_dirs:
+                    return [sub], "exact"
+                return ([f"{RUN_OF_RECORD_FILE} resolves to {target_dir!r}, but {sub!r} is not "
+                         f"tracked"], "pointer-error")
+            if cand in tracked_set or cand in tracked_dirs:
+                return [cand], "exact"
+            return None
+
+        hit = tracked_or_pointer(path)
+        if hit is not None:
+            return hit
+        if rel is not None:
+            hit = tracked_or_pointer(rel)
+            if hit is not None:
+                return hit
         if "/" not in path:
             low = path.lower()
             cands = list(by_basename.get(low, []))

From 5fdcf9ee513c8fc2e44ecf667450a0696ce666aa Mon Sep 17 00:00:00 2001
From: "basquin-bot[bot]" <307641014+basquin-bot[bot]@users.noreply.github.com>
Date: Fri, 31 Jul 2026 17:58:39 -0400
Subject: [PATCH 5/5] docs(dd045): drop line numbers from the docstring's own
 citations
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The review found TODO.md:1293 stale in the docstring added by 793c18e: that
same commit inserted ~17 lines earlier in the file, so the citation rotted
inside the commit that fixed citation rot. A second line number in the same
sentence had moved too.

Replaced with the grep that finds the sites, not a list that goes stale. This
file is outside check-citations.py's own corpus — it scans *.md, */citations.txt
and the '#'-comments of *.sh and workflow files, so a Python docstring's
citations have no guard and must not carry line numbers. A figure that cannot
drift beats one that is currently right.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LHBLwqfM1acog2bHRS8WCb
---
 scripts/check-citations.py | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/scripts/check-citations.py b/scripts/check-citations.py
index 61042e8..af013c4 100644
--- a/scripts/check-citations.py
+++ b/scripts/check-citations.py
@@ -91,10 +91,15 @@
 independent copies of the ordering instead of one shared, correctly-ordered check; folding both
 through `tracked_or_pointer()` is the fix, so a third citation shape reaching the tracked tree
 by some future route gets the correct ordering for free rather than needing its own patch. That
-was a real, review-found gap for the literal shape: three citations (`TODO.md:1200`,
-`TODO.md:1293`, `docs/ROADMAP.md:102`) name only the bare form, and none of the three was
-flagged when the pointer was deliberately pointed at a nonexistent directory, while sub-path
-citations of the same broken pointer were. For the citing-dir-relative shape no citation was
+was a real, review-found gap for the literal shape: several citations in TODO.md and
+docs/ROADMAP.md name only the bare form, and not one of them was flagged when the pointer was
+deliberately pointed at a nonexistent directory, while sub-path citations of the same broken
+pointer were. (Those sites were originally listed here by `file:line`; the list is deliberately
+gone. Two of the three line numbers were stale within one commit, because the same commit
+inserted lines earlier in TODO.md — a citation rotting inside the commit that fixed citation
+rot. Nothing scans this file: the corpus is *.md, */citations.txt and the '#'-comments of *.sh
+and workflow files, so a Python docstring's own citations are unguarded and must not carry line
+numbers. Find them with: git grep -nE '`bench-results/RUN-OF-RECORD/`' -- '*.md') For the citing-dir-relative shape no citation was
 ever written that way — but `bench-results/dd043-pr3-restvillains-2026-07-26/README.md` already
 cites the run of record from one level under bench-results/, so it was one edit away. A bare
 citation (literal or citing-dir-relative) now resolves to the target directory itself — a