Orchestrata Ultimate › Plans › tools-family-implementation-plan

Tools-family implementation plan (N-V3 / N-V4) — specs, design, implementation

Source: plans/tools-family-implementation-plan.md at 8a2cb42ad · last changed 2026-10-18 · first committed 2026-10-18 · 116 lines.

Prose pending.

Plan text

Tools-family implementation plan (N-V3 / N-V4) — specs, design, implementation

Status: Awaiting ratification · Date: 2026-10-18 · Authorised by: Mohamed 2026-10-18 ("create a detailed plan including specs and design and implementation of the missing features first, then implement them all until they are done, then go forward with the rest of the plan") · Follows ADR-0106 (Accepted: "Hold the claims, gate green now") — this plan ends the holds by implementing the held features.

1. Scope

Implement the five features the lift deliberately stopped (the N-V3/N-V4 tools knot), so every package parity suite is green with zero held claims, then finish the ADR-0105 push packet.

Measured blockers, frozen snapshot e57782ea4:

• tools family: 20 modules, 13,449 LOC, zero orchestrata_ultimate imports — fully self-contained; external roots: httpx, psutil, redis, typer, urllib. (tools.search 1,608 · schedule_cron_tool 1,445 · task_tools 1,357 · remote_trigger_tool 1,284 · repl_tool 1,062 · worktree_tools 971 · lsp_tool 892 · codebase_tools 822 · context_tools 724 · ast_query 613 · ast_query_cli 464 · codebase_query_tools 456 · mcp_resource_tools 455 · ast_pipeline 283 · mcp_stdio_client 273 · registry 199 · base 196 · conversation_tools 175 · approval 95 · tools/__init__ 75)
• openspec family: 7 modules, 723 LOC (requirements_parser 219 · parse 121 · repo 109 · detect 94 · render 73 · models 60 · __init__ 47)
• AST toolkit scripts.serialize_codebase_ast: 13,797 LOC, the host/root code-intelligence engine; volks needs exactly two functions: gate0_construction_smoke, generate_skeleton_modules.

2. Specs

• SPEC-126 — orchestrata-tools (new, minted for this wave): one FR per frozen tools/openspec module (20 + 7), REQ-126-001..027 in the package's specs/126-tools/ checklist; the checklist rows cite the frozen module paths and the ##UNRESOLVED## pending-family entries this wave resolves (tools.approval, tools.codebase_query_tools, tools.context_tools, tools.lsp_tool, tools.mcp_resource_tools, tools.registry, tools.remote_trigger_tool, tools.repl_tool, tools.schedule_cron_tool, tools.search, tools.task_tools, tools.worktree_tools, tools:openspec.requirements_parser, tools:scripts.* (protocol-seamed, see §3)).
• REQ-125 re-claims: the volks holds end — REQ-125-039/040/041/042 (tool_registry), 058/909 (architect), 067/068/911 (codedirector), 060 (implementation), 957 (spec_completeness) move back to TESTED proof class once their parity tests are green.
• Spec deltas for the seam (§3): orchestrata-contracts gains the AST-toolkit protocol (SPEC-116 rows, REQ-116-9xx minted) and the repo-root resolution contract is reused (ORCHESTRATA_ROOT pattern already in landed drivers).

3. Design (the N-V3 / N-V4 rulings — Proposed ADR-0107 / ADR-0108)

• N-V3 — tools + openspec land as their own package. packages/tools (import name orchestrata_tools, the placeholder packages/tools/design/boundaries.json already reserved) receives the whole frozen tools family + the openspec family (~14.2K LOC), lifted by the existing lift machinery (component_wave + land_component), with its own parity suite generated like the other six packages. packages/volks/pyproject.toml gains orchestrata-tools as a declared dependency; tool_registry's 25 frozen tools imports re-point orchestrata_ultimate. tools.* → orchestrata_tools.*. The tools family imports no ultimate code, so this is the mechanical wave of the lot.
• N-V4 — the AST toolkit stays host-side behind a contracts protocol. The 13.8K-LOC scripts.serialize_codebase_ast is the host/root code-intelligence engine, not a component; lifting it would drag the whole root tree into the packages graph (and its tests/daemon/CLI). orchestrata-contracts gains a small protocol (AstToolkitProtocol): gate0_construction_smoke and generate_skeleton_modules signatures, module-level importable in the volks venv. codedirector.implementation lands retargeted to the protocol (TYPE_CHECKING import of the protocol; the host wires the real toolkit at runtime). Signature parity holds — the frozen fixture pins the declared params, which the protocol mirrors.
• Repo-root hack removal. The three function-scope import orchestrata_ultimate calls (_repo_root() in architect/codedirector) become the landed packages' own root resolution (ORCHESTRATA_ROOT env override, the exact pattern already shipped in orchestrata_volks/drivers/claude_code_driver.py).

4. Implementation phases (each ends green + committed)

• P1 — land the tools package. component_wave tools + openspec from frozen → land into packages/tools (ADR-0103: clean target, parity oracle); pyproject (SPEC-126, deps httpx/psutil/redis/typer/urllib + lock pins); venv provisioned.
• P2 — tools parity suite. New generator packages/design-scripts/tools/tools_parity.py (vk_parity pattern: one test per REQ-126, real imports, allowed-roots census, click/classmethod unwraps); fixtures + tests generated; cd packages/tools && .venv/bin/python -m pytest tests/ -q → 0 failed.
• P3 — contracts seam. orchestrata_contracts/ast/ast_toolkit_protocol.py (2 signatures + @traces REQ-116-9xx) + real tests; contracts suite stays green.
• P4 — the five volks modules. Wave + land agents.tool_registry, agents.volks.architect.volk, agents.volks.codedirector.volk, agents.volks.codedirector.implementation, verification.spec_completeness with the §3 retargets; vk_parity.py hold-list shrinks to empty; regen volks parity (deterministic — frozen pin + checklist + increments README only); packages/volks suite → 0 failed.
• P5 — Definition-of-Done sweep (ADR-0069) per packet: @traces on every new symbol; RTM regeneration (held ids move TESTED); docs (SPEC-126 checklist flips, CODEBASE_MAP, wiki page) via the wiki's own ship gate; ≥90% line coverage for every new/modified file (the wave's main cost: ~14.2K tools LOC + 4.3K volks LOC need real tests — parity suites give per-REQ coverage, the remainder backfilled with behavioural tests; quantified per file, no padding).
• P6 — gate + ship (the rest of the ADR-0105 plan): affected run run_tests.py --affected origin/master...HEAD green with 0 UNTESTED; ship.sh cheap gates; deploy/ship.sh → push components to origin.

5. Risks

• Coverage backfill for ~18.5K new LOC is the dominant effort in P5; bounded by per-file measurement and the ≥90% floor.
• Cross-package retargets (kernel imports VolkProtocol, in-flight) — resolved in the current contracts retarget; the tools landing adds volks→tools edges only.
• Regen drift (measured with sinc): only regen where the chain is deterministic (vk_parity: frozen pin + checklist + increments README); everywhere else sync-edit generated outputs and record the owed chain re-run.
• typer/psutil become new package deps — declared + lock-pinned in P1.

6. Verification gates

Each phase: package venv suite 0 failed · pre-commit review PASS · RTM before/after · run_tests.py --affected origin/master...HEAD at P6 with 0 UNTESTED · ship.sh green · pushed.

Related

• Plans
• Orchestrata Ultimate — project index
• Workflow
• Tasks