AGENTS.md (7379B)
1 # Radroots SDK agent specification 2 3 This file applies to the complete standalone SDK repository. Read 4 `CONTRIBUTING.md` before editing. A closer `AGENTS.md` overrides this file for 5 its subtree. 6 7 ## Current authority 8 9 - This capsule is an independently verifiable public generated-package and 10 source-lock consumer. Its Rust workspace contains only the unpublished 11 `radroots_sdk_source_lock` package; canonical Rust SDK implementation and 12 generators remain in the exact public `radrootslabs/lib` revision selected 13 by `radroots.lib.source-lock.v1.toml` and `Cargo.toml`. 14 - `radroots.lib.source-lock.v1.toml` is the exact lib source-lock authority. 15 `contracts/provenance/**`, `contracts/packages/**`, and 16 `contracts/exports/**` own generated artifact provenance and package/export 17 selection. 18 - `contracts/historical_authority.v1.json` owns the closed Release V1 machine 19 artifact inventory and its exact digests. Historical API baselines live at 20 `contracts/api_baselines/**`; other retained machine history lives below 21 `contracts/architecture/**` and `contracts/crates/release_v1/**`. 22 - Human specifications, decisions, migration history, and qualification 23 evidence are parent-owned under `docs/oss/sdk/**`. They are not present in a 24 standalone clone and must never become a build, test, generation, package, 25 or release input for this capsule. 26 - Current source, generated output, tests, and lockfiles are implementation 27 evidence. They do not silently override the selected source revision or 28 checked-in contracts. 29 30 ## Repository boundary 31 32 - Keep the repository standalone, forge agnostic, and open-source-readable. 33 Do not depend on a non-public parent path, non-public contract, local sibling 34 checkout, unpublished local artifact, or internal coordination context. 35 - Production source selection must use the exact remotely reachable public Git 36 revision recorded by both source-lock surfaces. Floating branches, tags, 37 local paths, and mismatched revisions are forbidden. 38 - The `.radroots-consumer-root` marker must remain exactly `sdk` followed by 39 LF. Source resolution must remain absolute, canonical, non-symlinked, and 40 explicitly supplied through `RADROOTS_LIB_SOURCE_ROOT`. 41 - `docs/**`, `.github/**`, and `.act/**` are forbidden tracked roots. Public 42 validation commands live in this repository; private cross-repository 43 orchestration belongs only to the parent repository's root `.act/**`. 44 - Do not make this repository responsible for private applications, 45 deployment policy, service runtime ownership, or compatibility packages. 46 47 ## Generated artifacts and packages 48 49 - `tools/radroots_sdk_artifact.mjs` is the governed generation/check adapter. 50 It delegates generation and source-lock verification to the selected public 51 lib checkout through lib's `cargo xtask` surface. 52 - Generated artifacts are reproducible outputs of checked-in source locks, 53 package/export contracts, and producer generators. Do not hand-edit 54 `generated/**`, generated files under `packages/**`, provenance JSON, or 55 package source-lock output. 56 - Update generators and canonical contracts first, regenerate, inspect the 57 complete diff, and run freshness checks. Generated output never dictates a 58 native source model or creates a second source authority. 59 - Keep package manifests, the pnpm lockfile, provenance, exports, generated 60 source, producer-revision-bound package licenses, and consumer-facing package 61 READMEs synchronized. Repository-root license files remain repository-owned 62 and are not a substitute for the selected producer's generated-package 63 license bytes. 64 - Do not reintroduce retired prototype evidence, outcomes, receipts, event 65 models, runtime contracts, or compatibility aliases. Services-hardening 66 generated changes must expose the approved four coverage states and three 67 outcomes together across every applicable language/package surface. 68 69 ## Working and verification rules 70 71 - Inspect `git status --short`, relevant contracts, package manifests, tools, 72 generated outputs, and tests before editing. Preserve unrelated work. 73 - Run `cargo extbuild doctor` before the first mutating build, test, check, 74 dependency, package, or generation command, then route it through 75 `cargo extbuild run -- ...`. 76 - `pnpm run contracts:check` validates the exact historical inventory and the 77 absence of forbidden public roots without requiring a lib checkout. 78 - `pnpm run boundaries:check` validates the historical API baselines, exact 79 generated-source inventory, forbidden surfaces, and credential exclusions 80 without requiring a lib checkout. 81 - `pnpm run supply-chain:check` validates the exact pnpm toolchain and lock, 82 immutable public Lib source lock, package repository identities, workspace- 83 only internal edges, and byte-identical package license artifacts. 84 - `pnpm run test:tools` runs standalone tool and boundary tests. 85 - `pnpm run source:check` and generation/freshness commands require an exact 86 `RADROOTS_LIB_SOURCE_ROOT` matching the checked-in lock. `pnpm run check` is 87 the full non-mutating generated-package lane; use `pnpm run generate` 88 explicitly when intentionally refreshing outputs. 89 - This repository has no local `cargo xtask` package. Do not document or invoke 90 nonexistent SDK-local xtask commands; the artifact adapter invokes the 91 selected producer's governed xtask explicitly. 92 - Use the narrowest check that proves a change while iterating, followed by the 93 complete affected standalone lane. Never claim a check passed unless it ran 94 successfully. 95 - Prefer explicit typed models, deterministic behavior, bounded inputs, narrow 96 side effects, and fail-closed validation. Avoid hidden production panics and 97 `unsafe`; if `unsafe` becomes unavoidable, document and test its invariants. 98 - Never expose secrets, credentials, tokens, private identifiers, sensitive 99 user data, or sensitive event content in source, logs, fixtures, generated 100 output, examples, or errors. 101 102 ## Changes, commits, and external gates 103 104 - Make one coherent, reviewable target-state change at a time. Do not mix 105 unrelated cleanup, speculative abstraction, compatibility scaffolding, or 106 roadmap work. 107 - Use commit subjects in the form `<scope>: <lower-case imperative summary>`. 108 - A machine-contract change must update its validator and negative tests in the 109 same checkpoint. A generated contract change must update all affected 110 outputs and consumer qualification evidence in its owning sequence. 111 - Repository evidence that invalidates an active parent specification is a 112 review finding to record in parent-owned authority; do not create a local 113 human deviation ledger or silently redefine behavior. 114 - Do not push, tag, publish packages, mutate registry ownership, change trusted 115 publishers, deploy, or perform credential operations without the separate 116 authority required for that external action. 117 118 ## Definition of done 119 120 - The change is complete at the source-lock, contract, generator, or package 121 boundary that owns it. 122 - Contracts, tools, tests, package metadata, generated outputs, and lockfiles 123 agree, with zero tracked `docs/**`, `.github/**`, or `.act/**` paths. 124 - Relevant standalone validation passed, exact failures are reported, the diff 125 contains no private dependency or unrelated change, and the next sequence 126 step is explicitly safe or blocked by a real external gate.