LLP 0098, 0099 and 0111 each have two claimants; the renumber-vs-qualified-citation choice is unowned and needs a decision

[philcunliffe]

Why this exists

Three LLP numbers on `master` each name two different documents:

Number	Earlier claimant	Later claimant
0098	`0098-scancolumn-where-pushdown.decision.md` (2026-07-11)	`0098-inactive-not-unknown-dispatch-miss.decision.md` (2026-07-29)
0099	`0099-codex-attach-auth-route.decision.md` (2026-07-11)	`0099-dispatch-miss-repair-by-cause.decision.md` (2026-07-14)
0111	`0111-report-cli.decision.md` (2026-07-21)	`0111-hyp-policy-verb.design.md` (2026-07-27)

This slice is named by both issue #463 and issue #457, but neither of their PRs fixes it:

• PR LLP corpus hygiene: illustrative @refs are marked and no gloss uses an em dash (#463 items 2 and 3) #468 (`Fixes LLP corpus hygiene: 3 duplicate LLP numbers, 9 placeholder refs that keep /ref-check from ever exiting 0, and 459 em-dash @ref glosses #463`) fixed the placeholder refs and the em-dash `@ref` glosses and deliberately left the duplicates, encoding the invariant as a skipped test with the reason in the skip message.
• PR LLP 0103 names its CLI and reporting sections; the usage-policy fail-safe refs cite a live doc #461's own body asks for the duplicates to be re-filed, which is why LLP corpus hygiene: 3 duplicate LLP numbers, 9 placeholder refs that keep /ref-check from ever exiting 0, and 459 em-dash @ref glosses #463 was opened in the first place.

So when those two PRs merge, both issues close and this work silently disappears. This issue exists so it does not.

Why it is `neutral:stuck` rather than just `neutral:fix`

It is a corpus-level convention choice that only a human should make, not a mechanical repair, and neutral should not pick one and impose it. The fork:

1. Renumber the later claimant of each pair to the next free number. Mechanical and restores "one number, one document", but it breaks every existing citation of those three numbers, in code `@ref` annotations and in LLP cross-links, and it mutates documents that are otherwise immutable. Someone has to accept that churn.
2. Adopt a filename-qualified citation form in LLP 0001, so `@ref LLP 0098-scancolumn-where-pushdown#anchor` disambiguates and duplicate bare numbers become legal. No churn to existing docs, but it changes the citation grammar corpus-wide and every tool that parses `@ref` has to follow.

There may be a third option, for example declaring one of each pair `Superseded`, if any pair is actually a redundant document rather than a genuine numbering collision. Worth checking before renumbering: nobody has confirmed all six are documents we want to keep.

Not urgent, and not currently breaking anything

PR #468's resolver resolves anchors against either claimant, so the collision produces no false broken refs today and `/ref-check` is not blocked by it. This is corpus hygiene and a convention decision, not a defect with user-visible impact.

How to unstick

Reply on this issue naming which option you want (or a different one). neutral monitors this thread and will pick the work up with your guidance on a later tick.

Related

• Discovered during the fan-in of a neutral reconcile tick, while clearing a fourth, separate duplicate: PRs One reader for the Codex session_meta header, in core (#465) #466 and Codex lineage reads the durable body client_metadata, not header names Codex never sends (#464) #467 were implemented in parallel and each independently minted an `llp/0143-*` document. That one was resolved by renumbering Codex lineage reads the durable body client_metadata, not header names Codex never sends (#464) #467's to 0144. Nothing serializes LLP number allocation across parallel workers, which is the mechanism behind at least some of these collisions and is worth considering as part of whichever option you choose.
• LLP corpus hygiene: 3 duplicate LLP numbers, 9 placeholder refs that keep /ref-check from ever exiting 0, and 459 em-dash @ref glosses #463, Pre-existing @ref breakage found by a corrected ref-check: 14 refs to a nonexistent LLP 0103#cli anchor, 2 refs into a Superseded LLP, and 3 duplicate LLP numbers #457, PR LLP corpus hygiene: illustrative @refs are marked and no gloss uses an em dash (#463 items 2 and 3) #468, PR LLP 0103 names its CLI and reporting sections; the usage-policy fail-safe refs cite a live doc #461

[philcunliffe]

🤖 neutral: three more collisions just arrived, and one of them lands on master on its own

New evidence for this decision, observed at the start of a reconcile tick. Neutral has taken no action on the PR involved and will not: PR #475 (llp/openclaw-full-capture, authored by a human, carries no neutral:* label) is outside neutral's scope, so this is a report, not a request.

The collisions

PR #475 adds eight decision documents numbered 0142 through 0149. Three of those numbers are already claimed:

Number	Existing claimant	PR #475 adds	Status of the existing claimant
0142	llp/0142-privacy-surface-and-skill-discoverability.decision.md	llp/0142-openclaw-plugin-steered-shadow-providers.decision.md	already on master
0143	llp/0143-one-reader-for-codex-session-meta.decision.md	llp/0143-openclaw-registers-no-attach-probe.decision.md	PR #466, held with neutral:approved
0144	llp/0144-codex-lineage-from-body-client-metadata.decision.md	llp/0144-shadow-provider-per-api-shape.decision.md	PR #467, held with neutral:approved

The 0142 case is the one worth pausing on: it is a duplicate against master as it stands today. It does not depend on anything neutral did, and it does not depend on the merge order of any other PR. Merging PR #475 as-is adds a fourth duplicate number to the corpus on its own.

Verified with:

git ls-tree -r --name-only origin/master llp/ | grep -oE '^llp/014[0-9]' | sort -u   # 0141, 0142
git diff --name-only origin/master...origin/llp/openclaw-full-capture               # 0142..0149

Why this matters for the decision on this issue

This issue asks whether to renumber the later claimant or adopt a filename-qualified citation form. The evidence has now shifted somewhat in favour of thinking about it as a process problem, not only a corpus cleanup:

• The collision count went from 3 pre-existing (0098, 0099, 0111) to 3 pre-existing plus 4 live in one day (an llp/0143 between PRs One reader for the Codex session_meta header, in core (#465) #466 and Codex lineage reads the durable body client_metadata, not header names Codex never sends (#464) #467, already resolved by renumbering Codex lineage reads the durable body client_metadata, not header names Codex never sends (#464) #467's to 0144, and now 0142/0143/0144 against llp: OpenClaw full capture — plugin-steered shadow providers replace the settings edit (LLP 0142–0149) #475).
• Nothing serializes LLP number allocation. Every author, human or agent, picks "one past the highest number I can see", and anyone working from a branch cut earlier sees a stale maximum. Parallel work makes collisions the default outcome rather than the exception.
• Whichever option is chosen here, it may be worth pairing it with something that makes the next collision impossible or loud: a pre-merge check, a reserved-number registry, or dropping sequential numbers for the citation key entirely.

A concrete, cheap option already sitting in the tree

PR #468 (held, neutral:approved) adds test/core/llp-ref-hygiene.test.js, which contains a duplicate-number test that is currently SKIPPED precisely because 0098/0099/0111 already collide. Once those three are resolved, un-skipping that test turns this entire class of problem into a red CI check on any PR that introduces a duplicate, including a human's. It would have caught all three #475 collisions before merge.

That does not decide renumber-versus-qualified-citation, but it is the enforcement half, and it is already written.

Related

• LLP corpus hygiene: 3 duplicate LLP numbers, 9 placeholder refs that keep /ref-check from ever exiting 0, and 459 em-dash @ref glosses #463, Pre-existing @ref breakage found by a corrected ref-check: 14 refs to a nonexistent LLP 0103#cli anchor, 2 refs into a Superseded LLP, and 3 duplicate LLP numbers #457, PR LLP corpus hygiene: illustrative @refs are marked and no gloss uses an em dash (#463 items 2 and 3) #468 (the skipped test), PR One reader for the Codex session_meta header, in core (#465) #466 and PR Codex lineage reads the durable body client_metadata, not header names Codex never sends (#464) #467 (the two held claimants), PR llp: OpenClaw full capture — plugin-steered shadow providers replace the settings edit (LLP 0142–0149) #475 (the human PR, untouched by neutral)

[philcunliffe]

🤖 neutral: you chose "renumber" twice. Does that settle the convention here, or only those two cases?

Asking narrowly rather than assuming, because the answer changes what neutral does next and it would be easy to over-read a short instruction into a corpus-wide ruling.

What has happened since this issue was filed

Two live collisions arrived and both were resolved by renumbering the later claimant:

• PR One reader for the Codex session_meta header, in core (#465) #466's llp/0143 moved to 0150 (mechanical, during a conflict resolve it needed anyway).
• PR Codex lineage reads the durable body client_metadata, not header names Codex never sends (#464) #467's llp/0144 moved to 0151, at your explicit instruction, accepting that it stripped neutral:approved and re-opened the ladder.

Both commit messages say they resolve one collision and set no precedent for this issue, which is why this is still open.

What is still unresolved

master carries four duplicate numbers right now:

git ls-tree -r --name-only origin/master llp/ | grep -oE '^llp/[0-9]{4}' | sort | uniq -d
llp/0098   0098-scancolumn-where-pushdown        vs 0098-inactive-not-unknown-dispatch-miss
llp/0099   0099-codex-attach-auth-route          vs 0099-dispatch-miss-repair-by-cause
llp/0111   0111-report-cli                       vs 0111-hyp-policy-verb
llp/0142   0142-privacy-surface-and-skill-discoverability vs 0142-openclaw-plugin-steered-shadow-providers

The first three predate all of this. The fourth arrived with PR #475.

The narrow question

May neutral renumber the later claimant of those four on master, and then delete the skip on the duplicate-number test?

That test is already merged, in test/core/llp-ref-hygiene.test.js:

test('no LLP number is claimed by two documents', { skip: 'issue #463 item 1: renumber vs qualified-citation is an open corpus decision' }, ...)

Its skip reason points at this very issue. Clear the four duplicates and delete the skip, and the whole class becomes a red CI check on every future PR, including yours. It would have caught all three of #475's collisions before merge.

Why neutral has not just done it

Renumbering on master is different in kind from renumbering an unmerged branch:

• It breaks every existing citation of those four numbers, in code @ref annotations and in LLP cross-links, and all of those have to move in the same commit.
• It mutates documents that are otherwise immutable, which is a convention call, not a mechanical repair.
• One of the four pairs might not be a numbering accident at all. Before renumbering anything, someone should check whether either document in a pair is actually redundant and should be marked Superseded instead. Nobody has confirmed all eight are documents worth keeping.

That last point is the real reason to ask rather than act: renumbering assumes both claimants deserve a number, and that assumption has not been tested.

Answering

• "Yes, renumber all four and un-skip the test" and neutral will do it as one PR, held for your review as usual.
• "Renumber, but check for redundancy first" and neutral will report on the four pairs before touching anything.
• "Only those two PRs, leave master alone" and this issue stays open with the convention still undecided, which is a fine answer too.

Reply here and neutral picks it up on a later tick.

[philcunliffe]

Resolved by PRs #486 and #487: the later claimants of 0098/0099/0111 were renumbered to 0153/0154/0155, #475's 0142 moved to 0152, the repair policy is settled as decision LLP 0156 (renumber the later claimant), the duplicate-number test in test/core/llp-ref-hygiene.test.js is un-skipped, and the llp-check CI gate now fails any PR that introduces a duplicate. Verified master currently has zero duplicate numbers. Closing.