docs/vrs: R27 is assigned to two different live requirements, so every reference to it is ambiguous

[schickling-assistant]

docs/vrs/requirements.md on main declares two different live requirements as R27:

• R27 Transactional catalog authoring — introduced by 7e1bd02 feat: publish agent specs transactionally
• R27 Typed agent desired state — introduced by 65f82fb feat(agent-spec): add reversible desired state (#175)

Both are present and neither is retired, so every reference to "R27" is ambiguous.

Which one the existing references mean

All of them mean the second:

docs/vrs/ontology.md:108   Authority: [R27 typed agent desired state](requirements.md)
docs/vrs/ontology.md:117   Authority: [R27 typed agent desired state](requirements.md)
docs/vrs/ontology.md:125   Authority: [R27 typed agent desired state](requirements.md)
docs/vrs/ontology.md:133   Authority: [R27 typed agent desired state](requirements.md)
docs/vrs/spec.md:564       **R27/R28:** Agent lifecycle intent is one closed declaration state
docs/vrs/.experiments/2026-08-04-agent-desired-state-prototype.md:58   adds root R27 and R28

Nothing anywhere references R27 Transactional catalog authoring. So the low-risk repair is to renumber that one and leave Typed agent desired state as R27, which keeps all six references correct without touching them.

Choosing the replacement id

The list currently runs R01–R28 with R12 and R18 absent. Those two look like retired requirements rather than accidents, and refilling a retired id is worse than leaving a gap — a gap is visibly nothing, whereas a refilled id silently changes what an old reference resolves to. So the natural target is the next free id past the end rather than either gap.

Worth noting for sequencing: #77 appends R29 and R30, so if that lands first the next free id is R31.

Why it seems worth fixing rather than living with

A duplicate id is strictly worse than a gap for exactly the reason above: a reader who follows "R27" from ontology.md lands on a list containing two of them and has no way to tell which was meant, and a future requirement that cites R27 inherits the ambiguity permanently. It is also the kind of thing that gets harder to repair the longer both live, because each new reference has to be individually disambiguated later.

Happy to send the renumbering PR if you would like it, and equally happy for you to pick the other direction — you own which requirement keeps the number, and the reference count is only an argument, not a decision.

Posted on behalf of @schickling

field	value
agent_name	unknown
agent_tool	Claude Code
agent_tool_version	2.1.220
agent_runtime	Claude Code 2.1.220
agent_session_lookup	unavailable
tooling_profile	dotfiles@unknown-dirty

[schickling-assistant]

Sharpening why this is worth fixing rather than tolerating, from a second reader who hit it cold while allocating new IDs in a VRS-only PR.

The duplicate is not only a broken cross-reference. It makes "take the next free number" unreliable as an allocation method, which is the method anyone appending a requirement will reach for. A reader scanning for the highest live ID gets an answer that is correct about the maximum and silently wrong about the space being contiguous, and nothing in the file signals that one ID resolves to two requirements.

Concretely, at current main:

• docs/vrs/requirements.md:153 — R27 Transactional catalog authoring
• docs/vrs/requirements.md:265 — R27 Typed agent desired state

Two distinct requirements, one ID, so any existing or future reference to "R27" cannot resolve to one of them.

Worth separating from something that looks similar and is not a defect: R12 and R18 do not appear at all, and those gaps are deliberate. A gap marks a retired requirement and is safe — old references stay unambiguous because the ID is never reused for something else. A duplicate is the opposite: it makes every back-reference ambiguous, including ones written before the duplicate existed. Appending past the maximum preserves that property; refilling a gap would not.

So the fix that keeps the invariant is to renumber one of the two R27s to a fresh ID past the current maximum rather than to reuse either gap.

Posted on behalf of @schickling

field	value
agent_name	unknown
agent_tool	Claude Code
agent_tool_version	2.1.220
agent_runtime	Claude Code 2.1.220
agent_session_lookup	unavailable
tooling_profile	dotfiles@unknown-dirty

[schickling-assistant]

A second live instance of this, found while sweeping the ID space before adding R31/R32 in #209 — and it is in an open branch rather than in history.

main defines R28 Desired-state authoring and observation (st2 agent desired-state changing lifecycle intent in one canonical KDL declaration).

Open draft #73 adds, in its requirements list:

- **R28 Independent fleet convergence:** Hosts may use different catalog
  versions and converge...

Two different requirements, same number, and the second is not yet merged — so this one is still cheap to fix, unlike the R27 pair.

It also sharpens what this issue is about. The R27 collision could be read as a one-off; two independent authors reaching for R28 and R31 in the same week, one of them the maintainer, is the "take the next free number" convention failing under normal use rather than through carelessness. main currently defines R01–R30 with gaps at R12 and R18, and nothing tells an author which numbers are claimed by open branches.

For the record on the other side: I checked all six open PRs touching docs/vrs/requirements.md before #209 claimed R31/R32, and no other open PR claims either. That check took a GraphQL query over every open PR's file list — which is roughly the point. It should not need one.

Posted on behalf of @schickling

field	value
agent_name	unknown
agent_tool	Claude Code
agent_tool_version	2.1.220
agent_runtime	Claude Code 2.1.220
agent_session_lookup	unavailable
tooling_profile	dotfiles@unknown-dirty