Document native bus adoption path

Author: myobie

README.md

@@ -65,9 +65,10 @@ The compact declaration shape is:
 ```kdl
 agent "<identity>" {
   host "<host>"
-  role "worker"
   workspace "<workspace>"
-  supervisor "<supervisor-bus-id>"
+  // Optional metadata:
+  // role "worker"
+  // supervisor "<supervisor-bus-id>"
   env { ST_AGENT "<host>.<identity>" }
   command #"exec codex --dangerously-bypass-approvals-and-sandbox --dangerously-bypass-hook-trust '<boot prompt>'"#
   ding
@@ -142,6 +143,17 @@ st2 agents --json --enrich
 st2 context read --full
 ```
 
+For a catalog-backed agent, every native bus operation resolves the same agent directory used by
+the roster: presence is `<agent-dir>/status`, while unread messages, archive receipts, context, and
+links live under `<agent-dir>/resources/`. The flat `<root>/<identity>` layout remains only as the
+intentional catalog-less fallback used by isolated folder evals.
+
+Adopters should cut directly to this native layout rather than stage through a retired compatibility
+transport. Before launching a migrated identity, install and verify hooks, validate and materialize
+its hand-authored declaration, stop the predecessor transport, and decide how any unread legacy
+backlog will be archived or forwarded. Never run old and native DING owners concurrently for the same
+identity.
+
 Native DING watches the recipient inbox and safely stages:
 
 ```text
@@ -181,15 +193,18 @@ message, ding, agents, status, context, resource
 env, pty, shell, pretrust
 hooks, service, eval
 compile-agent (experimental)
+completions
 ```
 
-The project ships no completion or manpage generator.
+`st2 completions <shell>` emits completions from the live command tree. No generated completion or
+manpage tree is committed.
 
 ## Clean-room verification
 
-The test suite builds a temporary `PATH` containing only the current `st2` binary plus `pty`,
-`codex`, and `claude` shims. It verifies the supported help/doctor/native authoring surface without
-any retired binary:
+The test suite builds a temporary `PATH` containing only the current `st2` binary, required Git,
+and `pty`, `codex`, and `claude` shims. It installs and verifies a scratch hook receipt, instantiates
+both maintained hand-authored KDL examples in fresh Git workspaces, validates and materializes them
+twice, and verifies the help/doctor/native authoring surface without any retired binary:
 
 ```sh
 cargo test --test native_only --all-features
@@ -204,7 +219,7 @@ cargo test --all-targets --all-features
 
 ## Eval corpus
 
-The evidence ledger is pinned at
+The Codex evidence ledger is pinned at
 [`67b45d2694ac40762b09f51bf625d092ab68de74`](https://github.com/compoundingtech/evals/blob/67b45d2694ac40762b09f51bf625d092ab68de74/HARNESS-MATRIX.md).
 
 Current native Codex examples:
@@ -219,14 +234,21 @@ Current native Codex examples:
 The pinned [native static checker](https://github.com/compoundingtech/evals/blob/67b45d2694ac40762b09f51bf625d092ab68de74/bin/check-codex-native.sh)
 does not consume model usage.
 
-Claude corpus references are historical and are not native-current examples:
+The Claude native-readiness ledger is pinned at
+[`a52b68dfe4bdb65a3bb6a1ba51c674476cf197df`](https://github.com/compoundingtech/evals/blob/a52b68dfe4bdb65a3bb6a1ba51c674476cf197df/CLAUDE-NATIVE-READINESS.md).
+Its current event-first native examples and gates are immutable at
+[`56b86a04837dc176f1a53d9f90dee3f3a7e57499`](https://github.com/compoundingtech/evals/commit/56b86a04837dc176f1a53d9f90dee3f3a7e57499):
+
+- [`ding-reply`](https://github.com/compoundingtech/evals/blob/56b86a04837dc176f1a53d9f90dee3f3a7e57499/cells/ding-reply/ding-reply.kdl):
+  one Claude seat with a native bare `ding`.
+- [`signal-rename`](https://github.com/compoundingtech/evals/blob/56b86a04837dc176f1a53d9f90dee3f3a7e57499/cells/signal-rename/signal-rename.kdl):
+  one Claude supervisor and three specialists, each with a native bare `ding`.
 
-- [`ding-reply`](https://github.com/compoundingtech/evals/blob/67b45d2694ac40762b09f51bf625d092ab68de74/cells/ding-reply/ding-reply.kdl):
-  free syntax gate `bash -n cells/ding-reply/judges/*.sh`; authoritative run
-  `st2 eval ./cells/ding-reply/ --keep`, opt-in paid.
-- [`team-standup`](https://github.com/compoundingtech/evals/blob/67b45d2694ac40762b09f51bf625d092ab68de74/cells/team-standup/team-standup.kdl):
-  free syntax gate `bash -n cells/team-standup/judges/*.sh`; authoritative run
-  `st2 eval ./cells/team-standup/ --keep`, opt-in paid.
+Run `bin/check-claude-native.sh` and `bin/check-claude-reset.sh` from that tree for the free static
+acceptance. The gates reject polling language and legacy bus declarations, require event-first DING
+guidance, and prove repeatable clean fixture resets. They do not invoke a model. A current-build
+`st2 eval` model run remains pending explicit authorization, so these examples have static acceptance
+but no current native live-smoke claim.
 
-There is currently no native-current Claude eval KDL or free authoritative folder-eval parser.
-Claude conversion, a native static gate, and an explicitly authorized current-build run remain open.
+[`team-standup`](https://github.com/compoundingtech/evals/blob/a52b68dfe4bdb65a3bb6a1ba51c674476cf197df/cells/team-standup/team-standup.kdl)
+remains a legacy reference to the retired generated-declaration flow, not a current native example.

tests/native_only.rs

@@ -1,5 +1,5 @@
 use std::fs;
-use std::os::unix::fs::PermissionsExt;
+use std::os::unix::fs::{PermissionsExt, symlink};
 use std::path::{Path, PathBuf};
 use std::process::Command;
 
@@ -10,6 +10,12 @@ fn executable(path: &Path, body: &str) {
 
 fn clean_path() -> tempfile::TempDir {
     let bin = tempfile::tempdir().unwrap();
+    symlink(env!("CARGO_BIN_EXE_st2"), bin.path().join("st2")).unwrap();
+    let git = std::env::split_paths(&std::env::var_os("PATH").unwrap())
+        .map(|dir| dir.join("git"))
+        .find(|path| path.is_file())
+        .expect("the native authoring guide requires git on PATH");
+    symlink(git, bin.path().join("git")).unwrap();
     executable(
         &bin.path().join("pty"),
         "#!/bin/sh\nif [ \"$1\" = \"list\" ]; then printf '[]\\n'; fi\nexit 0\n",
@@ -19,6 +25,19 @@ fn clean_path() -> tempfile::TempDir {
     bin
 }
 
+fn clean_st2(bin: &Path, state: &Path, hooks: &Path) -> Command {
+    let mut command = Command::new(bin.join("st2"));
+    command
+        .env("PATH", bin)
+        .env("XDG_STATE_HOME", state)
+        .env("ST_HOOKS", hooks)
+        .env_remove("CATALOG")
+        .env_remove("ST_ROOT")
+        .env_remove("PTY_ROOT")
+        .env_remove("ST_AGENT");
+    command
+}
+
 fn native_catalog(root: &Path, workspace: &Path) {
     let declaration = root.join("agents/h/worker/agent.kdl");
     fs::create_dir_all(declaration.parent().unwrap()).unwrap();
@@ -33,6 +52,193 @@ fn native_catalog(root: &Path, workspace: &Path) {
     .unwrap();
 }
 
+#[test]
+fn clean_path_executes_the_maintained_native_authoring_guide() {
+    let bin = clean_path();
+    let tmp = tempfile::tempdir().unwrap();
+    let state = tmp.path().join("state");
+    let hooks = tmp.path().join("hooks");
+    let catalog = tmp.path().join("catalog");
+    let codex_workspace = tmp.path().join("codex-workspace");
+    let claude_workspace = tmp.path().join("claude-workspace");
+    fs::create_dir_all(catalog.join("agents/clean/codex")).unwrap();
+    fs::create_dir_all(catalog.join("agents/clean/claude")).unwrap();
+    fs::create_dir_all(catalog.join("_templates")).unwrap();
+    fs::create_dir_all(&codex_workspace).unwrap();
+    fs::create_dir_all(&claude_workspace).unwrap();
+
+    let manifest = Path::new(env!("CARGO_MANIFEST_DIR"));
+    let codex = fs::read_to_string(manifest.join("examples/native/agent-codex.kdl"))
+        .unwrap()
+        .replace("<identity>", "codex")
+        .replace("<host>", "clean")
+        .replace("<workspace>", &codex_workspace.display().to_string())
+        .replace("<boot prompt>", "boot");
+    let claude = fs::read_to_string(manifest.join("examples/native/agent-claude.kdl"))
+        .unwrap()
+        .replace("<identity>", "claude")
+        .replace("<host>", "clean")
+        .replace("<workspace>", &claude_workspace.display().to_string())
+        .replace("<boot prompt>", "boot");
+    fs::write(
+        catalog.join("agents/clean/codex/agent.kdl"),
+        codex.as_bytes(),
+    )
+    .unwrap();
+    fs::write(
+        catalog.join("agents/clean/claude/agent.kdl"),
+        claude.as_bytes(),
+    )
+    .unwrap();
+    fs::write(
+        catalog.join("_templates/clean.codex.AGENTS.md"),
+        "# Clean Codex agent\n",
+    )
+    .unwrap();
+    fs::write(
+        catalog.join("_templates/clean.claude.persona.md"),
+        "# Clean Claude persona\n",
+    )
+    .unwrap();
+    fs::copy(
+        manifest.join("templates/bus.st2.md"),
+        catalog.join("_templates/bus.st2.md"),
+    )
+    .unwrap();
+
+    for workspace in [&codex_workspace, &claude_workspace] {
+        let git = Command::new(bin.path().join("git"))
+            .args(["init", "-q"])
+            .arg(workspace)
+            .env("PATH", bin.path())
+            .status()
+            .unwrap();
+        assert!(git.success());
+    }
+
+    let install = clean_st2(bin.path(), &state, &hooks)
+        .args(["hooks", "install"])
+        .output()
+        .unwrap();
+    assert!(
+        install.status.success(),
+        "{}",
+        String::from_utf8_lossy(&install.stderr)
+    );
+    let verify = clean_st2(bin.path(), &state, &hooks)
+        .args(["hooks", "verify"])
+        .output()
+        .unwrap();
+    assert!(
+        verify.status.success(),
+        "{}",
+        String::from_utf8_lossy(&verify.stderr)
+    );
+
+    let validate = clean_st2(bin.path(), &state, &hooks)
+        .arg("validate")
+        .arg("--catalog")
+        .arg(&catalog)
+        .output()
+        .unwrap();
+    assert!(
+        validate.status.success(),
+        "stdout:\n{}\nstderr:\n{}",
+        String::from_utf8_lossy(&validate.stdout),
+        String::from_utf8_lossy(&validate.stderr)
+    );
+
+    let materialize = || {
+        clean_st2(bin.path(), &state, &hooks)
+            .arg("up")
+            .arg("--catalog")
+            .arg(&catalog)
+            .args(["--host", "clean", "--materialize-only"])
+            .output()
+            .unwrap()
+    };
+    let first = materialize();
+    assert!(
+        first.status.success(),
+        "stdout:\n{}\nstderr:\n{}",
+        String::from_utf8_lossy(&first.stdout),
+        String::from_utf8_lossy(&first.stderr)
+    );
+    let codex_settings = fs::read(codex_workspace.join(".codex/hooks.json")).unwrap();
+    let claude_settings = fs::read(claude_workspace.join(".claude/settings.local.json")).unwrap();
+    let second = materialize();
+    assert!(
+        second.status.success(),
+        "stdout:\n{}\nstderr:\n{}",
+        String::from_utf8_lossy(&second.stdout),
+        String::from_utf8_lossy(&second.stderr)
+    );
+    assert_eq!(
+        fs::read(codex_workspace.join(".codex/hooks.json")).unwrap(),
+        codex_settings
+    );
+    assert_eq!(
+        fs::read(claude_workspace.join(".claude/settings.local.json")).unwrap(),
+        claude_settings
+    );
+
+    let receipt: serde_json::Value =
+        serde_json::from_slice(&fs::read(hooks.join("current.json")).unwrap()).unwrap();
+    let selected = hooks.join(receipt["directory"].as_str().unwrap());
+    for (settings, names) in [
+        (
+            serde_json::from_slice::<serde_json::Value>(&codex_settings).unwrap(),
+            vec![
+                "codex-session-start.sh",
+                "codex-pre-compact.sh",
+                "codex-stop.sh",
+            ],
+        ),
+        (
+            serde_json::from_slice::<serde_json::Value>(&claude_settings).unwrap(),
+            vec![
+                "claude-session-start.sh",
+                "claude-pre-compact.sh",
+                "claude-stop-failure.sh",
+            ],
+        ),
+    ] {
+        let encoded = settings.to_string();
+        for name in names {
+            assert!(
+                encoded.contains(&selected.join(name).display().to_string()),
+                "{name} did not resolve into {}:\n{encoded}",
+                selected.display()
+            );
+        }
+    }
+
+    assert_eq!(
+        fs::read_to_string(codex_workspace.join("AGENTS.md")).unwrap(),
+        "# Clean Codex agent\n"
+    );
+    assert_eq!(
+        fs::read_to_string(claude_workspace.join(".st2/PERSONA.md")).unwrap(),
+        "# Clean Claude persona\n"
+    );
+    for workspace in [&codex_workspace, &claude_workspace] {
+        let status = Command::new(bin.path().join("git"))
+            .arg("-C")
+            .arg(workspace)
+            .args(["status", "--porcelain"])
+            .env("PATH", bin.path())
+            .output()
+            .unwrap();
+        assert!(status.status.success());
+        assert!(
+            status.stdout.is_empty(),
+            "{} was left dirty:\n{}",
+            workspace.display(),
+            String::from_utf8_lossy(&status.stdout)
+        );
+    }
+}
+
 #[test]
 fn clean_path_supports_help_validate_env_and_doctor() {
     let bin = clean_path();
@@ -53,7 +259,14 @@ fn clean_path_supports_help_validate_env_and_doctor() {
         .unwrap();
     assert!(help.status.success());
     let help = String::from_utf8_lossy(&help.stdout);
-    for command in ["validate", "message", "ding", "hooks", "compile-agent"] {
+    for command in [
+        "validate",
+        "message",
+        "ding",
+        "hooks",
+        "compile-agent",
+        "completions",
+    ] {
         assert!(help.contains(command), "missing {command} in help:\n{help}");
     }
     for removed in [