{"row":{"id":"ADR-011","title":"cargo xtask as canonical automation surface","file":"adr-011-cargo-xtask.md","status":"accepted","date":"2026-04-14","cites":4,"supersedes":[],"superseded_by":[],"layers":[],"tags":["tooling","xtask","automation","ci"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-011: `cargo xtask` as canonical automation surface","id":"adr-011-cargo-xtask-as-canonical-automation-surface"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"Diamond currently runs CI ratchets + hygiene checks via ~10 bash scripts under "},{"k":"code","text":"scripts/ci/"},{"k":"text","text":" and supernovae-hq parent runs 10 more under "},{"k":"code","text":"scripts/hygiene/"},{"k":"text","text":". Bash works for 5 admitted crates. It does not scale to 40 — concerns:"}]},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"Portability:"},{"k":"text","text":" macOS bash 3.2 quirks already bit us (associative arrays). Windows users of "},{"k":"code","text":"nika init"},{"k":"text","text":" cannot run these scripts at all."}],[{"k":"strong","text":"Type safety:"},{"k":"text","text":" parsing "},{"k":"code","text":"Cargo.toml"},{"k":"text","text":" via "},{"k":"code","text":"awk"},{"k":"text","text":" + "},{"k":"code","text":"grep"},{"k":"text","text":" is fragile; we've already fixed one regex-injection bug (supernovae-hq allowlist checker)."}],[{"k":"strong","text":"Composability:"},{"k":"text","text":" rust-analyzer, Zed, tokio, rust-lang/rust itself all migrated to "},{"k":"code","text":"cargo xtask"},{"k":"text","text":" pattern (separate workspace crate named "},{"k":"code","text":"xtask"},{"k":"text","text":", unaffiliated with release binaries)."}]]},{"k":"p","inline":[{"k":"text","text":"Web researcher and Nika-SOTA architect both flagged this as the #2 impact-per-effort improvement."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"text","text":"Introduce an "},{"k":"code","text":"xtask/"},{"k":"text","text":" workspace crate (type "},{"k":"code","text":"bin"},{"k":"text","text":") that owns all Diamond automation:"}]},{"k":"list","ordered":false,"items":[[{"k":"code","text":"cargo xtask gate <crate>"},{"k":"text","text":" — run 12 gates against one crate"}],[{"k":"code","text":"cargo xtask hygiene"},{"k":"text","text":" — the 15-vector-adjacent parent hygiene"}],[{"k":"code","text":"cargo xtask loc"},{"k":"text","text":" / "},{"k":"code","text":"xtask crate-size"},{"k":"text","text":" / "},{"k":"code","text":"xtask fn-length"},{"k":"text","text":" — ratchet checks (replacing "},{"k":"code","text":"scripts/ci/check-*.sh"},{"k":"text","text":")"}],[{"k":"code","text":"cargo xtask bench"},{"k":"text","text":" — orchestrate criterion + divan runs"}],[{"k":"code","text":"cargo xtask release <crate> <version>"},{"k":"text","text":" — tag + CHANGELOG sync"}]]},{"k":"p","inline":[{"k":"text","text":"Shell scripts stay as "},{"k":"strong","text":"thin shims"},{"k":"text","text":" calling "},{"k":"code","text":"cargo xtask <subcmd>"},{"k":"text","text":" until fully retired. "},{"k":"code","text":"xtask"},{"k":"text","text":" crate is excluded from the 100-crate cap (industry convention — xtask is not a library crate)."}]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"h","depth":3,"text":"Positive","id":"positive"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Cross-platform (Windows for "},{"k":"code","text":"nika init"},{"k":"text","text":" users)."}],[{"k":"code","text":"cargo_metadata"},{"k":"text","text":" crate for manifest parsing — typed, no regex."}],[{"k":"text","text":"Subcommand composition (can call other xtask subcmds programmatically)."}],[{"k":"text","text":"Unit-testable automation logic (bash is not)."}]]},{"k":"h","depth":3,"text":"Negative","id":"negative"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"New crate adds compile time (cold build ~15s extra one-time)."}],[{"k":"text","text":"Migration is ~2 sessions of focused work for the 20+ scripts."}]]},{"k":"h","depth":3,"text":"Neutral","id":"neutral"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Convention-only exclusion from crate cap. Documented in ADR-004."}]]},{"k":"h","depth":2,"text":"Evidence","id":"evidence"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Pattern source: "},{"k":"link","text":"rust-lang/rust x tool","href":"https://github.com/rust-lang/rust/tree/master/src/tools/x"},{"k":"text","text":", rust-analyzer "},{"k":"code","text":"xtask"},{"k":"text","text":", tokio "},{"k":"code","text":"xtask"},{"k":"text","text":" (upstream examples, not local paths)"}],[{"k":"code","text":"scripts/ci/*.sh"},{"k":"text","text":" — 10 scripts currently"}],[{"k":"code","text":"scripts/hygiene/*.sh"},{"k":"text","text":" (in supernovae-hq parent) — 11 scripts"}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"h","depth":3,"text":"Alt A — Keep bash","id":"alt-a--keep-bash"},{"k":"p","inline":[{"k":"text","text":"Rejected — portability + type safety."}]},{"k":"h","depth":3,"text":"Alt B — Python scripts","id":"alt-b--python-scripts"},{"k":"p","inline":[{"k":"text","text":"Rejected — adds Python runtime to CI. We're a Rust workspace."}]},{"k":"h","depth":3,"text":"Alt C — `just` (justfile)","id":"alt-c--just-justfile"},{"k":"p","inline":[{"k":"text","text":"Considered. Lower friction than xtask but still not-Rust. Loses "},{"k":"code","text":"cargo_metadata"},{"k":"text","text":" access. xtask is idiomatic for our scale."}]},{"k":"h","depth":2,"text":"Related","id":"related"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"ADR-003 — 12-gate admission (xtask "},{"k":"code","text":"gate"},{"k":"text","text":" subcommand hosts the gates)"}],[{"k":"text","text":"ADR-004 — context-window sizing (xtask is the documented exclusion from the 100-crate cap; this ADR formalises the convention ADR-004 references)"}],[{"k":"text","text":"ADR-009 — ADR process ("},{"k":"code","text":"check-adr-coverage.sh"},{"k":"text","text":" → "},{"k":"code","text":"xtask check-adr-coverage"},{"k":"text","text":")"}]]},{"k":"h","depth":2,"text":"Notes","id":"notes"},{"k":"p","inline":[{"k":"text","text":"Migration is non-urgent. Execute before Phase 3 admissions (when verb crates start landing and gate complexity grows). Until then bash shims remain authoritative."}]}]

ADR-011

cargo xtask as canonical automation surface

accepted · 2026-04-14 · cites 4

ADR-011: `cargo xtask` as canonical automation surface #

Context #

Diamond currently runs CI ratchets + hygiene checks via ~10 bash scripts under scripts/ci/ and supernovae-hq parent runs 10 more under scripts/hygiene/. Bash works for 5 admitted crates. It does not scale to 40 — concerns:

Portability: macOS bash 3.2 quirks already bit us (associative arrays). Windows users of nika init cannot run these scripts at all.
Type safety: parsing Cargo.toml via awk + grep is fragile; we've already fixed one regex-injection bug (supernovae-hq allowlist checker).
Composability: rust-analyzer, Zed, tokio, rust-lang/rust itself all migrated to cargo xtask pattern (separate workspace crate named xtask, unaffiliated with release binaries).

Web researcher and Nika-SOTA architect both flagged this as the #2 impact-per-effort improvement.

Decision #

Introduce an xtask/ workspace crate (type bin) that owns all Diamond automation:

cargo xtask gate <crate> — run 12 gates against one crate
cargo xtask hygiene — the 15-vector-adjacent parent hygiene
cargo xtask loc / xtask crate-size / xtask fn-length — ratchet checks (replacing scripts/ci/check-*.sh)
cargo xtask bench — orchestrate criterion + divan runs
cargo xtask release <crate> <version> — tag + CHANGELOG sync

Shell scripts stay as thin shims calling cargo xtask <subcmd> until fully retired. xtask crate is excluded from the 100-crate cap (industry convention — xtask is not a library crate).

Consequences #

Positive #

Cross-platform (Windows for nika init users).
cargo_metadata crate for manifest parsing — typed, no regex.
Subcommand composition (can call other xtask subcmds programmatically).
Unit-testable automation logic (bash is not).

Negative #

New crate adds compile time (cold build ~15s extra one-time).
Migration is ~2 sessions of focused work for the 20+ scripts.

Neutral #

Convention-only exclusion from crate cap. Documented in ADR-004.

Evidence #

Pattern source: rust-lang/rust x tool, rust-analyzer xtask, tokio xtask (upstream examples, not local paths)
scripts/ci/*.sh — 10 scripts currently
scripts/hygiene/*.sh (in supernovae-hq parent) — 11 scripts

Alternatives considered #

Alt A — Keep bash #

Rejected — portability + type safety.

Alt B — Python scripts #

Rejected — adds Python runtime to CI. We're a Rust workspace.

Alt C — `just` (justfile) #

Considered. Lower friction than xtask but still not-Rust. Loses cargo_metadata access. xtask is idiomatic for our scale.

ADR-003 — 12-gate admission (xtask gate subcommand hosts the gates)
ADR-004 — context-window sizing (xtask is the documented exclusion from the 100-crate cap; this ADR formalises the convention ADR-004 references)
ADR-009 — ADR process (check-adr-coverage.sh → xtask check-adr-coverage)

Notes #

Migration is non-urgent. Execute before Phase 3 admissions (when verb crates start landing and gate complexity grows). Until then bash shims remain authoritative.

read at v0.107.0 · the decision record ships with the engine

Every decision, with its status This one in the repo