Knowledge Wiki Orchestrata Ultimate

Orchestrata Ultimate › Plans › briefs › move-109-rename-engine

MOVE-109 — the SPEC-109 rename engine moves to codetools (ADR-0117 + ADR-0118 phase discipline)

Source: plans/briefs/move-109-rename-engine.md at 8a2cb42ad · last changed 2026-10-20 · first committed 2026-10-20 · 108 lines.

Prose pending.

Plan text

MOVE-109 — the SPEC-109 rename engine moves to codetools (ADR-0117 + ADR-0118 phase discipline)

Contract: docs/adr/0117-spec-109-rename-engine-moves-to-codetools-and-orchestrata-consumes-the-deployed-cli.md (the ruling) + docs/adr/0118-... §4 (phase discipline) + plans/refactor-convergence-design.md P-A. Design of record for the engine itself: plans/rename-engine-design.md (SPEC-109, ratified+spiked) — read its §2 spike findings and §5 wiring plan; ADR-0117 SUPERSEDES §5's registration plan.

You are a worker. You do NOT commit (the coordinator commits both repos with explicit file lists). 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 that caught a bug. Byte-faithful means byte-faithful: the ONLY permitted content changes are the named decoupling edits below.

Pre-move oracle (already recorded by the coordinator — verify, do not re-run)

ORACLE: run_tests.py tests/refactor/rename/ --skip-gates, recorded 2026-10-20 ~06:35 UTC — observer parent session 1359692-1792476090837; result: 143 tests passed, 0 failed, 0 errors, 0 skipped — all 13 modules RUL-032-reused from the ledger (unchanged since their last green run), infra 5/5 ready (Redis/Graph/Gateway/Kernel/Link). This is the pre-move oracle: a ledger-backed green at exactly the pre-move code state. Confirm the row exists (observe-pytest list). If the ledger state contradicts this (any rename module red), STOP and report — a red pre-move state means the move has no oracle and does not proceed.

Fence

orchestrata (/home/mohamed/workspace/wt-COMPONENTS):

codetools (/home/mohamed/workspace/orchestrata.codetools):

The five-import decoupling (the ONLY content changes; everything else byte-faithful)

Measured external coupling: core.base.traces (@traces), core.tracing.tracer (Tracer), tools.base, tools.lsp_tool (_path_to_uri/_uri_to_path), tools.registry (the tool shell only — deleted, so this one vanishes with tool.py).

  1. _path_to_uri/_uri_to_path: replace the lsp_tool import with the stdlib/equivalent inline or lsprotocol-style helpers INSIDE the moved package (measure what lsprotocol/pygls offer; codetools already depends on neither — prefer a 10-line local helper module over adding a dependency; the helpers are trivial file:// joins).
  2. @traces decorators: codetools has its own trace lane (src/codetools/trace/) — measure its surface. If it offers an equivalent decorator, re-point; if not, STRIP the decorators from the moved code and record the strip as a disposition line (the spec travels with the code — see bookkeeping — so traceability is preserved by the spec record, not by a decorator pointing at a foreign spec registry).
  3. Tracer: measure its use in the engine (probably span/event emission). Replace with codetools' equivalent if one exists; else strip with recorded disposition (same rule). 4/5. tools.base/tools.registry: vanish with tool.py's deletion.

Spec + RTM bookkeeping (propose, coordinator rules)

specs/109-rename-engine/ (spec.md + checklists): propose ONE disposition — (a) move the spec dir into codetools' spec-lane convention with an origin note (measure how codetools numbers/stores its specs: it has a spec/ package and its own SPEC-NNN registry — a renumbering proposal must name the target id and the mapping), or (b) archive in place with a MOVED header pointing at the codetools home. Do NOT execute a renumbering unilaterally — propose it in your report with the measured codetools convention; the coordinator rules. Orchestrata RTM effect (REQ-109 declarations leave the tree): name it in your report; the coordinator records the disposition so REQ-109 never dangles silently.

module_move overlap (measure + recommend, do NOT delete theirs)

codetools already has src/codetools/refactor/module_move.py + module_move_result.py. The engine brings its own module_move.py. Measure both surfaces and RECOMMEND in your report: compose (one delegates), coexist under distinct names, or a follow-up merge packet. Land yours under a name that cannot collide (e.g. inside the rename/ subpackage — which the fence already guarantees).

VERIFY (report verbatim)

  1. Pre-move oracle row confirmed (observe-pytest list excerpt).
  2. Post-move, codetools side green: run the moved tests with CODETOOLS' runner/pytest convention (measure it; report the exact invocation + result; never xdist).
  3. Byte-faithfulness proof: for every moved module, diff original vs landed showing ONLY the decoupling edits (report the diff summary per file; zero-diff files listed as byte-identical).
  4. Orchestrata side post-deletion: grep -rn "refactor.rename\|refactor/rename" src/ scripts/ tests/ → only the historical comment references you updated; .venv/bin/ruff check + black --check on every orchestrata file you edited; python scripts/serialize_codebase_ast.py who-imports refactor.rename.lsp_client → 0 (post-deletion).
  5. python scripts/gate.py run (orchestrata) → unchanged verdict vs pre-move (if it exits 2 on a stale fact base, run uv run ast-sync first and report both states).
  6. basdedpyright engine smoke: the moved CLI entry (run it from the codetools tree the way their tools run — measure; a single-symbol dry-run rename on a scratch fixture proving the langserver handshake still works end-to-end AFTER the move).

Report

Per-fence file lists (moved/deleted/edited, with dispositions), the decoupling decisions (traces/ Tracer/URI-helpers) with measurements, the spec-bookkeeping PROPOSAL (a or b, with the codetools convention evidence), the module_move recommendation, all VERIFY outputs verbatim, and anything you could not execute faithfully, named. Fabricated or unverified claims cause a full reject (L11/L13).