cli

Command-line interface for Radroots
git clone https://radroots.dev/git/cli.git
Log | Files | Refs | README | LICENSE

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.