commit 5fb6c08684f622df27739d908c0a69cdd25f2612
parent 435829183fa77d338b1cbdcaa54e7a439198ad04
Author: triesap <tyson@radroots.org>
Date: Mon, 27 Jul 2026 07:10:29 +0000
docs: add repository agent instructions
- Anchor public crate work to the release-v1 specification.
- Record the lib package ownership and architecture constraints.
- Add the contributor workflow and deviation process.
- Guard publication and other irreversible repository actions.
Diffstat:
3 files changed, 122 insertions(+), 11 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,6 +1,7 @@
# Radroots Core Libraries - Agent Specification
-See [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for full instructions.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the contributor workflow and
+[AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for extended execution detail.
This file exists for compatibility with tools that look for AGENTS.md.
@@ -11,7 +12,20 @@ This file exists for compatibility with tools that look for AGENTS.md.
- Put detailed procedures, examples, and extended guidance in `AGENT_INSTRUCTIONS.md`.
- If a closer directory-level `AGENTS.md` is added later, it overrides this file for that subtree.
-## 2. Repository operating model
+## 2. Source of intent
+
+- Read `docs/specs/README.md` and
+ `docs/specs/radroots_crates_release_v1.md` before changing a public package,
+ package identity, dependency, feature, or release control.
+- The Markdown specification is normative. Its TOML catalog is the executable
+ package and dependency representation; the CSV and DOT files are review
+ aids.
+- Current source and tests are implementation evidence. They do not silently
+ override `radroots.crates.release.v1`.
+- Record any evidence-based plan deviation in
+ `docs/implementation/DEVIATIONS.md` before proceeding.
+
+## 3. Repository operating model
- This is a public open-source library workspace; optimize for durable library design, portability, determinism, and explicit contracts.
- Keep release and validation automation forge-agnostic; repo-owned xtask commands, Nix apps, tags, and contract metadata are canonical, while committed provider-specific workflow automation is not.
@@ -19,9 +33,11 @@ This file exists for compatibility with tools that look for AGENTS.md.
- Stay within the requested scope and the smallest coherent file set.
- Do not fold unrelated cleanup, speculative refactors, or roadmap work into the same change.
- Do not create hidden task trackers in markdown checklists, source comments, or stray notes.
-- Keep commits and handoff language standalone and open-source-readable; do not reference internal monorepo paths, internal mapping rationale, or private repository context.
+- Keep commits and handoff language standalone and open-source-readable; do
+ not reference non-public repository paths, internal mapping rationale, or
+ private repository context.
-## 3. Preflight before edits
+## 4. Preflight before edits
Before editing code:
@@ -33,7 +49,7 @@ Before editing code:
- Inspect `git status --short` before broad edits or refactors.
- Fail early when the task is blocked by missing prerequisites, contaminated scope, or unresolved public contract questions.
-## 4. Canonical command surface
+## 5. Canonical command surface
- `nix flake check`
- `nix run .#contract`
@@ -44,9 +60,10 @@ Before editing code:
- targeted `cargo xtask contract ...`, `cargo xtask coverage ...`, `cargo xtask release ...`, or `cargo xtask hygiene ...` only when narrowing a repo-owned workflow
- if Beads is active, read `.beads/PRIME.md`
-## 5. Rust engineering rules
+## 6. Rust engineering rules
-- Use Rust `1.97.0`, edition `2024`, and workspace dependency versions from the root `Cargo.toml`.
+- Use Rust `1.97.1`, edition `2024`, resolver `3`, and workspace dependency
+ versions from the root `Cargo.toml` after the release-v1 workspace cutover.
- Preserve intended `no_std` portability; gate `std`, wasm, and runtime-specific behavior explicitly.
- Keep core logic functional and composable: prefer pure transformations, explicit state, and narrow side-effect boundaries.
- Prefer enums, newtypes, and typed domain models over stringly APIs, boolean mode switches, or loosely typed maps.
@@ -58,21 +75,46 @@ Before editing code:
- Treat generated bindings and generated type artifacts as generated; do not hand-edit them.
- Add or update deterministic tests for new behavior, invariants, parsing, conversions, feature gates, and cross-target behavior where relevant.
-## 6. Contract and release discipline
+## 7. Architecture, contract, and release discipline
- `contracts/` and `tools/xtask` are authoritative for core-library contracts, conformance, coverage, hygiene, and release-candidate governance.
- Behavior changes that affect public surfaces must update the relevant contract metadata, conformance vectors, export rules, or validation flows in the same change.
- Keep pure flake checks and repo-aware command apps aligned with the documented Nix command map.
-
-## 7. Commit directives
+- This repository owns packages 1-17 in `radroots.crates.release.v1`, from
+ `radroots-core` through `radroots-geonames`. `radroots-sdk` and `radroots`
+ remain owned by the standalone SDK repository.
+- Public packages have no dependency on private Radroots packages. Every
+ Radroots dependency edge points downward in the approved graph.
+- Domain and protocol packages do not own storage, live networking, host UI,
+ executors, schedulers, or process-global behavior.
+- Generic SPIs do not expose concrete SQLx, Tokio, Reqwest, Nostr SDK,
+ keyring, or operating-system implementation types.
+- Preview, code-generation, fixture, binding-generator, coverage, xtask, and
+ implementation-assembly packages remain private and absent from published
+ feature closures.
+- During the migration, every package remains non-publishable until its
+ package-realistic release gates pass and publication is explicitly
+ authorized.
+
+## 8. Irreversible actions
+
+Do not publish crates, create release tags, change crates.io ownership, merge
+or rename repositories, merge pull requests, rotate credentials, or mutate
+trusted-publisher configuration without explicit authorization.
+
+## 9. Commit and deviation directives
- Format commits as `<scope>: <imperative summary>`.
- Use lowercase scopes that match the crate or subsystem being changed.
- Leave a blank line after the summary when writing a multi-line commit.
- Use `- ` bullets for notable changes, validations, or compatibility notes when a body is needed.
- Split unrelated changes into separate commits.
+- If repository evidence proves a planned step obsolete or unsafe, record the
+ evidence, affected specification anchor, disposition, and validation in
+ `docs/implementation/DEVIATIONS.md`. A normative architecture change also
+ requires an approved decision record. Never silently skip or reorder work.
-## 8. Definition of done
+## 10. Definition of done
- The requested change is implemented.
- Affected code, tests, docs, and contract surfaces are updated together.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,47 @@
+# Contributing
+
+Radroots core-library changes are contract-driven and independently
+reviewable. Before editing, read these files in order:
+
+1. `AGENTS.md`
+2. `docs/specs/README.md`
+3. `docs/specs/radroots_crates_release_v1.md` for crate-surface work
+4. `AGENT_INSTRUCTIONS.md`
+5. the affected manifests, implementation, contracts, and tests
+
+The release-v1 architecture identifier is `radroots.crates.release.v1`. This
+repository owns its first 17 public packages, from `radroots-core` through
+`radroots-geonames`; the standalone SDK repository owns `radroots-sdk` and
+`radroots`.
+
+## Workflow
+
+1. Inspect repository status and the current source authority.
+2. Make one coherent, commit-sized change.
+3. Update public contracts, tests, fixtures, generated authorities, and docs
+ with the implementation they govern.
+4. Run the narrowest repository-owned validation that proves the change, then
+ the broader contract or release lane required by its scope.
+5. Review the staged diff for API leakage, private dependencies, generated
+ drift, secrets, hidden side effects, and unrelated changes.
+
+Canonical repository-wide lanes are `nix flake check`,
+`nix run .#contract`, and `nix run .#release-preflight`. Targeted Rust work is
+performed in the repository's Nix environment with the applicable format,
+check, test, Clippy, contract, coverage, and generated-freshness commands.
+
+## Commits and deviations
+
+Use this commit form:
+
+```text
+<scope>: <lower-case imperative summary>
+```
+
+Keep commits focused and keep public commit language independent of any
+private checkout. Do not publish, tag, merge, or change registry ownership
+without explicit authorization.
+
+When current evidence proves a planned step obsolete or unsafe, follow
+`docs/implementation/DEVIATIONS.md`. Record the evidence and affected spec
+anchor before changing the plan; do not silently redefine the architecture.
diff --git a/docs/implementation/DEVIATIONS.md b/docs/implementation/DEVIATIONS.md
@@ -0,0 +1,22 @@
+# Implementation deviations
+
+This ledger records evidence-based deviations from
+`radroots.crates.release.v1` implementation planning. It does not authorize a
+change to the normative package architecture.
+
+No deviations are currently recorded.
+
+## Required record
+
+Every deviation entry must include:
+
+- a stable identifier and date;
+- the affected plan step and normative specification anchor;
+- current repository evidence proving the planned action obsolete or unsafe;
+- the smallest safe disposition and any temporary compatibility boundary;
+- validation performed and unresolved risk;
+- the approving decision record when normative architecture changes.
+
+Do not silently skip, merge, reorder, or broaden implementation steps. Keep
+the repository at a known-good checkpoint and obtain approval for any
+normative change before proceeding.
