check-agent-record stores a measurement of model-matrix.md, so re-anchoring a citation forces an edit to the checker and its test
Nobody has claimed this yet.
- Dominant language
- C++
- Stars
- 423
- Forks
- 53
- Avg merge
- 20h 26m
- Merged PRs (30d)
- 310
Description
Row: -
Owed by the model matrix. .agents/specs/upstream-pin-advance-e126687.md lists it
under ## Owed.
Found by the fresh review of #2975 (wave MATRIX), which repaired #2819's stale
matrix citations. Not fixed there: that change is a records-only edit across a
keyed matrix, and removing the coupling is a change to a gate's semantics, which
AGENTS.md §"Changing the rules or a checker" says needs its own spec and a
red-before test.
The defect
check_model_invariants in scripts/check-agent-record.py stores a measurement
of .agents/model-matrix.md inside scripts/check-agent-record.py:
expected = {
"rows": 324,
"memberships": 373,
"architectures": 356,
"targets": 309,
"modules": 245,
}
targets and modules are derived from the matrix's Upstream cell, so they move
whenever a citation is re-anchored — not only when a row is added, removed,
merged or re-aliased.
AGENTS.md §"Records" states the rule this breaks in two sentences:
Never store a measurement of one file inside another file. A number that
changes after each edit couples every pull request to lines that it does not
own.
and names the remedy:
A gate often creates the lock. If a checker requires every change to edit one
shared file, the checker is defective. Move the obligation to a per-row
surface. Do not delete the obligation.
#2975 is its own proof
#2975 added no row, removed none, merged none, re-aliased none. rows,
memberships and architectures are all unchanged. It re-anchored twenty
Upstream cells onto symbols that still exist at the e126687a9a pin, and that
alone forced edits to two files it does not otherwise own:
scripts/check-agent-record.py—targets310 → 309,modules261 → 245tests/scripts/test_agent_record.py— the fixture that pins those constants
So a matrix repair, the most per-row edit this repository has, writes a shared
checker and a shared test. N concurrent matrix pull requests all write those two
files, which is the lock shape AGENTS.md §"Records" describes and the shape that
made the retired .agents/issue-index.md the repository's dominant conflict
source (#883, #2290).
What is owed
- Derive the invariant at read time instead of storing it, or move the
obligation to a per-row surface (one file per row, read with a glob), as
AGENTS.md §"Records" prescribes. Do NOT delete the invariant: it catches a
silently dropped or duplicated row, which is the failure it was written for. - Keep whatever replaces it insensitive to a citation re-anchor, so the only
edits that move it are the inventory changes it means to gate. - Red-before evidence for the replacement: a deleted row must still red, and a
re-anchored citation must NOT.
What this issue is NOT
It is not a claim that check_model_invariants is wrong about today's tree. The
constants in #2975 are correct, were re-derived from the matrix, and were proven
red against the old matrix. The defect is the coupling, not the value.
FOLLOWING_AGENTS_PROTOCOL
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with AGENTS.md sections “Records” and “Changing the rules or a checker,” then inspect check_model_invariants in scripts/check-agent-record.py and its fixture in tests/scripts/test_agent_record.py. Run the existing checker and test before changing them; done means a deleted row is still red while a re-anchored citation no longer requires shared checker or test edits.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- tooling
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 38/100