CMP-2: Architecture Decision Records

[rororowyourboat]

Summary

Decisions affecting canonical fields, role semantics, execution contracts, cross-layer boundaries, and framework-vs-DSL responsibility should be captured as lightweight Architecture Decision Records (ADRs) so future contributors understand why things are the way they are.

Several such decisions have already been made and documented as design pages (controller-plant-duality, temporal-agnosticism, execution-semantics, disturbance-formalization, check-specifications). This item is about adopting the convention going forward, not retroactively converting existing docs.

Proposed structure

docs/decisions/
  0001-controlaction-as-output-map.md      (retroactive, from T0-3)
  0002-temporal-agnosticism-invariant.md   (retroactive, from T0-4)
  0003-execution-contract-design.md        (retroactive, from T1-1)
  ...
  NNNN-title.md

Each ADR follows a minimal template:

• Status: proposed / accepted / superseded
• Context: what problem or question arose
• Decision: what was decided and why
• Consequences: what follows from this decision (tradeoffs, migration impact)

Scope

Capture ADRs for decisions affecting:

• Canonical fields (CanonicalGDS schema changes)
• Role semantics (BoundaryAction, Policy, Mechanism, ControlAction constraints)
• Execution contracts (time domain, synchrony, ordering)
• Cross-layer boundaries (framework vs DSL vs simulation responsibility)
• Verification check additions or semantic changes

Routine code changes (bug fixes, refactors, new examples) do not need ADRs.

Acceptance criteria

• docs/decisions/ directory exists with ADR template
• At least 1-2 retroactive ADRs written for the most impactful past decisions
• Convention documented in CONTRIBUTING.md or the ADR template itself

Source

Cross-cutting mitigation program CMP-2 from improvement-plans/gds_core_risk_register_and_doctrines.md. Mitigates risks RA-9 (underformalization) and RA-15 (contributor mental model divergence).