fallback-review-panel contract item 7 carries four requirements under one number, and stable numbering blocks splitting it

[topij]

Surfaced by the fallback panel on #166 (LOW, flagged independently as a length/structure concern). Not repaired there: rebuilding the contract inside a fix round is the mechanism creep fallback-review-panel.md itself warns against.

What is wrong

Contract item 7 is now 75 of 389 lines (~19%) of docs/agentic-dev-kit/fallback-review-panel.md, and it is the largest single item by a wide margin. It has been repaired in four separate changes.

The doc's own "Keep the record small" section says "A claim that has needed repairing twice is doing more work than it can carry; cut it back to what you can stand behind." Item 7 is exempt from the letter of that rule — it is executed prose, first class, so the remedy is not deletion — but the size is a real problem for a different reason: item 7 now carries four separable requirements under one number.

1. Do not mutate the shared tree (the original requirement).
2. Establish your placement — linked worktree vs. the shared checkout — before any write, and report HEAD + git status --short at the end.
3. Namespace the scratch path by lens and revision.
4. Resolve the right revision — diff against the named sha, verify the base, handle the wrong-repo case.

(2) and (4) were added on #166; (3) came from #136. A lens is handed this as one blob, and a reader looking for "how do I get to the right code" has to read past three other requirements to find it.

Why it was not just split

The obvious repair — promote each into its own numbered item — is blocked by stable numbering. Items 2, 5, 7 and 9 are referenced by number from:

• fallback-review-panel.md itself ("contract item 7", "contract item 9", "the anchoring contract item 2 forbids")
• scripts/tests/test_mutation_gate.py:3 ("contract item 5")
• the titles of Invert fallback-review-panel contract item 7: assume the isolated worktree points at the wrong ref #75 and fallback-review-panel contract item 7 isolates the worktree but not the scratchpad, and one lens deleted another's mutation copy #136, and the body of Where five review rounds actually spent their cycles, and the two sinks worth closing #163

So renumbering silently invalidates external references, including in tests and issue titles. #166 worked around it by appending item 10 rather than inserting, which preserves references but puts a report-shape requirement after the severity requirement instead of beside the other report-shape items (8, 9).

What a repair needs to decide

• Whether the contract gets named anchors instead of numbers (item 7 → #isolation), with a one-time sweep of every referencing site, so future inserts are cheap. This is the version that actually closes the problem.
• Or whether items get sub-numbers (7a/7b/7c), which keeps item 7 resolving but reads awkwardly and does not help item 8/9/10 ordering.
• Either way: a check that a contract item N reference in any tracked file resolves to an item that exists. There is none today, so a renumber would fail silently — the same class as archive_plan_sessions must warn on relative cross-references — both inside moved blocks and into them #73 (relative cross-references) and A three-space list continuation is correct CommonMark and silently renumbers under Python-Markdown #116 (list renumbering under Python-Markdown).

Not urgent

Nothing is broken. This is a readability and maintainability ceiling on the file that every panel run reads, filed so the next person to touch item 7 does not have to re-derive why it could not simply be split.

[topij]

Correction to this issue's own enumeration — requirement (2) no longer exists.

Filed mid-PR on #166, and the following commit deleted one of the four requirements it enumerates. Recording it here so a reader is not sent looking for a mechanism the doc no longer has.

The issue lists item 7 as carrying:

1. Do not mutate the shared tree.
2. Establish your placement — linked worktree vs. the shared checkout — before any write, and report HEAD + git status --short at the end.
3. Namespace the scratch path by lens and revision.
4. Resolve the right revision.

(2) is gone. The placement check it describes (git rev-parse --git-dir --git-common-dir) was found to fail open from any subdirectory — git returns the first absolute and the second relative-to-cwd, so in a subdirectory of the shared checkout they differ, and the doc read that as "a linked worktree, yours to move". It also asked the wrong question: scripts/dev_session.sh:289 builds operator lanes with git worktree add -b, so a linked worktree can be live in-progress work. No git command answers is this tree mine.

It was replaced by an unconditional rule needing no discrimination — never write inside a tree you did not create; scratch at an absolute path outside it — so the current four are:

1. Do not mutate the tree you were given, and keep your scratch outside it.
2. Attest to what you left behind, with each probe labelled for what it does and does not prove.
3. Namespace the scratch path by lens and revision.
4. Resolve the right revision — the named sha, a current base, and a reachable object.

The count is unchanged at four, and the size grew: item 7 went 22 lines on main → 71 → 77 → 79 across the PR. So the structural problem this issue describes is not merely intact, it is larger than when the issue was filed, and none of the three review rounds reduced it — each round's findings were real gaps that needed instructions.

One correction to the issue body's supporting claim as well: it says numbering is referenced from this doc, scripts/tests/test_mutation_gate.py:3, and the titles of #75 and #136. A lens noted the enumeration is incomplete — the panel doc cites item 7 by number in two places (its own "Running it" step 2, and the stopping section's neighbours), and docs/kit-handoff.md:98 also refers to "contract item 7". None of that weakens the argument for named anchors; it strengthens it, since the sweep is wider than the issue estimated.

[topij]

Occurrence — the renumber landed on PR #218, and three archived citations now resolve to the wrong item. Logged rather than fixed, per the logged-disposition rule. This issue stays open for its other half.

What landed

PR #218 split fallback-review-panel.md and took this issue's named-anchors route, which the body calls "the version that actually closes the problem". Item 7's four requirements became four items, so the contract went from 10 to 13, and every citation on a shipped surface is now by name:

#	Item
1–6	Fresh context · No framing · Not the author · Execute, don't only read · Mutation-test new branches · Report, don't fix
7–10	No writes in the tree you were given · Attestation · Scratch namespace · Right revision ← old item 7, split
11–13	Verified clean · Severity and regression · Report what you reviewed, first

Swept: nine internal cross-references, scripts/tests/test_mutation_gate.py:3, and init.sh:1000.

The finding this comment exists for

A review lens on #218 caught what the PR body had not: the renumber left three citations in archived narrative logs pointing at the wrong item. Old 8/9/10 became 11/12/13, so any surviving numeric citation to those is now wrong — not merely stale in style.

Site	Says	Old item	New item at that number
docs/kit-friction-log-archive.md:417	"item 10 requires the lens to open with what it reviewed"	State what you reviewed	Right revision — a different topic
docs/kit-friction-log-archive.md:1649	"contract item 7 says to verify"	isolation and ref-verification bundled	No writes in the tree you were given — verification moved to item 10
docs/kit-handoff-history.md:765	"New contract item 9 makes lenses report both labels"	Severity and regression	Scratch namespace

Not fixed, and deliberately. These are archived record prose — nothing executes them — and the disposition rule for a sub-HIGH imprecision in record prose is logged, not fixed, with the artifact living outside the repo tree. Editing archived history to chase a renumber is also what "a record already carrying corrections should be shortened, not corrected again" argues against.

What #218 did instead: the shipped file now states the bound honestly rather than claiming a complete sweep. Its earlier wording — "Every reference in this kit is by name" — was false and was itself a finding (MED, adversarial lens); it now reads that the sweep covered shipped surfaces, and that narrative-log citations may no longer resolve.

Two corrections to this issue's own account of the sweep

Both found by running it rather than reading it:

1. docs/kit-handoff.md:98 no longer carries the reference. The correction comment above names it; that session block has since graduated to kit-handoff-history.md.
2. init.sh:1000 and docs/kit-friction-log.md:99,101 are citing sites neither the body nor the correction lists. init.sh is the surface adopters install from and is not in kit-manifest.json — the same shape that let an effort overclaim survive a correction sweep in an earlier session. It was swept.

The two kit-friction-log.md citations still resolve, because old item 7 and new item 7 are both the isolation rule. That is an accident of ordering, not a property to rely on — and it is why the three archive sites above, which sit past the split point, do not.

What keeps this issue open

The other half: a check that a contract reference resolves to an item that exists. #218 did not build it — a new mechanism gets filed rather than built inside the change that prompted it (safety-critical-changes.md rule 3). The three sites in the table are exactly what such a check would have caught, and they are now on the record as its acceptance criteria.

[topij]

Correction to my comment above — the "three archived citations" table is an undercount, and I am withdrawing the count rather than restating it.

That comment gave a table of three archived citations that no longer resolve, and called it "the acceptance criteria" for the check this issue still asks for. Two review lenses on PR #218 independently found more, applying the same criterion the table itself used:

• one found kit-friction-log-archive.md:1422 and :1453 (both cite old item 9 — severity/regression — where new item 9 is Scratch namespace)
• the other found six more, all old-item-7 citations whose actual subject was verifying the revision, which moved to new item 10: kit-friction-log-archive.md:1250, :1629, and kit-handoff-history.md:123, :271, :1007, :1137

A wrap-tolerant sweep then found 38 numeric contract-item citations across docs/, reports/ and state/. My original sweep used contract item [0-9]+, which cannot match a citation broken across a line — kit-friction-log-archive.md:1453 reads contract item\n 9. That is how the count was arrived at, and it is a concrete requirement for the check this issue asks for: it must survive line wrapping.

What replaces the count

This claim has now needed repairing twice, so per "a claim that has needed repairing twice is doing more work than it can carry", it gets cut back rather than corrected a third time. The mapping is complete and checkable; the enumeration was not.

Old item	Content	Where it lives now
1–6	unchanged	1–6 — citations still resolve
7	isolation + attestation + namespace + revision, bundled	split across 7 No writes, 8 Attestation, 9 Scratch namespace, 10 Right revision
8	State what was verified clean	11 Verified clean
9	Severity and regression	12 Severity and regression
10	State what you reviewed, first	13 Report what you reviewed, first

So, without enumerating sites:

• Any archived citation to old items 8, 9 or 10 now names the wrong item.
• An item-7 citation resolves only if its subject is isolation-in-general. If its subject is verifying or inverting the revision, that content is now item 10 and the citation is wrong.
• Citations to items 1–6 are unaffected.

Still not fixed, and still deliberately. Archived record prose, sub-HIGH imprecision → logged, not fixed, artifact outside the tree. Editing archived history to chase a renumber is what "a record already carrying corrections should be shortened, not corrected again" argues against — and this correction is itself the second repair of the same claim, which is the evidence for that rule rather than an exception to it.

What this changes for the check this issue still wants

The acceptance criteria are the mapping above, not a site list. Three concrete requirements the undercount surfaced:

1. It must match across line wraps — the naive same-line grep missed a real citation.
2. It must cover reports/ and state/, not just docs/ — both carry citations.
3. Number-resolves-to-an-item is necessary but not sufficient. Every one of the eight sites above resolves to an item that exists; they resolve to the wrong one. A check that only verifies existence would pass all of them. That is the harder half, and it is why the shipped file now instructs citing by name — a name cannot silently retarget.

Filed as a correction beside the original rather than an edit to it (#149).