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