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

ADR-0056: Two-gate architecture measurement — runtime gate + static ratchet with a pinned baseline

field	value
Status	Accepted — Accepted (executed under Mohamed's direction)
Date	2026-09-21
Register	factory (`docs/adr`, 4-digit ids)
Source	`docs/adr/0056-static-ratchet-baseline.md` — permalink at `8ceb2e5a4` (unchanged on master since that commit)
Wiki register entry	ADR-0056 (wiki status: Accepted)

← ADR-0055 · ADR-0057 →

The record

Date: 2026-09-21 · Status: Accepted (executed under Mohamed's direction)

Context

Two measurements of layer debt disagreed and each was partial: the repo's architecture_checker.py (top-level imports only; reported 0 violations, 68 accepted function-scoped) and the review's static-graph count (141, including TYPE_CHECKING edges, taken on a since-deleted branch). The function-scoped count was informational — nothing stopped it from growing. There was no CI enforcement of the static view at all.

Decision

Runtime gate (existing): architecture_checker.py --strict stays the blocking check for top-level imports. 0 violations is the law.
Static gate (new): scripts/architecture_static_check.py classifies EVERY import edge by scope (top-level / TYPE_CHECKING / function-scoped) against the same LAYER_ASSIGNMENTS, plus a Tarjan SCC cycle count.
The pinned baseline is the authoritative debt ledger: scripts/architecture_static_baseline.json (first pinned 2026-09-21 at merge 4110815a: 100 total = 0 top-level + 32 TYPE_CHECKING + 68 function-scoped; 6 SCCs / 18 modules). It is regenerated whenever work reduces the counts — the ratchet only moves down.
CI: the blocking architecture-ratchet job (lint stage, dependency-free like architecture-check) fails if any count or cycle count exceeds the baseline. Improvements must be baked into the baseline in the same PR.

Consequences

The review's 141/10-cycle figures are superseded by the baseline JSON (different snapshot, deleted branch).
Cross-validation built in: the static function-scoped count equals the runtime checker's accepted count exactly (68 at pinning).
Debt can no longer grow invisibly while the runtime gate stays green — which is exactly how the accepted-lazy-import bucket had been behaving.

No other ADR is named in this record.

Rulings cited

None.

Specs cited

None (or no spec page exists for the ones named).