Home / Projects / Orchestrata Ultimate / Decisions / ADR index / ADR-0069

ADR-0069: Every spec's Definition of Done includes @traces annotations, RTM regeneration, documentation, wiki update and ≥90% coverage

← ADR-0068 · ADR-0070 →

The record

Status: Accepted (ruling, Mohamed, 2026-10-06: "do not forget annotations, rtm, documentation, wiki update and 90% code coverage" then "it should br the definition of done for all specs") · Date: 2026-10-06

Context

Until today the project's written Definition of Done (AGENTS.md § "Definition of Done: ≥90% coverage (Non-Negotiable)") named one criterion: ≥90% line coverage for every source file a change creates or modifies, with real tests. The other four things every packet in practice owes were scattered: @traces annotations live in the RUL-013 / check_spec_authority.py corpus rules and the trace-intel tooling; RTM regeneration (scripts/generate_rtm_evidence.py, scripts/derive_rtm.py) is run when someone remembers; documentation and the knowledge-wiki update are ADR-0046 obligations for decisions but had no stated obligation for feature packets. Measured consequences on 2026-10-06 in SPEC-110 (plans/spec-110-completion-plan.md §0): requirements with working code but no @traces citation (REQ-110-006, REQ-110-011), code citing ids the spec does not define (REQ-110-050, REQ-110-085), a checklist row marked complete for code that does not exist (REQ-110-140), and an observability design that was built in parts and never documented as wired. Each is a packet that was called done without one of the five.

Mohamed issued the rule while packet S1 of SPEC-110 was in flight, first as a reminder for that packet, then as a standing rule for every spec.

Decision (Mohamed, ruling)

For every spec and every packet that implements part of a spec, a packet is DONE only when all five hold, in the same ship as the code:

1. Annotations. Every function, class or test the packet adds or changes carries @traces("REQ-…") citing only ids the spec defines (RUL-013). A requirement whose behaviour exists but is uncited is a traceability defect the packet closes, not a note it leaves.
2. RTM. The evidence-graded requirements traceability matrix is regenerated after the code lands (scripts/generate_rtm_evidence.py, scripts/trace_intel.py untraced-reqs) and the packet's requirement ids move to an implemented-and-tested proof class; the before/after untraced count for the spec is reported.
3. Documentation. The spec's checklists/requirements.md rows are flipped in the same commit as the code, with the test module path; the affected docs/ page and any design document under plans/ whose status the packet changes (DESIGNED → BUILT) are updated.
4. Wiki update. The knowledge-wiki project page that describes the subsystem gains the packet's summary (what changed, where, test module, commit sha), shipped through the wiki's own ship gate. ADR-0046's three homes continue to govern decisions; this clause covers feature packets.
5. Coverage. ≥90% line coverage for every source file the packet creates or modifies, measured with a targeted --cov run, real tests only, residuals quantified and named when a file legitimately cannot reach it (the existing AGENTS.md rule, unchanged).

A builder brief for any spec packet lists the five under DONE WHEN; a reviewer verdict of GO requires evidence for each; a ship record in the packet's plan carries the five as columns.

Alternatives rejected

• Keep coverage as the only written DoD item and rely on reminders for the rest. This is the state that produced the SPEC-110 findings above; a reminder is not a rule.
• Make the five a reviewer checklist only. Puts the cost at the end of the packet, after the builder has moved on; the five belong in the brief so they are built in.
• Waive the wiki item for small packets. The wiki is the cross-project memory other agents and machines read; a packet too small to summarise in four lines is too small to be a packet.

Consequences

• AGENTS.md § Definition of Done is extended from one criterion to five (this ship).
• plans/spec-110-completion-plan.md §2 gains the five as packet DoD; the S1 builder brief was amended in flight with the same five on 2026-10-06.
• Wiki ruling RUL-034 records the rule in the rulings canon with enforcement: none (judgment) until a gate exists; candidate mechanical gates are scripts/trace_intel.py untraced-reqs scoped to the packet's spec (annotations + RTM), scripts/coverage_ratchet.py (coverage), and a ship-time check that the spec checklist and the wiki page changed in the same ship (documentation + wiki). Adding those gates is a follow-up packet, not part of this record.
• Every open packet (SPEC-110 S1–S5, ADR-0067 P4–P7) inherits the five before it can be called shipped.

Provenance

• Mohamed, 2026-10-06, during SPEC-110 packet S1, verbatim: "do not forget annotations, rtm, documentation, wiki update and 90% code coverage".
• Mohamed, 2026-10-06, same session, verbatim: "it should br the definition of done for all specs".
• Prior text: AGENTS.md § "Definition of Done: ≥90% coverage (Non-Negotiable)"; ADR-0046 (three homes for decisions); RUL-013 (spec authority over cited ids); RUL-014 (rulings are binding and need a mechanism or an explicit judgment-only status).
• Recorded the same turn as the ruling; commit shas in the session record.

Related ADRs

• Also mentioned: ADR-0046, ADR-0067

Rulings cited

• RUL-013: RUL-013 — Specs are authoritative — resolve decisions from them, not guesses
• RUL-034: RUL-034 — Every spec packet's Definition of Done is five items
• RUL-014: RUL-014 — A ruling that exists only in prose is incomplete work

Specs cited

• SPEC-110