Retire the linked-record plane; st2 resource becomes the binding surface

[schickling-assistant]

Retire the linked-record plane; st2 resource becomes the binding surface

st2 had two disjoint durable things both called resource, and an agent reading
one while reasoning about the other measured the wrong store. This retires one of
them and repoints the verb at the other.

Closes #62. Closes #231. Refutes #122. Answers #261. Partially answers #60.

The problem, reproduced

Downstream report schickling/dotfiles#2071,
both instances measured on a live catalog:

• a declaration with 5 bindings and 0 link records printed # 0 resources
• a declaration with 2 bindings and 14 link records printed 14 rows containing
  neither binding

Both surfaces answered correctly. Neither said which question it had answered.

What the measurement showed

One live catalog, 655 agent declarations, 2026-08-27:

	bindings	link records
declarations carrying any	647	82
records	1161	241
distinct URIs	889	233

Exact-match URI overlap: 0 — and still 0 after normalizing across all five
schemes both planes used (file, worktree, git-commit, https,
st2-message). 81 of the 82 link-carrying declarations also carried bindings, so
the planes coexisted constantly and never named one thing.

The disjointness is semantic. Bindings carry what an agent is for (728
self-state carriers, 378 work inputs); link records carried what it made (196
of 241 were output/produces/evidence/verified).

So a shared descriptor type — #122's proposal — deduplicates nothing and joins
nothing. (#122 also assumes a _tag field removed in #307.)

Why the link plane went rather than the wording

• Write-only by construction. The only reader in the source tree was its own
  ls/read verb. No projection, roster, or doctor consumed one.
• 12.5% adoption, decaying. 45 records on 2026-08-08, 5 on 2026-08-26, none
  after. 14 of the 25 most recent came from one declaration on one day.
• Superseded. axe work update --artifact <path> --pty <name> covers the
  job, matching the observed relation values and the 8 pty:// URLs.
• Still advertised. templates/bus.st2.md told every agent on the bus to use
  it, which is what produced the adoption. That advertisement is removed here.

The root cause, which naming would not have fixed

45 of 241 link records were not products at all: supervises, reference,
current-work (duplicating the work binding outright), depends-on-slice-*,
blocked-design — dependency edges filed in a products store.

Agents wrote them there because a binding required publisher authority plus
whole-declaration CAS republication, while a link record was one file write.
The drift was caused by write-cost asymmetry, not by two concepts sharing a
word. Retiring the plane removes the escape hatch; the mediated write verbs
remove the pressure that produced it.

Changes

st2 resource now reads and writes declared bindings:

st2 resource ls [<identity>] [--json]
st2 resource read [<identity>] <name> [--json]
st2 resource add <name> --uri <uri> --reason <text> [--inactive-reason <text>] [--agent <id>]
st2 resource remove <name> [--agent <id>]
st2 resource rename <old> <new> [--agent <id>]

The write verbs do read-modify-CAS-publish internally; the caller never renders
KDL. Validation, exact-target selection, compare-and-swap, fail-closed
concurrent-change behavior and R21 non-disruption are preserved, and a
Nix-managed declaration refuses the edit.

This is the fourth caller of an existing pattern, not new machinery —
src/agent_author.rs already does this for streams, desired state, and
presentation.

Removed: src/resource.rs, the link-record ResourceCmd, and the
templates/bus.st2.md advertisement.

<agent-dir>/resources/ is untouched and remains canonical for an agent's
resource files. Only links/ goes.

Requirements: none

requirements.md is identical to main. This branch makes no constitutional
edit.

It briefly carried one. working-state needed a requirement only while R20 read
"st2 does not register schemes" — a scheme st2 resolves would have contradicted
it. #351 landed first and
rewrote R20: a scheme is now the exact lookup key for an optional,
catalog-declared Resource Profile. That removed the barrier, and the drafted R35
— an exemption from a clause R20 no longer contains — was withdrawn rather than
rebased into a self-contradiction. Decision 0012 records the withdrawal as an
amendment. Nothing about the carrier, its scheme name, or its realization
changed.

VRS

New docs/vrs/07-resource/ tree, three decision records
(0011/0012/0013 — 0008/0009 went to #345 and #351), and ontology
entries for Resource, Resource binding, linked record (retired),
agent resource directory, and working state — the ontology previously had
zero entries for any of them, which is how two concepts came to share one
word.

Rebased onto the merged Resource Profile foundation. The ontology's Resource
and working state entries and 07-resource/spec.md now state the post-#351
contract rather than the one they were written against.

Rebased onto the merged Resource Profile work

#351 and #345 landed while this was open. Rebased onto them, and three
assertions written against the older contract were realigned: #345 admits a
catalog-relative carrier path as a binding uri and reserves the name
declaration, so the refusals now pinned are the ones that escape the catalog.
agent_publish additionally asserts that an incomplete-apply marker fences
resource add — correct now that a binding write is a declaration write.

Verification

nix flake check — the repo's CI gate — passes.

Full cargo test --no-fail-fast compared against a same-toolchain
git archive origin/main baseline. No failure is unique to this branch — its
failing-target set is a strict subset of main's own (main additionally flakes
completed_single_agent_writer_abas_during_runtime_observation_are_incomplete).
The 6 shared failures are pre-existing environmental ones on this host: the
agent-policy pty wrapper, and doc drift in files this PR does not touch.

New tests/agent_resource.rs covers ls/read/--json, add-publishes,
add-idempotent, exact URI byte preservation, remove-idempotent, rename
absent/collision refusal, invalid-URI and empty-reason refusal, the Nix-managed
refusal, and that the retired invocation no longer creates a link store. 7/7.

cargo fmt --check clean. Clippy is deliberately not gated (flake.nix:258).

Not in this PR

• Declaring the working-state carrier across existing declarations (decision
  0012 is accepted; the rollout is a bulk authoring pass, not a code change).
• The 241 orphaned link-record files, left in place (DQ-R10).
• Runtime bindings on a configuration-generated declaration (How should Nix-managed Agent Specs compose runtime Resource bindings? #305, DQ-R4).
• Syncing the stale upstream evals/AGENT-SPEC.md (DQ-R8).

Posted on behalf of @schickling

field	value
agent_identity	unknown
agent_persona	generalist
agent_supervisor	unavailable
agent_tool	Claude Code
agent_tool_version	2.1.237
agent_runtime	Claude Code 2.1.237
tooling_profile	dotfiles@11eaf2d-dirty

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 215f2683bc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".