Knowledge Wiki Orchestrata Ultimate

Orchestrata Ultimate › Plans › spec-audit › 00-MASTER-PLAN

Orchestrata Ultimate — Spec Implementation Master Plan

Source: plans/spec-audit/00-MASTER-PLAN.md at 8a2cb42ad · last changed 2026-07-27 · first committed 2026-07-04 · 322 lines.

Prose pending.

Plan text

Orchestrata Ultimate — Spec Implementation Master Plan

Session 195 planning deliverable. Evidence-based audit of all 60 specs (61 entries — SPEC-007 is two specs) against the actual code, plus a cross-spec dependency graph, parallelism analysis, and named implementation swarms with an execution order.

Per-spec detail (classification + file:line evidence + implementation plan) lives in the 11 cluster reports: A-core-runtime · B-session-gov-di · C-knowledge-memory · D-providers-llm · E-volks-1 · F-volks-2 · G-gateway-ui · H-integrations · I-tools · J-standards-arch · K-harness-greenfield. Method: _METHOD.md.

1. Executive summary

The port is essentially complete. Of 61 audited entries, ~24 are DONE or divergence-only (no code work — just spec-text reconciliation), and the real remaining work is concentrated in a small number of coupled themes, not spread thin across 60 features.

Classification Count Meaning
DONE ~13 All material capability implemented & wired. No action.
DIVERGENCE ~11 Code intentionally differs; update the spec, not the code.
PARTIAL ~23 Core works; named capabilities missing/unwired — real work.
GAP ~13 Genuinely absent (greenfield).

Two headline findings the stale checklists hid:

  1. A recurring "which implementation is canonical?" theme. The live system runs on a fixed PipelineRunner, but the repo also carries generic duplicates that are fully built, tested, and wired to nothing (0 src refs): Kernel subsystems, IntentBroker, AgentCoordinator, kernel/session_manager.py, three goal-system impls, the entire verification/ U:Vfy subsystem, the DIContainer, VolkContextInjector, PM goal_registry. Much "remaining work" is really a wire-or-delete decision, and several specs share the same decision.
  2. Four small "keystone" builds unlock most of the parallel work (gateway HTTP surface, unified tool framework, persistent DI memory-engine, CLI entry scaffold). Land those first and 6–8 implementation swarms open up concurrently.

The guardrail specs (097 testing, 100 logging/errors, 101 architecture) are not tracks — they are rules every swarm obeys: no mocks, no xdist, function-scope fixtures, real infra, absolute imports, core.logging + per-package *Error bases, deny-by-default governance. Enforced by the standards / check-deps AST gates (currently green).

2. Consolidated classification (all 61 entries)

Spec Name Class Effort Cluster
000 Ultimate CLI PARTIAL L A
001 Kernel PARTIAL M A
002 Postman DONE — A
003 Intent DONE (orphan facade) S A
004 CXP DONE — A
005 Multi-agent DONE (diverge+orphan) S A
006 Session management PARTIAL M B
007a Prolog governance DIVERGENCE S B
007b Verification (U:Vfy) ORPHANED L wire / S retire B
008 Knowledge graph DIVERGENCE S C
009 Volk context injection DIVERGENCE+ORPHAN S C
010 Memory engine PARTIAL L C
011 Provider manager PARTIAL L D
012 PM volk PARTIAL L E
013 UX volk PARTIAL M E
014 WebSocket gateway PARTIAL M G
015 Plugin SDK PARTIAL/ORPHAN M G
016 VizInt command center DONE — G
017 Calendar integration PARTIAL M H
018 Fireflies integration PARTIAL L H
019 Intent impact analyzer PARTIAL M C
020 Claude-code harness DONE — H
021 OpenCode integration PARTIAL M H
022 TUI interface GAP L G
023 Goal system PARTIAL L B
024 Dependency injection DONE-lib / ORPHAN-adopt S B
025 Code-gen drivers DONE S (spec) D
026 Compliance DONE — C
027 Junior volk DONE — E
028 LLM client DIVERGENCE S / M cleanup D
029 CodeDirector volk PARTIAL S E
030 Architect volk DONE S cleanup E
031 QA volk PARTIAL S–M F
032 Concierge volk DONE S (spec) F
050 CheetahClaws integration PARTIAL M G
051 VizInt UI DIVERGENCE (deprecated) — G
052 Todoist integration GAP L H
053 OpenRouter provider DIVERGENCE S D
060 Enhanced PAM++ runtime PARTIAL/GAP M–L B
061 CheetahClaws volk DIVERGENCE (→050) S F
062 CheetahClaws tools-gap GAP/meta (→063–072) S F
063 REPLTool GAP L I
064 Git worktree tools GAP M I
065 LSPTool GAP L I
066 PowerShellTool GAP M I
067 RemoteTriggerTool GAP M I
068 ScheduleCronTool GAP L I
069 Task-management tools GAP M–L I
070 Team tools GAP L I
071 MCP resource tools GAP M–L I
072 ToolSearchTool GAP M–L I
097 Testing standards PARTIAL S J
098 API standards DIVERGENCE/GAP S rewrite / L build J
099 Security & auth framework GAP M slice / L full J
100 Logging & exceptions PARTIAL M J
101 Ultimate architecture DONE — J
102 Volk test harness PARTIAL M K
103 Tool-calling refactor DONE S (opt) K
104 OpenSpec format DONE S (opt) K
105 Ontology domain model DONE (1 diverge) S (doc) K

3. Foundational gates — decisions & keystone builds (Wave 0)

Nothing large should start before these resolve. Four are decisions (need an architect call — fast, no code) and four are keystone builds (small, high-leverage, each unlocks a swarm).

Decisions — ✅ RESOLVED in session 195 (full record: 01-DECISIONS.md)

ID Decision Gates ✅ Resolution
D1 Canonical orchestration engine: live fixed PipelineRunner vs generic Kernel/IntentBroker/AgentCoordinator/kernel.SessionManager 001, 003, 005, 006 PipelineRunner canonical; QUARANTINE the 0-ref generics to experimental/ (preserve, don't delete). Wave-3 cleanup + spec-text update.
D2 Goal-system + session controller: 3 goal impls (claude/tools/session CLI is LIVE, _goals.py, PM goal_registry) and 3 session impls 023, 006 BUILD the in-product runtime goal capability (volks set/track/evaluate at runtime) → new swarm S9 Helmsman (L); also closes the 009 goal-injection gap. Dev CLI stays separate tooling.
D3 Verification U:Vfy: wire the orphaned multi-tier subsystem into the pipeline, or retire it 007b, 005 WIRE it into the pipeline — multi-tier verification is a product goal → new swarm S10 Sentinel (L).
D4 Observability deps: opentelemetry-* + structlog are declared-but-unused — wire or prune 100, S3 PRUNE now (S8 Scribe); re-add with wiring when SPEC-100 observability is scoped (S3).
D5 Security scope (SPEC-099): which of MFA/OAuth/encryption/lockout/hash-chain fit this deployment model 099 INTERNAL/TRUSTED — keep JWT+PAM++; re-spec 099 down (no security build). S3 shrinks; 099 → S8 Scribe.

Plan deltas from the decisions: two new build swarms — S9 Helmsman (in-product goals, from D2) and S10 Sentinel (wired verification, from D3) — join the roster; the SPEC-099 security build is removed (D5); D1 orphans are quarantined in Wave 3. See §6–§7 and 01-DECISIONS.md.

Keystone builds (small, unlock the parallel swarms)

ID Build Unlocks Effort Status (session 195)
K1 — Gateway HTTP surface FastAPI/HTTP alongside the WS gateway: /health /ready /metrics + http_port/health_enabled config 014, 060 (middleware/451/metrics), 098, 099 (auth endpoints), 052 (webhooks), 100 (/metrics) M ✅ done (b69f8abd)
K2 — Unified tool framework tools/base.py (BaseTool, ToolMetadata) + tools/registry.py (ToolRegistry), bridged to the existing function-tool registry all of 063–072 M ✅ done (b1b9380b)
K3 — Persistent DI memory engine DI-resolved singleton IMemoryEngine subscribed to session.closed on the EventBus 010 (migrate_to_cold, DI), 024 (adoption), 011 (audit via same hook), 060 (enforcement reaches engine) M ⏳ pending — needs a lifecycle-ownership decision (where the singleton lives / who bootstraps the DI container)
K4 — CLI entry scaffold orchestrata console_scripts entry + Click subcommand pattern 000 verbs, 015 plugin CLI, 022 TUI S ✅ done (e9a32df2)

K1–K4 are independent of each other → the four keystones can be built concurrently.

Session-195 execution progress: K1/K2/K4 landed + verified. Also done: D4 dep-prune (376c2abf) and a bonus fix — the scaffolded-but-unbuilt stage retry loop in the VizInt PipelineRunner, plus the _is_retryable FileNotFoundError ordering bug (596ad4e8). K3 remains and is the entry to swarm S2 Mnemosyne; its lifecycle-ownership decision is the next open call.

4. Cross-spec dependency graph

Diagram projects-orchestrata-ultimate-plans-spec-audit-00-MASTER-PLAN-m270bd7fdc8

Hard dependency edges (the ones that force ordering):

Blocked work Requires Why
063–072 (all tools) K2 tool framework No BaseTool/ToolRegistry exists; tools have nothing to register against.
072 ToolSearch 063–071 present It searches the registry's populated tools.
010 migrate_to_cold + DI + 011 audit K3 persistent engine Request-scoped engines can't hold a session.closed subscription.
060 middleware/451 + 100 /metrics + 052 webhooks + 099 endpoints K1 gateway HTTP The WS-only gateway has no HTTP surface to mount these on.
000 verbs + 015 plugin CLI + 022 TUI K4 CLI scaffold No orchestrata console entry to hang subcommands on.
000 intent/respond/review/approve S2 + S3 partial Those verbs call the gateway, governance, session, knowledge subsystems.
Delete 001/003/005/006 orphans D1, D2 Can't remove duplicates until the canonical is declared.
013 UX validation reaches into 031 QA ux_design must be carried PM→UX→Ar→Cd→Junior→QA and QA gains a wireframe check.

Independent from everything (can start immediately): S5 Guild (volk-internal: 012/013/019/029/031) and S8 Scribe (spec-text updates for all divergences + dead-dep pruning) have no keystone dependency.

5. Parallelism analysis

Maximum concurrency ≈ 10 swarms once the keystones land (S1–S10; +2 from the D2/D3 build decisions). The critical path is K1/K3 → S2/S3 → S4 (CLI verbs), because SPEC-000's real verbs depend on the gateway, memory, governance, and session subsystems being wired. S9 Helmsman and S10 Sentinel are independent L tracks that start on existing subsystems (session 006 / CXP 004).

Internal parallelism inside swarms:

6. The swarms (implementation clusters)

Each swarm is an independent implementation track — a cluster that can be handed to one agent team and run concurrently with the others. Named for legibility.

S1 · Toolsmith — greenfield tool suite (063–072)

S2 · Mnemosyne — memory, DI adoption & governance persistence

S3 · Gatekeeper — gateway HTTP + observability + runtime governance surface

S4 · Interface — CLI verbs, plugin CLI & TUI

S5 · Guild — volk completion (no external deps)

S6 · Bridge — external integrations

S7 · Medic — self-healing test harness (SPEC-102)

S8 · Scribe — spec-hygiene, docs & dead-dep pruning (fully parallel, ~no code)

S9 · Helmsman — in-product runtime goal system (new — from D2)

S10 · Sentinel — multi-tier verification wired into the pipeline (new — from D3)

7. Execution order (waves)

Wave 0  ✅ decisions done → build keystones ∥   K1 gateway-HTTP ‖ K2 tool-framework ‖ K3 DI-memory ‖ K4 CLI-scaffold
Wave 1  (open immediately)               S5 Guild ‖ S8 Scribe ‖ S1 Toolsmith(after K2) ‖ S7 Medic(CXP+repair volks)
                                         ‖ S9 Helmsman(session 006) ‖ S10 Sentinel(CXP 004 + pipeline)
Wave 1.5(after their keystone)           S2 Mnemosyne(after K3) ‖ S3 Gatekeeper(after K1)
Wave 2  (after upstream swarms)          S6 Bridge(after K1) ‖ S4 Interface: 015+022 after K4; 000 verbs after S2+S3
Wave 3  (tail cleanup)                   quarantine D1 orphans → experimental/ ‖ refresh SPEC_INVENTORY ‖ regenerate RTM+AST

Recommended first moves (highest leverage, low risk): (D1–D5 now resolved — see 01-DECISIONS.md)

  1. Build keystones K1–K4 in parallel (four small, independent enablers).
  2. Kick off S5 Guild and S8 Scribe immediately (no prerequisites) to retire spec-debt (incl. the D4 dep-prune, D5 099 re-spec) and finish the volks while the keystones land.
  3. Stand up the two decision-driven build swarms S9 Helmsman (in-product goals) and S10 Sentinel (wired verification) — both L, both start on existing subsystems (session 006 / CXP 004).

Guardrails on every swarm (SPEC-097/100/101): real infra only (no mocks/fakes/doubles); no pytest-xdist (batched/threadpool runner); function-scope fixtures; absolute imports; core.logging

8. What is genuinely DONE (no work — for confidence)

SPEC-002, 004, 016, 020, 025, 026, 027, 030, 032, 101, 103, 104, 105 are implemented and wired (some carry only an S spec-text tidy). The multi-agent pipeline, CXP protocol, Postman routing, KG semantic layer, compliance gate, junior/architect/concierge volks, VizInt command center, the Claude-code harness, and the three newest capabilities (refactor / OpenSpec / ontology-codegen) are real and tested against live infrastructure.