AGENTS.md (29027B)
1 # Radroots Core Libraries - Agent Specification 2 3 See [CONTRIBUTING.md](CONTRIBUTING.md) for the contributor workflow and 4 [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for extended execution detail. 5 6 This file exists for compatibility with tools that look for AGENTS.md. 7 8 ## 1. Scope and hierarchy 9 10 - This file applies to the full repository. 11 - Keep this file concise and durable. 12 - Put detailed procedures, examples, and extended guidance in `AGENT_INSTRUCTIONS.md`. 13 - If a closer directory-level `AGENTS.md` is added later, it overrides this file for that subtree. 14 15 ## 2. Source of intent 16 17 - Read `contracts/crates/release.v2.toml`, 18 `contracts/crates/release_v1/radroots_crates_release_v1.toml`, and 19 `contracts/crates/catalog.v2.toml` before changing a public package, package 20 identity, dependency, feature, or release control. 21 - Machine contracts under `contracts/**` are the standalone authority. Human 22 specifications, decisions, runbooks, and qualification evidence belong 23 under the parent monorepo's `docs/oss/lib/**` authority and must never become 24 a standalone build, test, package, or release input. 25 - The approved shared SDK target is 26 `contracts/architecture/decisions/shared_sdk_refactor.v1.json`. 27 Lib owns shared domain, execution, persistence, signing, transport and recovery; 28 `radroots` is the ordinary facade. The SDK repository consumes source-owned 29 generators and artifacts. Its target graph, roles, limits and host matrix are 30 prospective requirements, not current implementation or qualification claims. 31 Preserve the exact source and proving inputs at each migration checkpoint. 32 - The pre-implementation service-event reservation is 33 `contracts/architecture/decisions/services_hardening_events.v1.json`. 34 Service-event source, registry, generated, and consumer work must implement 35 that exact kind, tag, cardinality, query, and supersession contract; it may 36 not reinterpret the reservation from current prototype wire behavior. 37 - The pre-implementation local-admin, process-exit, doctor, readiness, 38 peer-credential, systemd, and bare-Rust host decisions are reserved by 39 `contracts/architecture/decisions/services_hardening_host.v1.json`. 40 Service-host and service-owned operator contracts must implement or narrow 41 that boundary without adding a second transport, exit map, or readiness 42 authority. 43 - Source-lock consumer identities include `sdk`, `myc`, and `rhi`. 44 Only `sdk` is a generated-artifact product identity; 45 accepting a service consumer marker must not expose an artifact route. 46 Tera owns its application packages and native/WASM artifact routes. Lib must 47 not regain an application package or a dependency on the Tera application. 48 - The current service source lock is the bounded, canonical 49 `radroots.service.source_lock.v4.toml`, defined by 50 `contracts/architecture/decisions/services_hardening_source_lock.v4.json`. 51 It binds exact public Lib source, catalog, Cargo/Nix lock and service artifact 52 inputs to Rust `1.99.0`, the `service-host` profile and positive contract 53 versions. Bound Nix inputs must match the active Lib revision and do not 54 establish executed qualification. Preserve V1-V3 contracts and bootstrap 55 evidence as history. Reject noncanonical/extra fields and coexisting 56 predecessor locks; keep the codec and diagnostics private to repo tooling. 57 - Generate or verify the current lock with `cargo xtask service-source-lock 58 --mode write|check --service-root <absolute-directory> --source-archive 59 <absolute-bundle>`. The verified bundle transports the exact public revision; 60 the lock binds its canonical exact-tree archive, never its Git history. 61 Every Lib dependency, Cargo/Nix input and public remote must agree. The 62 service-owned V4 artifact contract must be committed in that service revision. 63 Ordinary write/check rejects every source-tree change except the exact 64 generated lock path. For an atomic migration before a green commit, use 65 `--mode prepare`: stage the complete intended candidate first. Preparation 66 requires no other unstaged/untracked inputs, a resolved stable index and 67 HEAD, and exact index/live artifact-contract bytes. It grants no acceptance; 68 verify and commit the complete candidate, then run clean-source check. 69 - Current unsigned artifact preparation is governed by 70 `contracts/architecture/decisions/services_hardening_release_artifacts.v5.json`. 71 Bound source and generated outputs require separate executed platform and 72 release evidence; this command never activates a candidate. 73 - Generate or verify one immutable service release artifact set with `cargo 74 xtask service-release-artifacts --mode write|check --service-root 75 <absolute-directory> --lib-root <absolute-directory> --input-root 76 <absolute-directory> --output-root <absolute-directory> --target <rust-target> 77 --source-date-epoch <seconds> --candidate-digest <sha256>`. 78 The command consumes the exact fixed input inventory, validates clean and 79 stable service and Lib source bundles, and emits the canonical binary 80 archive, OCI/source metadata, CycloneDX SBOM, notices, manifest, unsigned 81 provenance signing input, and checksums. Signing credentials and signatures 82 remain external; generated artifacts must contain no protected material. 83 - Current SDK compiler-preparation requirements are governed by 84 `contracts/architecture/decisions/shared_sdk_compiler_preparation.v1.json`. 85 Existing contract and preflight commands validate exact current inputs; 86 declaration validation supplies no execution or release qualification. 87 - Historical shared-build qualification contracts V2 and V3 remain under 88 `contracts/architecture/decisions/services_hardening_build_qualification.*.json`. 89 Their fixed targets, fixtures and evidence do not qualify current compiler 90 changes. Current native checks use the approved shared SDK compiler target; 91 successor qualification and actual platform execution remain required. 92 Preserve the historical Nix output deferrals without claiming execution. 93 - Current source and tests are implementation evidence. They do not silently 94 override machine contracts. Release V2 preserves Release V1 as historical 95 authority; the approved shared SDK decision governs the successor target. 96 - Record any evidence-based plan deviation in 97 `contracts/architecture/deviations.toml` before proceeding. Validate it with 98 `cargo xtask architecture`; a normative architecture exception also requires 99 the applicable machine decision under `contracts/architecture/decisions/**`. 100 Deviation anchors must resolve the Release V1 TOML through a validated 101 selector: `repositories.<name>`, `repository_policy`, `release_policy`, 102 `quality_policy.coverage`, or `package.<name>`. 103 104 ## 3. Repository operating model 105 106 - This is a public open-source library workspace; optimize for durable library design, portability, determinism, and explicit contracts. 107 - Keep release and validation automation forge-agnostic; repo-owned xtask 108 commands, native Cargo lanes, tags, and contract metadata are canonical, 109 while committed provider-specific workflow automation is not. Checked-in 110 Nix surfaces are deferred compatibility inputs, not current qualification 111 authority. 112 - Do not add or retain tracked `docs/**`, `.github/**`, or `.act/**` content. 113 Keep validation forge-agnostic. Any required monorepo orchestration belongs 114 exclusively to the parent repository's root `.act/**` authority and must not 115 be copied into this standalone capsule. 116 - Prefer clean target-state changes over compatibility scaffolding unless compatibility is explicitly required. 117 - Stay within the requested scope and the smallest coherent file set. 118 - Do not fold unrelated cleanup, speculative refactors, or roadmap work into the same change. 119 - Do not create hidden task trackers in markdown checklists, source comments, or stray notes. 120 - Keep commits and handoff language standalone and open-source-readable; do 121 not reference non-public repository paths, internal mapping rationale, or 122 private repository context. 123 124 ## 4. Preflight before edits 125 126 Before editing code: 127 128 - Read this file, `AGENT_INSTRUCTIONS.md`, and `README.md`. 129 - When preserving deferred Nix behavior, read `flake.nix` and the relevant 130 implementation files under `build/nix/`, but do not install, invoke, or 131 require Nix as part of current qualification. 132 - Run `cargo extbuild doctor` before the first governed build, test, check, 133 generation, package, artifact, or release-preflight command, then route the 134 command through `cargo extbuild run --`. 135 - Discover commands from checked-in repo surfaces; do not invent ad hoc workflows. 136 - Read the current implementation and nearby tests before designing a change. 137 - Inspect `git status --short` before broad edits or refactors. 138 - Fail early when the task is blocked by missing prerequisites, contaminated scope, or unresolved public contract questions. 139 140 ## 5. Canonical command surface 141 142 - `cargo extbuild run -- cargo check --workspace --all-targets --locked` 143 - `cargo extbuild run -- cargo test --workspace --all-targets --locked` 144 - `cargo extbuild run -- cargo xtask contract validate` 145 - `cargo extbuild run -- cargo xtask release preflight` 146 - `cargo extbuild run -- cargo xtask architecture` for controlled deviation records and local spec 147 anchors 148 - Public API baselines live in `contracts/api_baselines/**`. Regenerate one 149 with `cargo-public-api` `0.52.0` and rustdoc JSON from 150 `nightly-2026-07-16`, writing the reviewed output back to that directory. 151 - targeted `cargo check -p <crate>` and `cargo test -p <crate>` through 152 `cargo extbuild run --` 153 - `cargo xtask dto-roots --write` after changing configured DTO exports and 154 `cargo xtask dto-roots --check` for exact generated-root freshness 155 - targeted `cargo xtask contract ...`, `cargo xtask coverage ...`, `cargo xtask release ...`, or `cargo xtask hygiene ...` only when narrowing a repo-owned workflow 156 - `cargo xtask hygiene prototype-contracts` for the governed report-only 157 service-prototype census; use `--strict` only when the cleanup sequence has 158 made every non-allowlisted finding release-blocking 159 - if Beads is active, read `.beads/PRIME.md` 160 161 ## 6. Rust engineering rules 162 163 - Use exact stable Rust and MSRV `1.99.0`, edition `2024`, and resolver `3` as 164 the approved successor target. Update active selectors, compiler acquisition, 165 validators, generators and qualification together; the existing workspace 166 metadata has not been declared migrated by adopting the target decision. 167 Frozen receipts and dedicated nightly/SP1 toolchains retain their identities. 168 - Preserve intended `no_std` portability; gate `std`, wasm, and runtime-specific behavior explicitly. 169 - Keep core logic functional and composable: prefer pure transformations, explicit state, and narrow side-effect boundaries. 170 - Prefer enums, newtypes, and typed domain models over stringly APIs, boolean mode switches, or loosely typed maps. 171 - Avoid hidden panics in library code; reserve `unwrap` and `expect` for tests, build tooling, or proven internal invariants. 172 - Prefer typed public error surfaces; do not expose opaque convenience errors as stable library contracts. 173 - Avoid `unsafe` unless it is strictly necessary and documented by invariants close to the code. 174 - Borrow first, clone late, and allocate intentionally. 175 - Keep `lib.rs` thin as a module manifest and public re-export surface. 176 - Treat generated bindings and generated type artifacts as generated; do not hand-edit them. 177 - Add or update deterministic tests for new behavior, invariants, parsing, conversions, feature gates, and cross-target behavior where relevant. 178 179 ## 7. Architecture, contract, and release discipline 180 181 - `contracts/` and `tools/xtask` are authoritative for core-library contracts, conformance, coverage, hygiene, and release-candidate governance. 182 - `contracts/crates/catalog.v2.toml` is the package-catalog authority. Preserve 183 imported packages as `provenance_kind = "imported"` with their immutable 184 repository, revision, path, and tree digest. New repository-native packages 185 begin as active private `provenance_kind = "native"` entries; public eligibility 186 requires the approved current release allocation. Native entries always 187 store only `introduction_tree_sha256`; never embed a self-referential 188 introducing commit OID. 189 - Before validating a new native catalog entry, stage the complete package path 190 and run `cargo xtask catalog check` or `cargo xtask catalog write`. The 191 pre-commit digest is derived from stage-zero index records, not the mutable 192 worktree. After the introducing commit, the same command derives the first 193 adding commit from repository history and verifies its immutable tree. Do 194 not rewrite that digest for later source changes. 195 - Behavior changes that affect public surfaces must update the relevant contract metadata, conformance vectors, export rules, or validation flows in the same change. 196 - Preserve deferred flake expressions as unqualified compatibility inputs; 197 do not use their evaluation or outputs as evidence until an accepted 198 contract explicitly reactivates them. 199 - `contracts/crates/release.v2.toml` records the twenty-two current public Lib 200 packages, including `radroots_sdk` and `radroots`. Release V1's earlier 201 repository split remains history. The approved successor replaces old 202 SDK/trade/model boundaries directly and retains ancillary capabilities; 203 target package declarations do not create implemented or published packages. 204 - Public packages have no dependency on private Radroots packages. Every 205 Radroots dependency edge points downward in the approved graph. 206 - Domain and protocol packages do not own storage, live networking, host UI, 207 executors, schedulers, or process-global behavior. 208 - Generic SPIs do not expose concrete SQLx, Tokio, Reqwest, Nostr SDK, 209 keyring, or operating-system implementation types. 210 - Preview, code-generation, fixture, binding-generator, coverage, xtask, and 211 implementation-assembly packages remain private and absent from published 212 feature closures. 213 - Current public eligibility is governed by the catalog and Release V2, 214 including exact `contracts/releases/publish_policy.toml` ownership. Package 215 upload still requires its release gates and explicit authorization; current 216 Release V2 keeps `publication_authorized = false`. Source publication and 217 validation metadata never authorize a package upload. 218 219 ## 8. Service hardening boundaries 220 221 - Service hardening is clean-slate: do not add or preserve prototype 222 configuration readers, environment-file configuration, prototype state 223 importers, JSON/JSONL mutable state, fallback path searches, compatibility 224 aliases, deprecated modules/APIs/re-exports, dual wire encodings, or old/new 225 feature switches. Update affected consumers directly. 226 - `radroots_service_host` owns reusable host mechanics only, and 227 `radroots_service_sqlite` owns reusable SQLite mechanics only. Neither crate 228 may contain Myc or RHI domain configuration, tables, policy, or business 229 rules, and neither may become a broad lifecycle framework. 230 - Each service instance has one live SQLite database. Keep its pool private to 231 the owning store, keep live mutable state daemon-owned, and route live-state 232 mutations from local tools through the typed, permissioned Unix-socket 233 local-admin boundary. 234 - `radroots_service_sqlite::ServiceSqliteHost` is the sole public owner of the 235 private SQLx pool. Service code may execute typed SQLx queries only through 236 the sealed `&mut ServiceSqliteTransaction` executor passed to 237 `ServiceSqliteHost::transaction`; do not expose or reconstruct raw pools, 238 pooled connections, SQLx transactions, commit/rollback handles, or inner 239 accessors. Do not attach or detach secondary SQLite databases through the 240 transaction executor. Writable host construction must finish governed 241 migrations before returning, while read-only inspection must require current 242 migration and schema state. Every host owner must explicitly await 243 `ServiceSqliteHost::close`: close permanently stops admission, drains admitted 244 work, applies the fixed unblocked `TRUNCATE` WAL checkpoint for writable 245 hosts only, closes its private checkpoint connection, and explicitly releases 246 writer or inspection authority. A cancelled close retains authority and must 247 be resumed through the host-owned connect/checkpoint/connection-close driver; 248 Drop is not an asynchronous close or completion proof. Do not add public 249 checkpoint knobs, background close tasks, or Drop-based async cleanup. 250 - `ServiceBackupManifest` is the sole v1 backup-manifest model. Preserve its 251 exact 1,024-byte compact canonical JSON, raw canonical-byte SHA-256, typed 252 service/instance/source-generation/schema/time binding, singleton 253 `state.sqlite` inventory, exact `ok` integrity projection, and mandatory 254 protected-material exclusion. Parsing is structural only and must not perform 255 filesystem or SQLite work. Online capture belongs only to the writable 256 `ServiceSqliteHost`: admit one capture at a time, use SQLite's incremental 257 online-backup API, create a caller-selected new owner-only staging directory, 258 return the manifest in memory, and retain host authority until success or 259 exact-artifact cancellation cleanup completes. Do not expose raw backup 260 handles, capture credentials, invent a manifest filename, read an ambient 261 clock, or fold untrusted verification or restore behavior into capture. 262 - Untrusted backup verification is the synchronous, task-free 263 `verify_backup_bundle` boundary. Require an independently protected manifest 264 digest, exact `ServiceDatabaseIdentity`, and caller-supplied positive member 265 limit; retain the verified directory and member descriptors in the sealed 266 non-cloneable proof. Do not expose paths or raw handles, treat pathname-only 267 verification as restore authority, create an internal task/deadline, mutate 268 the bundle, or introduce restore markers, staging, replacement, or recovery 269 into verification. Later restore work must consume the retained member and 270 reverify its staged copy. 271 - Restore recovery markers are private `radroots_service_sqlite` mechanics. 272 Preserve the fixed sibling names, exact 2,048-byte canonical v1 JSON, 273 domain-separated self-checksum, typed database and backup intent, and the 274 only legal durable sequence `prepared -> live_retained -> 275 replacement_installed`. Marker creation and advancement require retained 276 writer authority, descriptor-relative owner-only files, exact inode 277 revalidation, file and parent synchronization, and create-new scratch plus 278 atomic replacement. Reads never repair or remove evidence. Do not expose 279 marker types or paths, truncate markers in place, accept caller-selected 280 names, or move, copy, open, or delete a database in the marker checkpoint; 281 restore staging, replacement, and open-time recovery remain separate steps. 282 - Offline restore staging consumes a sealed `VerifiedServiceBackup`, acquires 283 exclusive writer authority after every governed host has closed, and creates 284 only the fixed adjacent `state.restore-staged.sqlite` file. It must copy from 285 the retained source descriptor, reverify exact metadata, migration prefix, 286 schema catalog, integrity, foreign keys, length, and digest through retained 287 descriptors, and keep authority plus exact cleanup ownership across caller 288 cancellation. The returned sealed capability owns the staged inode until 289 finalization or an identity-checked drop cleanup attempt; failed cleanup must 290 remain evidence that later admission rejects. Staging must not create a 291 marker, rename live state, retain an old live database, or install a 292 replacement; those are later finalization and recovery boundaries. 293 - Atomic restore finalization consumes only a sealed `StagedServiceRestore`. 294 Staging must bind the exact live inode, length, and digest that finalization 295 will retain. The owned blocking worker creates and synchronizes `prepared` 296 before disarming stage cleanup, then uses descriptor-relative no-replace 297 renames and parent synchronization for live-to-backup and staged-to-live, 298 advancing the marker only after each durable rename. Cancellation observed 299 before the worker atomically claims commit ownership may cleanly stop; 300 caller loss after that handoff is an unknown immediate outcome, including 301 the interval before `prepared` is durable. Once `prepared` is durable, stage 302 cleanup must remain disarmed after every later error so the marker never 303 loses a bound artifact. 304 Successful finalization returns no host and leaves the old live database and 305 `replacement_installed` marker for the next writable open to recover. Other 306 open modes reject that evidence as `Recovery`. Finalization itself must not 307 roll back, delete recovery evidence, reopen SQLite, or expose paths, 308 descriptors, marker controls, or rename controls. 309 - Interrupted restore recovery is private and automatic only for 310 read-write-existing open under exclusive `WriterAuthority`, before any 311 SQLite connection or await point. Initialize, initialized-open, and 312 read-only inspection must reject every fixed stage, backup, marker, or 313 marker-scratch artifact without mutation. Recovery must bind the marker to 314 the requested database identity, hash and revalidate exact owner-only 315 single-link artifacts, reject sidecars, and let exact topology decide the 316 sole action: roll back `prepared` while old live is still installed, then 317 roll forward once old live is durably retained. Persist every inferred phase 318 before the next destructive step; retire exact backup before marker; and 319 admit marker scratch only as a canonical topology-consistent one-edge 320 successor whose exact bound inode is removed and durably reproduced through 321 the governed marker-advance path without overwriting the valid marker. 322 Repeated recovery may 323 finish already-absent stage or backup cleanup, but every other missing, 324 replaced, linked, malformed, mismatched, or ambiguous artifact remains 325 `Recovery` evidence. Do not expose recovery controls, add a background task 326 or hidden timeout, repair without writer authority, or fold Step 070 327 integrity/status APIs and the later process failpoint harness into recovery. 328 - Explicit active integrity inspection belongs only to 329 `ServiceSqliteHost::inspect_integrity`. It admits at most one check per host, 330 uses one governed read snapshot, accepts an injected positive wall-clock 331 timestamp, and returns only the closed SQLite/foreign-key outcomes plus at 332 most two stable diagnostic codes in canonical order. Preserve authority 333 precedence after every await. Do not expose raw SQLite diagnostics, paths, 334 SQL, pool handles, or dependency errors; persist or cache the result; read an 335 ambient clock; create a timer/task; or weaken the strict restore/backup 336 integrity verifier. Callers own the monotonic deadline by cancelling the 337 future. The host-owned integrity driver must retain a cancelled in-flight 338 connection and its explicit close future until the SQLx worker terminates; 339 retry and host close resume that cleanup before proceeding. A retry must 340 inject a new timestamp. 341 - State-filesystem capacity inspection is an explicit, synchronous, 342 host-independent doctor and admission input. Callers must supply a positive 343 `MinimumFreeBytes`; there is no default threshold. The platform adapter 344 measures unprivileged available bytes through a retained owner-owned state 345 directory descriptor that is not group/other writable, and the immutable 346 result classifies exact equality as 347 ready and anything below the policy as low disk. Measurement failure is a 348 typed unavailable result, never fabricated low-disk evidence. Consumers may 349 cache a successful snapshot and project low disk to the stable 350 `database_low_disk` reason, but passive readiness handlers must never invoke 351 the adapter. Keep inspection advisory: do not add a reservation, host/pool or 352 SQLite dependency, ambient timer, background sampler, service default, or 353 status persistence to this crate. 354 - Durability failpoints are private, instance-scoped test mechanics only. Keep 355 a closed before/after inventory across initialization, transaction commit, 356 online backup, restore-marker persistence, restore rename/synchronization, 357 and explicit close. One armed controller may fail one selected edge once; 358 ordinary controllers have zero behavior. Never export failpoint types, use 359 process-global failpoint state, select a point from environment or service 360 configuration, or add a Cargo feature that alters production behavior. 361 Process-level crash and signal qualification must remain in private Cargo 362 test binaries. Pass only one bounded temporary root over stdin, require a 363 fixed stdout token from an occurrence-aware failpoint barrier before 364 `SIGKILL`, and retain a parent kill-on-drop watchdog. Cover writer-lock death 365 and the exact pre-marker, prepared, marker-scratch, installed-replacement, 366 and terminal-marker restore topologies under a permissive child umask. 367 Require Linux x86_64 execution for OS-level qualification; macOS aarch64 on 368 the current machine is developer evidence only. No other platform or 369 architecture is an active qualification gate. Do not ship a helper binary, 370 add production signal/process behavior, poll filesystem state for crash 371 timing, or claim abrupt power-loss durability from process-death tests. 372 - Runtime-management flows consume a sealed `RuntimeContext` for every service 373 instance. They must not reconstruct service paths from raw identifiers, 374 ambient selectors, or manager-owned roots, and registries must not persist 375 duplicate config, state, logs, run, secrets, or binary paths. Manager-owned 376 install and process-tracking artifacts remain separate; uninstall and 377 cleanup must never recursively delete canonical service state or secrets. 378 The manager has no credential read/write authority, executable artifact 379 names are validated single path components, and ordinary manager errors and 380 `Debug` output must not expose filesystem paths, file contents, or raw 381 dependency-owned causes. 382 - Runtime-path consumers must use the sole typed 383 `services/<service>/<instance>` model through `RuntimeContext`. The generic 384 app/service/worker/shared namespace, public raw root containers, path 385 overrides, ambient process-environment selectors, bootstrap helpers, and 386 duplicate service-instance path constructors are removed breaking surfaces; 387 do not restore them or add compatibility aliases. 388 - Runtime-distribution and runtime-management service metadata is the sealed 389 exact Myc/RHI v1 inventory. Both services support multiple validated 390 instances, one TOML config, explicit initialization with existing-only run, 391 detailed HTTP/1.1-over-Unix local administration, cached 392 `/livez`/`readyz`/`metrics`, and only Linux x86_64/aarch64 Tier-1 eligibility 393 in `target` posture. This metadata does not authorize service registration, 394 PID/config/log probing, lifecycle actions, artifact names, channels, archive 395 resolution, or a `qualified` support claim. 396 - Library code must not initialize a tracing subscriber, parse a process CLI, 397 read service configuration from environment variables, install signal 398 handlers, create a Tokio runtime, call `process::exit`, or spawn arbitrary 399 signer executables. 400 - Inject time, entropy, transport, providers, and failpoints. Bound queues, 401 pools, retries, requests, responses, and collections; redact sensitive data 402 from logs, status, metrics, fixtures, errors, and ordinary `Debug` output. 403 - Preserve public Nostr interoperability while removing Radroots-owned 404 prototype behavior; clean-slate rules never authorize protocol drift. 405 406 ## 9. Irreversible actions 407 408 Do not publish crates, create release tags, change crates.io ownership, merge 409 or rename repositories, merge pull requests, rotate credentials, or mutate 410 trusted-publisher configuration without explicit authorization. 411 412 ## 10. Commit and deviation directives 413 414 - Format commits as `<scope>: <imperative summary>`. 415 - Use lowercase scopes that match the crate or subsystem being changed. 416 - Leave a blank line after the summary when writing a multi-line commit. 417 - Use `- ` bullets for notable changes, validations, or compatibility notes when a body is needed. 418 - Split unrelated changes into separate commits. 419 - If repository evidence proves a planned step obsolete or unsafe, record the 420 evidence, affected specification anchor, disposition, and validation in 421 `contracts/architecture/deviations.toml`. A normative architecture change 422 also requires an approved machine decision under 423 `contracts/architecture/decisions/**`. Never silently skip or reorder work. 424 425 ## 11. Definition of done 426 427 - The requested change is implemented. 428 - Affected code, tests, docs, and contract surfaces are updated together. 429 - Relevant canonical validation ran, or a concrete blocker is reported. 430 - The handoff states what changed, what validations ran, and any follow-up risks or assumptions.