Orchestrata Ultimate › Gates › green-ledger
Gate: green-ledger reuse (RUL-032)
| Purpose | A test that passed is not run again until its code or the test changes |
| Where it runs | scripts/hooks/pre-push and deploy/ship.sh (source stamp); scripts/run_tests.py steps 2b and 2c (report reuse, module ledger) |
| Trigger | Every push, ship and run_tests.py run |
| Exact command | none of its own; inspect with python scripts/test_green_ledger.py --status <test files>; seed with --seed-from reports/run-tests-latest.json; bypass with run_tests.py --force |
| Blocks | It never fails a run; it removes proven modules from the run and reports them as reused |
| Ruling / ADR | RUL-032 (Enforcement: gate scripts/run_tests.py RUL-032, gate scripts/test_green_ledger.py RUL-032); RUL-040 obligation 3 (function-level ledger) |
Why it exists
RUL-032 (Mohamed, 2026-09-22): "with the rule enforced that test only run once unless the code in the test or code is changed, and watch for escalation to full suite when the tests have already been run, this should never happen." Measured the same day: the selector resolved the changes since the last verified base to 1,008 tests and escalated to the full suite (1,608 modules, 400–490 s) while 197 gateway, kernel and CXP modules (3,977 tests) had already passed on identical code (ruling page).
The three reuse checks
| Layer | Identity | Where | Effect |
|---|---|---|---|
| Source stamp | sha256 over the tracked files outside reports/ plus untracked names (_ship_source_id), stored with the commit in reports/.ship-verified |
scripts/hooks/pre-push, deploy/ship.sh |
Skips the whole suite when this exact source already passed and reports/run-tests-latest.json is green at the stamped commit |
Proven-run reuse (_try_reuse_report) |
head_commit + dirty_sig of reports/run-tests-latest.json, and a scope that covers this run (a full report, or an affected report whose test set is a superset) |
run_tests.py step 2b |
Exit 0 without running |
Module ledger (test_green_ledger.partition) |
per test module: sha256 over the module, every src/ file in its import closure, every conftest.py from the root down, and pyproject.toml |
run_tests.py step 2c |
Reused modules are dropped before batching; their recorded counts are folded into the report under reused |
Nothing else is in the module key. An env/*.env edit does not change a module's key,
and the selector resolves it to the tests that name the changed keys instead of escalating
(RUL-032 mechanism 3). The ledger is reports/test-green-ledger.json, git-ignored and
per checkout (9 entries in wt-MAP-PRECOMMIT on 2026-10-23), written atomically.
run_tests.py records every module that went green, in a batch or a solo retry, and a
capped run saves its passing modules there as the resume point (RUL-038 amendment).
Real output
Attempt 4 of the 2026-10-22 item-3 push (worked example):
[run_tests] ♻ RUL-032: 6 module(s) unchanged since their last green run — reused, not re-run; 1 to run
[run_tests] Selected: 12 tests in 1 modules (6 modules reused from ledger) · hard cap 300s
[run_tests] ✅ 134 tests passed, 0 failed, 0 errors, 0 skipped · 1/1 modules in 31s (0.5m)
The report recorded "reused": {"modules": 6, "tests": 122}; the 134 in the summary is
122 reused plus 12 run.
Typical failures and how to fix them
| Symptom | Cause | Fix |
|---|---|---|
| A module re-runs although "nothing changed" | something in its key changed: a src/ file in its closure, a conftest on its path, or pyproject.toml |
Expected. test_green_ledger.py --status <file> shows the key state |
| A module is reused that should not be | an input outside the key changed (data files, env, an external service) | Run with --force; if the class recurs, the key needs the input (a ruling question) |
| The source stamp skipped a push you wanted verified | the stamp matches this exact source | "touch any tracked file, or delete that stamp, to force a re-run" (hook message) |
| One changed line re-runs a whole 60-test module | the ledger keys at module level | RUL-040 obligation 3 asks for a function-level ledger; not built in this tree as of 2026-10-23 |