Orchestrata Ultimate › Gates › architecture

Gate: architecture

At a glance


Purpose	Refuse an import that breaks the 6-layer model (a lower layer importing a higher one, a Layer-3 service importing a concrete peer).
Where it runs	The `scripts/gates.py` battery (registered as `architecture`); `scripts/health_check.py`; CI's `architecture-check` job (`uv run --no-project python scripts/architecture_checker.py src/ --strict`, `.gitlab-ci.yml`).
Trigger	A battery run, a health check, a CI pipeline.
Exact command	`python scripts/architecture_checker.py` (battery argv: `[sys.executable, "scripts/architecture_checker.py"]`, input root `src`).
Blocks	Exit 1 on any violation, 0 clean.
Ruling / ADR	RUL-008 declares `gate scripts/architecture_checker.py check_di_instantiation` as one of its mechanisms. The edge-level ratchet beside it is ADR-0056.
Last recorded verdict	`ok: true` in the primary checkout's `.cache/gates.json` (file last written 2026-09-22 10:01 local). `wt-MAP-PRECOMMIT` has no `.cache/gates.json`.

What it refuses

An import that breaks the layer model — a lower layer importing a higher one, or a Layer-3 domain service importing a concrete peer service instead of a protocol.

Why it exists

The module docstring is a single line: "Architecture checker — validates import rules, module boundaries, and layering constraints." No motivating incident is recorded in the source — origin not recorded in the source beyond the layer doc it enforces. The in-file comments do record the authority chain:

"Based on architecture-standards.md (the authoritative layer doc — this LAYER_ASSIGNMENTS table is the enforcement source; architecture-standards.md mirrors it for humans and MUST be kept in sync when this table changes)."

The layer model it enforces:

Layer	Name	Members (examples from `LAYER_ASSIGNMENTS`)
0	Vocabulary ("no orchestrata imports")	`core.domain`, `core.protocols`, `core.enums`, `core.interfaces`, `core.base`, `types`, `models`, `interfaces`, `exceptions`
1	Infrastructure	`core.config`, `core.logging`, `core.tracing`, `core.monitoring`, `core.patterns`, `core.state`, `core.threading`, `core.adapters`, `core.redis_factory`, `core.graph_factory`, `di`, …
2	Communication	`cxp`, `postman`, `memory`
3	Domain Services ("no concrete peer imports")	`agents`, `governance`, `knowledge_graph`, `providers`, `verification`, `llm`, `drivers`, …
4	Orchestration	(kernel/orchestrator tier)
5	Interface	(gateway/CLI tier)

How it runs

Command: python scripts/architecture_checker.py (default root src/orchestrata_ultimate, overridable via --path).
When it fires: the scripts/gates.py battery (registered as architecture); scripts/health_check.py; and CI is required to carry it — validate-ci's Gate 7 asserts "Architecture checker or mypy present" in the pipeline.
Inputs: fingerprint root ("src",).
Caching: the verdict is cached in .cache/gates.json against _fingerprint(("src",)): a sha256 over the relative path and bytes of every file under src/ whose suffix is .py, .toml, .pl, .json, .md or .sh (_interesting() in scripts/gates.py, read through the AST toolkit on 2026-10-23). There is no per-gate suffix mask: this page previously quoted a GATE_MASKS comment, and git log --all -S GATE_MASKS -- scripts/gates.py finds no commit that ever contained one.

Typical failures and how to fix them

Exit codes: main() returns 1 on any violation, 0 clean (verified from its return sites).
What a failure looks like (representative): one line per illegal import edge, naming the importing module, its layer, the imported module, and the violated constraint.
Un-blocking: move the import behind a protocol (Layer-3 peers), push the dependency down a layer, or — if the layer table itself is wrong — change LAYER_ASSIGNMENTS and architecture-standards.md together (the comment makes the pairing mandatory).
A TYPE_CHECKING-only or function-scoped edge. This gate checks top-level imports. Every edge including TYPE_CHECKING and function-scoped imports, plus Tarjan cycles, is the job of scripts/architecture_static_check.py against its pinned baseline (ADR-0056; CI's architecture-ratchet job runs it with --baseline scripts/architecture_static_baseline.json). A new edge there fails the ratchet even when this gate passes.

Wiring

Invokers: scripts/gates.py (battery), scripts/health_check.py, CI's architecture-check job (--strict), which also satisfies validate-ci Gate 7.
Tests: tests/scripts/test_architecture_checker.py.

Gates master index
Development workflow
ci-pipeline — the architecture-check and architecture-ratchet jobs
RUL-008 — Review before every commit
ADR-0056 — static ratchet with a pinned baseline
prolog-gate — the Key-Rule layer that replaced the old per-file standards walk
check-deps — the other structural import gate (declared-dependency direction)