docs(vrs): disambiguate the duplicate R27 and ratchet ledger ids

[schickling-assistant]

Problem

The root VRS reused requirement ID R27 for two unrelated contracts: transactional execution and typed agent desired state. The ledger also had no executable uniqueness ratchet, so another duplicate root requirement or delta ID could land unnoticed. Bare references to duplicated decision numbers were similarly ambiguous.

Goal

Give each root requirement and delta a unique numeric ID, make decision citations unambiguous, and enforce the current ledger identity rules in tests.

Decisions

• Kept the original transactional-execution requirement as R27.
• Renumbered typed agent desired state to R41, the next free requirement ID at the time of the audit.
• Renumbered launch-argv transparency from the later duplicate R40 to R42; prompt convergence keeps R40.
• Require decision citations to use NNNN-<slug>. Bare 0005, 0007, 0014, and 0015 citations are ambiguous; decision numbers must not be reused under 0006.
• Added integration-test ratchets for unique root requirement IDs, exact allowed duplicate root decision-number pairs, and unique root delta IDs.

R27 citation classification

Changed to typed-state R41:

• docs/vrs/requirements.md: second R27 heading.
• docs/vrs/ontology.md: four desired-state authority citations.
• docs/vrs/spec.md: lifecycle requirement pair.
• docs/vrs/.decisions/0005-streams-are-agent-nested-and-stream-named.md: suspension semantics.
• docs/vrs/.experiments/2026-08-04-agent-desired-state-prototype.md: validated requirement.

Kept as transactional R27:

• docs/vrs/requirements.md: first R27 heading.
• docs/vrs/.decisions/0015-immutable-agent-id-and-mutable-address.md: transactional-addressing rationale.

Verification

• axe vrs check --profile strict docs/vrs — axe vrs check: ok
• cargo test --test vrs_ledger — 3 passed
• CARGO_BUILD_JOBS=8 nix build .#st2 --no-link -L — exit 0, full Nix check gate passed

Complexity

One small file-scanning integration test; no runtime code or shipped dependency changes.

Concerns

The allowed duplicate-decision map deliberately freezes four historical pairs. Any future cleanup must update both the files and this ratchet atomically.

Friction & bottlenecks

The strict VRS gate was already red on main; #488 repaired and merged that prerequisite before this branch was rebased and revalidated.

Follow-ups

None required for this change.

References

• docs(vrs): restore the strict validation gate #488
• docs/vrs/.decisions/0006-do-not-reuse-decision-ids.md

Posted on behalf of @schickling

field	value
agent_identity	dev3.direct.omp.43sz6ujq
session	dev3.43sz6ujq
agent_persona	generalist
agent_supervisor	unavailable
agent_tool	OMP
agent_tool_version	18.1.7
agent_runtime	OMP 18.1.7
tooling_profile	dotfiles@39a19af