Knowledge Wiki Orchestrata Ultimate

Orchestrata Ultimate › Plans › decisions-2026-07-06

Decision Register Rulings — 2026-07-06

Source: plans/decisions-2026-07-06.md at 8a2cb42ad · last changed 2026-08-10 · first committed 2026-07-05 · 267 lines.

Prose pending.

Plan text

Decision Register Rulings — 2026-07-06

Ruled by the orchestrator under Mohamed's directive: "make the D1-D10 decisions per the evidence recommendations favouring the specs; if there are more complete implementations elsewhere where they shouldn't be, consolidate and refactor." Evidence: plans/evidence/d1..d4-*.md + session-201 findings. Each ruling names its executing task.

D1 — PipelineRunner ownership → ORCHESTRATOR ENGINE SURVIVES

orchestrator/pipeline_runner.py is the product engine (owns the gateway live path, session CLI, TUI; SPEC-003 US4-traced dynamic routing). It must ABSORB the kernel engine's real capabilities before the kernel engine retires: checkpoint persistence (implement backlog #38 for real — the docstring promise), KG-sync mixin behavior, escalation. kernel/pipeline.py demotes to the out-of-process boot/registration shim (SPEC-001 scope: boot/registry, not execution); its false "Sole orchestrator" docstring is corrected immediately. kernel/workflow_engine.py (992 LOC, no @traces, no spec, 0 product consumers) is DELETED with its 3 unit test files. → W3.1 (staged: docstring+delete now; absorb+retire designed next).

D2 — Traceability canon → core/base/traces.py; consolidate engines

Canonical decorator: core/base/traces.py (444 importers, layer-0). All four redefining modules stop redefining traces() and alias the canonical (unifies the 3-way REQ-regex divergence at the source). Fix the Arabic-corrupted RTM header NOW. core/tracing/traceability.py becomes a re-export shim of core/traceability → deleted once its 2 importers (session/kg_sync/_common.py, _stage_docs.py) repoint. Fix the 2 broken core.traceability.traceability_utils imports in rtm/scripts. FORK RESOLUTION (spec-favouring: the copy-into-generated- projects contract is the documented spec of traceability_utils): traceability_utils stays PHYSICALLY SELF-CONTAINED as the copy-target; production consumers that wrongly import it (compliance/_pipeline.py ×4, rtm/scripts/generate_rtm.py ×3) repoint to verification/traceability.py (same Requirement/RTMReport API, already on the canonical decorator). → W3.2.

D3 — Twins → mechanical collapses EXECUTE; unwired-but-complete WIRE per spec

Mechanical (pack sequence 1-5): delete postman_types.py, analyst mixins ×2, architect dead mixins ×3 (+5 dead test files, assertions diffed first), package senior_dev, ErrorHandler collapse with @traces UNION onto core/patterns survivor. Decision items — per the consolidate-don't-delete directive:

D4 — DI → OPTION (b): shrink to plugin+gateway scope; bless explicit wiring

Adoption evidence decisive (8/9 roots bypass; flagship FR-008 is a stub falsely RTM-VERIFIED). Spec-favouring is satisfied by an HONEST SPEC REWRITE: SPEC-024 FR-008/FR-012 descoped with rationale (hierarchy never load-bearing; ERR-009 removed), container documented as the plugin/gateway assembly mechanism. Delete dead agents/di.py, get_with_parent stub, with_components() private-mutation path. Add architecture_checker rule: no new DIContainer() outside plugin/gateway; composition roots use explicit ctor/setter wiring. Chase the shutdown() _context-vs-_singletons question during execution. → W3.4.

D5 — Root junk → UNTRACK reviews/; DELETE port_all.sh + 'Read ux/' after diff

reviews/: git rm -r --cached the 359 tracked files (honors the existing .gitignore intent; files stay on disk). port_all.sh: the Stage-2 port completed 2026-04 — delete. Read ux/: diff volk.py against the canonical ux volk first; if subset/stale-copy → delete; if it contains unique logic → salvage diff into the canonical volk, then delete. → W2.2/W2.3.

D6 — Codebase-map tier → RATIFIED two-tier (implemented f279a801)

31K-token @import header + 263K on-demand CODEBASE_MAP_FULL.md. Evidence: 4 agent deaths + rate-limit storm in one night. Revert path documented in the hook header.

D7 — Lazy-import layer fixes → CODIFY as accepted pattern + visibility

Documented-accepted in architecture-standards.md; architecture_checker gains an INFO-level count of function-scoped cross-layer imports (visibility without blocking). Protocol-extraction listed as an improvement item, not a gate. → W3.5.

D8 — Volk tool-loop rollout → Ar, Cd, Qa first; staged; harness-gated

One volk per builder task, existing AGENT_TOOLS allowlists are the per-volk tool sets, single-shot→multi-turn behavior change lands with test updates + a harness scenario run per volk before the next volk starts. → W4.3.

D9 — VolkContextInjector → CONSOLIDATE into the live injection path

SPEC-009's acceptance criteria (now checklist REQ-009-US-001..006) describe task-type-specific context (BUILD/REFACTOR/DEBUG/DOCUMENT/TEST/REVIEW) — which is exactly what the orphaned VolkContextInjector implements and the live ContextInjector lacks. Spec-favouring: merge VolkContextInjector's task-type handlers into the live volk-execution injection path (wire, don't delete); delete whichever shell remains after the merge. → W4.4.

D10 — SPEC-028 → implement the sentinel; profiles authoritative for models

REQ-028-021/028 describe a 'default' sentinel fallback — IMPLEMENT it in llm/config.py + spike-profiles.yaml (spec wins over code). Model-assignment divergence: spike-profiles.yaml is operational config — UPDATE the spec's model table to declare profiles authoritative (spec kept truthful, TEST-028-017 assertion updated to match the contract not the literal model id). → W5.3 tail.

D11 — Context semantic layer: selection is DETERMINISTIC (user directive 2026-07-06)

The LLM never drives node selection. Pipeline: (1) REQUEST ANALYSIS — deterministic task-type classification (reuse the intent/work-type parsers: orchestrator intent parsing, PipelineRouter work_type routing) + deterministic entity linking (exact/ normalized name match of request terms against KG node names: Module/Class/ Function/Spec/Requirement); (2) SELECTION — parameterized query templates per task-type (generalizing SPEC-009's six deterministic handlers) with deterministic ranking: graph distance from linked entities, trace-link degree, test coverage, recency — NO LLM scoring anywhere; (3) PACKING — reproducible token budgeter (greedy by rank under explicit budget; same request + same graph = same pack, byte-stable modulo timestamps); (4) the LLM consumes the pack and may EXPAND via tools (ast_query, kg queries) on demand, and the orchestrator/human can TRIM/EDIT the pack file before injection. Applies to W8.2 design, W8.4 selector/packer, W8.5 integrations.

D1-addendum — W3.1 absorption ruling (2026-07-06, evidence: W3.1-map)

CHECKPOINT: MOVE now — orchestrator PipelineRunner constructs kernel's PipelineCheckpoint (zero kernel-engine coupling; session/cli/pipeline.py already imports it cross-package), _run_stage saves after RESOLVED, and an orchestrator resume() reconstructs from PipelineRouter.route() order. This implements backlog #38 for real. KG: MOVE now — mix PipelineKGMixin into the orchestrator runner; adapt call sites from CXP packet shape to StageSpec/ StageResult (mixin body unchanged; tests port unchanged). ARTIFACTS: ALREADY-PRESENT — traces-union REQ-001-901/911 onto orchestrator/ artifact_store.py + the runner artifact block; kernel's stringly-typed store is NOT moved. ESCALATION: DEFERRED to its own designed pass — capability-mesh free-hop routing vs router-driven fixed sequence is a real design fork that changes live gateway control flow; kernel retains escalation and kernel/pipeline.py does NOT fully demote until that pass lands. Layer check verified: kernel/orchestrator/session all layer-4, no peer restriction, no cycles (kernel pipeline modules import nothing from orchestrator).

D1-addendum-2 — Escalation absorbs as an INTERRUPT (2026-07-06)

The capability-mesh-vs-fixed-router fork resolves by reframing: escalation is the exception path, not a routing mode. Escalate = checkpoint(ESCALATED) + suspend; approve = resume from next stage; reject/respond = re-enter same stage with feedback (REQ-000-056); needs_capability = bounded provider-stage INSERTION into the remaining sequence (depth-capped, cycle-guarded), not free-hop. Port the kernel mixin's approval workflow + guards to orchestrator/pipeline_escalation.py with traces-union; kernel keeps its copy until proven; kernel/pipeline.py demotes afterward. Full design: plans/design-escalation-absorption-2026-07-06.md.

D12 — Unified persistence layer (user ruling, 2026-07-06)

Ruling: All persistence access (Neo4j, Redis, and any future store) goes through ONE unified layer. No subsystem creates drivers/clients directly.

Evidence: 24 src modules call GraphDatabase.driver(...)/Neo4jClient(...) directly, 23 create Redis clients directly, only 22 use the existing core/neo4j_factory / core/redis_factory; core/base/repository.py exists but is nearly unused. The W8.1 inventory documented 6 uncoordinated KG writers with divergent merge keys (Session x3, Volk x3, Requirement x2). Test-side symptom: 233/1108 test modules bind to real infrastructure through ad-hoc client construction.

Design shape (extends SPEC-106, which is the graph half of this):

  1. Connection ownership: one process-wide Neo4j driver pool + Redis client, built by the core factories from env config (per-worker test mapping NEO4J_URI_GW respected automatically since it flows through the same env).
  2. Canonical identity: SPEC-106 FR-001 (single DDL source, <relpath>::<qualname> identity, merge-key canon) becomes the graph contract of this layer.
  3. Repositories per aggregate (SessionRepo, VolkRepo, RunRepo, RequirementRepo, MemoryStore, QueueStore, AuditWriter): subsystems depend on interfaces from core/base/repository.py, never on drivers. The 6 KG writers converge into ONE graph writer service.
  4. Machine enforcement: architecture_checker + a ratchet gate forbid GraphDatabase.driver( / redis.Redis( / Redis.from_url( outside the persistence layer — start at current counts (24/23) and ratchet to 0, same mechanism as the pyright ratchet.

Phasing: P1 funnel everything through the factories (mechanical, ratchetable); P2 single canonical KG writer (= W8.3); P3 aggregate repositories (with W8.5 integrations). Lazy connection acquisition throughout — fixes the eager verify_connectivity tax on PipelineRunner construction as a side effect.

D13 — Orphan-audit rulings (2026-07-06, evidence: 128-module audit)

Fresh module-granularity audit (auditor agent; artifacts in scratchpad): 128 true orphans = 10 entrypoints + 1 dynamic + 9 shims + 4 DEAD + 96 FLAG (implemented+traced+tested, zero production wiring, ~26K LOC).

Ruled now:

  1. DELETE architect/context_builder.py + architect/project_init.py — superseded twins of the wired architect_context.py/architect_project.py, 0 @traces, stale.
  2. UX js_mixin.py + ux_js_scaffold.py: DELETE unless specs mandate UX JS scaffolding (executor must check specs 000/vizint-ui first; if mandated, WIRE js_mixin into UXVolk instead and report the gap).
  3. WIRE claude_code_driver into drivers/driver_factory.py (one-line gap — every sibling driver is registered).
  4. WIRE OpenAIAdapter into llm/client.py routing (AnthropicAdapter sibling already wired).
  5. EXECUTE D3's unexecuted ruling on kernel/router.py (CXPRouter): consolidate into live cxp/router.py or kernel/dispatcher.py, delete file.
  6. Entrypoint orphans get a one-line docstring note (never imported — process entrypoints); knowledge_graph/sync notes its importlib loader.

Ruled 2026-07-06 (user): WIRE, not retire. Retirement was wrongly framed from the D1-D10 twin precedent; these are not twins — they are the ONLY implementations of active spec mandates. Built-to-spec, tested code whose defect is that nothing constructs it gets wired, period. Retirement of spec-mandated capability would be a spec-supersession product decision, which only the user makes — and the user ruled the opposite.

D16 — Verification wiring: stage plan + G226 reconciliation (2026-07-06)

D14 auditor delivered the SPEC-007b wiring plan. Accepted stages: A) audit-only "Gate 4: Constraint verification" in QA volk (mirrors the D3 PolicyEvaluator staged-wiring precedent exactly: config-flagged, degrade-to-None, never blocks) — requirements_parser → VerificationEngine (NOT the hollow VerificationCoordinator), Redis via core.redis_factory; B) author prolog/verification.pl from specs/035-verification/prolog-rules.md and FIX ConstraintEvaluator to actually consult its prolog_bridge (today it stores and ignores it — violates spec Key Principle #1); C) max_attempts 3→5 (spec immutable constant) + VerificationSession ESCALATED → EscalationInterruptMixin (the D1-addendum-2 transport); D) replace the four hardcoded model-wrapper stubs (opus/deepseek_r1/ qwen_max/grok4_minimax verify() returns canned "verified") with real llm.client.call_llm() — their current tests assert stub output and prove nothing; test-writer rewrites them with the change; E) IntentConstraint→Constraint adapter method (shape drift repair).

G226 reconciliation (ruled): the spec's 5-attempt cap governs the constraint-VERIFICATION session (VerificationSession.attempt_count); QA's G226 "no cap" ruling stays for the deterministic lint/syntax/checklist loop. Two counters, two scopes, both documented intents preserved.

Deferred (scoped, not scheduled): edge_cases→_testgen enrichment (US-006), proofs/impossibility → "constraint unsatisfiable" surface (US-007, needs a design decision), U:Vfy as separately-addressable CXP volk (needs real CXPPacket rewrite of verification_cxp.py; alias reserved but unregistered).

D17 — Kernel composition bundle (2026-07-06)

The 0%-cluster audit resolved the contradiction: kernel/audit/* and kernel/pam/* are genuinely-live shim targets with real-infra tests, but OrchestrationKernel composes NONE of its spec-mandated subsystems (SPEC-001: US-003 PAM, US-007 resource monitoring, US-008 audit trail — kernel/kernel.py builds only ComponentMetadata + EventBus). Not twins of governance/gateway audit (different specs). Ruling per wire-not-retire: wire the bundle INTO OrchestrationKernel.init/start() as one wave: AuditLogger (US-008), PAMEnforcer into the dispatcher path (US-003, kernel layer; governance.prolog_gate keeps its own SPEC-007 duty over the same rules file), ResourceMonitor into the kernel health loop (US-007), performance package alongside. ONE exception: kernel/pam/escalation.py is a true superseded twin (thin wrapper over already-wired governance.escalation_handler) — fold any genuinely-new behavior (AdvancedConflict, MultiHopEscalationManager) upstream, then delete the wrapper. kernel/cli.py is a coverage artifact (lazy import), no wiring action.

Also noted: .coverage in the main tree gets clobbered by concurrent agent runs — canonical coverage numbers come only from isolated chained runs.