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

agent-identity: dev3.direct.omp.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

Author: schickling-assistant

docs/vrs/.decisions/0005-streams-are-agent-nested-and-stream-named.md

@@ -72,7 +72,7 @@ run natively without a second producer-identity mechanism.
 - Issue #49's "topic" remains a message-side axis; the event-side grouping
   axis is *key*. The two must not be merged by name.
 - Suspension semantics follow locality: the stream task is an owned task, so
-  R27 tears it down with the agent — eyes closed, no accumulation, resume
+  R41 tears it down with the agent — eyes closed, no accumulation, resume
   re-observes; the dedup ring makes re-emission of still-current state safe.
 - Ingress authority follows the same locality: `event emit` runs only when its
   resolved logical owner host and catalog lock match the unsynchronized

docs/vrs/.decisions/0016-systemd-scope-wrappers-disable-environment-expansion.md

@@ -2,7 +2,7 @@
 
 Status: accepted
 
-Accepted on 2026-09-05 for R40 launch argv transparency.
+Accepted on 2026-09-05 for R42 launch argv transparency.
 
 ## Context
 

docs/vrs/.experiments/2026-08-04-agent-desired-state-prototype.md

@@ -55,7 +55,7 @@ and runtime observation.
 
 ## VRS Impact
 
-The result adds root R27 and R28, Agent Spec field rule F18, Doctor R07, the
+The result adds root R41 and R28, Agent Spec field rule F18, Doctor R07, the
 agent desired state/suspension/retirement/rationale ontology, and corresponding
 wire and acceptance text. It does not change the vision.
 

docs/vrs/.experiments/2026-09-05-systemd-scope-argv-transparency.md

@@ -42,12 +42,12 @@ Systemd's default command-line expansion is not transparent to caller-owned
 argv. Passing `--expand-environment=no` before the command separator is the
 narrow correction: it preserves the complete dollar-bearing literal while all
 measured scope lifecycle, descriptor, PTY, exit-status, collection, and reuse
-semantics remain unchanged. This supports [R40 launch argv transparency](../requirements.md)
+semantics remain unchanged. This supports [R42 launch argv transparency](../requirements.md)
 and [decision 0016](../.decisions/0016-systemd-scope-wrappers-disable-environment-expansion.md).
 
 ## VRS Impact
 
-- `requirements.md` adds R40 launch argv transparency.
+- `requirements.md` adds R42 launch argv transparency.
 - `ontology.md` defines **launch argv** as the canonical task-wide term.
 - `spec.md` fixes the exact systemd scope wrapper order and its deterministic
   scope/pass-through tests.

docs/vrs/ontology.md

@@ -76,7 +76,7 @@ the launch argv. This is not a shell command line. Use *provider argv* only
 when referring specifically to the canonical agent provider; *launch argv*
 applies to every PTY and exec task.
 
-Authority: [R06 restartable launch definitions and R40 launch argv
+Authority: [R06 restartable launch definitions and R42 launch argv
 transparency](requirements.md);
 [host-local scheduling and supervision](spec.md#host-local-scheduling-and-supervision)
 
@@ -463,7 +463,7 @@ Authority: [R31 reachable restart bounds](requirements.md);
 The declaration-owned whole-agent lifecycle intent: `running`, `suspended`, or
 `retired`. It is distinct from presence and session state.
 
-Authority: [R27 typed agent desired state](requirements.md);
+Authority: [R41 typed agent desired state](requirements.md);
 [`AgentDesiredState`](../../crates/agent-spec/src/spec.rs)
 
 ### suspension
@@ -472,23 +472,23 @@ Reversible desired absence of an agent's live tasks while its declaration and
 catalog-backed durable state remain available. Suspension is not process pause
 or checkpointing.
 
-Authority: [R27 typed agent desired state](requirements.md);
+Authority: [R41 typed agent desired state](requirements.md);
 [Agent Spec field rules](02-agent-spec/spec.md)
 
 ### retirement
 
 Terminal desired absence whose completion additionally requires every declared
 task record to be collected. Legacy `retired #true` is a readable spelling.
 
-Authority: [R27 typed agent desired state](requirements.md);
+Authority: [R41 typed agent desired state](requirements.md);
 [Doctor retired absence](02-doctor/requirements.md)
 
 ### desired-state rationale
 
 The bounded human explanation required by a new suspended or retired desired
 state. It explains intent and grants no lifecycle authority of its own.
 
-Authority: [R27 typed agent desired state](requirements.md)
+Authority: [R41 typed agent desired state](requirements.md)
 
 ### reconciliation
 

docs/vrs/requirements.md

@@ -126,7 +126,7 @@ accepted.
 - **R06 Restartable launch definitions:** A restarted PTY or exec receives the
   complete effective launch definition, including environment and supported
   launch fields.
-- **R40 Launch argv transparency:** Every st2-added launch wrapper preserves the
+- **R42 Launch argv transparency:** Every st2-added launch wrapper preserves the
   effective task program and each argument as ordered, opaque OS strings. A
   Linux systemd scope launch disables systemd command-line environment
   expansion before the wrapper separator, so dollar-bearing literals including
@@ -411,7 +411,7 @@ accepted.
   the only source of address, name, and description; an explicit ID roster
   query returns the subject's current address and presentation without
   publishing a duplicate Agent Spec state file.
-- **R27 Typed agent desired state:** Every admitted Agent Spec has exactly one
+- **R41 Typed agent desired state:** Every admitted Agent Spec has exactly one
   whole-agent desired state: `running`, `suspended`, or `retired`. Omission and
   legacy `retired #false` mean running; legacy `retired #true` means retired
   without a rationale. New suspended and retired declarations require one

docs/vrs/spec.md

@@ -16,6 +16,13 @@ delivers messages. The agent grammar and harness-facing contract remain
 canonical in
 [`compoundingtech/evals/AGENT-SPEC.md`](https://github.com/compoundingtech/evals/blob/main/AGENT-SPEC.md).
 
+## Decision citations
+
+Decision records are cited by their full filename stem, `NNNN-<slug>`. Bare
+numbers are ambiguous for 0005, 0007, 0014, and 0015; their collisions are
+recorded history, and numbers are never reused under
+[`0006-observed-harness-state-is-a-driver-written-catalog-record`](.decisions/0006-observed-harness-state-is-a-driver-written-catalog-record.md).
+
 ## Canonical Agent Spec eval teams
 
 An eval may opt into `canonical-agents` after its fixture copy and deterministic
@@ -67,7 +74,7 @@ implemented: the grammar, host-local address uniqueness, `st2 agent address`,
 and the fail-closed bare-or-qualified reference resolution. Its immutable-ID half
 is not: no writer emits `id`, so the positional `<host>.<identity>` bus identity
 remains the durable key every ownership, task-identity, and record surface uses.
-[0015 Amendment 1](.decisions/0015-immutable-agent-id-and-mutable-address.md)
+[`0015-immutable-agent-id-and-mutable-address` Amendment 1](.decisions/0015-immutable-agent-id-and-mutable-address.md)
 stages that half behind named triggers and
 [DELTA-003](.delta/DELTA-003-agent-address-not-implemented.md) records what it
 still requires.
@@ -285,7 +292,7 @@ its own durable waits. st2 provides no wait loop or timer and does not turn the
 request into agent lifecycle authority.
 
 This transport is design-superseded but still normative for the shipped
-implementation: [decision 0004](.decisions/0004-stream-events-are-a-distinct-record-kind.md)
+implementation: [`0004-stream-events-are-a-distinct-record-kind`](.decisions/0004-stream-events-are-a-distinct-record-kind.md)
 absorbs typed requests into stream events plus ordinary replies, staged behind
 a deprecation window ([04-stream DQ-S4](04-stream/open-questions.md)). Until
 that staging completes, this section and its invariant row remain the truth;
@@ -777,7 +784,7 @@ validate ──► materialize ──► host-local st2 scheduler/reconciler
   manual PTY restart under a different ambient environment reconstructs the
   same effective color policy. Adoption of an already-live task remains
   non-mutating: this policy is applied only when st2 creates a generation.
-- **R40:** [Launch argv](ontology.md#launch-argv) is opaque at every
+- **R42:** [Launch argv](ontology.md#launch-argv) is opaque at every
   st2-added wrapper boundary. In Linux systemd scope mode the exact outer
   command order is:
 
@@ -798,7 +805,7 @@ validate ──► materialize ──► host-local st2 scheduler/reconciler
   proves both pass-through modes. The live-system distinction and unaffected
   scope semantics are recorded in the
   [systemd scope argv experiment](.experiments/2026-09-05-systemd-scope-argv-transparency.md)
-  and [decision 0016](.decisions/0016-systemd-scope-wrappers-disable-environment-expansion.md).
+  and [`0016-systemd-scope-wrappers-disable-environment-expansion`](.decisions/0016-systemd-scope-wrappers-disable-environment-expansion.md).
 - **R07:** Hook bundles are explicit, content-addressed, installed separately,
   and verified before materialization references them. Their receipts use the
   same resolved build identity as the binary's version surfaces for both
@@ -911,7 +918,7 @@ validate ──► materialize ──► host-local st2 scheduler/reconciler
   only the marker channel owned by the exact canonical catalog folder and host
   it is observing.
 
-- **R27/R28:** Agent lifecycle intent is one closed declaration state:
+- **R41/R28:** Agent lifecycle intent is one closed declaration state:
   `running`, `suspended`, or `retired`. The KDL form is a direct child such as
   `desired-state "suspended" reason="Waiting for capacity"`. Omission means
   running. New suspended and retired states require a bounded rationale;
@@ -987,7 +994,7 @@ parses structured output that must be whole, so it uses the explicitly named
 full-stdout variant; that read is intentionally uncapped and visible at its
 call site. Eval run steps and agent log dumps stream child output straight to
 their catalog log files without buffering it. Rationale and rejected
-alternatives: [decision 0007](.decisions/0007-child-output-capture-is-bounded-and-tail-preserving.md).
+alternatives: [`0007-child-output-capture-is-bounded-and-tail-preserving`](.decisions/0007-child-output-capture-is-bounded-and-tail-preserving.md).
 
 ## Catalog graph and native delivery admission (R35–R38)
 
@@ -1385,7 +1392,7 @@ The measured basis for this design, including the runs that fixed `steer` and
 the modal case, is recorded in
 [2026-08-18-pi-harness-integration](./.experiments/2026-08-18-pi-harness-integration.md);
 the ruling is
-[decision 0005](./.decisions/0005-pi-delivers-natively-through-an-injected-extension.md).
+[`0005-pi-delivers-natively-through-an-injected-extension`](./.decisions/0005-pi-delivers-natively-through-an-injected-extension.md).
 
 ## Event contracts (R13–R15, R40)
 

tests/vrs_ledger.rs

@@ -0,0 +1,122 @@
+use std::collections::{BTreeMap, BTreeSet};
+use std::fs;
+use std::path::Path;
+
+#[test]
+fn root_requirement_ids_are_unique() {
+    let requirements = include_str!("../docs/vrs/requirements.md");
+    let mut seen = BTreeSet::new();
+
+    for line in requirements.lines() {
+        let Some(rest) = line.strip_prefix("- **R") else {
+            continue;
+        };
+        let digits = rest.bytes().take_while(u8::is_ascii_digit).count();
+        if digits == 0 || !rest[digits..].starts_with(' ') {
+            continue;
+        }
+        let number = rest[..digits]
+            .parse::<u32>()
+            .expect("requirement ID digits must parse");
+        assert!(
+            seen.insert(number),
+            "duplicate root requirement ID R{number}"
+        );
+    }
+}
+
+#[test]
+fn root_decision_number_duplicates_match_recorded_history() {
+    let decision_dir = Path::new(env!("CARGO_MANIFEST_DIR")).join("docs/vrs/.decisions");
+    let mut by_number = BTreeMap::<String, BTreeSet<String>>::new();
+
+    for entry in fs::read_dir(decision_dir).expect("root decision directory must be readable") {
+        let path = entry.expect("decision entry must be readable").path();
+        let Some(stem) = path.file_stem().and_then(|stem| stem.to_str()) else {
+            continue;
+        };
+        let Some((number, _)) = stem.split_once('-') else {
+            continue;
+        };
+        if number.len() == 4 && number.bytes().all(|byte| byte.is_ascii_digit()) {
+            by_number
+                .entry(number.to_owned())
+                .or_default()
+                .insert(stem.to_owned());
+        }
+    }
+
+    let duplicates = by_number
+        .into_iter()
+        .filter(|(_, stems)| stems.len() > 1)
+        .collect::<BTreeMap<_, _>>();
+    let expected = [
+        (
+            "0005",
+            [
+                "0005-pi-delivers-natively-through-an-injected-extension",
+                "0005-streams-are-agent-nested-and-stream-named",
+            ]
+            .as_slice(),
+        ),
+        (
+            "0007",
+            [
+                "0007-child-output-capture-is-bounded-and-tail-preserving",
+                "0007-omp-is-a-fifth-native-driver-with-its-own-channel-and-a-hard-version-gate",
+            ]
+            .as_slice(),
+        ),
+        (
+            "0014",
+            [
+                "0014-harness-context-is-a-sibling-numeric-record",
+                "0014-resource-profiles-are-state-first-read-and-observe-capabilities",
+            ]
+            .as_slice(),
+        ),
+        (
+            "0015",
+            [
+                "0015-catalog-commits-and-direct-edits-use-independent-wake-channels",
+                "0015-immutable-agent-id-and-mutable-address",
+            ]
+            .as_slice(),
+        ),
+    ]
+    .into_iter()
+    .map(|(number, stems)| {
+        (
+            number.to_owned(),
+            stems.iter().map(|stem| (*stem).to_owned()).collect(),
+        )
+    })
+    .collect::<BTreeMap<_, _>>();
+
+    assert_eq!(duplicates, expected);
+}
+
+#[test]
+fn root_delta_ids_are_unique() {
+    let delta_dir = Path::new(env!("CARGO_MANIFEST_DIR")).join("docs/vrs/.delta");
+    let mut seen = BTreeSet::new();
+
+    for entry in fs::read_dir(delta_dir).expect("root delta directory must be readable") {
+        let path = entry.expect("delta entry must be readable").path();
+        let Some(stem) = path.file_stem().and_then(|stem| stem.to_str()) else {
+            continue;
+        };
+        let Some(rest) = stem.strip_prefix("DELTA-") else {
+            continue;
+        };
+        let Some((number, _)) = rest.split_once('-') else {
+            continue;
+        };
+        if number.len() == 3 && number.bytes().all(|byte| byte.is_ascii_digit()) {
+            assert!(
+                seen.insert(number.to_owned()),
+                "duplicate root delta ID DELTA-{number}"
+            );
+        }
+    }
+}