Orchestrata Ultimate › Research › codetools versus components

codetools versus the components branch


Question	Is codetools a replacement for the `components` branch, or the other way round? And what does it take to merge `components` to `master`?
Method	Read both repos' `pyproject.toml` files and package lists, the cut-over plan in `wt-COMPONENTS/packages/integration/increments/README.md`, ADR-0107, ADR-0108, ADR-0113 and ADR-0118, and a read-only Hermes check of the source-tree statements (5.1 min, 54 tool calls). All read on 2026-10-22/23
Status	Analysis done. The merge has not started beyond INT-01. It is gated by the open `packages/` ruling

Short answer

They are different layers. codetools is the toolchain that generates and checks code. The components are the product it generated. Neither is a drop-in replacement for the other.

The two things side by side

	codetools	components branch
Repo	`~/workspace/orchestrata.codetools`	`orchestrata-ultimate-architecture`, branch `components` (worktree `wt-COMPONENTS`, at `d4b7e162a`)
What it is	A "Python-first code-tools module: byte-exact AST snapshots, knowledge graph + blast radius, refactoring, testing, coverage, tracing, debugging, RTM, SCM, deployment, Incus, IaC" (its `pyproject.toml` description)	The decomposition of the `src/orchestrata_ultimate` monolith into nine packages: `orchestrata-contracts`, `-gateway`, `-governance`, `-kernel`, `-kg`, `-session`, `-tools`, `-volks`, and the integration package `orchestrata`
Layer	Development toolchain. It reads, generates, verifies and deploys code	Runtime product: the kernel, gateway, volks and the rest that `/opt/orchestrata` runs
Source modules	`ast`, `realize`, `gate`, `review`, `rtm`, `coverage`, `trace`, `testing`, `refactor`, `scm`, `deploy`, `incus`, `iac`, `mcp`, `prolog`, `spec` and others (from `ls src/codetools`)	`packages/<c>/src/orchestrata_<c>/`
Deployed at	`/opt/codetools`, release `a5c419f5` (`ct-install 75`, 2026-10-23)	Not deployed. `/opt/orchestrata` still runs `src/orchestrata_ultimate` at `4ac0db570`

How they depend on each other

codetools generated the packages. packages/contracts/pyproject.toml opens with: "scaffolded from codetools realize's .realize-out/pyproject.toml". The eight upstream packages landed through component_wave.py and land_component.py. Example: volks landed 286 modules in 44 s with 0 model tokens, leaving 43 residue items.
The packages test through codetools. packages/contracts lists codetools in its test extra, as an editable /opt/codetools/current path. About 1,550 generated lines import codetools.rtm (session summary, not re-measured here).
codetools used to depend on orchestrata-ultimate. That made a cycle. Since a5c419f5, orchestrata-ultimate is only codetools' optional openspec extra, injected into read_requirements.

packages/tools is a different thing from codetools, despite the name. ADR-0107 lands the frozen tools family (src/orchestrata_ultimate/tools) as the component orchestrata-tools, which volks declares as a dependency. The Hermes check confirmed two related records:

per ADR-0118, only the repo's scripts/ tooling moves to codetools, and src/orchestrata_tools stays host-side as the backward-compatibility and deploy bridge;
per ADR-0108, src/orchestrata_ast (the AST toolkit) stays host-side behind a contracts protocol.

What merging `components` to `master` takes

ADR-0113 (Accepted 2026-10-19) records the merge condition: "integration green on the fleet tier, old src/orchestrata_ultimate/* removed, one merge to master, /opt/orchestrata ships from that tree". In concrete pieces:

The integration increments INT-01 to INT-25. 25 increments port 7,136 lines of original code, each at most 400 lines and 16 minutes. INT-01 (the scaffold) is done. ADR-0127 (Accepted 2026-10-23, ruling of 2026-10-22) drops INT-12 to INT-21 and the start_test_services half of INT-22 from the release: scripts/run_tests.py stays in the repo as a dev tool until codetools has an affected-set oracle. See the cut-over review for what else the plan is missing.
Removing src/orchestrata_ultimate. It is not in the increment plan, and it is large: 1,596 of 2,091 test modules and 100 of 181 scripts import it (6-root AST snapshot).
One workspace and one lock. Today there are nine per-package uv.lock files and no workspace over packages/. See Python deployment best practices.
deptry in CI, so that undeclared imports (kernel imports codetools without declaring it), transitive-only imports and dev-only imports fail before the merge, not after.
Porting 13 drifted files. These are files that changed on master after the freeze and that the packages do not carry. The Hermes check named two examples: core/paths.py resolve_project_root (3d77084d0), and session/audio_alarm.py, which is absent from every packages/*/src.
A codetools release pin. INT-01's pyproject.toml pins codetools as <PENDING tools release id>.

What is open

The packages/ ruling, ADR-0132 (Proposed). Whether packages/ is the edited source or a deployment copy decides whether items 2, 3 and 5 are needed at all. See open decisions.
Codetools hosting. Where codetools is published from, so the release pin can be filled in. Still open (session 271).

Already ruled: "cut-over first" (Mohamed, 2026-10-22), now Addendum 1 to ADR-0124. The cut-over lands before either container is built, and the containers only ever run the components build.