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

ADR-0116: Staged source .py files enter the T21 env-key review at commit time

← ADR-0115 · ADR-0117 →

The record

Status: Accepted (ruling, Mohamed, 2026-10-20, verbatim: "Approve as follow-up packet (Recommended)") · Date: 2026-10-20

Context

The T17 packet (rule id T21 in scripts/test-review.py) exists because of a SOURCE-file incident: scripts/run_tests.py::_child_run_env stamped a fabricated env key (ORCH_TEST_DEADLINE while the observer reads TEST_DEADLINE_ENV = "ORCHESTRATA_TEST_DEADLINE") and set no sanctioned-runner stamp at all — the RUL-038 cap mechanism was dead on arrival and nothing mechanical caught it (commit 4a470482c fixed the code; the T17 packet makes the class checkable).

Measured routing (T17 run-1 verification, 2026-10-20): commit_review.pl's reviewer_tree facts send only tests/ and end2end/ files to test_review (src/orchestrata_ultimate/prolog/commit_review.pl:70-72); code_review gets src/; scripts/ reaches neither. The rule therefore never gates, at commit time, the file class that founded it — the RUL-023 built-but-not-wired shape.

Measured blast radius of wiring (2026-10-20): exact-key WARNINGs (which block at pre-commit by the hook's standing policy) would fire on 29 test files that inline declared registry keys (tests/conftest.py, tests/factories/real.py, tests/fixtures/redis.py, and 26 more) and on 6 sites in scripts/run_tests.py (the latter fixed inside the T17 run-2 fence, defect D7).

Decision (Mohamed, verbatim: "Approve as follow-up packet (Recommended)")

1. Staged source .py files enter test-review's T21 env-key review at commit time.
2. The wiring is a follow-up packet, dispatched after the T21 rule lands (run 2 of the T17 packet): extend the commit-gate routing — minimally reviewer_tree(test_review, 'scripts/') in commit_review.pl, with the src/ question measured and ruled inside the packet — and make T21 apply to any .py the gate hands it (the run-2 brief's D2 already binds the tool side).
3. The 29-file exact-key worklist is made visible in the same packet: burn it down (files import their declared constants) or baseline it as an explicit ratchet, so unrelated commits touching those files are not blocked without a plan of record.
4. The warnings-block policy is unchanged — the T17 brief ruled WARNING-and-up blocking at pre-commit intended; this ADR does not create a source-file exception.

Alternatives rejected

• Decline — keep test-review tests-only: the fabricated-key incident happened in a source file; a rule that cannot see the founding file class is decoration.
• Wire immediately without the worklist: 29 test files start blocking pre-commit on their next touch, with no burn-down plan — the gate earns a bypass habit instead of a fix queue.
• Non-blocking warnings for source files: a second severity policy per file class complicates the hook contract; ERROR/WARNING semantics stay uniform across the gate.

Consequences

• After the packet: committing a staged .py under the routed trees runs T21 — fabricated/drifted keys are ERRORs, retyped declared keys are WARNINGs that block until the file imports the constant.
• The 29-file worklist becomes a tracked ratchet (burn-down or baseline, ruled in the packet).
• gate.py review-staged and the pre-commit hook need no policy invention — the Prolog reviewer_tree fact is the seam.
• T17-GEN (build order 2, task #570) widens the same registry from *_ENV constants to ALL declared module constants; this routing lands first so the widening inherits a gate that already sees source files.

Provenance

Mohamed's in-session ruling, 2026-10-20, on the coordinator's decision prompt (handoff §4 item 1 — "T17 routing: should staged SOURCE .py files enter test-review (a commit_review.pl policy change)?"), verbatim answer: "Approve as follow-up packet (Recommended)". Evidence: routing measurement in the T17 run-1 worker report (verified against commit_review.pl:70-72 by the coordinator); blast-radius grep (29 files, 2026-10-20); incident record: plans/briefs/t17-env-key-drift.md preamble and commit 4a470482c; run-2 defect corpus: plans/briefs/t17-env-key-drift-run2.md (D2, D7).

Related ADRs

No other ADR is named in this record.

Rulings cited

• RUL-038: RUL-038 — Test runs never create containers; container creation is exercised only by explicit rehearsals
• RUL-023: RUL-023 — A feature request means the thing is WIRED, not that code exists

Specs cited

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