{"row":{"id":"ADR-026","title":"workspace.toml single source of truth + auto-generated crate.md","file":"adr-026-workspace-toml-ssot.md","status":"accepted","date":"2026-04-16","cites":4,"supersedes":[],"superseded_by":[],"layers":["L0","L0.5","L1","L2","L3","L4","L5"],"tags":["hygiene","ssot","metadata","workspace"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-026: workspace.toml SSOT + auto-generated crate.md","id":"adr-026-workspacetoml-ssot--auto-generated-cratemd"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"Phase A baseline reset (commit cd9602ca0) revealed that workspace metadata is\nscattered across 5+ files:"}]},{"k":"list","ordered":false,"items":[[{"k":"code","text":"Cargo.toml [workspace.metadata.diamond.layers]"},{"k":"text","text":" (per-crate layer)"}],[{"k":"code","text":"docs/architecture/forward-compat-invariants.md"},{"k":"text","text":" (FCI references)"}],[{"k":"code","text":"docs/architecture/crate-layer-registry.md"},{"k":"text","text":" (layer rules)"}],[{"k":"code","text":"scripts/refresh-status.sh"},{"k":"text","text":" (status block generation)"}],[{"k":"text","text":"Per-crate "},{"k":"code","text":"Cargo.toml"},{"k":"text","text":" (LOC budget, gates, owner)"}],[{"k":"text","text":"Per-crate "},{"k":"code","text":"README.md"},{"k":"text","text":" (when present, often missing)"}]]},{"k":"p","inline":[{"k":"text","text":"Each manual edit drifts independently. Phase A added "},{"k":"code","text":"refresh-status.sh"},{"k":"text","text":" as\na partial fix. Need a deeper consolidation."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"h","depth":3,"text":"`docs/workspace.toml` — single source of truth","id":"docsworkspacetoml--single-source-of-truth"},{"k":"p","inline":[{"k":"text","text":"One file declaring per-crate metadata machine-readable:"}]},{"k":"code","lang":"toml","text":"[crates.nika-core]\nlayer = \"L0\"\ntier = 0\nleaf = true\npublish = false\ngates_passed = [\"spec\", \"tdd\", \"impl\", \"clippy\", \"mutation\", \"property\",\n                \"benchmarks\", \"docs\", \"canary\", \"parity\", \"review\", \"atomic\"]\nloc_budget = 5000\nfile_loc_warn = 800\nfile_loc_fail = 1500\npublic_api_baseline = \"docs/api-baselines/nika-core.txt\"\nsibling_deps = []\nowners = [\"diamond-team\"]\n\n[crates.nika-error]\nlayer = \"L0\"\ntier = 1\nleaf = false\npublish = false\ngates_passed = [...]\nsibling_deps = [\"nika-core\"]\n# ..."},{"k":"h","depth":3,"text":"Auto-generated `crates/<name>/README.md`","id":"auto-generated-cratesnamereadmemd"},{"k":"p","inline":[{"k":"text","text":"Hygiene vector reads "},{"k":"code","text":"docs/workspace.toml"},{"k":"text","text":" + "},{"k":"code","text":"Cargo.toml"},{"k":"text","text":" description +\n"},{"k":"code","text":"lib.rs"},{"k":"text","text":" "},{"k":"code","text":"//!"},{"k":"text","text":" docs and emits "},{"k":"code","text":"crates/<name>/README.md"},{"k":"text","text":":"}]},{"k":"code","lang":"markdown","text":"# nika-core\n\n**Layer**: L0 (tier-0 leaf)  •  **Publish**: false  •  **LOC budget**: 5000\n**Owners**: diamond-team\n**Sibling deps**: (none — leaf crate)\n\n## Purpose\n\nFoundation value types — IDs, Cost, Trust, Baggage, Resource, Hash,\nRetryConfig, TokenUsage, etc.\n\n## Gates passed (12/12)\n\n- ✅ spec ✅ TDD ✅ impl ✅ clippy ✅ mutation ✅ property\n- ✅ benchmarks ✅ docs ✅ canary ✅ parity ✅ review ✅ atomic\n\n## API baseline\n\n`docs/api-baselines/nika-core.txt`\n\n## Reference\n\n- Spec: `docs/crate-specs/nika-core.md`\n- Layer registry: `docs/architecture/crate-layer-registry.md`"},{"k":"h","depth":3,"text":"Hygiene vector 33 — workspace.toml ↔ Cargo.toml ↔ README sync","id":"hygiene-vector-33--workspacetoml--cargotoml--readme-sync"},{"k":"p","inline":[{"k":"text","text":"Reads "},{"k":"code","text":"docs/workspace.toml"},{"k":"text","text":", asserts:"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Every workspace member has an entry"}],[{"k":"text","text":"Every "},{"k":"code","text":"Cargo.toml"},{"k":"text","text":" "},{"k":"code","text":"version"},{"k":"text","text":"/"},{"k":"code","text":"publish"},{"k":"text","text":" matches"}],[{"k":"text","text":"Every "},{"k":"code","text":"README.md"},{"k":"text","text":" matches the auto-gen template"}],[{"k":"code","text":"[workspace.metadata.diamond.layers]"},{"k":"text","text":" matches "},{"k":"code","text":"workspace.toml.crates.*.layer"}],[{"k":"code","text":"scripts/refresh-status.sh"},{"k":"text","text":" output matches "},{"k":"code","text":"workspace.toml"},{"k":"text","text":"-derived counts"}]]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"✅ Drift eliminated by mechanical enforcement"}],[{"k":"text","text":"✅ Adding/renaming a crate = ONE edit (workspace.toml), README + status block"},{"k":"text","text":"+ Cargo.toml metadata regenerated"}],[{"k":"text","text":"✅ ADR-027 (cargo timings) reads from same SSOT"}],[{"k":"text","text":"❌ +1 hygiene vector (33), +1 generator script"}],[{"k":"text","text":"❌ Initial migration: write "},{"k":"code","text":"docs/workspace.toml"},{"k":"text","text":" for all 7 admitted + 7\nplanned crates (~2h, mechanical)"}]]},{"k":"h","depth":2,"text":"Reference","id":"reference"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"ADR-022 (foundation crate layout)"}],[{"k":"text","text":"ADR-023 (file modularity — values populated from workspace.toml)"}],[{"k":"text","text":"ADR-027 (cargo timings — budgets from workspace.toml)"}]]}]

ADR-026

workspace.toml single source of truth + auto-generated crate.md

accepted · 2026-04-16 · L0 L0.5 L1 L2 L3 L4 L5 · cites 4

ADR-026: workspace.toml SSOT + auto-generated crate.md #

Context #

Phase A baseline reset (commit cd9602ca0) revealed that workspace metadata is scattered across 5+ files:

Cargo.toml [workspace.metadata.diamond.layers] (per-crate layer)
docs/architecture/forward-compat-invariants.md (FCI references)
docs/architecture/crate-layer-registry.md (layer rules)
scripts/refresh-status.sh (status block generation)
Per-crate Cargo.toml (LOC budget, gates, owner)
Per-crate README.md (when present, often missing)

Each manual edit drifts independently. Phase A added refresh-status.sh as a partial fix. Need a deeper consolidation.

Decision #

`docs/workspace.toml` — single source of truth #

One file declaring per-crate metadata machine-readable:

toml

1[crates.nika-core]2layer = "L0"3tier = 04leaf = true5publish = false6gates_passed = ["spec", "tdd", "impl", "clippy", "mutation", "property",7                "benchmarks", "docs", "canary", "parity", "review", "atomic"]8loc_budget = 50009file_loc_warn = 80010file_loc_fail = 150011public_api_baseline = "docs/api-baselines/nika-core.txt"12sibling_deps = []13owners = ["diamond-team"]1415[crates.nika-error]16layer = "L0"17tier = 118leaf = false19publish = false20gates_passed = [...]21sibling_deps = ["nika-core"]22# ...

Auto-generated `crates/<name>/README.md` #

Hygiene vector reads docs/workspace.toml + Cargo.toml description + lib.rs //! docs and emits crates/<name>/README.md:

markdown

1# nika-core23**Layer**: L0 (tier-0 leaf)  •  **Publish**: false  •  **LOC budget**: 50004**Owners**: diamond-team5**Sibling deps**: (none — leaf crate)67## Purpose89Foundation value types — IDs, Cost, Trust, Baggage, Resource, Hash,10RetryConfig, TokenUsage, etc.1112## Gates passed (12/12)1314- ✅ spec ✅ TDD ✅ impl ✅ clippy ✅ mutation ✅ property15- ✅ benchmarks ✅ docs ✅ canary ✅ parity ✅ review ✅ atomic1617## API baseline1819`docs/api-baselines/nika-core.txt`2021## Reference2223- Spec: `docs/crate-specs/nika-core.md`24- Layer registry: `docs/architecture/crate-layer-registry.md`

Hygiene vector 33 — workspace.toml ↔ Cargo.toml ↔ README sync #

Reads docs/workspace.toml, asserts:

Every workspace member has an entry
Every Cargo.toml version/publish matches
Every README.md matches the auto-gen template
[workspace.metadata.diamond.layers] matches workspace.toml.crates.*.layer
scripts/refresh-status.sh output matches workspace.toml-derived counts

Consequences #

✅ Drift eliminated by mechanical enforcement
✅ Adding/renaming a crate = ONE edit (workspace.toml), README + status block+ Cargo.toml metadata regenerated
✅ ADR-027 (cargo timings) reads from same SSOT
❌ +1 hygiene vector (33), +1 generator script
❌ Initial migration: write docs/workspace.toml for all 7 admitted + 7 planned crates (~2h, mechanical)

Reference #

ADR-022 (foundation crate layout)
ADR-023 (file modularity — values populated from workspace.toml)
ADR-027 (cargo timings — budgets from workspace.toml)

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

Every decision, with its status This one in the repo