Orchestrata Ultimate › Plans › tool-wave-plan
Functionality-tool build plan — specs 063-071 (session 227)
Source: plans/tool-wave-plan.md at 8a2cb42ad · last changed 2026-07-27 · first committed 2026-07-12 · 87 lines.
Prose pending.
Plan text
Functionality-tool build plan — specs 063-071 (session 227)
User ruling 2026-07-12: SPEC-099 security work is DEPRIORITIZED ("forget security"); build the missing functionality tools, prioritized by functional importance, in swarm waves with code/test/architecture gates at every step.
Context
The spec-gap audit (plans/spec-implementation-gaps.md §4) found the entire
Claude-Code-parity tool wave (specs 063-071) has zero code. The SPEC-062
framework they plug into IS built and tested: tools/base.py (Tool Protocol /
BaseTool ABC + ToolMetadata + ToolCategory/ToolPriority), tools/registry.py
(thread-safe ToolRegistry + process-wide default_registry() +
register_tool()), searched by SPEC-072 ToolSearchTool.
Prioritization (functional importance to this system)
| Wave | Spec | Tool(s) | Why this priority |
|---|---|---|---|
| 1 | 069 | Task-management suite (TaskStop/TaskOutput + the base task lifecycle they extend) | agent-coordination primitive for swarm work — highest leverage |
| 1 | 063 | REPLTool (sandboxed Python/JS/Bash sessions) | code-execution primitive for QA/junior/senior volks |
| 1 | 064 | EnterWorktreeTool / ExitWorktreeTool | parallel-edit isolation for builder swarms |
| 2 | 068 | ScheduleCronTool | automation backbone (timezones, persistence) |
| 2 | 067 | RemoteTriggerTool | webhook/API outcall with auth+retry |
| 2 | 071 | ListMcpResources / ReadMcpResource | MCP integration surface |
| 2 | 065 | LSPTool | code-navigation primitive for code volks (was unassigned — added 2026-07-12) |
| 3 | 066, 070 | — ARCHIVE — | 066 targets Windows hosts we don't have; 070 is generic Team-CRUD/RBAC boilerplate disjoint from the volk model. Mark spec Status: Archived + SPEC_INVENTORY note. |
Standards gate — EVERY tool, EVERY wave (non-negotiable)
- Implements the SPEC-062 contract:
tools/<tool>.py,BaseTool(or Tool-Protocol + composition),ToolMetadata(name, category, priority, description, arg schema), returnsToolResult. specs/0XX-*/checklists/requirements.mdwritten (REQ-0XX-NNN extracted from spec.md) and code stamped@traces(spec="0XX", reqs=[...])— the tool goes green in the RTM the day it lands.- Tests: real implementations only (no mock/monkeypatch/skip), function-scope
fixtures,
test_id-scoped resources, parallel-safe; run via the live observer per project rule. - Gates per tool before wave-commit:
scripts/code-review.pyERROR-clean,scripts/test-review.pyclean,scripts/architecture_checker.py0 violations, targeted module tests green. - Wave close (orchestrator): diff review, gates re-run repo-wide, registry
wiring (
register_toolfactory), commit per wave. Full suite (scripts/run_tests.py, kernel REQUIRED) before the final wave-3 commit. - Deps: any new dependency goes in pyproject.toml via
uv add(checked against .claude/banned-libraries.txt); no undeclared imports (check-deps). - Wiring check (added 2026-07-12, user directive): a step is not done until the deliverable is REACHABLE in production — name the construction/ registration/import seam (registry factory, volk AGENT_TOOLS exposure, kernel boot, gateway RPC table, gadget manifest) or record the wiring as an explicit owed item. Enforced by the orphan-module ratchet in scripts/health_check.py. Retrospective: the wave's tools were built+ registered but volk exposure shipped separately — under this rule that gap is stated in the wave close, never silent.
Swarm mechanics
- Builders run in the MAIN tree (no worktree isolation: worktree base is origin/master which trails local HEAD — recorded trap). Safe because each tool is NEW disjoint files; builders are FORBIDDEN from editing shared files (tools/init.py, registry.py, base.py, pyproject.toml) — they REPORT needed wiring/deps and the orchestrator applies it.
- MVP-first briefs (recorded ruling): implement what spec.md defines; if the spec assumes absent infra, STOP and report rather than invent.
- Sandboxing note for 063: prefer subprocess-level isolation (resource limits, timeout, cwd jail) over Incus per-call; harness/isolation.py + IncusIsolation exist if the spec demands container isolation — builder reports the fork if ambiguous.
Wave status
- [x] Wave 1: 069 task suite (74 tests), 063 REPL (49), 064 worktree (42) — committed 2d14dae5
- [x] Wave 2: 068 cron (75), 067 remote-trigger (91), 071 MCP (24), 065 LSP (82) — committed 0da8f311
- [x] Wave 3: 066/070 archived (687b8bf7); all 10 native tools wired via register_native_tools + tools/init exports; checklist format normalized (check-traces 0 dangling/0 malformed); RTM regenerated (5,143 reqs, +261 from the 8 new checklists); full suite run at close.
Outcome (2026-07-12)
437 new tool tests across 7 specs, all gates green per tool. Recorded follow-ups (session backlog): volk-facing AGENT_TOOLS exposure (governance decision), Prolog may_stop_task/2 + may_access_mcp/3 wiring, official mcp SDK adoption, cron scheduler daemon (architecture decision), Redis-persisted task store, OAuth2 token caching + DNS-rebinding guard for remote_trigger, persistent-LSP-session backend.