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

ADR-0117: SPEC-109 rename engine moves to codetools, and orchestrata consumes the deployed CLI

← ADR-0116 · ADR-0118 →

The record

Status: Accepted (ruling, Mohamed, 2026-10-20, verbatim: "A" — ratifying option A of the coordinator's location prompt over plans/refactor-convergence-design.md) · Date: 2026-10-20

Context

The refactor-convergence design (2026-10-20, measured) inventoried five refactoring surfaces. SPEC-109's engine — a real stdio JSON-RPC client for basedpyright-langserver with the ratified spike findings (prepareRename/rename/definition, didOpen-before-prepareRename, wait_until_settled, the hard no-name-matching timeout policy REQ-109-103) — is built and 13-module-tested but stranded: the CLI seam shipped (scripts/rename_engine.py), the volk-tool registration was declared-deferred by its own design §5, and refactor.rename.tool has 0 production importers.

Four measurements decide the location question:

1. codetools already hosts the lane: ~/workspace/orchestrata.codetools/src/codetools/ carries 24 cross-project code-intelligence packages (ast, design — code2diagram/diagram2code, gate, graph, realize, refactor, review, rtm, spec, testing, trace, …), deployed at /opt/codetools/bin — and codetools.refactor holds import-level primitives (module_move, import_rewrite, Prolog-driven refactor results) with no pyright/LSP presence anywhere in codetools. SPEC-109 fills the lane; it does not duplicate it.
2. The engine is nearly coupling-free: across its 29 modules, exactly 5 external orchestrata imports — core.base.traces, core.tracing.tracer, tools.base, tools.lsp_tool (URI helpers), tools.registry. The LSP machinery itself is project-independent by construction.
3. The components refactor has no home for it: refactor/ has ZERO mentions in packages/integration/design/clean-target.md and boundary-census.md — unassigned dev tooling in the product tree that cut-over must evict anyway.
4. ADR-0108 is the precedent at the correct scope: the AST toolkit stayed host-side because it is THIS repo's KB engine; the rename engine is not repo-specific, so its host-side home is codetools. ADR-0108's seam shape (contracts-protocol injection) applies on concrete consumption — codedirector had two real function calls; rename has zero concrete volk consumers today, which is exactly why SPEC-109's own §5 deferred the registration.

Decision (Mohamed, verbatim: "A")

1. The SPEC-109 engine moves to codetools — refactor/rename/ (engine), scripts/rename_engine.py (CLI), the 13 test modules, and the SPEC-109 bookkeeping: the spec travels with the code into codetools' own spec/rtm machinery. Orchestrata's side RECORDS the move (RTM/spec disposition so REQ-109 ids do not dangle) — a move is recorded, never silently deleted.
2. Orchestrata consumes the deployed CLI (/opt/codetools/bin lane). A contracts-protocol injection seam is added ONLY when a concrete volk consumer exists — named trigger, no speculative seam (the ADR-0108 consumption precedent).
3. Two-copy parity discipline for the move: the owed orchestrata-side sanctioned green proof (M5: run_tests.py tests/refactor/rename/*.py --skip-gates — the RUL-038 guard named this exact invocation) runs BEFORE the move; the move is byte-faithful; codetools' runner proves green AFTER. The "before" leg is the move's oracle.
4. The toolkit's KB-native rename stays (repo-local snapshot + Prolog KB + symtable — it cannot move). The convergence design's lane split stands with the INFERENCE/type-resolved EXECUTION planner living in codetools: name/func/class/module kinds → toolkit fast path; method/type-scoped renames → the codetools engine.
5. In-packet adjudication: codetools.refactor.module_move vs SPEC-109's module_move (overlap measured — one wins or they compose; the packet's design note rules it, not the builder).
6. NOT in this ruling: refactor/codemod/ and refactor/ctok/ are the same unassigned- dev-tooling class but stay pending their own location ruling (asked alongside; deliberately not assumed from the "A").

Alternatives rejected

• B — keep in orchestrata, wire the volk tool per SPEC-109 §5: leaves project-agnostic tooling in the product tree; cut-over evicts it later under pressure; the volk registration wires a consumer nobody has (0 concrete users measured).
• C — move at cut-over: the same move with less time, an unruled spec disposition, and the parity proof compressed into the refactor's highest-stakes window.

Consequences

• MOVE-109 packet queued behind the current queue position (T17 lands first): engine+CLI+tests+ spec move, 5-import decoupling (traces/tracer adapters or codetools conventions; URI helpers via lsprotocol or codetools' own), module_move overlap ruled, deploy at /opt/codetools/bin, parity proofs both sides, orchestrata-side RTM/spec disposition + residue removal.
• Codetools gains its first pyright/basedpyright dependency; its gate and test state (including the RUL-038 rehearsal-class history in that repo) are packet inputs, measured at dispatch.
• The standing "persistent LSP session backend (065)" hardening item RESCOPES into this move: the real persistent-session machinery IS the moved engine (its spike findings are the persistence discipline); orchestrata's SPEC-065 lsp_tool remains the wired AST-approximation tool for volks and keeps its pyright-CLI diagnostics path.
• plans/refactor-convergence-design.md P-A rescopes from WIRE-109 to MOVE-109; its §6 decision 1 (lane split) is ratified by this ruling; decisions 2 (shared refs vocabulary) and 3 (type-fact persistence) remain open.
• src/orchestrata_ultimate/refactor/ shrinks to codemod + ctok + agent/tools surfaces pending their own ruling (decision 6).

Provenance

Mohamed's in-session ruling, 2026-10-20, verbatim "A" on the coordinator's three-option location prompt (options A/B/C as recorded in §Alternatives). Evidence of record: plans/refactor-convergence-design.md §2 inventory + §3 M1-M6 and the location-prompt measurements (codetools package listing; the 29-module/5-import coupling scan over plans/ast-ultimate.json; the zero-mention grep of clean-target.md + boundary-census.md; scripts/rename_engine.py present at 10.3KB; cst-lsp measured third-party — Roy Williams, MIT — and therefore NOT a codetools precedent). Precedents: ADR-0108 (host-side engine + seam-on- consumption), ADR-0107/0112 (component-package boundary rulings), SPEC-109 design §5 (the deferred-wiring declaration this ruling supersedes).

Related ADRs

• Also mentioned: ADR-0108, ADR-0107

Rulings cited

• RUL-038: RUL-038 — Test runs never create containers; container creation is exercised only by explicit rehearsals

Specs cited

• SPEC-109
• SPEC-065