fix(agent-spec): carry required resource reason through bundled declarations and docs

Codex review (P1): requiring reason invalidated the repository's own
examples — validate.rs/status_agents.rs fixtures parse-errored into empty
rosters, and README/vrs spec still documented a name+uri-only envelope.
Add reason to every bundled declaration and update the contract prose to
name+uri+reason with optional inactive-reason.

Author: schickling

README.md

@@ -187,7 +187,7 @@ The compact declaration shape is:
 agent "<identity>" {
   host "<host>"
   workspace "<workspace>"
-  resource "work" uri="github-issue://example/project/123"
+  resource "work" uri="github-issue://example/project/123" reason="release work item"
   // Optional metadata:
   // role "worker"
   // supervisor "<supervisor-bus-id>"
@@ -250,12 +250,13 @@ It neither registers schemes, owns profile schemas, nor resolves targets.
 Binding order is irrelevant and names must be unique within the agent:
 
 ```kdl
-resource "work" uri="github-issue://example/project/123"
-resource "source" uri="worktree://github.com/example/project/change"
-resource "delivery" uri="ding://host/agent"
+resource "work" uri="github-issue://example/project/123" reason="release work item"
+resource "source" uri="worktree://github.com/example/project/change" reason="primary checkout"
+resource "delivery" uri="ding://host/agent" reason="notification channel for this agent"
 ```
 
-The envelope is intentionally only `name` + `uri`. It carries no required/optional,
+The envelope is `name` + `uri` + a required human-facing `reason`, plus an optional
+`inactive-reason` that preserves a retired binding without deleting it. It carries no
 access, readiness, or lifecycle policy, and URI possession conveys no authority. A Resource URI may
 be referenced by any number of agent declarations. Resource-only declaration edits do not stop,
 replace, or relaunch a live task. Resource profiles and resolvers remain opaque to st2; catalog

docs/vrs/spec.md

@@ -191,10 +191,11 @@ the drift is fenced by
 An agent may directly declare zero or more generic Resource bindings:
 
 ```kdl
-resource "work" uri="github-issue://example/project/123"
+resource "work" uri="github-issue://example/project/123" reason="release work item"
 ```
 
-The positional name is an agent-local semantic role. `uri` is the exact RFC 3986 absolute resource
+The positional name is an agent-local semantic role. `reason` explains why the reference belongs
+to this agent (required; optional `inactive-reason` retains inactive bindings). `uri` is the exact RFC 3986 absolute resource
 identity, preserved byte-for-byte without normalization, and its scheme selects the open,
 downstream-owned Resource profile.
 Declaration order has no meaning and binding names are unique within one

tests/status_agents.rs

@@ -23,7 +23,7 @@ fn write(root: &Path, rel: &str, contents: &str) {
 fn agent_kdl(identity: &str, host: &str) -> String {
     format!(
         "agent \"{identity}\" {{\n  identity \"{identity}\"\n  host \"{host}\"\n  \
-         type \"service\"\n  resource \"work\" uri=\"issue://example/{identity}\"\n  \
+         type \"service\"\n  resource \"work\" uri=\"issue://example/{identity}\" reason=\"example work item\"\n  \
          pty \"agent\" {{ command \"exec claude boot\" }}\n}}\n"
     )
 }
@@ -218,7 +218,8 @@ fn roster_json_and_human_output_distinguish_retirement_from_presence() {
         rows[0]["resources"],
         serde_json::json!([{
             "name": "work",
-            "uri": "issue://example/live"
+            "uri": "issue://example/live",
+            "reason": "example work item"
         }])
     );
     assert_eq!(rows[1]["identity"], "h.retired");

tests/validate.rs

@@ -72,7 +72,7 @@ fn opaque_resource_bindings_are_structurally_valid() {
         "Silber/cos/agent.kdl",
         r#"agent "cos" {
   host "Silber"
-  resource "work" uri="vendor+thing://authority/exact%20identity"
+  resource "work" uri="vendor+thing://authority/exact%20identity" reason="example vendor work item"
   command "codex"
 }"#,
     )]);
@@ -88,15 +88,15 @@ fn active_agents_may_share_an_opaque_resource_uri() {
             "h/reviewer/agent.kdl",
             r#"agent "reviewer" {
   host "h"
-  resource "subject" uri="git-commit://github.com/example/project/0123456789abcdef"
+  resource "subject" uri="git-commit://github.com/example/project/0123456789abcdef" reason="reviewed example commit"
   command "true"
 }"#,
         ),
         (
             "h/integrator/agent.kdl",
             r#"agent "integrator" {
   host "h"
-  resource "subject" uri="git-commit://github.com/example/project/0123456789abcdef"
+  resource "subject" uri="git-commit://github.com/example/project/0123456789abcdef" reason="reviewed example commit"
   command "true"
 }"#,
         ),
@@ -114,15 +114,15 @@ fn duplicate_bus_ids_remain_an_error_when_resources_are_shared() {
             "h/one/agent.kdl",
             r#"agent "worker" {
   host "h"
-  resource "subject" uri="git-commit://github.com/example/project/0123456789abcdef"
+  resource "subject" uri="git-commit://github.com/example/project/0123456789abcdef" reason="reviewed example commit"
   command "true"
 }"#,
         ),
         (
             "h/two/agent.kdl",
             r#"agent "worker" {
   host "h"
-  resource "subject" uri="git-commit://github.com/example/project/0123456789abcdef"
+  resource "subject" uri="git-commit://github.com/example/project/0123456789abcdef" reason="reviewed example commit"
   command "true"
 }"#,
         ),