Orchestrata Ultimate › Plans › orchestrata-completion-plan

Orchestrata Completion Plan — autonomous execution

Source: plans/orchestrata-completion-plan.md at 8a2cb42ad · last changed 2026-08-10 · first committed 2026-07-04 · 159 lines.

Prose pending.

Plan text

Orchestrata Completion Plan — autonomous execution

Derived from 7 parallel audits (plans/research/audit-0*.md). Executed non-stop, committing per coherent unit, tests + lint green each step, documenting as I go.

Progress log (newest first)

• DONE b45e4f74 — Flaky Firefox e2e stabilized (workers=2/retries=1/90s; 3 runs green).
• DONE 3aa25ae2 — 7 research audits + this plan.
• DONE b52bbd64 (W0) — call-time session AI-model (default_ai_model()), stale anthropic IDs → 4-6. (Deferred: import-time env snapshot in infra_config across 14 files; divergent VOLK_CONFIG → do opportunistically / in W3.)
• DONE fa77cfca (W1) — runtime per-volk tracing wired (IterationTracer via thread_id registry; PipelineRunner + BaseAgent instrumentation; configure_logging activated). 1317 tests green. docs/observability.md.
• DONE 394dcbda (W4a) — kernel status_report() + status subject → live per-volk status queryable by orchestrator.
• DONE e935e8f3 (W4a+) — status subject now emits a deliverable reply_packet (gRPC receipt is ack-only) + handler test.
• DONE e5a32302 (W3a) — shared team-persona preamble (agents/volks/persona.py::compose_persona) prepended to every volk's role prompt in BaseAgent._call_llm/_call_reasoner (real path only).
• NEXT (W4b) — inject kernel client into gateway/handlers/volk.py::VolkHandler; make handle_list serve live status via a dedicated status RPC (volk.list needs a synchronous response; the streamed reply path is async); feed heartbeat/health at postman/sync_router.py:220 _dispatch_sync; volk↔volk capability routing in pipeline_escalation._route_escalation (audit-02 G6-G10).
• NEXT (W3b) — activate/delete dead CODEDIRECTOR_SYSTEM_PROMPT + CODE_REVIEW_PROMPT (behavior decision: U:Cd is a deterministic coordinator today); route pipeline volks through _call_llm_with_tools (behavior change — needs care).
• DONE 2027e760 (W2a) memory retrieval connected — agents/volks/memory_context.py registry + recall(); BaseAgent._call_llm folds relevant memories into graph_context; kernel_handler binds the engine for continuing conversations. Tested vs a real MemoryEngine.
• TODO (W2b) context injection remainder — spec/req facts (Gap B), session/goal (D), prior-artifact summary (E) at kernel/pipeline_kg.py:_maybe_inject_context; register the memory engine on the in-process (VizInt) orchestrator/pipeline_runner.py too; cache recall per run (avoid a search per LLM call); pick VolkContextInjector + one runner as canonical (audit-03).
• TODO (W3) volk personas/tools — shared persona base; activate/delete dead CODEDIRECTOR_SYSTEM_PROMPT/CODE_REVIEW_PROMPT; route pipeline volks through _call_llm_with_tools; wire/remove BaseAgent.set_kg (audit-01).
• DONE 2e4e2253 (W5a) KG semantic layer added to schema.py — Volk/Intent/PipelineRun/Component labels, Decision/Artifact realized, 11 provenance edges, identity constraints + indexes + search_semantic fulltext. DDL validated vs real Neo4j.
• DONE 29f3e952 (W5 loop live) boot-time Volk-node sync (sync_volks_to_kg) + volk_work_context query — schema→writer→query verified vs real Neo4j. Also: message_volk (W6a), IncusIsolation (W6b), persona messaging guidance, architecture-overview doc.
• TODO (W5b) canonicalise divergent-key writers (Session/Project/Requirement/Volk-vs-Agent) then constrain; WRITE the new semantic nodes from the runtime (create Intent/PipelineRun/Artifact/Decision + provenance edges, fed from W1 trace + W2 context); implement the volk-aware injection query (SPEC-008 spec.md:333-347). Consolidate the 3 DDL sites.
• DONE af10b2ca (W6a) message_volk peer-communication tool — every LLM-driven volk can CXP-message peers via the postman; wired through BaseAgent (postman+alias+thread). Real-postman tested.
• DONE 944b9fe2 (W6b) IncusIsolation implemented — ephemeral oh-trial- container + host-dir mount; idempotent cleanup; stderr surfacing. Verified end-to-end vs real Incus.
• TODO (W6c) greenfield tool suite 063-072 + unified registry/ToolSearch; REPL/LSP/MCP-resource (larger; scope per spec before building — avoid speculative tools).
• DECISION-NEEDED (spec-007) specs/035-verification collides with canonical SPEC-007 (Prolog Governance, per SPEC_INVENTORY + 95 code refs). But 035-verification's requirements are REQ-009-* ids, it is absent from the inventory, and code never references it by number — so it is an orphan/mislabel. Disposition (rename→106 / merge into 009 / delete) is a decision, not a mechanical fix; do NOT blind-renumber (risks traceability).
• TODO (W7) docs + fix duplicate spec 007 + RTM refresh; rewrite stale session/examples/basic_usage.py (uses a dozen removed SessionController methods).

Reframing (the single most important finding)

The core engine (volks, postman/CXP, KG, session, gateway, governance, harness, memory, goal) is real and tested. The mandate's value is WIRING existing primitives + semantic enrichment + the missing tool suite, not greenfield. Recurring pattern: fully-built subsystems with zero production callers (IterationTracer, VolkContextInjector, VolkRegistry heartbeat/health, _call_llm_with_tools for 8/9 volks, BaseAgent.set_kg, Decision/Artifact KG nodes).

Constraints (non-negotiable)

Python ≥3.14 · uv only · absolute imports · NO mocking · call-time env (os.environ.get) · function-scope fixtures · NO pytest-xdist (use scripts/run_tests.py) · declare deps in pyproject · use AST toolkit for structure/refactor · NO AI attribution in commits · fix EVERY defect encountered.

W0 — Foundation bugs (small, unblocks, "fix everything") ✅ FIRST

Confirmed defects from the audits:

1. Hardcoded model default "Claude Opus 4.5" → session/controller/_core.py:163, session/models.py:215, session/portfolio.py:146, session/cli/lifecycle.py:27, session/examples/basic_usage.py:34. Replace with a single call-time-resolved default.
2. Import-time env snapshot — core/infra_config.py:137-141 freezes REDIS_HOST/ NEO4J_URI etc. at import; consumers from ...infra_config import REDIS_HOST capture import-time. Make call-time accessors (violates project rule).
3. Divergent VOLK_CONFIG — core/infra_config.py:175 vs llm/config.py (spike-profiles.yaml). Pick one authority; make the other delegate.
4. Stale reasoning models — core/infra_config.py:194-197 pins opus-4-5/sonnet-4-5.
5. Duplicate spec 007, gateway/test_runner.py:288 coverage TODO. Acceptance: gate tests green; grep shows no "Opus 4.5"; call-time env verified.

W1 — Runtime tracing + observability (do early: makes all later work observable)

Wire the orphaned core/tracing/__init__.py::IterationTracer:

• orchestrator/pipeline_runner.py:144 run — create IterationTracer(thread_id), set a contextvar, call new_correlation_id().
• _run_stage (218/280) — live pipeline.stage.start/complete; capture traceback.format_exc() on failure (currently discarded at :276).
• agents/volks/base.py:152 _call_llm + :184 _call_llm_with_tools — trace_llm_call
  • tool-call records; set volk_id contextvar.
• llm/client.py:559-570 / _capture_exchange:416 — feed elapsed_ms + usage + thread_id.
• Startup — call configure_logging(json_format=True).
• Reconcile the two PIPELINE_STREAM_KEYs (pipeline_kernel.py:42 vs kernel/pipeline_events.py:46).
• DebugPanel gadget: surface prompt/tokens/latency from the trace. Acceptance: a pipeline run produces a thread_id-keyed JSONL trace with per-volk llm calls (prompt len/tokens/latency); DebugPanel shows them; new tests.

W2 — Context injection (connect it)

Central chokepoint kernel/pipeline_kg.py:_maybe_inject_context (L107):

• Pick canonical injector = VolkContextInjector (SPEC-009, task-type) over the code-only ContextInjector; wire it (needs async Neo4jClient).
• Inject: spec/requirement facts (Gap B), retrieved memory via memory_engine.search() (Gap C — currently zero retrieval), session/goal state (Gap D), prior-artifact summary from ArtifactStore.by_thread (Gap E).
• Add extra_context kwarg to llm/client.py:502 call_llm; concatenate alongside graph_context.
• Reconcile the two runners (kernel/pipeline.py vs orchestrator/pipeline_runner.py) so injection runs on the VizInt path too. Acceptance: a volk prompt provably contains memory + spec + prior-artifact context; tests.

W3 — Volk personas + tools (create/optimize the volks)

• Shared persona base — replace 10 bespoke prompt strings + hand-rolled parsers with a VolkPersona base (identity/voice/format contract + "you are a volk in Orchestrata" preamble). Each volk supplies role specifics.
• Activate dead personas — CODEDIRECTOR_SYSTEM_PROMPT (U:Cd has no active persona), CODE_REVIEW_PROMPT (QA) — either wire to an LLM call or delete.
• Route pipeline volks through _call_llm_with_tools so granted AGENT_TOOLS become real (only Documentor uses it today). Architect/CodeDirector prompts already advertise tools they can't use.
• Add KG-query tool + inter-volk delegate tool (see W4/W5).
• Wire BaseAgent.set_kg() (never called; _kg always None) or remove it.
• Per-volk verify vs specs 012/013/026/027/029/030/031/032. Acceptance: each pipeline volk has a distinct active persona + a working tool loop; tests.

W4 — Communication: volk↔volk + orchestrator status

• Live VolkRegistry — instantiate kernel/volk_registry.py::VolkRegistry in kernel/pipeline.py:__init__, register each volk (_register_volks:139-143).
• Heartbeat/health feed — call record_heartbeat(alias) + in-flight counters at the dispatch boundary (postman/sync_router.py:220 _dispatch_sync); emit PacketType.HEARTBEAT (interval agents/constants.py:38).
• Orchestrator status — expose get_status()/get_volk_health via a kernel.status RPC (gateway/rpc.py:293) + subject=="status" in agents/kernel_handler.py:81. Replace the static gateway/handlers/volk.py:233 roster with live data.
• volk↔volk mesh — capability resolver (VolkRegistry.list_volks_by_capability); let _route_escalation (pipeline_escalation.py:36) route arbitrary/multiple recipients; activate BaseAgent.send() for mid-process side-messages.
• Push status events — emit volk.status on every WorkStatus transition; forward like pipeline events → volk-status gadget. Acceptance: orchestrator can query every volk's live status any time; a volk can message a non-linear peer; volk-status gadget shows live health; tests.

W5 — KG semantic layer (review graph + add nodes/edges/queries)

• Canonical identity first — unify Volk/Agent, Spec/Specification, Class/CodeClass/DesignClass; single key + uniqueness for Session/Project/Requirement/Volk. One schema-authority migration module (consolidate schema.py/sync.py/kg_design.py DDL).
• New semantic nodes — realize dead Decision/Artifact; add Intent, PipelineRun, Component, NodeVersion, Concept/PropertyDef.
• New edges — ASSIGNED_TO/OWNS/WORKED_ON/EXECUTED_BY; Intent-TRIGGERED->PipelineRun -PRODUCED->Artifact-DERIVED_FROM->Spec, GENERATED_BY->Volk; Volk-MADE->Decision -APPLIES_TO->Component/SUPERSEDES/JUSTIFIED_BY; HAS_VERSION/NEXT_VERSION.
• New queries — volk-aware injection (ownership+recent decisions, SPEC-008 spec.md:333-347 specced-unimplemented), provenance/blast-radius, traceability audit, temporal as-of, decision reasoning.
• Constraints/indexes — uniqueness on all id keys; fulltext on titles/rationale.
• Write pipeline runs/artifacts/decisions into the graph (feed the new nodes from W1/W2). Acceptance: KG carries Intent/Run/Artifact/Decision with provenance edges; volk-aware query returns a volk's ownership+decisions; constraints prevent dup nodes; tests.

W6 — Tool suite (063–072) — the largest true gap

Implement a high-value, security-sane subset + unify the registry:

• Unified tool registry + ToolSearch (072) — consolidate agents/tool_registry.py, refactor/tools.py, session/*_tools.py; semantic tool discovery.
• REPL (063), git-worktree (064, ties to WorktreeIsolation), LSP (065), MCP-resource client (071), task-mgmt (069) — highest leverage for coding volks.
• Defer/flag lower-value or platform-specific (066 PowerShell, 067 remote-trigger, 068 cron, 070 team) with explicit log/doc notes — no silent omission.
• IncusIsolation — implement harness/isolation.py:127 (currently NotImplementedError; user runs Incus not Docker). Acceptance: coding volks can call new tools through the loop; ToolSearch discovers them; tests.

W7 — Documentation + spec verification + RTM (continuous + final pass)

• Per-subsystem docs under docs/ (volks, comms/status, context injection, tracing, KG schema, tools). Keep AGENTS.md + architecture docs in sync.
• Fix duplicate spec 007; refresh SPEC_INVENTORY.md; regenerate RTM; drive orphans down.
• Verify each workstream against its spec; record status.

Execution order (autonomous)

W0 → W1 → W2 → W3 → W4 → W5 → W6, with W7 docs/tests folded into each. Commit per unit with a descriptive message (no attribution). Run the relevant test slice per change; full scripts/run_tests.py at milestone boundaries. Each workstream is a session backlog item; mark complete via the session CLI as finished. If a step reveals a genuine scope/behaviour decision, implement the sound default AND record it — do not stop for approval (user directive: non-stop till morning).

Related

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