AGENT_INSTRUCTIONS.md (9285B)
1 # Radroots Core Libraries - Agent Instructions 2 3 **For repository overview and setup, see [README](README). For repository rules, see [AGENTS.md](AGENTS.md).** 4 5 This document contains detailed operational instructions for contributors and coding agents working on development, testing, and releases in the Radroots Core Libraries repository. 6 7 `AGENTS.md` is the concise repo contract. Read it first, then use this file for execution detail. 8 9 ## 1. How to use this file 10 11 - Treat `AGENTS.md` as the durable always-on contract. 12 - Use this file for interpretation, procedures, and detailed engineering expectations. 13 - If a closer subtree-specific `AGENTS.md` is added later, that file overrides root guidance for its scope. 14 - Keep durable rules short and proven; if a problem repeats, tighten the root contract instead of growing ad hoc prompt text. 15 16 ## 2. Repository operating model 17 18 This repository is a public open-source Rust workspace. Optimize for: 19 20 - portable library design 21 - deterministic behavior 22 - explicit contracts 23 - cross-target consistency 24 - clean public APIs 25 26 Stay disciplined: 27 28 - keep scope tight 29 - avoid drive-by cleanup 30 - avoid speculative abstraction 31 - avoid compatibility scaffolding unless it is explicitly required 32 - do not leave dead paths, temporary adapters, or silent fallback behavior behind 33 34 This repo is a library workspace, not an app monolith. The right default is small, durable changes that preserve clean crate boundaries. 35 Release automation should stay forge-agnostic. Keep release truth in repo-owned xtask commands, Nix apps, tags, and contract metadata rather than committed provider-specific workflow files. 36 37 ## 3. Preflight workflow 38 39 Before editing code: 40 41 - Read `AGENTS.md`. 42 - Read this file. 43 - Read `README` when the change touches workflow or public surfaces. 44 - When touching Nix behavior, read `flake.nix` and the active Nix implementation files under `build/nix/`. 45 - Read the relevant crate manifest, implementation files, and nearby tests before proposing a new structure. 46 - Check `git status --short`. 47 48 Before running cargo commands: 49 50 - Prefer `nix develop` or `direnv allow`. 51 - Treat Nix as the canonical environment contract. 52 - Prefer the documented repo-owned command surface over improvised local commands. 53 54 Fail early when: 55 56 - the environment is missing required tooling 57 - the task materially changes a public contract without enough local context 58 - the working tree is contaminated in a way that changes the requested scope 59 60 ## 4. Workspace interpretation 61 62 Use this mental model: 63 64 - `crates/` 65 - library crates and workspace tooling crates 66 - keep domain logic inside the correct crate rather than spreading it across the workspace 67 - `contracts/` 68 - core-library contract metadata, release-candidate policy, coverage governance, and public conformance assets 69 - `contracts/conformance/` 70 - cross-language and cross-surface vector expectations 71 - `docs/` 72 - durable workflow and environment documentation 73 - `build/nix/`, `flake.nix`, `treefmt.nix` 74 - canonical environment and CI contract 75 - `tools/xtask/` 76 - typed repo-owned automation used by canonical lanes 77 78 Do not duplicate contract knowledge between crates when `contracts/`, `contracts/conformance/`, or `tools/xtask` already owns it. 79 80 ## 5. Rust engineering standards 81 82 ### Core design 83 84 - Prefer pure functions and explicit data flow in core logic. 85 - Keep IO, filesystem, network, clocks, randomness, and runtime glue at the edges. 86 - Prefer data transformation pipelines over stateful orchestration when the problem is fundamentally transformational. 87 - Prefer explicit state machines and enums over ad hoc flags or loosely related booleans. 88 - Keep mutation local and minimal. 89 - Avoid hidden shared mutable state and interior mutability unless the boundary truly requires it. 90 91 ### API design 92 93 - Public APIs should make invalid states hard to represent. 94 - Prefer newtypes, enums, and dedicated structs when semantics matter. 95 - Avoid exposing dependency-specific types in public API surfaces unless that dependency is a deliberate part of the contract. 96 - Separate parsing, validation, normalization, and serialization instead of collapsing them into a single opaque function. 97 - Prefer exhaustive `match` behavior for semantic enums over wildcard-heavy control flow. 98 99 ### Errors and invariants 100 101 - Library code should not panic on normal invalid input. 102 - Reserve `unwrap`, `expect`, and panic-based control flow for tests, build scripts, or tightly proven internal invariants. 103 - Use precise typed errors for public and semantically important boundaries. 104 - Keep opaque convenience errors inside binaries, narrow tooling layers, or internal glue when appropriate. 105 - When an invariant truly cannot be violated, document it close to the code. 106 107 ### Portability and feature discipline 108 109 - Preserve `no_std` intent where the crate is designed for it. 110 - Gate `std` behavior, wasm behavior, and runtime-specific behavior explicitly and predictably. 111 - Keep feature interactions simple and testable. 112 - When a change affects native, wasm, or `std`/`no_std` parity, update the affected tests or validation flow in the same change. 113 114 ### Performance and allocation 115 116 - Borrow before cloning. 117 - Prefer `&str`, `&[u8]`, slices, and iterators when ownership is not required. 118 - Avoid unnecessary intermediate allocations. 119 - Preallocate only when the size is known or bounded meaningfully. 120 - Do not trade away clarity for micro-optimizations unless profiling or the hot-path nature of the code justifies it. 121 122 ### Module layout 123 124 - Keep `lib.rs` thin. 125 - Put heavy logic in focused modules. 126 - Avoid giant files that mix models, parsing, validation, transformations, and integration glue. 127 - Introduce traits only when they remove real duplication or encode a stable abstraction boundary. 128 - Avoid generic abstraction that makes the code harder to reason about without clear reuse value. 129 130 ### Documentation and source comments 131 132 - Do not add explanatory comments by habit. 133 - Add concise Rustdoc for non-obvious public APIs, invariants, and cross-target behavior. 134 - Keep docs aligned with the actual code and contract surface. 135 136 ## 6. Contract, conformance, and release workflow 137 138 `contracts/`, `contracts/conformance/`, and `tools/xtask` are first-class parts of the product surface, not secondary metadata. 139 140 When a change affects exported models, transforms, identifiers, or public runtime expectations: 141 142 - update the relevant contract metadata 143 - update or add conformance vectors 144 - update repo-aware validation flows if needed 145 - keep release and export rules aligned with the new behavior 146 147 Do not change public behavior in Rust and leave contract or conformance assets stale. 148 149 ## 7. Canonical validation strategy 150 151 Use the smallest authoritative lane that proves the change green. 152 153 Repo-wide canonical lanes: 154 155 - `nix flake check` 156 - `nix run .#contract` 157 - `nix run .#release-preflight` 158 159 Targeted iteration inside the Nix shell: 160 161 - `cargo check -p <crate>` 162 - `cargo test -p <crate>` 163 - `cargo xtask contract validate` 164 - `cargo xtask release preflight` 165 - `cargo xtask hygiene forbidden-identifiers` 166 167 Validation rules: 168 169 - crate-local changes may iterate with targeted cargo commands 170 - contract, export, conformance, flake, release, or multi-crate changes should close on a canonical Nix lane 171 - deterministic tests are required for new behavior and edge cases 172 - do not rely on wall-clock time, random order, external network access, or ambient machine state in unit tests 173 174 Release discipline: 175 176 - create annotated release tags that match the root release policy at `foundation/contracts/release_runtime/mounted_rust_crates/publish-policy.toml` in the owning monorepo 177 - keep repo-owned release commands runnable without depending on GitHub-specific workflow files 178 - when documenting release flow here, document the local repo contract rather than forge-specific orchestration 179 180 ## 8. Commit and handoff guidance 181 182 Commit messages in this repo are part of the public open-source surface. 183 184 That means: 185 186 - use `<scope>: <imperative summary>` 187 - keep the scope lowercase and meaningful 188 - keep the summary standalone and readable outside monorepo context 189 - do not reference internal repository paths, internal migration rationale, or private coordination context 190 - when using a body, leave a blank line after the summary and use `- ` bullets 191 192 Handoffs should state: 193 194 - what changed 195 - what validations ran 196 - any assumptions made 197 - any follow-up risks or missing work 198 199 ## 9. Beads and Agent Mail 200 201 If Beads is active for the task: 202 203 - use `.beads/PRIME.md` as the Beads-specific operator layer 204 - keep live execution state in Beads rather than markdown task lists 205 - do not use `bd edit` 206 - use Beads for durable multi-commit work, not as a replacement for contract docs or repo docs 207 208 If Agent Mail is active for the task: 209 210 - use `.beads/PRIME.md` for the repository coordination conventions 211 - use the active Beads issue id as the Agent Mail thread id and reservation reason when both tools are active 212 - reserve files before the first write for coordinated multi-agent work 213 - use shared build slots for long-running singleton lanes such as contract or release-preflight runs 214 215 If Beads or Agent Mail is not active, the repo still follows the same coding and validation standards; only the task-state and coordination backend changes.