Orchestrata Ultimate › Plans › briefs › t21-routing-source-files
T21-ROUTING — staged source .py files enter the T21 env-key review at commit time (ADR-0116)
Source: plans/briefs/t21-routing-source-files.md at 8a2cb42ad · last changed 2026-10-20 · first committed 2026-10-20 · 80 lines.
Prose pending.
Plan text
T21-ROUTING — staged source .py files enter the T21 env-key review at commit time (ADR-0116)
Contract: docs/adr/0116-staged-source-py-files-enter-the-t21-env-key-review-at-commit-time.md
(Accepted, Mohamed 2026-10-20). Dispatch AFTER the T21 rule lands (T17 packet). The rule itself is
frozen — this packet changes ROUTING and lands the WORKLIST, not rule semantics.
The founding measurement (why this packet exists)
The T21 rule was founded on a SOURCE-file incident (scripts/run_tests.py::_child_run_env
fabricated ORCH_TEST_DEADLINE), but commit_review.pl:70-72 routes only tests/ + end2end/
to test_review — the rule cannot see the file class that founded it at commit time. ADR-0116 rules:
staged source .py enters the T21 review; the exact-key WARNING worklist becomes visible; the
warnings-block policy stays uniform (no source-file exception).
Fence
src/orchestrata_ultimate/prolog/commit_review.pl
scripts/gate.py
scripts/hooks/pre-commit
reports/t21-worklist-baseline.json (NEW — the ratchet baseline artifact)
tests/scripts/test_gate_review_staged.py (or the existing test module covering gate.py review-staged — MEASURE which module that is and name it in your report; if none exists, create it)
READ-ONLY for measurement: scripts/test-review.py (the landed T21 — do not edit),
scripts/check_*ratchet*.py shapes (the repo's established ratchet pattern),
plans/briefs/t17-env-key-drift-run2.md (the rule's contract).
Work items
W1 — routing. Measure the staged-file flow end to end: scripts/hooks/pre-commit (the
STAGED_PY collection, ~lines 95-145) → scripts/gate.py review-staged → the Prolog policy
(commit_review.pl reviewer_tree/2 + whatever predicate partitions files to reviewers). Then
wire: staged .py files under scripts/ reach test-review's T21 pass. src/ scope: MEASURE
first (run test-review over a sample of src/ files; count T21 findings; report) and PROPOSE —
the coordinator rules src/ inclusion from your numbers, do not self-expand. The Prolog change is
a FACT addition in the established shape (reviewer_tree(test_review, 'scripts/').) unless
measurement shows the partition needs a new predicate — report what the policy actually needs.
CRITICAL: T1-T20 stay name-scoped inside test-review (the landed D10 behavior) — routing a source
file to test-review must NOT subject it to test-standards rules; verify with
test-review.py scripts/run_tests.py --stdout → 0 findings (its T3 at :151 must NOT fire —
non-test-named) and record the output.
W2 — worklist baseline (the ratchet). Enumerate every exact-key T21 WARNING across
tests/ + end2end/ + scripts/ as they exist at dispatch time (run the landed rule over the
trees; the 2026-10-20 audit measured 29 test files — re-measure, do not trust the old count).
Write reports/t21-worklist-baseline.json: rows of {file, literal, declared_constant,
declaring_module, line} + a generated-at header + the rule version. Wire the ratchet in the
ESTABLISHED repo shape (pyright_ratchet/coverage_ratchet philosophy: fail only on findings NOT in
the baseline; baseline rows are named debt, new rows block). Where the comparison lives (gate.py
review-staged lane vs test-review flag) — MEASURE both seams and PROPOSE; coordinator rules before
you implement the comparison. Burn-down of baseline rows is OUT of this packet (follow-up waves).
W3 — founding regression. An end-to-end test through the REAL routing: stage a source-file
fixture (tmp git repo or the established pattern in the gate tests you found) carrying a
fabricated env key (ORCH_TEST_DEADLINE shape) → gate.py review-staged (or the hook's
selection function) hands it to test-review → T21 ERROR blocks. Plus: a baseline-row file with an
exact-key literal → WARNING listed but NOT blocking (ratchet behavior pinned). Real subprocess
runs, no mocks (RUL-002).
VERIFY (report verbatim)
.venv/bin/pytest <your routing test module> -o addopts="" -q # single module, or pytest-live
.venv/bin/python scripts/gate.py run # Prolog gate still PASS (clause+fact counts)
.venv/bin/python scripts/test-review.py scripts/run_tests.py --stdout # 0 findings (T3 must NOT fire)
.venv/bin/ruff check <fence .py files> && .venv/bin/black --check <fence .py files>
jq length reports/t21-worklist-baseline.json 2>/dev/null || .venv/bin/python -m json.tool reports/t21-worklist-baseline.json | head -5 # baseline is valid JSON; report its row count
Plus: the Prolog edit proven — gate.py run exit 0 AND a query showing the new reviewer_tree fact
resolves (report the invocation). Report the src/-scope measurement + both PROPOSALS (src/
inclusion, ratchet seam) explicitly — they are coordinator rulings, not yours.
Done
Reply with: the staged-file flow diagram (hook → gate → Prolog → reviewer, with file:line), the routing change (exact Prolog diff), the baseline row count + top offenders, the src/ measurement table, both proposals, W3 test names, all VERIFY outputs verbatim, anything unfaithful named. Workers do not commit. RUL-037. Fence files only.