Orchestrata Ultimate › Plans › briefs › move-batch1-pyright-pair
MOVE Batch 1 — pyright_autofix.py + pyright_ratchet.py transfer to codetools (ADR-0118)
Source: plans/briefs/move-batch1-pyright-pair.md at 8a2cb42ad · last changed 2026-10-20 · first committed 2026-10-20 · 83 lines.
Prose pending.
Plan text
MOVE Batch 1 — pyright_autofix.py + pyright_ratchet.py transfer to codetools (ADR-0118)
Contract: docs/adr/0118-tier-1-host-side-scripts-transfer-to-codetools-in-two-batches.md decisions
2 + 4 (phase discipline) — the ADR-0117 move template applies (byte-faithful, green both sides,
recorded disposition). These two scripts are the pyright family that groups with the MOVE-109
rename engine in codetools' refactor lane.
You are a worker. You do NOT commit. RUL-037: Python only as .py files through editor tools — no
python -c, no heredocs, no codemod scripts. Never pytest-xdist. Never weaken a test.
What moves (measured inventory)
scripts/pyright_autofix.py(1,310 LOC) — pyright-driven autofix engine.scripts/pyright_ratchet.py(108 LOC) — the ratchet gate shape ("fail only on increase over ceiling",--max N).- Tests:
tests/scripts/test_pyright_autofix.py,test_pyright_autofix_cast_families.py,test_pyright_autofix_cli.py,test_pyright_autofix_roots.py,test_pyright_autofix_verify.py,test_pyright_ratchet.py, + the shared helpertests/scripts/_pyright_autofix_helpers.py.
Consumer surface (measured by the coordinator — re-verify, then rely)
ZERO hard consumers: no imports, no subprocess invocations, no hooks (user-level scanned per
RUL-035), no pyproject references. Docstring lineage references ONLY (they stay valid as history
but their path mentions go stale): scripts/gates.py:312, scripts/coverage_ratchet.py:5,22,28,
scripts/check_graph_write_swallow.py:55, scripts/check_spec_authority.py:23,103. Re-run the
grep yourself and report any consumer this list missed — if you find a HARD consumer (import/
subprocess/hook), STOP and report before moving anything.
Fence
orchestrata (/home/mohamed/workspace/wt-COMPONENTS):
- MOVE then delete originals (after parity): the 2 scripts + the 7 test files above.
- EDIT (doc-reference freshness, minimal touch): the lineage docstrings in
gates.py,coverage_ratchet.py,check_graph_write_swallow.py,check_spec_authority.py— append "(now in codetools:)" to the existing mention; do NOT restructure those files. - Do NOT touch
docs/CODEBASE_MAP*(another workstream's dirt) — record the staleness in your report.
codetools (/home/mohamed/workspace/orchestrata.codetools):
- NEW FILES ONLY: land in the refactor lane —
src/codetools/refactor/pyright_autofix/+pyright_ratchet/(or codetools' one-class-per-module convention — MEASURE their refactor lane's file naming first and follow it; propose the mapping in your report) + the moved tests under codetools' test-tree convention (MEASURE where their tests live and how their runner collects). - FORBIDDEN in codetools:
pyproject.toml,uv.lock, existing__init__.pyfiles outside dirs you create,src/codetools/review/**(active REV-3 workstream),.work/, console scripts, deploy, andsrc/codetools/refactor/rename/**(the MOVE-109 worker's concurrent fence — if it exists when you start, it is theirs).
Coupling (measured: 0 orchestrata_ultimate imports, 0-1 repo-path refs)
Both scripts are standalone CLIs over pyright's JSON output. Verify yourself: their imports, any
hardcoded repo paths (the audit measured pyright_ratchet.py 0/0 and pyright_autofix.py 0/0 —
confirm, and if either reads repo-specific config (e.g. a baseline file path, plans/ JSON), turn
that path into a CLI parameter with the current value as the invocation-time default in YOUR
report — do not hardwire an orchestrata path into codetools).
Pre-move oracle (record it yourself, single modules — sanctioned shapes)
For each of the 7 test modules: pytest-live tests/scripts/test_pyright_autofix.py -q style
(one module per invocation — the RUL-038 guard refuses multi-file bare pytest; the sanctioned
multi-module runner is run_tests.py, but this tree's run_tests.py is inside another worker's
fence this hour — use per-module pytest-live and report each ledger row). All 7 green BEFORE the
move, or STOP.
VERIFY (report verbatim)
- Pre-move: 7 per-module green ledger rows (observe-pytest list excerpt).
- Post-move, codetools side green: the moved tests under codetools' runner convention (exact invocation + result; never xdist).
- Byte-faithfulness: per-file diff original vs landed (zero-diff files listed; any edit named and justified — expected: none, or only the parameterized-path change if you found one).
- Orchestrata post-deletion:
grep -rn "pyright_autofix\|pyright_ratchet" scripts/ tests/→ only the updated lineage mentions; ruff + black clean on the 4 edited docstring files;python scripts/gates.py --helpstill works (gates.py unbroken by your docstring edit). - The ratchet still ratchets: run the landed
pyright_ratchetfrom the codetools tree against a scratch fixture proving the ceiling logic works post-move (measure how codetools tools are invoked — module path or console entry — and use that).
Report
Per-fence file lists (moved/deleted/edited with dispositions), the codetools naming-convention mapping you followed, any parameterized path, consumer re-verification result, all VERIFY outputs verbatim, anything you could not execute faithfully, named. Fabricated or unverified claims cause a full reject (L11/L13).