AGENTS.md (7045B)
1 # AGENTS.md — Radroots CLI 2 3 These instructions apply to the complete standalone `radrootslabs/cli` 4 repository. 5 6 ## Repository role 7 8 This repository owns the public `radroots_cli` package and the `radroots` 9 binary. It owns command parsing, invocation-scoped configuration, composition 10 of public Radroots library clients, stable output envelopes, exit behavior, 11 and CLI-specific presentation and tests. 12 13 It does not own Radroots domain policy, durable service state, signing or 14 custody internals, relay internals, SDK internals, platform deployment, 15 publication, promotion, or non-public parent integration behavior. Preserve 16 those boundaries unless an approved public contract explicitly changes them. 17 18 The repository must remain independently cloneable, buildable, testable, and 19 packageable. Do not depend on private repositories, parent-only contracts or 20 tools, sibling checkout paths, unpublished local artifacts, absolute host 21 paths, or an enclosing monorepo layout. 22 23 ## Authority and published-source boundary 24 25 Repository-local machine authority is limited to manifests and locks, 26 `radroots.lib.source-lock.v1.toml`, the checked-in dependency-policy store, and 27 explicit machine-readable contracts added under `contracts/**`. Source and 28 tests are implementation evidence. Native Cargo and repository scripts own 29 the standalone command surfaces; checked-in Nix material is deferred and 30 unclaimed through RCLD-RSHR-170. The root `README` is concise public routing 31 material, not a substitute for a machine contract. 32 33 Current compiler/provider preparation uses the exact V1 Lib source lock and 34 `contracts/release/cli-artifact-contract.v4.json`. Current Nix execution and 35 artifact qualification require separate source-scoped evidence. The original 36 V3 descriptor and Step 302 replay retain their original scope and do not 37 qualify new compiler or provider inputs. 38 39 `.env.example` is non-authoritative pre-refactor evidence. It does not describe 40 current runtime behavior and remains only until its owning later cleanup 41 checkpoint; do not use it to invent or preserve configuration behavior. 42 43 Human implementation specifications, decisions, runbooks, migration history, 44 qualification records, and execution evidence are parent-owned and do not ship 45 in this capsule. Never create or consume capsule-local `docs/**`. The parent 46 documentation is not a standalone command, build, test, package, or release 47 input. 48 49 The physical roots `docs/**`, `.github/**`, and `.act/**` are forbidden, 50 including symlinks. Run `tools/verify-repository-boundary.sh` in every governed 51 verification lane. Do not add a capsule-local workflow definition. External 52 automation may invoke the repository's ordinary forge-agnostic commands, but 53 it must not be required by an independent clone. 54 55 ## Dependency and source-lock rules 56 57 The public `radroots` dependency must use the canonical 58 `https://github.com/radrootslabs/lib.git` source, an exact immutable revision, 59 and the declared exact package version. Keep `Cargo.toml`, `Cargo.lock`, and 60 `radroots.lib.source-lock.v1.toml` consistent. Never replace it with a path, 61 branch, floating Git reference, private mirror, or implicit sibling override. 62 63 An exact revision is not releasable merely because it exists locally. Before a 64 downstream pin or release advances, the selected upstream commit must be 65 publicly reachable and its source-lock evidence must be verified under the 66 applicable publication authority. 67 68 ## Change rules 69 70 - Inspect the relevant manifest, lock, source lock, implementation, tests, and 71 public routing material before changing behavior. 72 - Make the smallest complete change and keep each checkpoint independently 73 reviewable. Do not mix unrelated cleanup or roadmap work into it. 74 - Preserve a clear separation between argument parsing, configuration loading, 75 service-client composition, domain-library calls, and output formatting. 76 - Prefer typed models, explicit inputs, deterministic behavior, narrow side 77 effects, and typed errors for expected failures. 78 - Do not add compatibility aliases, dual reads, dual writes, fallback behavior, 79 or hidden environment/runtime discovery for prototype surfaces being removed 80 by the active clean-slate services-hardening sequence. Change those surfaces 81 only in their owning implementation checkpoint. 82 - Keep output schemas, exit codes, help text, configuration examples, source, 83 tests, and machine contracts aligned with every user-visible change. 84 - Keep `unsafe` absent unless an approved contract makes it unavoidable; any 85 exception requires a narrow local invariant and dedicated tests. 86 87 ## Security and operational behavior 88 89 Never expose or commit private keys, credentials, tokens, invite codes, 90 approval proofs, private identifiers, sensitive user data, or sensitive event 91 content. Examples and fixtures must use unmistakably synthetic values. 92 93 Do not log secrets or raw protected material. Keep machine-readable output on 94 stdout, diagnostics on stderr, and non-success outcomes paired with a stable 95 structured error and nonzero exit status. Destructive or externally mutating 96 commands must remain explicit, fail closed, and require their governed 97 authorization rather than inferring consent from configuration or environment. 98 99 Avoid hidden production panics. Bound input, output, network, time, and retry 100 work where the relevant public contract defines a limit, and preserve 101 cancellation and failure context without leaking sensitive internals. 102 103 ## Verification 104 105 From an extbuild-enabled checkout, run `cargo extbuild doctor` before the first 106 mutating build, check, test, package, install, or generated-artifact command, 107 then route repository-owned commands through `cargo extbuild run -- ...`. 108 Standalone public verification surfaces are: 109 110 ```sh 111 cargo fmt --all --check 112 cargo check --all-targets --locked 113 cargo test --all-targets --locked 114 cargo clippy --all-targets --locked -- -D warnings 115 RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --locked 116 scripts/verify-boundaries.sh 117 scripts/verify-supply-chain.sh 118 tools/verify-repository-boundary.sh 119 ``` 120 121 Use the smallest relevant surface during development and the complete native 122 set for a production candidate. The supply-chain gate uses exact cargo-deny 123 0.19.8 and cargo-vet 0.10.2; its checked-in exemptions are visible accepted 124 review debt, not claims of independent source audits. Nix and OCI remain 125 deferred and unclaimed through RCLD-RSHR-170. Run `git diff --check` and 126 inspect the final status and diff before every checkpoint. 127 128 Never claim a lane passed unless it ran successfully. Record unavailable or 129 environment-blocked lanes exactly, and do not treat parent-only automation as a 130 substitute for standalone repository validation. 131 132 ## Git and release discipline 133 134 Preserve unrelated changes and repository identity. Do not reset, discard, 135 rewrite, push, tag, sign, publish, deploy, rotate credentials, or advance a 136 downstream revision without explicit authority for that action. Keep commits 137 focused and use `<scope>: <imperative summary>` unless a stronger repository 138 convention applies.