The record-anchor symbol test accepts a COMMENT that names the symbol, so a citation 70 lines off its declaration reads OK — and the two-way ratchet then forces the next commit to bank a repair nobody made

[localai-bot]

The record-anchor ratchet (ENG-RECORD-ANCHOR-RATCHET, #632) classifies a citation
STALE when the cited lines do not contain the symbol named beside it. The test is a
substring search over those lines. A comment that mentions the symbol therefore
satisfies it, so a citation can pass while pointing nowhere near the thing it names.

The live instance

KERNEL-ATTN-MLA-SPARSE cites include/vllm/v1/attention/backend.h:271 for
get_kv_cache_shape. The file is 431 lines. Line 271 is a comment:

// Upstream rocm_attn.py:247-256 (`get_kv_cache_shape`) returns

The real declaration is 70 lines further down, at :341:

  std::vector<int64_t> get_kv_cache_shape(
      int64_t num_blocks, int64_t block_size, int64_t num_kv_heads,

Drift on main moved that ROCm comment onto :271. The citation now reads OK, and
nothing repaired it. .agents/specs/record-anchor-ratchet.md §Our baseline records
this honestly as a measured limit of the conservative rule rather than as a repair,
and that framing is right: separating a declaration from a comment needs a parser per
language, which is the cry-wolf trade the whole design refuses
(scripts/check-agent-record.py, the WHERE THE CONSERVATIVE LINE IS DRAWN block).

So this is not a request to tighten the symbol test by parsing. It is a request to make
the false negative visible, because of what it costs downstream.

The second-order cost, which the spec does not currently draw out

The ratchet fails in both directions. A bucket above its baseline fails, and a bucket
below it fails too, with the instruction to lower the baseline in the same commit as the
repair that earned it. That rule exists so improvements are banked rather than silently
absorbed, and it is correct as long as a fall means a repair.

A fall does not always mean a repair. Unrelated drift that parks a comment naming the
symbol on a cited line lowers the count with no work done, and the next contributor to
touch the tree is then forced to bank an improvement that never happened. The banked
number is permanent, because the baseline only ever moves down.

This is not hypothetical. It happened while row/anchor-ratchet-impl merged main:

• 72bd06a5a (record(ROAD-V1-C6), record(ROAD-V1-C6): punch-list item 9 asks for a lever the project refuted and a flip that landed 10 days before the item was written #535) is a record reconciliation that touches no
  src/, include/ or tests/ file. It rewrote the SERVE-ASYNC-LLM row and replaced
  the citation `examples/server/main.cpp:230-247` with a bare
  `examples/server/main.cpp`.
• That citation was BROKEN (the file is 23 lines). Dropping the line number did not
  repair it; it removed the anchor, so the ratchet stopped counting it.
• broken fell 7 to 6. The ratchet then went red on the fall, and the merge commit had
  to lower the baseline to 6 to go green — banking an improvement nobody made, on a row
  that had nothing to do with SERVE-ASYNC-LLM.

The same mechanism runs through the STALE bucket via the comment case above, and there
it is harder to see, because the citation still looks anchored.

What would close this

Not a per-language parser. Candidates, in increasing cost:

1. --report marks a citation whose only match is inside a comment, so the false
   negative is legible without changing any verdict or count.
2. --write-baseline refuses, or warns loudly, when the fall is not attributable to a
   citation the same commit edited. That is the property actually wanted: a bank should
   name the repair that earned it.
3. A cheap non-parser heuristic, for example preferring a match on a line that is not
   inside a // or # prefix when the file offers both.

None of these is in scope for #632, which lands the ratchet itself.

Not a duplicate

• Spec-body file:line anchors are unchecked (4772 of them) and an anchor into a file the row is editing is stale by default: one spec shipped 8 stale anchors, then 7 more from the merge alone #911 is the different gap that spec bodies are not policed at all. This one is
  about citations the ratchet does read and rules OK for the wrong reason.
• Recorded line anchors are never validated against what they name, and ACTIVE rows are not anchor-checked at all #632 owns the ratchet's landing. This is the residual false negative the landing
  measured and recorded.
• --write-baseline banks a record-anchor baseline from a tree that failed other record checks #1270 is the --write-baseline ordering bug, already fixed.

Owning row: ENG-RECORD-ANCHOR-RATCHET.

[localai-bot]

Measured: the de-lining path is a repeatable two-command bypass, and the gate prints the second command

Confirming this from the operator side while gating #851, with one addition — the
SERVE-ASYNC-LLM case is not only an accident that happened to cost accuracy. The same
mechanism works deliberately on any inconvenient anchor, and the gate itself supplies
the instructions.

Measured in a scratch copy at a2d43da5b (shared checkout untouched, probe copy restored):

1. Baseline at head — record anchors: ok=844, stale=32, broken=6 -> rot 38

2. Pick any offender. BROKEN KV-PREFIX-CACHE -> examples/server/main.cpp:126.
   Delete the line number, leaving a bare examples/server/main.cpp:
   ok=844, stale=32, broken=5 -> rot 37

   The anchor was not repaired. examples/server/main.cpp is 23 lines, so :126 is still
   out of range. It simply stopped matching BARE_CITATION_RE / RAW_LOCAL_ANCHOR_RE,
   both of which require :(\d+), so it left the population entirely.

3. The two-way ratchet then goes red on the fall, and prints:

   ERROR: record-anchor baseline STALE in bucket 'broken': 5 < baseline 6. A repair must lower the baseline in the SAME commit: run python3 scripts/check-agent-record.py --write-baseline and commit it.

4. Running exactly that command banks 6 → 5 permanently, and the anchor is gone for good,
   because the baseline only ever moves down.

So the escape hatch costs one deletion plus the command the error message hands you, and
at no point does anything say the anchor was retired rather than fixed. A contributor
following the gate's own instruction in good faith completes the bypass.

This does not change the diagnosis, and it is not an argument for a parser — it lands
squarely on candidate 2 in "What would close this": a bank should have to name the
repair that earned it. I read that as the load-bearing one of the three, because it fixes
the comment case and the de-lining case with a single property, and it is the only
candidate that closes the deliberate path rather than making the accidental path legible.

Worth noting for whoever picks this up: a citation with no line number is currently not
checked for anything at all, not even that the file still exists. Requiring a line number,
or classifying bare paths, may be a cheaper fourth candidate — though it would raise the
counted population, so it wants measuring before it is proposed as a repair.