Orchestrata Ultimate › Plans › execution-plan

Execution Plan: Port Orchestrata → Orchestrata-Ultimate

Source: plans/execution-plan.md at 8a2cb42ad · last changed 2026-08-03 · first committed 2026-04-11 · 4636 lines.

Prose pending.

Plan text

Execution Plan: Port Orchestrata → Orchestrata-Ultimate

STATUS: DONE — Superseded by plans/stage2_port_plan.md on 2026-04-19. The bulk port is complete. Stage 2 addresses syntax errors, test failures, coverage gaps, and production readiness.

224 steps across 5 phases. ~122K LOC from 26 packages into single-package. Generated from implementation-plan.md (13 rounds of adversarial review) + deep AST comparison.

How to Use This Plan

1. Read one step. Execute it. Verify the expected output. Move to the next step.
2. If verification fails, read the "If it fails" note before proceeding.
3. Steps within a sub-phase are sequential. Sub-phases within a tier are sequential.
4. Commit only at gate checks (marked with 🚪), not after every step.
5. Every cp command copies from the frozen orchestrata source. Never modify orchestrata.
6. After every cp, apply the import translation before doing anything else.

Conventions

SRC=/home/mohamed/workspace/orchestrata/packages
ULT=/home/mohamed/workspace/orchestrata-ultimate/src/orchestrata_ultimate
TESTS=/home/mohamed/workspace/orchestrata-ultimate/tests
ORCH_TESTS=/home/mohamed/workspace/orchestrata/packages

Standard Import Translation (apply to every ported file)

Run this sed chain on every file copied from orchestrata, then apply the manual fixes listed after:

# Pass 1: Bulk sed (order matters — specific before generic)
sed -i \
  -e 's/from orchestrata\.core\.interfaces/from orchestrata_ultimate.core.protocols/g' \
  -e 's/from orchestrata\.core\.traceability_utils/from orchestrata_ultimate.core.tracing.traceability/g' \
  -e 's/from orchestrata\.core\.traceability/from orchestrata_ultimate.core.tracing.traceability/g' \
  -e 's/from orchestrata\.core\.infra_config/from orchestrata_ultimate.core.config.infra/g' \
  -e 's/from orchestrata\.core\.base\.entity/from orchestrata_ultimate.core.domain.domain_entity/g' \
  -e 's/from orchestrata\.core\.base/from orchestrata_ultimate.core.domain/g' \
  -e 's/from orchestrata\.core\.redis_factory/from orchestrata_ultimate.core.redis/g' \
  -e 's/from orchestrata\.core\.lru_cache/from orchestrata_ultimate.core.cache/g' \
  -e 's/from orchestrata\.core\.state\./from orchestrata_ultimate.core.state./g' \
  -e 's/from orchestrata\.core\.monitoring/from orchestrata_ultimate.core.metrics/g' \
  -e 's/from orchestrata\.volks\./from orchestrata_ultimate.agents.volks./g' \
  -e 's/from orchestrata\.agents\.volks\./from orchestrata_ultimate.agents.volks./g' \
  -e 's/from orchestrata\.provider\./from orchestrata_ultimate.providers./g' \
  -e 's/from orchestrata\.knowledge\./from orchestrata_ultimate.knowledge_graph./g' \
  -e 's/from orchestrata\./from orchestrata_ultimate./g' \
  "$FILE"

# Pass 2: Fix import X (no dot after orchestrata)
sed -i 's/import orchestrata\b/import orchestrata_ultimate/g' "$FILE"

Handled automatically by sed (no manual fix needed):

• from orchestrata.volks.<role> → from orchestrata_ultimate.agents.volks.<role> (line 11 of sed chain)
• from orchestrata.agents.volks.<role> → from orchestrata_ultimate.agents.volks.<role> (line 12)

NOT handled by sed — requires manual grep-and-fix:

• String literals like "orchestrata.volks.analyst.volk" in code (e.g., task_executor.py dynamic imports). Sed only matches lines with from prefix. Run:

  grep -n '"orchestrata\.\|'"'"'orchestrata\.' "$FILE" | grep -v "^#"
  

  Fix each match manually.

Standard os.environ Fix

For every os.environ["X"] in ported files, replace with os.environ.get("X", default).

Exception — required infra endpoint keys (RUL-003, standards rule 30d): these must have NO literal default and RAISE when unset. Route them through the raising seams core.graph_factory.resolve_uri/resolve_kg_database and core.redis_factory.resolve_redis_host/resolve_redis_port. Endpoints come from the active ORCHESTRATA_ENV_PROFILE (env/{dev,test,prod}.env) layered over .env secrets — never hardcode an Incus IP. The retired NEO4J_URI/NEO4J_USERNAME/NEO4J_PASSWORD keys (2026-07-27) become KG_ROUTING_URI + KG_DATABASE (the orchgraph cluster is auth-less).

Standard Verification

After porting any module X, the minimum verification is:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "from orchestrata_ultimate.X import *; print('OK')"

Phase 0: Foundation (Steps 1–38)

Goal: Fix bugs in ultimate, port orchestrata-core, set up test infrastructure, update pyproject.toml.

Sub-phase 0.1: Fix Ultimate Bugs (Steps 1–11)

Step 1: Fix wrong import path in logging_config.py

Goal: Fix broken import that references core.context instead of core.logging.context.

File: $ULT/core/logging/logging_config.py

Actions:

1. Open $ULT/core/logging/logging_config.py
2. Find the import near line 71 that reads:

   from orchestrata_ultimate.core.context import ...
   

3. Change it to:

   from orchestrata_ultimate.core.logging.context import ...
   

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "from orchestrata_ultimate.core.logging.logging_config import *; print('OK')"

Expect: OK If it fails: Check the exact import line — it may use a different form. Grep: grep -n 'core.context' $ULT/core/logging/logging_config.py

Step 2: Fix deprecated asyncio.iscoroutinefunction in error_handling.py

Goal: Replace deprecated asyncio.iscoroutinefunction with inspect.iscoroutinefunction (7 locations).

File: $ULT/core/patterns/error_handling.py

Actions:

1. Open $ULT/core/patterns/error_handling.py
2. Add import inspect at the top if not already present
3. Replace all occurrences of asyncio.iscoroutinefunction with inspect.iscoroutinefunction

   grep -n 'asyncio.iscoroutinefunction' $ULT/core/patterns/error_handling.py
   

   Should find 7 matches (lines 118, 219, 409, 456, 476, 509, 606). Replace each one.

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
import warnings; warnings.filterwarnings('error', category=DeprecationWarning)
from orchestrata_ultimate.core.patterns.error_handling import *
print('OK')
"

Expect: OK (no DeprecationWarning) If it fails: Some occurrences may use asyncio.coroutines.iscoroutinefunction — check for that variant too.

Step 3: Fix race condition in error_handling.py (circuit breaker state)

Goal: Await circuit breaker state change tasks that are currently fire-and-forget.

File: $ULT/core/patterns/error_handling.py (lines ~307 and ~348)

Actions:

1. Find lines ~307 and ~348 where circuit breaker state is changed without await
2. These lines create asyncio tasks for state transitions but don't await them
3. Change the fire-and-forget pattern:

   # Before (line ~307):
   asyncio.create_task(self._transition_to_open())
   # After:
   await self._transition_to_open()
   

4. Apply same fix at line ~348

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && uv run pytest tests/test_error_handling.py -x -q 2>/dev/null; echo "exit: $?"

Expect: Tests pass, exit code 0 If it fails: Read the exact lines — the pattern may be task = asyncio.ensure_future(...) instead.

Step 4: (VERIFIED: NOT A BUG — _active_task_ids already protected)

Original claim: Race condition in thread_pool.py:430,441 on _active_task_ids. Verified: _active_task_ids is a set[str] (line 100) and both access sites at lines 430 and 441 are ALREADY inside with self._lock: blocks (RLock).

Action: Skip this step. No fix needed.

Verify (confirm it's already safe):

cd /home/mohamed/workspace/orchestrata-ultimate && grep -n '_active_task_ids' $ULT/core/threading/thread_pool.py

Expect: All accesses are within locked sections.

Step 5: Fix memory leak in thread_pool.py (completed tasks)

Goal: Add cleanup for completed tasks when count exceeds 1000.

File: $ULT/core/threading/thread_pool.py

Actions:

1. Find the data structure that tracks completed tasks (likely a dict or set)
2. Add cleanup logic after task completion:

   # After recording task completion:
   if len(self._completed_tasks) > 1000:
       # Keep only the most recent 500
       excess = len(self._completed_tasks) - 500
       for _ in range(excess):
           self._completed_tasks.pop(next(iter(self._completed_tasks)))
   

3. If _completed_tasks is a list, use slicing: self._completed_tasks = self._completed_tasks[-500:]

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "from orchestrata_ultimate.core.threading.thread_pool import *; print('OK')"

Expect: OK

Step 6: Fix Pydantic v1 API in node.py

Goal: Migrate class Config to Pydantic v2 model_config and replace json_encoders with @field_serializer.

File: $ULT/core/domain/node.py (line ~40)

Actions:

1. Open $ULT/core/domain/node.py
2. Add imports at top:

   from pydantic import ConfigDict, field_serializer
   

3. Replace the inner class Config: block (around line 40):

   # Before:
   class Config:
       json_encoders = {datetime: lambda v: v.isoformat()}
       # ... other settings
   
   # After:
   model_config = ConfigDict(arbitrary_types_allowed=True)
   
   @field_serializer('created_at', 'updated_at', check_fields=False)
   @classmethod
   def serialize_datetime(cls, v: datetime) -> str:
       return v.isoformat() if v else None
   

4. If there are other json_encoders entries, convert each to a @field_serializer

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.core.domain.node import Node
n = Node(name='test')
print(n.model_dump())
print('OK')
"

Expect: Dict output followed by OK If it fails: Check the exact field names in the Node class — created_at/updated_at may have different names.

Step 7: Fix Pydantic v1 API in domain_entity.py

Goal: Replace .dict() calls with .model_dump().

File: $ULT/core/domain/domain_entity.py

Actions:

1. Open $ULT/core/domain/domain_entity.py
2. Replace all .dict() calls with .model_dump():

   grep -n '\.dict()' $ULT/core/domain/domain_entity.py
   

3. For each match, change .dict() to .model_dump()
4. Also check for .dict(exclude=...) → .model_dump(exclude=...)

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.core.domain.domain_entity import DomainEntity
print('OK')
"

Expect: OK

Step 8: Fix duration unrecorded in metrics decorators.py

Goal: Record actual duration in the metric that currently ignores the measured time.

File: $ULT/core/metrics/decorators.py (lines ~144-149)

Actions:

1. Open $ULT/core/metrics/decorators.py
2. Find lines 144-149 where a duration is calculated but not recorded
3. The pattern is likely:

   duration = time.time() - start_time
   # Missing: metric.observe(duration) or similar
   

4. Add the metric observation:

   duration = time.time() - start_time
   if hasattr(metric, 'observe'):
       metric.observe(duration)
   elif hasattr(metric, 'record'):
       metric.record(duration)
   

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "from orchestrata_ultimate.core.metrics.decorators import *; print('OK')"

Expect: OK

Step 9: Fix no-op cleanup in metrics_config.py

Goal: Implement the stop function that currently does nothing.

File: $ULT/core/metrics/metrics_config.py (lines ~304-307)

Actions:

1. Open $ULT/core/metrics/metrics_config.py
2. Find the stop() function around lines 304-307
3. It likely looks like:

   def stop():
       pass  # TODO
   

4. Implement actual cleanup:

   def stop():
       """Stop metrics collection and clean up resources."""
       global _metrics_initialized
       if _metrics_initialized:
           # Reset all registered metrics/collectors
           _metrics_initialized = False
   

5. Adapt based on what state variables exist in the file

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "from orchestrata_ultimate.core.metrics.metrics_config import *; print('OK')"

Expect: OK

Step 10: Fix hardcoded state in audit.py

Goal: Capture real after_state instead of hardcoded placeholder.

File: $ULT/core/logging/audit.py (lines ~376-379)

Actions:

1. Open $ULT/core/logging/audit.py
2. Find lines ~376-379 where after_state is set to a hardcoded value
3. It likely reads:

   after_state = "completed"  # or some hardcoded dict
   

4. Replace with actual state capture:

   after_state = self._capture_current_state()  # or the appropriate method
   

5. If _capture_current_state() doesn't exist, implement it based on the context of how before_state is captured earlier in the same function

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "from orchestrata_ultimate.core.logging.audit import *; print('OK')"

Expect: OK

Step 11: 🚪 Sub-phase 0.1 Gate Check

Goal: Confirm all bug fixes pass existing test suite.

Actions:

1. Run full test suite:

   cd /home/mohamed/workspace/orchestrata-ultimate && uv run pytest tests/ -x -q
   

2. All pre-existing tests must pass. Note the pass count.

Expect: All tests pass (the count was ~213-244 before changes) If it fails: Read the failure output. The bug fixes may have introduced regressions — fix before proceeding.

Sub-phase 0.2: Port orchestrata-core (Steps 12–27)

Step 12: Create core/protocols.py from orchestrata interfaces (1,231 LOC)

Goal: Port ABC interfaces to Protocol classes (PEP 544).

Source: $SRC/orchestrata-core/src/orchestrata/core/interfaces/__init__.py (1,231 LOC — this is the main file, NOT just exports) and $SRC/orchestrata-core/src/orchestrata/core/interfaces/volk.py

IMPORTANT: interfaces/__init__.py contains actual class implementations including ComponentType, HealthStatus, ComponentScope, ComponentMetadata, ServiceEndpoint, SystemEvent and all the ABC interfaces. This is NOT a simple re-export file.

Destination: $ULT/core/protocols.py

Actions:

1. Read both source files to understand all interfaces defined
2. Create $ULT/core/protocols.py
3. For each class I<Name>(ABC):, create class <Name>Protocol(Protocol)::

   from typing import Protocol, runtime_checkable, Any, Optional
   
   @runtime_checkable
   class AgentProtocol(Protocol):
       """Was IVolk — agent processing interface."""
       async def process(self, packet: 'CXPPacket') -> Optional['CXPPacket']: ...
       def set_postman(self, postman: Any) -> None: ...
       def set_kg(self, kg: Any) -> None: ...
   

4. Convert ALL ABC classes to Protocol classes
5. Apply standard import translation to any internal imports
6. Add __all__ listing all Protocol classes

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "from orchestrata_ultimate.core.protocols import *; print('OK')"

Expect: OK If it fails: Protocol classes may reference types not yet ported. Use TYPE_CHECKING imports with string annotations for forward references.

Step 13: Port traceability to core/tracing/traceability.py (509 + 1,020 LOC)

Goal: Port the @traces decorator and traceability utilities.

Source:

• $SRC/orchestrata-core/src/orchestrata/core/traceability/__init__.py (509 LOC — actual implementation, not just exports. Contains traces() decorator, collect_traces(), generate_rtm(), validate_traces())
• $SRC/orchestrata-core/src/orchestrata/core/traceability.py (top-level re-export, may be redundant)
• $SRC/orchestrata-core/src/orchestrata/core/traceability_utils.py

IMPORTANT: The traceability package's __init__.py IS the implementation. Read it first to understand the full API before merging.

Destination: $ULT/core/tracing/traceability.py

Actions:

1. Read all three source files — __init__.py has the core implementation
2. Create $ULT/core/tracing/traceability.py by merging all into one file
3. Apply standard import translation
4. Update $ULT/core/tracing/__init__.py to export traceability symbols:

   from orchestrata_ultimate.core.tracing.traceability import traces, ...
   

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "from orchestrata_ultimate.core.tracing.traceability import traces; print('OK')"

Expect: OK

Step 14: Create core/config/ subpackage

Goal: Port orchestrata's config module as a subpackage.

Source: $SRC/orchestrata-core/src/orchestrata/core/config/

Destination: $ULT/core/config/

Actions:

1. mkdir -p $ULT/core/config
   

2. Copy files:

   cp $SRC/orchestrata-core/src/orchestrata/core/config/__init__.py $ULT/core/config/__init__.py
   cp $SRC/orchestrata-core/src/orchestrata/core/config/manager.py $ULT/core/config/manager.py
   

3. Apply standard import translation to both files
4. Fix any os.environ["X"] reads

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "from orchestrata_ultimate.core.config import *; print('OK')"

Expect: OK

Step 15: Port infra_config.py to core/config/infra.py

Goal: Port infrastructure configuration with safe environment variable defaults.

Source: $SRC/orchestrata-core/src/orchestrata/core/infra_config.py Destination: $ULT/core/config/infra.py

Actions:

1. cp $SRC/orchestrata-core/src/orchestrata/core/infra_config.py $ULT/core/config/infra.py
   

2. Apply standard import translation
3. CRITICAL: Fix ALL os.environ["X"] reads (this file has the most). Replace:

   # Before:
   REDIS_HOST = os.environ["REDIS_HOST"]
   REDIS_PORT = int(os.environ["REDIS_PORT"])
   NEO4J_URI = os.environ["NEO4J_URI"]
   NEO4J_USER = os.environ["NEO4J_USERNAME"]
   NEO4J_PASSWORD = «redacted»
   
   # After (RUL-003 — required infra endpoints RAISE when unset, no literal defaults;
   # endpoints come from the active ORCHESTRATA_ENV_PROFILE via env/{dev,test,prod}.env):
   from orchestrata_ultimate.core.redis_factory import resolve_redis_host, resolve_redis_port
   from orchestrata_ultimate.core.graph_factory import resolve_uri, resolve_kg_database
   REDIS_HOST = resolve_redis_host()
   REDIS_PORT = resolve_redis_port()
   KG_URI = resolve_uri()            # replaces retired NEO4J_URI (2026-07-27)
   KG_DATABASE = resolve_kg_database()
   

4. Audit for ANY remaining bare os.environ[ calls:

   grep -n 'os\.environ\[' $ULT/core/config/infra.py
   

   Result must be 0 matches.

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "from orchestrata_ultimate.core.config.infra import *; print('OK')"

Expect: OK (no KeyError even without env vars set) If it fails: A KeyError means a bare os.environ["X"] was missed. Grep and fix.

Step 16: Port adapters/claude/

Goal: Port Claude adapter hooks and tool interceptor.

Source: $SRC/orchestrata-core/src/orchestrata/core/adapters/claude/ Destination: $ULT/adapters/claude/

Actions:

1. mkdir -p $ULT/adapters/claude
   cp $SRC/orchestrata-core/src/orchestrata/core/adapters/__init__.py $ULT/adapters/__init__.py
   cp $SRC/orchestrata-core/src/orchestrata/core/adapters/claude/__init__.py $ULT/adapters/claude/__init__.py
   cp $SRC/orchestrata-core/src/orchestrata/core/adapters/claude/hooks.py $ULT/adapters/claude/hooks.py
   cp $SRC/orchestrata-core/src/orchestrata/core/adapters/claude/tool_interceptor.py $ULT/adapters/claude/tool_interceptor.py
   

2. Apply standard import translation to all 4 files

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "from orchestrata_ultimate.adapters.claude import *; print('OK')"

Expect: OK

Step 17: Merge monitoring/ into core/metrics/

Goal: Port monitoring engine and spans into ultimate's existing metrics package.

Source: $SRC/orchestrata-core/src/orchestrata/core/monitoring/ (engine.py, spans.py) Destination: $ULT/core/metrics/ (merge into existing)

Actions:

1. Read $SRC/orchestrata-core/src/orchestrata/core/monitoring/engine.py and spans.py
2. Read existing $ULT/core/metrics/metrics_config.py and decorators.py to avoid conflicts
3. Copy non-conflicting code:

   cp $SRC/orchestrata-core/src/orchestrata/core/monitoring/engine.py $ULT/core/metrics/monitoring_engine.py
   cp $SRC/orchestrata-core/src/orchestrata/core/monitoring/spans.py $ULT/core/metrics/spans.py
   

4. Apply standard import translation to both new files
5. Update $ULT/core/metrics/__init__.py to export new symbols

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "from orchestrata_ultimate.core.metrics.monitoring_engine import *; print('OK')"

Expect: OK

Step 18: Port base/ modules into core/domain/

Goal: Merge orchestrata's base entity, error, repository, and service into ultimate's domain package.

Source: $SRC/orchestrata-core/src/orchestrata/core/base/ (entity.py, error.py, repository.py, service.py) Destination: $ULT/core/domain/

Actions:

1. Read existing $ULT/core/domain/domain_entity.py — it already has DomainEntity (which maps from BaseEntity)
2. Do NOT overwrite domain_entity.py. Instead port only the pieces missing from ultimate:
   • from_dict(), to_dict(), touch() methods from entity.py — add to DomainEntity if useful
3. Port the other base files:

   cp $SRC/orchestrata-core/src/orchestrata/core/base/error.py $ULT/core/domain/error.py
   cp $SRC/orchestrata-core/src/orchestrata/core/base/repository.py $ULT/core/domain/repository.py
   cp $SRC/orchestrata-core/src/orchestrata/core/base/service.py $ULT/core/domain/service.py
   

4. Apply standard import translation
5. In each file, change from orchestrata.core.base.entity import BaseEntity to from orchestrata_ultimate.core.domain.domain_entity import DomainEntity
6. If classes inherit from BaseEntity, change to inherit from DomainEntity
7. Update $ULT/core/domain/__init__.py

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "from orchestrata_ultimate.core.domain import DomainEntity; print('OK')"

Expect: OK

Step 19: Port redis_factory.py → core/redis.py

Goal: Port Redis factory with in-memory fallback.

Source: $SRC/orchestrata-core/src/orchestrata/core/redis_factory.py Destination: $ULT/core/redis.py

Actions:

1. cp $SRC/orchestrata-core/src/orchestrata/core/redis_factory.py $ULT/core/redis.py
   

2. Apply standard import translation
3. Fix os.environ["REDIS_HOST"] → resolve_redis_host() (RUL-003 raising seam — no literal default) etc.
4. Add in-memory fallback if not present:

   def create_redis_client(url: str | None = None):
       if url:
           try:
               import redis
               return redis.Redis.from_url(url)
           except (ImportError, Exception):
               pass
       return InMemoryRedis()  # Fallback
   

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "from orchestrata_ultimate.core.redis import *; print('OK')"

Expect: OK

Step 20: Port state/ → core/state.py

Goal: Port state management module.

Source: $SRC/orchestrata-core/src/orchestrata/core/state/ (state_manager.py) Destination: $ULT/core/state.py

Actions:

1. cp $SRC/orchestrata-core/src/orchestrata/core/state/state_manager.py $ULT/core/state.py
   

2. Apply standard import translation
3. Fix any os.environ["X"] reads

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "from orchestrata_ultimate.core.state import *; print('OK')"

Expect: OK

Step 21: Port standards.py

Source: $SRC/orchestrata-core/src/orchestrata/core/standards.py Destination: $ULT/core/standards.py

Actions:

1. cp $SRC/orchestrata-core/src/orchestrata/core/standards.py $ULT/core/standards.py
   

2. Apply standard import translation

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "from orchestrata_ultimate.core.standards import *; print('OK')"

Expect: OK

Step 22: Port lru_cache.py → core/cache.py

Source: $SRC/orchestrata-core/src/orchestrata/core/lru_cache.py Destination: $ULT/core/cache.py

Actions:

1. cp $SRC/orchestrata-core/src/orchestrata/core/lru_cache.py $ULT/core/cache.py
   

2. Apply standard import translation

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "from orchestrata_ultimate.core.cache import *; print('OK')"

Expect: OK

Step 23: Port enums.py and paths.py

Source: $SRC/orchestrata-core/src/orchestrata/core/enums.py and $SRC/orchestrata-core/src/orchestrata/core/paths.py Destination: $ULT/core/enums.py and $ULT/core/paths.py

Actions:

1. cp $SRC/orchestrata-core/src/orchestrata/core/enums.py $ULT/core/enums.py
   cp $SRC/orchestrata-core/src/orchestrata/core/paths.py $ULT/core/paths.py
   

2. Apply standard import translation to both

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "from orchestrata_ultimate.core.enums import *; from orchestrata_ultimate.core.paths import *; print('OK')"

Expect: OK

Step 24: Port domain/enums/ subdirectory

Source: $SRC/orchestrata-core/src/orchestrata/core/domain/enums/ Destination: $ULT/core/domain/enums/

Actions:

1. mkdir -p $ULT/core/domain/enums
   cp $SRC/orchestrata-core/src/orchestrata/core/domain/enums/__init__.py $ULT/core/domain/enums/__init__.py
   cp $SRC/orchestrata-core/src/orchestrata/core/domain/enums/fact_scope.py $ULT/core/domain/enums/fact_scope.py
   

2. Apply standard import translation to both files

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "from orchestrata_ultimate.core.domain.enums import *; print('OK')"

Expect: OK

Step 25: Port graph_directives.py

Source: $SRC/orchestrata-core/src/orchestrata/core/graph_directives.py Destination: $ULT/core/graph_directives.py

Actions:

1. cp $SRC/orchestrata-core/src/orchestrata/core/graph_directives.py $ULT/core/graph_directives.py
   

2. Apply standard import translation

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "from orchestrata_ultimate.core.graph_directives import *; print('OK')"

Expect: OK

Step 26: Update core/init.py with new exports

Goal: Ensure all newly ported core modules are accessible.

File: $ULT/core/__init__.py

Actions:

1. Read current $ULT/core/__init__.py
2. Add exports for all new modules. The __init__.py should have:

   from orchestrata_ultimate.core.protocols import *
   from orchestrata_ultimate.core.standards import *
   from orchestrata_ultimate.core.enums import *
   from orchestrata_ultimate.core.cache import *
   from orchestrata_ultimate.core.state import *
   # Don't re-export config, metrics, tracing, domain — they're subpackages
   

3. Ensure __all__ is defined if star imports are used

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.core.protocols import *
from orchestrata_ultimate.core.config.infra import *
from orchestrata_ultimate.core.tracing.traceability import traces
from orchestrata_ultimate.core.cache import *
from orchestrata_ultimate.core.state import *
from orchestrata_ultimate.core.standards import *
from orchestrata_ultimate.core.enums import *
from orchestrata_ultimate.core.domain import DomainEntity
print('ALL CORE OK')
"

Expect: ALL CORE OK If it fails: The failing import tells you which module has issues. Fix that module first.

Step 27: 🚪 Sub-phase 0.2 Gate Check

Goal: All core modules import cleanly and existing tests still pass.

Actions:

1. Run import verification from Step 26
2. Run full test suite:

   cd /home/mohamed/workspace/orchestrata-ultimate && uv run pytest tests/ -x -q
   

3. Confirm pass count is >= the count from Step 11

Expect: Same or more tests passing than after Step 11 If it fails: New core modules may have side effects at import time. Check for module-level code that accesses external services.

Sub-phase 0.3: Port Test Infrastructure (Steps 28–35)

Step 28: Port root conftest.py (with isolation enforcement)

Goal: Merge orchestrata's test configuration into ultimate's conftest, REMOVING all isolation violations.

Source: /home/mohamed/workspace/orchestrata/tests/conftest.py (~338 LOC) Destination: $TESTS/conftest.py (merge into existing)

Actions:

1. Read orchestrata's root conftest.py
2. Read ultimate's existing $TESTS/conftest.py — it already has isolation, test_id, enforce_test_isolation fixtures. Keep ALL of these.
3. From orchestrata's conftest, port ONLY:
   • pytest_collection_modifyitems hook (auto-markers)
   • pytest_configure marker registration
   • Factory fixture registrations
4. DO NOT PORT these violation patterns from orchestrata's conftest:
   • _prolog_cleanup_counter global (line ~65) — REMOVE
   • _prolog_stack_limit_set global (line ~70) — REMOVE
   • Any scope="module" fixtures — DOWNSCOPE to function
   • Bare os.environ["X"] reads — pass values explicitly (monkeypatch is BANNED); required infra endpoints resolve via the RUL-003 raising seams against the pinned env/test.env
5. Add Prolog fixture as per-test (not global):

   @pytest.fixture
   def prolog_engine():
       """Per-test Prolog engine — no global singleton."""
       try:
           from pyswip import Prolog
           engine = Prolog()
           yield engine
       except ImportError:
           pytest.skip("pyswip not available")
   

6. Apply standard import translation to all ported code

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && uv run pytest --co -q 2>/dev/null | tail -3
# Also verify no globals:
grep -n '^_[a-zA-Z].*= ' $TESTS/conftest.py

Expect: Shows collected test count. No module-level mutable globals in conftest.

Step 29: Port tests/fixtures/ (with parallel-safety fixes)

Goal: Port test fixtures for Redis, Neo4j, temp directories, Prolog — ensuring all are parallel-safe.

Source: /home/mohamed/workspace/orchestrata/tests/fixtures/ Destination: $TESTS/fixtures/

Actions:

1. mkdir -p $TESTS/fixtures
   cp /home/mohamed/workspace/orchestrata/tests/fixtures/*.py $TESTS/fixtures/
   

2. Apply standard import translation to all files
3. CRITICAL — Redis fixture (redis.py):
   • Downscope from scope="session" to scope="function" — session scope causes cross-test data pollution
   • Keep the per-worker DB isolation logic (_worker_redis_db()) — it's correct
   • Replace client.flushdb() cleanup with per-test key deletion using test_id prefix
4. CRITICAL — Neo4j fixture (neo4j.py):
   • Keep the per-test test_id cleanup pattern — it's already correct
   • Downscope async_neo4j_driver from session to function if present
   • Ensure ALL node creation includes test_id property
5. CRITICAL — Prolog fixture (prolog.py):
   • Remove any global Prolog() instantiation
   • Create per-test instances only (see Step 28 prolog_engine fixture)
6. Fix ALL os.environ["X"] reads — pass values explicitly (monkeypatch is BANNED); infra endpoints via the RUL-003 raising seams
7. Verify no module-scope fixtures remain:

   grep -n 'scope="module"\|scope="session"\|scope="class"' $TESTS/fixtures/*.py
   

   scope="session" is OK ONLY for read-only driver creation (connection pool). NOT for data fixtures.

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "from tests.fixtures import *; print('OK')" 2>/dev/null || echo "Check"

Step 30: Port tests/factories/

Goal: Port test factories used by 86+ test files.

Source: Find tests/factories/ in orchestrata Destination: $TESTS/factories/

Actions:

1. mkdir -p $TESTS/factories
   

2. Locate factory files:

   find $SRC/.. -path "*/tests/factories/*.py" -not -path "*/__pycache__/*"
   

3. Copy all 8 modules: agents.py, cxp.py, governance.py, intent.py, knowledge.py, postman.py, session.py, init.py
4. Apply standard import translation to all files
5. Many factories will reference types not yet ported (CXPPacket, Intent, etc.) — add # type: ignore or try/except ImportError with placeholder for now. These will resolve as Tier 1+ modules are ported.

Verify:

ls $TESTS/factories/*.py | wc -l

Expect: 8 files

Step 31: Port tests/infrastructure.py

Goal: Port centralized test config with safe environment defaults.

Source: Find tests/infrastructure.py in orchestrata Destination: $TESTS/infrastructure.py

Actions:

1. Locate and copy:

   find $SRC/.. -name "infrastructure.py" -path "*/tests/*" -not -path "*/__pycache__/*"
   

2. Copy to $TESTS/infrastructure.py
3. Apply standard import translation
4. CRITICAL: Fix ALL os.environ["X"] reads to use .get() with defaults

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "from tests.infrastructure import *; print('OK')" 2>/dev/null || echo "Check"

Step 32: Port conftest_infra_gate.py

Goal: Port infrastructure health check conftest.

Source: Find conftest_infra_gate.py in orchestrata tests Destination: $TESTS/conftest_infra_gate.py

Actions:

1. Locate and copy
2. Apply standard import translation
3. CRITICAL: Fix bare os.environ["REDIS_HOST"] reads (lines ~30-34) to .get() with defaults

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "import tests.conftest_infra_gate; print('OK')" 2>/dev/null || echo "Check"

Step 33: Set up auto-markers and pytest plugins

Goal: Configure pytest auto-markers for requires_redis, requires_neo4j, etc.

Actions:

1. In $TESTS/conftest.py, add or verify the pytest_collection_modifyitems hook:

   def pytest_collection_modifyitems(config, items):
       for item in items:
           # Auto-mark tests based on fixtures they request
           if "redis_client" in item.fixturenames:
               item.add_marker(pytest.mark.requires_redis)
           if "neo4j_client" in item.fixturenames:
               item.add_marker(pytest.mark.requires_neo4j)
           if "prolog" in item.fixturenames:
               item.add_marker(pytest.mark.requires_prolog)
   

2. Register markers in pyproject.toml under [tool.pytest.ini_options]:

   markers = [
       "requires_redis: test needs Redis",
       "requires_neo4j: test needs Neo4j",
       "requires_prolog: test needs SWI-Prolog",
   ]
   

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && uv run pytest --markers 2>/dev/null | grep requires_redis

Expect: Shows requires_redis marker

Step 33b: Audit and fix os.environ in ALL test files

Goal: 107 bare os.environ["X"] reads exist across 26 test files in orchestrata. Fix them during port.

Actions:

1. After porting each conftest/fixture/factory, run:

   grep -rn 'os\.environ\[' $TESTS/ --include="*.py" | grep -v '\.get('
   

2. Fix every match to use .get() with defaults (see Appendix B)
3. Key files with the most reads:
   • tests/kernel/test_config_manager.py — 20 reads
   • tests/postman/test_postman_config.py — 18 reads
   • tests/core/test_config_manager_unified.py — 15 reads
   • tests/conftest_infra_gate.py — 6 reads
   • tests/knowledge/test_real_neo4j_knowledge.py — 5 reads
4. Note: QA volk tests may have os.environ in f-strings generating test code — these are string literals, not actual reads. Leave those as-is.

Verify:

grep -rn 'os\.environ\[' $TESTS/ --include="*.py" | grep -v '\.get(' | grep -v "f'" | grep -v 'f"' | wc -l

Expect: 0

Step 34: Port per-directory conftest.py files (skeleton)

Goal: Create placeholder conftest.py files for test directories that will be populated in later tiers.

Actions:

1. Create directories and empty conftest files for upcoming test packages:

   for dir in cxp providers llm di drivers agents governance postman kernel orchestrator knowledge_graph session memory gateway plugin; do
       mkdir -p $TESTS/$dir
       touch $TESTS/$dir/__init__.py
       touch $TESTS/$dir/conftest.py
   done
   

2. Each conftest.py gets a minimal header:

   """Test configuration for <package> tests."""
   

Verify:

find $TESTS -name conftest.py | wc -l

Expect: >= 17 conftest.py files

Step 35: 🚪 Sub-phase 0.3 Gate Check

Goal: Test infrastructure is in place; existing tests still pass.

cd /home/mohamed/workspace/orchestrata-ultimate && uv run pytest tests/ -x -q

Expect: Same pass count as Step 27

Test Porting Strategy (applies to ALL tiers)

IMPORTANT: Orchestrata has 408 test files with ~8,600 test functions. These tests MUST be ported alongside the source code, but they require significant transformation to comply with ultimate's test standards. Orchestrata's tests have isolation violations that BREAK parallel execution. Do NOT blindly copy tests — each file needs the transformations below.

Mandatory Transformations (apply to EVERY ported test file)

T1. Import Translation — same as source code:

# Standard sed chain (see Conventions section)

T2. Remove ALL bare os.environ mutations — pass values explicitly — 107 locations across 26 files. monkeypatch is BANNED under the current test standards (no monkeypatch anywhere); do not substitute it. Required infra endpoints are never set by tests at all — tests/conftest.py hard-pins the suite to env/test.env, and code resolves them via the RUL-003 raising seams (core.redis_factory / core.graph_factory).

# BEFORE (orchestrata pattern — VIOLATES isolation):
os.environ["REDIS_HOST"] = "localhost"
os.environ["POSTMAN_PORT"] = "7777"

# AFTER (ultimate pattern — parallel-safe):
# Pass config/parameters explicitly to the object under test;
# infra endpoints come from the pinned env/test.env profile via the raising resolvers.

Verify per file: grep -n 'os\.environ\[.*\] =' <file> must return 0 matches after transformation.

T3. Downscope ALL module-scope and class-scope fixtures to function scope:

# BEFORE (orchestrata — BREAKS parallel execution):
@pytest.fixture(scope="module")
def prolog():
    bridge = PrologBridge()
    bridge.load_all_rules()
    return bridge

# AFTER (ultimate — per-test isolation):
@pytest.fixture  # scope="function" is default
def prolog():
    bridge = PrologBridge()
    bridge.load_all_rules()
    yield bridge
    # Cleanup if needed

Verify per file: grep -n 'scope="module"\|scope="class"' <file> must return 0 matches.

T4. Remove ALL global/module-level mutable state:

# BEFORE (orchestrata — shared state pollutes parallel workers):
_prolog_cleanup_counter = 0
_redis_healthy = None
_LOADED_MODULES = {}

# AFTER: Move to fixtures or remove entirely.
# If state must be cached, use a fixture with appropriate scope.
@pytest.fixture(scope="session")
def _infra_health():
    """Read-only health check — OK at session scope because immutable."""
    return {"redis": _check_redis(), "neo4j": _check_neo4j()}

Verify: grep -n '^[a-zA-Z_].*= ' <conftest_file> — audit all module-level assignments.

T5. Replace hardcoded ports with dynamic allocation:

# BEFORE (orchestrata — port collision under xdist):
config = ServerConfig(host="localhost", port=50053)

# AFTER (ultimate — OS assigns free port):
import socket
def _get_free_port() -> int:
    with socket.socket() as s:
        s.bind(("", 0))
        return s.getsockname()[1]

config = ServerConfig(host="localhost", port=_get_free_port())

Verify: grep -rn 'port=5[0-9]\{4\}' <file> must return 0 matches.

T6. Use isolation fixture for ALL resource creation:

# BEFORE (orchestrata — no cleanup guarantee):
def test_file_ops():
    with open("/tmp/test_data.txt", "w") as f: ...

# AFTER (ultimate — UUID-prefixed, auto-cleanup):
def test_file_ops(isolation, temp_test_dir):
    test_file = isolation.create_test_file(
        temp_test_dir / "data.txt", content="test"
    )
    # Auto-cleaned after test

T7. Use test_id for ALL database operations:

# BEFORE (orchestrata — global data pollution):
session.run("CREATE (n:Document {name: 'test'})")

# AFTER (ultimate — isolated by test_id):
def test_neo4j(isolation, neo4j_session):
    node_id = isolation.create_test_node_id("Document")
    neo4j_session.run(
        "CREATE (n:Document {id: $id, test_id: $tid, name: 'test'})",
        id=node_id, tid=isolation.test_id
    )
    # Cleaned up by test_id after test

T8. Redis: per-worker DB isolation (already in orchestrata fixtures — keep):

# Worker gw0 → db 0, gw1 → db 1, etc.
# This pattern is CORRECT in orchestrata — port as-is, but downscope fixture to function.

T9. Prolog: lazy import + per-test instance (NOT global singleton):

# BEFORE (orchestrata — global singleton, xdist_group workaround):
_prolog = Prolog()  # Module-level singleton

# AFTER (ultimate — per-test, lazy):
@pytest.fixture
def prolog_engine():
    try:
        from pyswip import Prolog
        engine = Prolog()
        yield engine
    except ImportError:
        pytest.skip("pyswip not available")

Per-Tier Test Porting Workflow

For each tier, after porting source code:

1. Copy test files from orchestrata to ultimate test directory
2. Apply T1 (import translation) to all copied files
3. Apply T2-T9 transformations — this is the bulk of the work
4. Run linter check for remaining violations:

   # Check for remaining orchestrata references
   grep -rn "from orchestrata\." $TESTS/<tier_dir>/ | grep -v orchestrata_ultimate
   # Check for bare os.environ mutations
   grep -rn 'os\.environ\[.*\] =' $TESTS/<tier_dir>/
   # Check for module/class-scope fixtures
   grep -rn 'scope="module"\|scope="class"' $TESTS/<tier_dir>/
   # Check for global mutable state
   grep -rn '^[a-zA-Z_].*= \[\|^[a-zA-Z_].*= {}\|^[a-zA-Z_].*= None\|^[a-zA-Z_].*= 0' $TESTS/<tier_dir>/ --include="conftest.py"
   # Check for hardcoded ports
   grep -rn 'port=5[0-9]\{4\}' $TESTS/<tier_dir>/
   

   ALL checks must return 0 matches.
5. Run tests with parallel flag to verify isolation:

   uv run pytest $TESTS/<tier_dir>/ -n auto -x --timeout=120
   

6. Tests depending on later tiers: mark with @pytest.mark.xfail(reason="Tier N dependency")

Test Directory Mapping

Target Pass Rates

CRITICAL: Every gate check MUST run with -n auto to verify parallel safety. A test that passes sequentially but fails in parallel is NOT passing.

Sub-phase 0.4: Update pyproject.toml and Pin (Steps 36–38)

Step 36: Update pyproject.toml

Goal: Bump versions and add the few missing dependencies. Most deps already exist in the file.

File: /home/mohamed/workspace/orchestrata-ultimate/pyproject.toml

Actions:

1. Read current pyproject.toml to see what's already there
2. Change requires-python from ">=3.11" to ">=3.14"
3. Bump existing httpx from >=0.25.0 to >=0.28.0
4. Bump existing fastapi from >=0.104.0 to >=0.110.0
5. Add these 2 NEW dependencies (not already in pyproject.toml):

   "pyjwt>=2.8.0",
   "watchfiles>=0.21",
   

6. Remove "asyncio>=3.4.3" (it's stdlib, the PyPI package is a no-op shim)
7. Add dev dependencies:

   "pytest-xdist>=3.5.0",
   "pytest-timeout>=2.1.0",
   

Already present (DO NOT duplicate): click, fastapi, jinja2, msgpack, neo4j, redis, websockets, pyyaml, structlog, typer — these are already in pyproject.toml.

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && uv sync --dev 2>&1 | tail -3

Expect: Successful sync (no resolution errors) If it fails: Dependency conflict — check which package versions clash and adjust.

Step 37: Pin orchestrata source

Goal: Record the exact commit of orchestrata being ported.

Actions:

cd /home/mohamed/workspace/orchestrata && git rev-parse HEAD > /home/mohamed/workspace/orchestrata-ultimate/plans/ORCHESTRATA_PIN.txt

Verify:

cat /home/mohamed/workspace/orchestrata-ultimate/plans/ORCHESTRATA_PIN.txt

Expect: A 40-character git SHA

Step 38: 🚪 Phase 0 Final Gate Check + Commit

Goal: Full test suite passes IN PARALLEL. Commit all Phase 0 work.

Actions:

1. Run full suite with parallel execution:

   cd /home/mohamed/workspace/orchestrata-ultimate && uv run pytest tests/ -n auto --timeout=120 -q
   

2. If any test fails with -n auto but passes without it, that test has an isolation violation — fix it before proceeding.
3. Note exact pass count
4. Commit:

   cd /home/mohamed/workspace/orchestrata-ultimate
   git add -A
   git commit -m "Phase 0: Fix bugs, port orchestrata-core, test infrastructure, update deps"
   

Expect: All tests pass. Clean commit.

Tier 1: Agents That Talk and Think (Steps 39–98)

Goal: Agents make real LLM calls, coordinate via CXP. ~37,000 LOC. Done when: ultimate intent "write tests for X" produces real LLM output in <30s.

Sub-phase 1.1: CXP Protocol (Steps 39–47)

Step 39: Create cxp/ package directory

Actions:

mkdir -p $ULT/cxp
touch $ULT/cxp/__init__.py

Step 40: Port cxp/packet.py

Source: $SRC/orchestrata-cxp/src/orchestrata/cxp/packet.py Destination: $ULT/cxp/packet.py

Actions:

1. cp $SRC/orchestrata-cxp/src/orchestrata/cxp/packet.py $ULT/cxp/packet.py
2. Apply standard import translation
3. CXPPacket is a @dataclass — it stays as-is (not Pydantic)
4. Verify no os.environ["X"] reads

Verify: python -c "from orchestrata_ultimate.cxp.packet import CXPPacket; print('OK')"

Step 41: Port cxp/json_serializer.py

Source: $SRC/orchestrata-cxp/src/orchestrata/cxp/json_serializer.py Destination: $ULT/cxp/json_serializer.py

Actions:

1. Copy and apply standard import translation
2. This replaces the gRPC binary serializer (which we skip)

Verify: python -c "from orchestrata_ultimate.cxp.json_serializer import *; print('OK')"

Step 42: Port cxp/exceptions.py and cxp/headers.py

Source: $SRC/orchestrata-cxp/src/orchestrata/cxp/exceptions.py and headers.py Destination: $ULT/cxp/

Actions:

1. Copy both files, apply standard import translation

Verify: python -c "from orchestrata_ultimate.cxp.exceptions import *; from orchestrata_ultimate.cxp.headers import *; print('OK')"

Step 43: Port cxp/payload.py and cxp/threads.py

Source: $SRC/orchestrata-cxp/src/orchestrata/cxp/payload.py and threads.py Destination: $ULT/cxp/

Actions:

1. Copy both, apply standard import translation

Verify: python -c "from orchestrata_ultimate.cxp.payload import *; from orchestrata_ultimate.cxp.threads import *; print('OK')"

Step 44: Port cxp/validator.py

Source: $SRC/orchestrata-cxp/src/orchestrata/cxp/validator.py Destination: $ULT/cxp/validator.py

Actions:

1. Copy, apply standard import translation

Verify: python -c "from orchestrata_ultimate.cxp.validator import *; print('OK')"

Step 44b: Port remaining CXP modules (19 files, ~3,900 LOC)

Goal: The CXP package has ~31 files total. Steps 40-44 cover 7 core files (packet, json_serializer, exceptions, headers, payload, threads, validator). This step ports the remaining non-gRPC files.

Files to skip (gRPC — not portable to 3.14t):

• binary_serializer.py, grpc_client.py, grpc_server.py, prolog_bridge.py, proto/

Files to port:

# Copy all remaining CXP files (excluding gRPC)
for f in constants.py delivery_status.py deterministic_ids.py dispatcher.py \
         handler.py interfaces.py priority.py postman_adapter.py router.py \
         schema.py serializer.py session_adapter.py thread_store.py types.py \
         version.py version_compat.py work_status.py ws_client.py ws_server.py; do
    cp $SRC/orchestrata-cxp/src/orchestrata/cxp/$f $ULT/cxp/$f
done
# Also copy the __init__.py (301 LOC — has significant exports)
cp $SRC/orchestrata-cxp/src/orchestrata/cxp/__init__.py $ULT/cxp/__init__.py

Apply standard import translation to ALL copied files:

for f in $ULT/cxp/*.py; do
    sed -i 's/from orchestrata\./from orchestrata_ultimate./g' "$f"
    sed -i 's/import orchestrata\b/import orchestrata_ultimate/g' "$f"
done

Key files:

Notes:

• dispatcher.py from orchestrata is a full-featured dispatcher. Keep both: the simple InMemoryDispatcher (Step 45) for Tier 1, orchestrata's dispatcher for Tier 2+.
• postman_adapter.py and session_adapter.py reference Postman and Session (Tier 2/3). Add TYPE_CHECKING guards.
• ws_client.py and ws_server.py require the websockets package (added in Step 36).
• Convert interfaces.py ABCs to Protocol classes.

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.cxp.constants import *
from orchestrata_ultimate.cxp.types import *
from orchestrata_ultimate.cxp.work_status import *
from orchestrata_ultimate.cxp.delivery_status import *
from orchestrata_ultimate.cxp.schema import *
print('CXP EXTENDED OK')
"

Step 45: Create cxp/dispatcher.py (InMemoryDispatcher)

Goal: Create the Tier 1 in-memory message dispatcher (replaced by Postman in Tier 2).

Destination: $ULT/cxp/dispatcher.py

Actions:

1. Create new file with:

   """In-memory CXP dispatcher for Tier 1 (replaced by Postman in Tier 2)."""
   from __future__ import annotations
   
   import asyncio
   from typing import Any, Callable, Optional
   
   from orchestrata_ultimate.cxp.packet import CXPPacket
   
   
   class InMemoryDispatcher:
       """Direct async routing. No persistence, no guarantees."""
   
       def __init__(self, max_pending: int = 1000):
           self._handlers: dict[str, Callable] = {}
           self._queue: asyncio.Queue = asyncio.Queue(maxsize=max_pending)
   
       def register(self, alias: str, handler: Callable) -> None:
           self._handlers[alias] = handler
   
       async def aroute(self, packet: CXPPacket) -> Optional[CXPPacket]:
           handler = self._handlers.get(packet.to_agent)
           if handler is None:
               return None
           return await handler(packet)
   
       def unregister(self, alias: str) -> None:
           self._handlers.pop(alias, None)
   
   
   _dispatcher: InMemoryDispatcher | None = None
   
   
   def get_dispatcher() -> InMemoryDispatcher:
       global _dispatcher
       if _dispatcher is None:
           _dispatcher = InMemoryDispatcher()
       return _dispatcher
   

Verify: python -c "from orchestrata_ultimate.cxp.dispatcher import InMemoryDispatcher, get_dispatcher; print('OK')"

Step 46: Update cxp/init.py

File: $ULT/cxp/__init__.py

Actions:

1. Add exports:

   from orchestrata_ultimate.cxp.packet import CXPPacket
   from orchestrata_ultimate.cxp.dispatcher import InMemoryDispatcher, get_dispatcher
   
   __all__ = ["CXPPacket", "InMemoryDispatcher", "get_dispatcher"]
   

Verify: python -c "from orchestrata_ultimate.cxp import CXPPacket, InMemoryDispatcher; print('OK')"

Step 47: 🚪 CXP Gate Check

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.cxp.packet import CXPPacket
from orchestrata_ultimate.cxp.json_serializer import *
from orchestrata_ultimate.cxp.dispatcher import InMemoryDispatcher
from orchestrata_ultimate.cxp.validator import *
from orchestrata_ultimate.cxp.headers import *
from orchestrata_ultimate.cxp.payload import *
from orchestrata_ultimate.cxp.threads import *
from orchestrata_ultimate.cxp.exceptions import *
print('CXP OK')
"

Expect: CXP OK

Sub-phase 1.2: Provider + LLM (Steps 48–60)

Step 48: Create providers/ and llm/ directories

mkdir -p $ULT/providers/adapters
touch $ULT/providers/__init__.py
touch $ULT/providers/adapters/__init__.py
mkdir -p $ULT/llm
touch $ULT/llm/__init__.py

Step 49: Port provider_manager.py

Source: $SRC/orchestrata-provider/src/orchestrata/provider/provider_manager.py Destination: $ULT/providers/provider_manager.py

Actions:

1. Copy, apply standard import translation
2. Fix from orchestrata.provider. → from orchestrata_ultimate.providers.
3. Fix any os.environ["X"] reads

Verify: python -c "from orchestrata_ultimate.providers.provider_manager import ProviderManager; print('OK')"

Step 50: Port adapters/base.py

Source: $SRC/orchestrata-provider/src/orchestrata/provider/adapters/base.py Destination: $ULT/providers/adapters/base.py

Actions:

1. Copy, apply standard import translation
2. Fix: from orchestrata.provider. → from orchestrata_ultimate.providers.

Verify: python -c "from orchestrata_ultimate.providers.adapters.base import *; print('OK')"

Step 51: Port anthropic_adapter.py

Source: $SRC/orchestrata-provider/src/orchestrata/provider/adapters/anthropic_adapter.py Destination: $ULT/providers/adapters/anthropic_adapter.py

Actions:

1. Copy, apply standard import translation
2. Anthropic SDK import should be conditional:

   try:
       import anthropic
   except ImportError:
       anthropic = None
   

Verify: python -c "from orchestrata_ultimate.providers.adapters.anthropic_adapter import *; print('OK')"

Step 52: Port openai_adapter.py and deepseek_adapter.py

Source: $SRC/orchestrata-provider/src/orchestrata/provider/adapters/ Destination: $ULT/providers/adapters/

Actions:

1. Copy both files, apply standard import translation

Verify: python -c "from orchestrata_ultimate.providers.adapters.openai_adapter import *; from orchestrata_ultimate.providers.adapters.deepseek_adapter import *; print('OK')"

Step 53: Port claude_cli_adapter.py and ollama_adapter.py

Source: $SRC/orchestrata-provider/src/orchestrata/provider/adapters/ Destination: $ULT/providers/adapters/

Actions:

1. Copy both files, apply standard import translation

Verify: python -c "from orchestrata_ultimate.providers.adapters.claude_cli_adapter import *; from orchestrata_ultimate.providers.adapters.ollama_adapter import *; print('OK')"

Step 54: Port cost_tracker.py and rate_limiter.py

Source: $SRC/orchestrata-provider/src/orchestrata/provider/ Destination: $ULT/providers/

Actions:

1. Copy both, apply standard import translation

Verify: python -c "from orchestrata_ultimate.providers.cost_tracker import *; from orchestrata_ultimate.providers.rate_limiter import *; print('OK')"

Step 55: Port circuit_breaker.py and health_monitor.py

Source: $SRC/orchestrata-provider/src/orchestrata/provider/ Destination: $ULT/providers/

Actions:

1. Copy both, apply standard import translation

Verify: python -c "from orchestrata_ultimate.providers.circuit_breaker import *; from orchestrata_ultimate.providers.health_monitor import *; print('OK')"

Step 56: Port router.py and registry.py

Source: $SRC/orchestrata-provider/src/orchestrata/provider/ Destination: $ULT/providers/

Actions:

1. Copy both, apply standard import translation

Verify: python -c "from orchestrata_ultimate.providers.router import *; from orchestrata_ultimate.providers.registry import *; print('OK')"

Step 57: Port llm/client.py (call_llm, call_reasoner)

Source: $SRC/orchestrata-llm/src/orchestrata/llm/ — find the main client file (likely client.py or the module with call_llm) Destination: $ULT/llm/client.py

Actions:

1. List LLM source files: ls $SRC/orchestrata-llm/src/orchestrata/llm/
2. Copy the main client module
3. Apply standard import translation
4. Ensure call_llm() and call_reasoner() are exported

Verify: python -c "from orchestrata_ultimate.llm.client import call_llm; print('OK')"

Step 58: Port llm/config.py and llm/exceptions.py

Source: $SRC/orchestrata-llm/src/orchestrata/llm/ Destination: $ULT/llm/

Actions:

1. Copy config.py and exceptions.py, apply standard import translation
2. Add VolkConfig thread safety fix:

   import threading
   _config_lock = threading.Lock()
   _CONFIG: VolkConfig | None = None
   
   def _get_config() -> VolkConfig:
       global _CONFIG
       if _CONFIG is None:
           with _config_lock:
               if _CONFIG is None:
                   _CONFIG = VolkConfig()
       return _CONFIG
   

3. Update llm/init.py with exports

Verify: python -c "from orchestrata_ultimate.llm import *; print('OK')"

Step 59: Delete integrations/openrouter.py stub

Goal: Remove the stub now that real providers are ported.

Actions:

1. Delete $ULT/integrations/openrouter.py
2. Update $ULT/integrations/__init__.py to remove openrouter reference

Verify: python -c "from orchestrata_ultimate.providers.provider_manager import ProviderManager; print('Stub replaced')"

Step 60: 🚪 Provider + LLM Gate Check

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.providers.provider_manager import ProviderManager
from orchestrata_ultimate.providers.adapters.base import *
from orchestrata_ultimate.providers.circuit_breaker import *
from orchestrata_ultimate.providers.cost_tracker import *
from orchestrata_ultimate.providers.rate_limiter import *
from orchestrata_ultimate.providers.health_monitor import *
from orchestrata_ultimate.providers.router import *
from orchestrata_ultimate.providers.registry import *
from orchestrata_ultimate.llm import *
print('PROVIDER+LLM OK')
" && uv run pytest tests/ -x -q

Expect: PROVIDER+LLM OK and existing tests still pass

Sub-phase 1.3: DI Container (Steps 61–62)

Step 61: Port di/container.py

Source: $SRC/orchestrata-di/src/orchestrata/di/ Destination: $ULT/di/

Actions:

1. mkdir -p $ULT/di
   cp $SRC/orchestrata-di/src/orchestrata/di/__init__.py $ULT/di/__init__.py
   cp $SRC/orchestrata-di/src/orchestrata/di/container.py $ULT/di/container.py
   

2. Apply standard import translation to both files

Verify: python -c "from orchestrata_ultimate.di.container import *; print('OK')"

Step 62: 🚪 DI Gate Check

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "from orchestrata_ultimate.di import *; print('DI OK')"

Sub-phase 1.4: Drivers (Steps 63–68)

Step 63: Create drivers/ package

mkdir -p $ULT/drivers

Step 64: Port base.py and driver_factory.py

Source: $SRC/orchestrata-drivers/src/orchestrata/drivers/ Destination: $ULT/drivers/

Actions:

1. cp $SRC/orchestrata-drivers/src/orchestrata/drivers/__init__.py $ULT/drivers/__init__.py
   cp $SRC/orchestrata-drivers/src/orchestrata/drivers/base.py $ULT/drivers/base.py
   cp $SRC/orchestrata-drivers/src/orchestrata/drivers/driver_factory.py $ULT/drivers/driver_factory.py
   

2. Apply standard import translation

Verify: python -c "from orchestrata_ultimate.drivers.driver_factory import *; print('OK')"

Step 65: Port claude_code_driver.py and aider_driver.py

Source: $SRC/orchestrata-drivers/src/orchestrata/drivers/ Destination: $ULT/drivers/

Actions:

1. Copy both, apply standard import translation

Verify: python -c "from orchestrata_ultimate.drivers.claude_code_driver import *; print('OK')"

Step 66: Port deepseek_coder_driver.py and qwen_driver.py

Actions:

1. Copy both, apply standard import translation

Verify: python -c "from orchestrata_ultimate.drivers.deepseek_coder_driver import *; from orchestrata_ultimate.drivers.qwen_driver import *; print('OK')"

Step 67: Port browser_driver.py, browser_providers.py, extraction.py

Actions:

1. Copy all three, apply standard import translation

Verify: python -c "from orchestrata_ultimate.drivers.browser_driver import *; print('OK')"

Step 68: 🚪 Drivers Gate Check

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.drivers import *
from orchestrata_ultimate.drivers.driver_factory import *
print('DRIVERS OK')
"

Sub-phase 1.5: Verification Review Subset (Steps 69–73)

Step 69: Create verification/ package

mkdir -p $ULT/verification/review
touch $ULT/verification/__init__.py
touch $ULT/verification/review/__init__.py

Step 70: Port review/types.py and review/helpers.py

Source: $SRC/orchestrata-verification/src/orchestrata/verification/review/ Destination: $ULT/verification/review/

Actions:

1. Copy types.py and helpers.py, apply standard import translation

Verify: python -c "from orchestrata_ultimate.verification.review.types import *; print('OK')"

Step 71: Port review check modules

Source: $SRC/orchestrata-verification/src/orchestrata/verification/review/checks_*.py Destination: $ULT/verification/review/

Actions:

1. Copy all 4 check files:
   • checks_correctness.py
   • checks_quality.py
   • checks_safety.py
   • checks_structure.py
2. Apply standard import translation to each
3. Also copy issue_triage.py

Verify: python -c "from orchestrata_ultimate.verification.review.checks_correctness import *; print('OK')"

Step 72: Port review/engine.py

Source: $SRC/orchestrata-verification/src/orchestrata/verification/review/engine.py Destination: $ULT/verification/review/engine.py

Actions:

1. Copy, apply standard import translation
2. Update $ULT/verification/review/__init__.py with exports

Verify: python -c "from orchestrata_ultimate.verification.review.engine import *; print('OK')"

Step 73: 🚪 Verification Review Gate Check

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.verification.review import *
print('VERIFICATION REVIEW OK')
"

Sub-phase 1.6: Agent Implementations (Steps 74–96)

Step 74: Port agents base framework — types, constants, exceptions

Source: $SRC/orchestrata-agents/src/orchestrata/agents/ (types.py, constants.py, exceptions.py) Destination: $ULT/agents/

Actions:

1. Copy all three files into $ULT/agents/
2. Apply standard import translation
3. In types.py: rename any Volk references to Agent in type names
4. In constants.py: rename VOLK_ prefixed constants to AGENT_

Verify: python -c "from orchestrata_ultimate.agents.types import *; print('OK')"

Step 75: Port communication.py and hierarchy.py

Source: $SRC/orchestrata-agents/src/orchestrata/agents/ Destination: $ULT/agents/

Actions:

1. Copy both, apply standard import translation
2. Rename Volk → Agent in class/function names where applicable

Verify: python -c "from orchestrata_ultimate.agents.communication import *; from orchestrata_ultimate.agents.hierarchy import *; print('OK')"

Step 76: Port constraints.py

Source: $SRC/orchestrata-agents/src/orchestrata/agents/constraints.py Destination: $ULT/agents/constraints.py

Actions:

1. Copy, apply standard import translation

Verify: python -c "from orchestrata_ultimate.agents.constraints import *; print('OK')"

Step 77: Create CXPMixin and merge into BaseAgent

Goal: Add CXP communication methods to BaseAgent via CXPMixin.

File: $ULT/agents/base_agent.py

Actions:

1. Read current $ULT/agents/base_agent.py (the existing stub)
2. Read $SRC/orchestrata-agents/src/orchestrata/agents/volks/base.py for the source BaseVolk
3. Create the unified BaseAgent:

   """Unified base agent: Pydantic validation + CXP communication."""
   from __future__ import annotations
   
   import uuid
   from abc import abstractmethod
   from typing import Any, ClassVar, Optional
   
   from pydantic import BaseModel, ConfigDict, Field, field_validator
   
   from orchestrata_ultimate.cxp.packet import CXPPacket
   
   
   class CXPMixin:
       """CXP communication. Injected at runtime via set_postman()."""
       _postman: ClassVar[Any] = None
       _kg_context: ClassVar[Any] = None
   
       def set_postman(self, postman: Any) -> None:
           self._postman = postman
   
       def set_kg(self, kg: Any) -> None:
           self._kg_context = kg
   
       async def send(self, packet: CXPPacket) -> Optional[CXPPacket]:
           if self._postman is None:
               raise RuntimeError(f"{self.alias}: postman not set — cannot send")
           return await self._postman.aroute(packet)
   
       async def emit_event(self, event_type: str, payload: dict | None = None) -> None:
           """Emit a system event via CXP. Wired to EventBus in Tier 2."""
           if self._postman is not None and payload is not None:
               from orchestrata_ultimate.cxp.packet import CXPPacket
               packet = CXPPacket(
                   from_agent=self.alias,
                   to_agent="system",
                   action=event_type,
                   payload=payload,
               )
               await self._postman.aroute(packet)
   
       def get_output_display(self) -> str:
           return f"[{self.alias}] {self.role}: {self.status}"
   
   
   class BaseAgent(CXPMixin, BaseModel):
       """Unified base: Pydantic validation + CXP communication."""
       model_config = ConfigDict(arbitrary_types_allowed=True)
   
       agent_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
       alias: str
       role: str
       model: str = "claude-sonnet-4-20250514"
       status: str = "idle"
       current_thread: Optional[str] = None
       summary: str = ""
   
       @field_validator('model')
       @classmethod
       def validate_model(cls, v: str) -> str:
           if not v:
               raise ValueError("model must not be empty")
           return v
   
       @abstractmethod
       async def process(self, packet: CXPPacket) -> Optional[CXPPacket]:
           """Process incoming CXP packet. All subclasses MUST implement as async."""
           ...
   

4. IMPORTANT: This code COMPLETELY REPLACES the existing stub at $ULT/agents/base_agent.py. Overwrite the file entirely — do not merge with the stub. Rename the old stub to base_agent_stub.py first for reference. Delete after Step 96.

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.agents.base_agent import BaseAgent, CXPMixin
print(f'BaseAgent MRO: {[c.__name__ for c in BaseAgent.__mro__]}')
print('OK')
"

Expect: MRO shows CXPMixin before BaseModel. OK

Step 78: Port agents/interfaces.py → agents/protocols.py

Source: $SRC/orchestrata-agents/src/orchestrata/agents/interfaces.py Destination: $ULT/agents/protocols.py

Actions:

1. Copy file
2. Apply standard import translation
3. Convert ABC classes to Protocol classes

Verify: python -c "from orchestrata_ultimate.agents.protocols import *; print('OK')"

Step 79: Create agents/volks/ directory structure + port swarm (dependency of CodeDirector)

Actions — Part A: Create directories:

mkdir -p $ULT/agents/volks/{analyst,architect,codedirector,codedirector/scaffold,compliance,concierge,junior,qa,ux,pm}
for d in $ULT/agents/volks/*/; do touch "$d/__init__.py"; done
touch $ULT/agents/volks/__init__.py

Actions — Part B: Port swarm FIRST (CodeDirector depends on it):

mkdir -p $ULT/agents/swarm
cp $SRC/orchestrata-agents/src/orchestrata/agents/swarm/__init__.py $ULT/agents/swarm/__init__.py
cp $SRC/orchestrata-agents/src/orchestrata/agents/swarm/coordinator.py $ULT/agents/swarm/coordinator.py
cp $SRC/orchestrata-agents/src/orchestrata/agents/swarm/types.py $ULT/agents/swarm/types.py

Apply standard import translation to all 3 files.

Verify: python -c "from orchestrata_ultimate.agents.swarm.coordinator import *; print('SWARM OK')" Why here: codedirector/volk.py:6 has from orchestrata.agents.swarm.coordinator import _is_source_file (top-level import). codedirector/implementation.py:7 imports SwarmCoordinator. Both are hard dependencies — CodeDirector cannot import without swarm.

Step 80: Port analyst volk

Source: $SRC/orchestrata-analyst/src/orchestrata/volks/analyst/ (volk.py, parsers.py, prompts.py) Destination: $ULT/agents/volks/analyst/

Actions:

1. Copy all .py files:

   cp $SRC/orchestrata-analyst/src/orchestrata/volks/analyst/volk.py $ULT/agents/volks/analyst/volk.py
   cp $SRC/orchestrata-analyst/src/orchestrata/volks/analyst/parsers.py $ULT/agents/volks/analyst/parsers.py
   cp $SRC/orchestrata-analyst/src/orchestrata/volks/analyst/prompts.py $ULT/agents/volks/analyst/prompts.py
   

2. Apply standard import translation to each file
3. In volk.py: rename class AnalystVolk(BaseVolk) → class AnalystAgent(BaseAgent)
4. Change base class import: from orchestrata_ultimate.agents.base_agent import BaseAgent
5. Fix os.environ["X"] if any

Verify: python -c "from orchestrata_ultimate.agents.volks.analyst.volk import AnalystAgent; print('OK')"

Step 81: Port architect volk (9 files, 2,028 LOC)

Source: $SRC/orchestrata-architect/src/orchestrata/volks/architect/ Destination: $ULT/agents/volks/architect/

Actions:

1. Copy ALL files:

   for f in __init__.py volk.py architect_prompts.py architect_project.py \
            architect_context.py context_builder.py prompts.py project_init.py volk_context.py; do
       cp $SRC/orchestrata-architect/src/orchestrata/volks/architect/$f $ULT/agents/volks/architect/$f
   done
   

2. Apply standard import translation to all 9 files
3. Rename ArchitectVolk → ArchitectAgent in volk.py, change base to BaseAgent
4. CRITICAL os.environ fix: architect_context.py has 6 bare reads, context_builder.py has 3 bare reads:

   grep -n 'os\.environ\[' $ULT/agents/volks/architect/architect_context.py
   grep -n 'os\.environ\[' $ULT/agents/volks/architect/context_builder.py
   

   Fix ALL to .get() with defaults.

Verify: python -c "from orchestrata_ultimate.agents.volks.architect.volk import ArchitectAgent; print('OK')"

Step 82: Port codedirector volk (including scaffold/)

Source: $SRC/orchestrata-codedirector/src/orchestrata/volks/codedirector/ Destination: $ULT/agents/volks/codedirector/

Actions:

1. Copy ALL files including scaffold/ subdirectory:

   cp $SRC/orchestrata-codedirector/src/orchestrata/volks/codedirector/volk.py $ULT/agents/volks/codedirector/volk.py
   cp $SRC/orchestrata-codedirector/src/orchestrata/volks/codedirector/implementation.py $ULT/agents/volks/codedirector/implementation.py
   cp $SRC/orchestrata-codedirector/src/orchestrata/volks/codedirector/prompts.py $ULT/agents/volks/codedirector/prompts.py
   cp $SRC/orchestrata-codedirector/src/orchestrata/volks/codedirector/review.py $ULT/agents/volks/codedirector/review.py
   cp $SRC/orchestrata-codedirector/src/orchestrata/volks/codedirector/review_checks.py $ULT/agents/volks/codedirector/review_checks.py
   cp $SRC/orchestrata-codedirector/src/orchestrata/volks/codedirector/scaffold/__init__.py $ULT/agents/volks/codedirector/scaffold/__init__.py
   cp $SRC/orchestrata-codedirector/src/orchestrata/volks/codedirector/scaffold/generator.py $ULT/agents/volks/codedirector/scaffold/generator.py
   cp $SRC/orchestrata-codedirector/src/orchestrata/volks/codedirector/scaffold/parser.py $ULT/agents/volks/codedirector/scaffold/parser.py
   cp $SRC/orchestrata-codedirector/src/orchestrata/volks/codedirector/scaffold/types.py $ULT/agents/volks/codedirector/scaffold/types.py
   

2. CRITICAL: Copy Jinja2 templates (scaffold/generator.py loads these at runtime):

   mkdir -p $ULT/agents/volks/codedirector/scaffold/templates
   cp $SRC/orchestrata-codedirector/src/orchestrata/volks/codedirector/scaffold/templates/*.j2 \
      $ULT/agents/volks/codedirector/scaffold/templates/
   

   Files: pyproject.toml.j2, init.py.j2, conftest.py.j2, module.py.j2
3. Apply standard import translation to ALL .py files
4. Rename CodeDirectorVolk → CodeDirectorAgent, base → BaseAgent
5. Fix any os.environ["X"] reads

Verify: python -c "from orchestrata_ultimate.agents.volks.codedirector.volk import CodeDirectorAgent; print('OK')"

Step 83: Port compliance volk

Source: $SRC/orchestrata-compliance/src/orchestrata/volks/compliance/ Destination: $ULT/agents/volks/compliance/

Actions:

1. Copy volk.py and _pipeline.py, apply standard import translation
2. Rename ComplianceVolk → ComplianceAgent

Verify: python -c "from orchestrata_ultimate.agents.volks.compliance.volk import ComplianceAgent; print('OK')"

Step 84: Port concierge volk

Source: $SRC/orchestrata-concierge/src/orchestrata/volks/concierge/ Destination: $ULT/agents/volks/concierge/

Actions:

1. Copy volk.py, apply standard import translation
2. Rename ConciergeVolk → ConciergeAgent

Verify: python -c "from orchestrata_ultimate.agents.volks.concierge.volk import ConciergeAgent; print('OK')"

Step 85: Port junior volk

Source: $SRC/orchestrata-junior/src/orchestrata/volks/junior/ Destination: $ULT/agents/volks/junior/

Actions:

1. Copy volk.py, apply standard import translation
2. Rename JuniorVolk → JuniorAgent
3. Fix import of drivers (top-level import): from orchestrata.drivers → from orchestrata_ultimate.drivers
4. Fix import of verification review: from orchestrata.verification.review → from orchestrata_ultimate.verification.review

Verify: python -c "from orchestrata_ultimate.agents.volks.junior.volk import JuniorAgent; print('OK')" If it fails: JuniorVolk has top-level imports of drivers and verification — both must be ported first (Steps 63-73).

Step 86: Port qa volk

Source: $SRC/orchestrata-qa/src/orchestrata/volks/qa/ Destination: $ULT/agents/volks/qa/

Actions:

1. Copy volk.py (~3,039 LOC), apply standard import translation
2. Rename QaVolk → QualityAssuranceAgent

Verify: python -c "from orchestrata_ultimate.agents.volks.qa.volk import QualityAssuranceAgent; print('OK')"

Step 87: Port ux volk

Source: $SRC/orchestrata-ux/src/orchestrata/volks/ux/ Destination: $ULT/agents/volks/ux/

Actions:

1. Copy volk.py, apply standard import translation
2. Rename UXVolk → UserExperienceAgent

Verify: python -c "from orchestrata_ultimate.agents.volks.ux.volk import UserExperienceAgent; print('OK')"

Step 88: Port pm volk

Source: $SRC/orchestrata-pm/src/orchestrata/volks/pm/ (volk.py, goal_registry.py, goal_report.py) Destination: $ULT/agents/volks/pm/

Actions:

1. Copy all 3 .py files + init.py
2. Apply standard import translation
3. Rename PMVolk → ProjectManagerAgent

Verify: python -c "from orchestrata_ultimate.agents.volks.pm.volk import ProjectManagerAgent; print('OK')"

Step 89: Port senior_dev volk

Source: $SRC/orchestrata-agents/src/orchestrata/agents/volks/senior_dev.py (NOT a separate package — inline in agents) Destination: $ULT/agents/volks/senior_dev.py

Actions:

1. cp $SRC/orchestrata-agents/src/orchestrata/agents/volks/senior_dev.py $ULT/agents/volks/senior_dev.py
   

2. Apply standard import translation
3. Rename SeniorDevVolk → SeniorDevAgent

Verify: python -c "from orchestrata_ultimate.agents.volks.senior_dev import SeniorDevAgent; print('OK')"

Step 90: (Merged into Step 79 — swarm already ported before volks)

Step 91: Port prompt_builder.py

Source: $SRC/orchestrata-agents/src/orchestrata/agents/prompt_builder.py Destination: $ULT/agents/prompt_builder.py

Actions:

1. Copy, apply standard import translation

Verify: python -c "from orchestrata_ultimate.agents.prompt_builder import *; print('OK')"

Step 92: Port spec_writer.py and uml_generator.py

Source: $SRC/orchestrata-agents/src/orchestrata/agents/ Destination: $ULT/agents/

Actions:

1. Copy both, apply standard import translation

Verify: python -c "from orchestrata_ultimate.agents.spec_writer import *; print('OK')"

Step 93: Port cxp_adapter.py and postman_adapter.py

Source: $SRC/orchestrata-agents/src/orchestrata/agents/ Destination: $ULT/agents/

Actions:

1. Copy both, apply standard import translation
2. postman_adapter.py references Postman (Tier 2) — add TYPE_CHECKING guard:

   from __future__ import annotations
   from typing import TYPE_CHECKING
   if TYPE_CHECKING:
       from orchestrata_ultimate.postman import Postman
   

Verify: python -c "from orchestrata_ultimate.agents.cxp_adapter import *; print('OK')"

Step 94: Port agents/di.py

Source: $SRC/orchestrata-agents/src/orchestrata/agents/di.py Destination: $ULT/agents/di.py

Actions:

1. Copy, apply standard import translation

Verify: python -c "from orchestrata_ultimate.agents.di import *; print('OK')"

Step 95: Update agents/init.py

File: $ULT/agents/__init__.py

Actions:

1. Add comprehensive exports:

   from orchestrata_ultimate.agents.base_agent import BaseAgent, CXPMixin
   
   __all__ = ["BaseAgent", "CXPMixin"]
   

2. Do NOT import individual volks in init — they're imported via their specific paths

Verify: python -c "from orchestrata_ultimate.agents import BaseAgent; print('OK')"

Step 96: Delete old agent stubs

Goal: Remove the 4 old stub files (now replaced by real implementations).

Actions:

1. Delete these stubs (only if their real replacements import cleanly):
   • $ULT/agents/architect.py (replaced by agents/volks/architect/volk.py)
   • $ULT/agents/code_director.py (replaced by agents/volks/codedirector/volk.py)
   • $ULT/agents/quality_assurance.py (replaced by agents/volks/qa/volk.py)
   • $ULT/agents/user_experience.py (replaced by agents/volks/ux/volk.py)
2. Keep base_agent.py — it's the real unified BaseAgent now

Verify: Ensure no imports reference the deleted stubs:

grep -rn "from orchestrata_ultimate.agents.architect import\|from orchestrata_ultimate.agents.code_director import\|from orchestrata_ultimate.agents.quality_assurance import\|from orchestrata_ultimate.agents.user_experience import" $ULT/ $TESTS/

Expect: No matches (or fix references to use agents.volks.<role>.volk paths)

Step 96b: Port Tier 1 test files (with isolation transformations)

Goal: Port test files for CXP, providers, LLM, DI, drivers, agents — fully compliant with ultimate's parallel isolation standards.

Actions:

1. Copy test directories:

   for dir in cxp agents; do
       if [ -d /home/mohamed/workspace/orchestrata/tests/$dir ]; then
           cp -r /home/mohamed/workspace/orchestrata/tests/$dir/* $TESTS/$dir/ 2>/dev/null
       fi
   done
   

2. T1: Apply standard import translation to all ported test files
3. T2: Remove ALL bare os.environ mutations — pass values explicitly (monkeypatch is BANNED):

   grep -rn 'os\.environ\[.*\] =' $TESTS/cxp/ $TESTS/agents/ --include="*.py"
   

   Fix every match.
4. T3: Downscope all scope="module" and scope="class" fixtures to function scope
5. T4: Remove global mutable state from ported conftest.py files
6. T5: Replace hardcoded ports (especially in CXP gRPC tests) with dynamic ports. Skip pure gRPC tests.
7. T6-T8: Add isolation fixture usage where tests create files/resources
8. Verification — parallel safety check:

   cd /home/mohamed/workspace/orchestrata-ultimate && uv run pytest tests/cxp tests/agents -n auto -x --timeout=120 -q
   

9. Mark tests depending on Tier 2+ code as @pytest.mark.xfail(reason="Tier 2 dependency")

Expect: ~2,700+ tests passing with -n auto (90% of ~3,000 ported)

Step 97: 🚪 Tier 1 Full Gate Check

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
## CXP
from orchestrata_ultimate.cxp import CXPPacket, InMemoryDispatcher
## Providers
from orchestrata_ultimate.providers.provider_manager import ProviderManager
## LLM
from orchestrata_ultimate.llm.client import call_llm
## DI
from orchestrata_ultimate.di.container import *
## Drivers
from orchestrata_ultimate.drivers.driver_factory import *
## Verification review
from orchestrata_ultimate.verification.review.engine import *
## Agents
from orchestrata_ultimate.agents.base_agent import BaseAgent
from orchestrata_ultimate.agents.volks.analyst.volk import AnalystAgent
from orchestrata_ultimate.agents.volks.codedirector.volk import CodeDirectorAgent
from orchestrata_ultimate.agents.volks.qa.volk import QualityAssuranceAgent
from orchestrata_ultimate.agents.volks.junior.volk import JuniorAgent
from orchestrata_ultimate.agents.volks.pm.volk import ProjectManagerAgent
print('TIER 1 ALL IMPORTS OK')
"

Then run tests:

cd /home/mohamed/workspace/orchestrata-ultimate && uv run pytest tests/ -q

Expect: All imports succeed. Tests pass.

Step 98: 🚪 Tier 1 Commit

cd /home/mohamed/workspace/orchestrata-ultimate
git add -A
git commit -m "Tier 1: CXP protocol, providers, LLM, DI, drivers, verification review, 11 agent implementations"

Tier 2: Coordination and Governance (Steps 99–175)

Goal: Multi-agent coordination, message routing, governance enforcement. ~50,000 LOC. Done when: Submit intent → routes through Postman → agents collaborate → results aggregated.

Sub-phase 2.1: Knowledge Subset (Steps 99–104)

Step 99: Prepare knowledge_graph/ for real implementation

Goal: Replace the stub graph.py with real knowledge modules (subset needed by Tier 2).

Actions:

1. Keep $ULT/knowledge_graph/__init__.py
2. Do NOT delete graph.py yet — keep until Step 185 (Tier 3)

Step 100: Port neo4j_client.py

Source: $SRC/orchestrata-knowledge/src/orchestrata/knowledge/neo4j_client.py Destination: $ULT/knowledge_graph/neo4j_client.py

Actions:

1. Copy, apply standard import translation
2. from orchestrata.knowledge. → from orchestrata_ultimate.knowledge_graph.
3. Fix os.environ["NEO4J_URI"] etc. via the raising seams (resolve_uri()/resolve_kg_database(); the NEO4J_* keys were retired 2026-07-27 — no literal defaults, RUL-003)
4. Ensure neo4j import is conditional:

   try:
       from neo4j import GraphDatabase
   except ImportError:
       GraphDatabase = None
   

Verify: python -c "from orchestrata_ultimate.knowledge_graph.neo4j_client import *; print('OK')"

Step 101: Port context_injector.py

Source: $SRC/orchestrata-knowledge/src/orchestrata/knowledge/context_injector.py Destination: $ULT/knowledge_graph/context_injector.py

Actions:

1. Copy, apply standard import translation
2. Fix os.environ["X"] reads

Verify: python -c "from orchestrata_ultimate.knowledge_graph.context_injector import *; print('OK')"

Step 102: Port synchronizer.py

Source: $SRC/orchestrata-knowledge/src/orchestrata/knowledge/synchronizer.py Destination: $ULT/knowledge_graph/synchronizer.py

Actions:

1. Copy, apply standard import translation

Verify: python -c "from orchestrata_ultimate.knowledge_graph.synchronizer import *; print('OK')"

Step 103: Port cxp_auditor.py, config.py, constants.py

Source: $SRC/orchestrata-knowledge/src/orchestrata/knowledge/ Destination: $ULT/knowledge_graph/

Actions:

1. Copy all three, apply standard import translation

Verify: python -c "from orchestrata_ultimate.knowledge_graph.config import *; print('OK')"

Step 104: 🚪 Knowledge Subset Gate Check

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.knowledge_graph.neo4j_client import *
from orchestrata_ultimate.knowledge_graph.context_injector import *
from orchestrata_ultimate.knowledge_graph.synchronizer import *
print('KNOWLEDGE SUBSET OK')
"

Sub-phase 2.2: Agent Infrastructure (Steps 105–113)

Step 105: Port runtime.py → agents/runtime.py

Source: $SRC/orchestrata-agents/src/orchestrata/agents/runtime.py Destination: $ULT/agents/runtime.py

Actions:

1. Copy, apply standard import translation

2. Rename VolkRuntime → AgentRuntime

3. CRITICAL: runtime.py has top-level imports from kernel and orchestrator (not yet ported at this step):

   • from orchestrata.kernel.volk_registry import VolkRegistry (becomes Step 159)
   • from orchestrata.orchestrator.redis_state import RedisStateManager (becomes Step 169)

   Convert both to TYPE_CHECKING + runtime lazy imports:

   from __future__ import annotations
   from typing import TYPE_CHECKING
   if TYPE_CHECKING:
       from orchestrata_ultimate.kernel.agent_registry import AgentRegistry
       from orchestrata_ultimate.orchestrator.redis_state import RedisStateManager
   

   Then in any method that USES these types, do a lazy import at first call:

   # Before (top-level, will fail):
   from orchestrata_ultimate.kernel.agent_registry import AgentRegistry
   
   # After (lazy, in the method that needs it):
   def register_with_kernel(self):
       from orchestrata_ultimate.kernel.agent_registry import AgentRegistry
       # Now use AgentRegistry...
   

   Apply this pattern to every function in runtime.py that uses AgentRegistry or RedisStateManager.

4. Add crash isolation fix:

   async def _execute_task(self, agent, packet):
       try:
           return await agent.process(packet)
       except Exception as e:
           agent.status = "failed"
           logger.error(f"Agent {agent.alias} crashed: {e}")
           return None  # Or failure CXP packet
   

Verify: python -c "from orchestrata_ultimate.agents.runtime import AgentRuntime; print('OK')"

Step 106: Port pool.py → agents/pool.py

Source: $SRC/orchestrata-agents/src/orchestrata/agents/pool.py Destination: $ULT/agents/pool.py

Actions:

1. Copy, apply standard import translation
2. Rename VolkPool → AgentPool

Verify: python -c "from orchestrata_ultimate.agents.pool import AgentPool; print('OK')"

Step 107: Port task_executor.py

Source: $SRC/orchestrata-agents/src/orchestrata/agents/task_executor.py Destination: $ULT/agents/task_executor.py

Actions:

1. Copy, apply standard import translation
2. CRITICAL: Fix dynamic import strings (lines ~60-68):

   # Before:
   "orchestrata.volks.analyst.volk"
   "orchestrata.volks.architect.volk"
   # ... (9 entries)
   
   # After:
   "orchestrata_ultimate.agents.volks.analyst.volk"
   "orchestrata_ultimate.agents.volks.architect.volk"
   # ... (all 9 entries)
   

3. Verify ALL 9 string-based module references are updated

Verify:

grep -n "orchestrata\." $ULT/agents/task_executor.py | grep -v "orchestrata_ultimate"

Expect: 0 matches (all orchestrata references translated)

Step 108: Port coordinator.py → agents/coordinator.py

Source: $SRC/orchestrata-agents/src/orchestrata/agents/coordinator.py Destination: $ULT/agents/coordinator.py

Actions:

1. Copy, apply standard import translation
2. Rename VolkCoordinator → AgentCoordinator

Verify: python -c "from orchestrata_ultimate.agents.coordinator import AgentCoordinator; print('OK')"

Step 109: Port escalation.py

Source: $SRC/orchestrata-agents/src/orchestrata/agents/escalation.py Destination: $ULT/agents/escalation.py

Actions: Copy, apply standard import translation

Verify: python -c "from orchestrata_ultimate.agents.escalation import *; print('OK')"

Step 110: Port lifecycle.py

Source: $SRC/orchestrata-agents/src/orchestrata/agents/lifecycle.py Destination: $ULT/agents/lifecycle.py

Actions: Copy, apply standard import translation

Verify: python -c "from orchestrata_ultimate.agents.lifecycle import *; print('OK')"

Step 111: Port agents/prolog_bridge.py

Source: $SRC/orchestrata-agents/src/orchestrata/agents/prolog_bridge.py Destination: $ULT/agents/prolog_bridge.py

Actions:

1. Copy, apply standard import translation
2. Ensure pyswip import is conditional:

   try:
       from pyswip import Prolog
   except ImportError:
       Prolog = None
   

Verify: python -c "from orchestrata_ultimate.agents.prolog_bridge import *; print('OK')"

Step 112: Port intent_adapter.py

Source: $SRC/orchestrata-agents/src/orchestrata/agents/intent_adapter.py Destination: $ULT/agents/intent_adapter.py

Actions: Copy, apply standard import translation

Verify: python -c "from orchestrata_ultimate.agents.intent_adapter import *; print('OK')"

Step 113: 🚪 Agent Infrastructure Gate Check

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.agents.runtime import AgentRuntime
from orchestrata_ultimate.agents.pool import AgentPool
from orchestrata_ultimate.agents.coordinator import AgentCoordinator
print('AGENT INFRA OK')
"

Sub-phase 2.2b: Verification Framework Remainder (Steps 114–124)

Port all remaining verification modules NOT included in Step 69-73.

Step 114: Port verification/constraints/

Source: $SRC/orchestrata-verification/src/orchestrata/verification/constraints/ Destination: $ULT/verification/constraints/

Actions:

1. mkdir -p $ULT/verification/constraints
2. Copy init.py, definitions.py, evaluator.py
3. Apply standard import translation

Verify: python -c "from orchestrata_ultimate.verification.constraints import *; print('OK')"

Step 115: Port verification/checkpoints/

Source: $SRC/orchestrata-verification/src/orchestrata/verification/checkpoints/ Destination: $ULT/verification/checkpoints/

Actions:

1. mkdir -p $ULT/verification/checkpoints
2. Copy all 4 files, apply standard import translation

Verify: python -c "from orchestrata_ultimate.verification.checkpoints import *; print('OK')"

Step 116: Port verification/proofs/

Source: $SRC/orchestrata-verification/src/orchestrata/verification/proofs/ Destination: $ULT/verification/proofs/

Actions: mkdir -p, copy, translate

Verify: python -c "from orchestrata_ultimate.verification.proofs import *; print('OK')"

Step 117: Port verification/autofix/

Source: $SRC/orchestrata-verification/src/orchestrata/verification/autofix/ (7 files) Destination: $ULT/verification/autofix/

Actions: mkdir -p, copy all 7 files, translate

Verify: python -c "from orchestrata_ultimate.verification.autofix import *; print('OK')"

Step 118: Port verification/edge_cases/

Source: $SRC/orchestrata-verification/src/orchestrata/verification/edge_cases/ Destination: $ULT/verification/edge_cases/

Actions: mkdir -p, copy, translate

Verify: python -c "from orchestrata_ultimate.verification.edge_cases import *; print('OK')"

Step 119: Port verification/agents/

Source: $SRC/orchestrata-verification/src/orchestrata/verification/agents/ Destination: $ULT/verification/agents/

Actions: mkdir -p, copy 4 files, translate

Verify: python -c "from orchestrata_ultimate.verification.agents import *; print('OK')"

Step 120: Port verification/orchestration/

Source: $SRC/orchestrata-verification/src/orchestrata/verification/orchestration/ Destination: $ULT/verification/orchestration/

Actions: mkdir -p, copy, translate

Verify: python -c "from orchestrata_ultimate.verification.orchestration import *; print('OK')"

Step 121: Port verification/session/

Source: $SRC/orchestrata-verification/src/orchestrata/verification/session/ Destination: $ULT/verification/session/

Actions: mkdir -p, copy, translate

Verify: python -c "from orchestrata_ultimate.verification.session import *; print('OK')"

Step 122: Port verification subdirs: models/, config/, protocols/, integrations/, impossibility/, requirements/

Actions:

1. For each subdirectory:

   for subdir in models config protocols integrations impossibility requirements; do
       mkdir -p $ULT/verification/$subdir
       cp $SRC/orchestrata-verification/src/orchestrata/verification/$subdir/*.py $ULT/verification/$subdir/
   done
   

2. Apply standard import translation to all files:

   find $ULT/verification -name "*.py" -exec sed -i 's/from orchestrata\./from orchestrata_ultimate./g' {} +
   

3. Then fix compound paths manually

Verify: python -c "from orchestrata_ultimate.verification.models import *; print('OK')"

Step 123: Port verification/types.py, escalation_handler.py, verification/engine.py, feedback.py

Source: Top-level files in $SRC/orchestrata-verification/src/orchestrata/verification/ Destination: $ULT/verification/

Actions:

1. Copy types.py, escalation_handler.py
2. Copy verification/verification/engine.py → $ULT/verification/engine.py
3. Copy verification/verification/feedback.py → $ULT/verification/feedback.py
4. Apply standard import translation

Verify: python -c "from orchestrata_ultimate.verification.types import *; print('OK')"

Step 124: 🚪 Verification Framework Gate Check

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.verification.constraints import *
from orchestrata_ultimate.verification.checkpoints import *
from orchestrata_ultimate.verification.autofix import *
from orchestrata_ultimate.verification.types import *
print('VERIFICATION OK')
"

Sub-phase 2.3: Governance (Steps 125–137)

Step 125: Prepare governance/ for real implementation

Actions:

1. Keep $ULT/governance/__init__.py
2. The stub pam.py stays until Step 137 gate confirms real code works

Step 126: Port policy_engine.py

Source: $SRC/orchestrata-governance/src/orchestrata/governance/policy_engine.py Destination: $ULT/governance/policy_engine.py

Actions:

1. Copy, apply standard import translation
2. Rename class if needed: PolicyEngine → GovernanceEngine
3. Fix os.environ["X"] reads

Verify: python -c "from orchestrata_ultimate.governance.policy_engine import *; print('OK')"

Step 127: Port escalation_handler.py

Source: $SRC/orchestrata-governance/src/orchestrata/governance/escalation_handler.py Destination: $ULT/governance/escalation_handler.py

Actions: Copy, translate

Verify: python -c "from orchestrata_ultimate.governance.escalation_handler import *; print('OK')"

Step 128: Port constitutional.py (fix dynamic imports — __import__ pattern!)

Source: $SRC/orchestrata-governance/src/orchestrata/governance/constitutional.py Destination: $ULT/governance/constitutional.py

Actions:

1. Copy, apply standard import translation (sed pass)
2. CRITICAL: sed will NOT catch the __import__() call on line ~302. Fix MANUALLY:

   # Before (line ~302):
   __import__("orchestrata.core.enums", fromlist=["FactScope"])
   # After:
   __import__("orchestrata_ultimate.core.enums", fromlist=["FactScope"])
   

   This is the ONLY __import__() pattern in the entire codebase. Standard sed misses it because the module path is a string argument to a function, not an import statement.
3. Also grep for ALL string-based module references (double and single quotes):

   grep -n '"orchestrata\.\|'"'"'orchestrata\.' $ULT/governance/constitutional.py | grep -v orchestrata_ultimate
   

   Fix every match.

Verify:

grep -E '("|'"'"')orchestrata\.' $ULT/governance/constitutional.py | grep -v orchestrata_ultimate

Expect: 0 matches

Step 129: Port ethical.py

Source: $SRC/orchestrata-governance/src/orchestrata/governance/ethical.py Destination: $ULT/governance/ethical.py

Actions: Copy, translate

Verify: python -c "from orchestrata_ultimate.governance.ethical import *; print('OK')"

Step 130: Port prolog_client.py and prolog_gate.py

Source: $SRC/orchestrata-governance/src/orchestrata/governance/ Destination: $ULT/governance/

Actions:

1. Copy both, apply standard import translation
2. Ensure pyswip is conditional in both files
3. prolog_gate.py is required by kernel/pipeline.py (Tier 2.5)

Verify: python -c "from orchestrata_ultimate.governance.prolog_gate import *; print('OK')"

Step 131: Port resource_access.py and safe_mode.py

Actions: Copy both, translate

Verify: python -c "from orchestrata_ultimate.governance.resource_access import *; print('OK')"

Step 132: Port cache.py and monitoring.py

Actions: Copy both, translate

Verify: python -c "from orchestrata_ultimate.governance.cache import *; print('OK')"

Step 133: Port audit.py and violations.py

Actions: Copy both, translate

Verify: python -c "from orchestrata_ultimate.governance.audit import *; print('OK')"

Step 134: Port dynamic_policy.py, types.py, interfaces.py, constants.py, exceptions.py

Actions:

1. Copy all 5 files, apply standard import translation
2. Convert interfaces.py ABC classes to Protocol if applicable

Verify: python -c "from orchestrata_ultimate.governance.types import *; print('OK')"

Step 135: Port event_emitting_policy_engine.py

Actions: Copy, translate

Verify: python -c "from orchestrata_ultimate.governance.event_emitting_policy_engine import *; print('OK')"

Step 136: Port configs/ YAML and prolog/ rule files

Goal: Copy non-Python data files needed by governance.

Actions:

1. Check if orchestrata-governance has configs/ and prolog/ directories:

   find $SRC/orchestrata-governance -name "*.yaml" -o -name "*.yml" -o -name "*.pl"
   

2. Copy to appropriate location in ultimate:

   mkdir -p /home/mohamed/workspace/orchestrata-ultimate/configs
   mkdir -p /home/mohamed/workspace/orchestrata-ultimate/prolog
   # Copy found files
   

3. Update pyproject.toml force-include if not already done in Step 36

Verify: ls /home/mohamed/workspace/orchestrata-ultimate/configs/ /home/mohamed/workspace/orchestrata-ultimate/prolog/

Step 137: 🚪 Governance Gate Check + Delete Stub

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.governance.policy_engine import *
from orchestrata_ultimate.governance.prolog_gate import *
from orchestrata_ultimate.governance.constitutional import *
print('GOVERNANCE OK')
"

If all imports pass, delete the stub:

• Delete $ULT/governance/pam.py

Sub-phase 2.4: Postman (Steps 138–150)

Step 138: Create postman/ package

mkdir -p $ULT/postman
touch $ULT/postman/__init__.py

Step 139: Port postman.py (main broker)

Source: $SRC/orchestrata-postman/src/orchestrata/postman/postman.py Destination: $ULT/postman/postman.py

Actions:

1. Copy, apply standard import translation
2. Fix os.environ["X"] reads
3. Add TTL check fix:

   async def aroute(self, packet: CXPPacket) -> Optional[CXPPacket]:
       if hasattr(packet, 'is_expired') and packet.is_expired():
           logger.warning(f"Dropping expired packet {packet.message_id}")
           return None
       # ... normal routing
   

Verify: python -c "from orchestrata_ultimate.postman.postman import *; print('OK')"

Step 140: Port postman/router.py

Actions: Copy, translate, fix env vars

Verify: python -c "from orchestrata_ultimate.postman.router import *; print('OK')"

Step 141: Port delivery.py and guarantees.py

Actions: Copy both, translate

Verify: python -c "from orchestrata_ultimate.postman.delivery import *; print('OK')"

Step 142: Port queue.py and priority.py

Actions:

1. Copy both, translate
2. Add InMemoryQueue fallback if not present (Redis optional)

Verify: python -c "from orchestrata_ultimate.postman.queue import *; print('OK')"

Step 143: Port envelope.py and payload.py

Actions: Copy both, translate

Verify: python -c "from orchestrata_ultimate.postman.envelope import *; print('OK')"

Step 144: Port message_store.py and receipt_store.py

Actions:

1. Copy both, translate
2. Fix os.environ["REDIS_HOST"] reads

Verify: python -c "from orchestrata_ultimate.postman.message_store import *; print('OK')"

Step 145: Port replay_engine.py

Actions: Copy, translate

Verify: python -c "from orchestrata_ultimate.postman.replay_engine import *; print('OK')"

Step 146: Port governance.py and spike_router.py

Actions:

1. Copy both, translate
2. spike_router.py is required by kernel/pipeline.py and agents/base.py

Verify: python -c "from orchestrata_ultimate.postman.spike_router import *; print('OK')"

Step 147: Port types.py, config.py, interfaces.py, exceptions.py, constants.py

Actions:

1. Copy all 5 files, apply standard import translation
2. Convert interfaces.py (1,358 LOC!) ABCs to Protocols — this is the largest file in Postman

Verify: python -c "from orchestrata_ultimate.postman.types import *; print('OK')"

Step 147b: Port remaining postman modules (13 files, ~3,272 LOC)

Goal: Steps 139-147 cover 17 core files. This step ports the 13 remaining files.

Files to port:

for f in admin.py cli.py error_handler.py event_emitting_postman.py filter.py \
         health.py metrics.py postman_types.py queue_manager.py routing_rules.py \
         subscription_manager.py topic_registry.py; do
    cp $SRC/orchestrata-postman/src/orchestrata/postman/$f $ULT/postman/$f
done

Apply standard import translation to all. Fix os.environ["X"] reads in health.py (3 reads).

Key files:

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.postman.postman_types import *
from orchestrata_ultimate.postman.queue_manager import *
from orchestrata_ultimate.postman.metrics import *
print('POSTMAN EXTENDED OK')
"

Step 148: Wire InMemoryQueue fallback

Goal: Ensure postman works without Redis.

File: $ULT/postman/queue.py (or create $ULT/postman/memory_queue.py)

Actions:

1. Check if the ported queue.py already has an in-memory option
2. If not, add:

   class InMemoryQueue:
       def __init__(self):
           self._queues: dict[str, asyncio.Queue] = {}
       async def enqueue(self, queue_name: str, item: Any):
           if queue_name not in self._queues:
               self._queues[queue_name] = asyncio.Queue()
           await self._queues[queue_name].put(item)
       async def dequeue(self, queue_name: str):
           return await self._queues[queue_name].get()
   

Verify: python -c "from orchestrata_ultimate.postman.queue import *; print('OK')"

Step 149: Update postman/init.py

Actions: Add key exports (Postman, Router, etc.)

Verify: python -c "from orchestrata_ultimate.postman import *; print('OK')"

Step 150: 🚪 Postman Gate Check

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.postman.postman import *
from orchestrata_ultimate.postman.router import *
from orchestrata_ultimate.postman.queue import *
from orchestrata_ultimate.postman.spike_router import *
print('POSTMAN OK')
" && uv run pytest tests/ -x -q

Sub-phase 2.5: Kernel (Steps 151–166)

Step 151: Create kernel/ package (replace orchestrator.py stub)

Actions:

1. mkdir -p $ULT/kernel
   touch $ULT/kernel/__init__.py
   

2. Keep $ULT/core/orchestrator.py for now — delete after kernel is verified

Step 152: Port kernel.py

Source: $SRC/orchestrata-kernel/src/orchestrata/kernel/kernel.py Destination: $ULT/kernel/kernel.py

Actions:

1. Copy, apply standard import translation
2. Rename OrchestrationKernel → OrchestrataKernel
3. Fix os.environ["X"] reads (kernel has ~20)
4. Add graceful shutdown fix:

   async def stop(self):
       self._shutting_down = True
       # Wait for active tasks
       if self._active_tasks:
           done, pending = await asyncio.wait(self._active_tasks, timeout=30)
           for task in pending:
               task.cancel()
       # Then cleanup
   

Verify: python -c "from orchestrata_ultimate.kernel.kernel import OrchestrataKernel; print('OK')"

Step 153: Port event_bus.py with InMemoryEventBus fallback

Source: $SRC/orchestrata-kernel/src/orchestrata/kernel/event_bus.py Destination: $ULT/kernel/event_bus.py

Actions:

1. Copy, translate, fix env vars
2. Add factory function:

   def create_event_bus(redis_url: str | None = None) -> EventBus:
       if redis_url:
           try:
               return RedisEventBus(redis_url)
           except Exception:
               pass
       return InMemoryEventBus()
   

3. Create InMemoryEventBus class if not present in source

Verify: python -c "from orchestrata_ultimate.kernel.event_bus import create_event_bus; eb = create_event_bus(); print('OK')"

Step 154: Port dispatcher.py (conditional gRPC)

Source: $SRC/orchestrata-kernel/src/orchestrata/kernel/dispatcher.py Destination: $ULT/kernel/dispatcher.py

Actions:

1. Copy, translate
2. Make gRPC import conditional:

   try:
       import grpc
       HAS_GRPC = True
   except ImportError:
       HAS_GRPC = False
   

3. Guard gRPC-dependent code paths with if HAS_GRPC:

Verify: python -c "from orchestrata_ultimate.kernel.dispatcher import *; print('OK')"

Step 155: Port kernel/router.py

Actions: Copy, translate

Verify: python -c "from orchestrata_ultimate.kernel.router import *; print('OK')"

Step 156: Port pipeline.py and pipeline_events.py

Source: $SRC/orchestrata-kernel/src/orchestrata/kernel/pipeline.py and pipeline_events.py Destination: $ULT/kernel/

Actions:

1. Copy both, translate
2. pipeline.py requires prolog_gate.py (ported in Step 130) and spike_router.py (ported in Step 146)
3. Verify these dependencies resolve

Verify: python -c "from orchestrata_ultimate.kernel.pipeline import *; print('OK')"

Step 157: Port workflow_engine.py

Actions: Copy, translate

Verify: python -c "from orchestrata_ultimate.kernel.workflow_engine import *; print('OK')"

Step 158: Port queue_manager.py

Actions: Copy, translate, fix env vars

Verify: python -c "from orchestrata_ultimate.kernel.queue_manager import *; print('OK')"

Step 159: Port volk_registry.py → kernel/agent_registry.py

Source: $SRC/orchestrata-kernel/src/orchestrata/kernel/volk_registry.py Destination: $ULT/kernel/agent_registry.py

Actions:

1. Copy, translate
2. Rename VolkRegistry → AgentRegistry
3. Add TYPE_CHECKING imports for agent types:

   from __future__ import annotations
   from typing import TYPE_CHECKING
   if TYPE_CHECKING:
       from orchestrata_ultimate.agents.base_agent import BaseAgent
   

Verify: python -c "from orchestrata_ultimate.kernel.agent_registry import AgentRegistry; print('OK')"

Step 160: Port config_manager.py

Actions: Copy, translate, fix env vars

Verify: python -c "from orchestrata_ultimate.kernel.config_manager import *; print('OK')"

Step 161: Port policy_evaluator.py and pam_enforcer.py

Actions: Copy both, translate

Verify: python -c "from orchestrata_ultimate.kernel.policy_evaluator import *; print('OK')"

Step 162: Port performance_manager.py and resource_monitor.py

Actions: Copy both, translate

Verify: python -c "from orchestrata_ultimate.kernel.performance_manager import *; print('OK')"

Step 163: Port audit_logger.py

Actions: Copy, translate

Verify: python -c "from orchestrata_ultimate.kernel.audit_logger import *; print('OK')"

Step 164: Port session_manager.py and session_context.py

Source: $SRC/orchestrata-kernel/src/orchestrata/kernel/ (these are kernel-level, not full session package) Destination: $ULT/kernel/

Actions: Copy both, translate, fix env vars

Verify: python -c "from orchestrata_ultimate.kernel.session_manager import *; print('OK')"

Step 165: Port error_handler.py and CLI files

Source: $SRC/orchestrata-kernel/src/orchestrata/kernel/error_handler.py, cli.py, cli_main.py, console_cli.py Destination: $ULT/kernel/

Actions:

1. Copy error_handler.py, translate
2. Copy CLI files, translate — these will be adapted to typer subcommands later

Verify: python -c "from orchestrata_ultimate.kernel.error_handler import *; print('OK')"

Step 166: 🚪 Kernel Gate Check + Update init.py

Actions:

1. Update $ULT/kernel/__init__.py with key exports
2. Update $ULT/__init__.py:

   # Change:
   from orchestrata_ultimate.core.orchestrator import UltimateOrchestrator
   # To:
   from orchestrata_ultimate.kernel.kernel import OrchestrataKernel as UltimateOrchestrator
   

3. Delete $ULT/core/orchestrator.py (the stub)
4. Verify:

   cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
   from orchestrata_ultimate.kernel.kernel import OrchestrataKernel
   from orchestrata_ultimate.kernel.event_bus import create_event_bus
   from orchestrata_ultimate.kernel.agent_registry import AgentRegistry
   from orchestrata_ultimate.kernel.pipeline import *
   print('KERNEL OK')
   "
   

Sub-phase 2.6: Orchestrator (Steps 167–173)

Step 167: Create orchestrator/ package

mkdir -p $ULT/orchestrator
touch $ULT/orchestrator/__init__.py

Step 168: Port orchestrator — intent modules (8 files, ~2,690 LOC)

Source: $SRC/orchestrata-orchestrator/src/orchestrata/orchestrator/ Destination: $ULT/orchestrator/

Actions:

for f in intent_parser.py intent_dispatcher.py intent_broker.py intent_types.py \
         intent_enums.py intent_template.py intent_results.py intent_validator.py; do
    cp $SRC/orchestrata-orchestrator/src/orchestrata/orchestrator/$f $ULT/orchestrator/$f
done

Apply standard import translation. Fix os.environ["X"] in intent_lifecycle.py.

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.orchestrator.intent_parser import *
from orchestrata_ultimate.orchestrator.intent_dispatcher import *
from orchestrata_ultimate.orchestrator.intent_broker import *
from orchestrata_ultimate.orchestrator.intent_types import *
from orchestrata_ultimate.orchestrator.intent_validator import *
print('INTENT MODULES OK')
"

Step 169: Port orchestrator — fact and state modules (6 files, ~2,480 LOC)

Actions:

for f in fact_manager.py fact_store.py fact_neo4j.py redis_state.py \
         intent_lifecycle.py intent_history.py; do
    cp $SRC/orchestrata-orchestrator/src/orchestrata/orchestrator/$f $ULT/orchestrator/$f
done

• Fix os.environ["X"] reads: fact_store.py has 5, intent_lifecycle.py has 2, redis_state.py has Redis env vars
• Make Redis optional in redis_state.py with in-memory fallback

Verify: python -c "from orchestrata_ultimate.orchestrator.redis_state import *; print('OK')"

Step 170: Port orchestrator — audit, impact analysis, NLP (10 files, ~3,396 LOC)

Actions:

# Neo4j audit
cp $SRC/orchestrata-orchestrator/src/orchestrata/orchestrator/neo4j_audit.py $ULT/orchestrator/neo4j_audit.py
# NLP
cp $SRC/orchestrata-orchestrator/src/orchestrata/orchestrator/nlp.py $ULT/orchestrator/nlp.py
# Impact analysis subpackage
mkdir -p $ULT/orchestrator/impact
for f in __init__.py analyzer.py classifier.py planner.py dependency_analyzer.py types.py cli.py; do
    cp $SRC/orchestrata-orchestrator/src/orchestrata/orchestrator/impact/$f $ULT/orchestrator/impact/$f
done

• Fix os.environ["X"] in neo4j_audit.py (3 reads)
• Make Neo4j conditional in neo4j_audit.py

Verify: python -c "from orchestrata_ultimate.orchestrator.impact.analyzer import *; print('OK')"

Step 171: Port orchestrator — policy, Prolog, workflow (7 files, ~2,566 LOC)

Actions:

for f in policy_registry.py prolog_bridge.py prolog_worker.py \
         ambiguity_resolver.py parameter_extractor.py intent_workflow.py \
         intent_security.py; do
    cp $SRC/orchestrata-orchestrator/src/orchestrata/orchestrator/$f $ULT/orchestrator/$f
done

• Make pyswip conditional in prolog_bridge.py and prolog_worker.py
• Handle Governance ↔ Orchestrator circular dependency:

  from __future__ import annotations
  from typing import TYPE_CHECKING
  if TYPE_CHECKING:
      from orchestrata_ultimate.governance.policy_engine import GovernanceEngine
  

Verify: python -c "from orchestrata_ultimate.orchestrator.prolog_bridge import *; print('OK')"

Step 172: Port orchestrator — remaining (4 files, ~1,818 LOC)

Actions:

for f in engine.py orchestrator.py intent_router.py intent_metrics.py; do
    cp $SRC/orchestrata-orchestrator/src/orchestrata/orchestrator/$f $ULT/orchestrator/$f
done
# Copy __init__.py
cp $SRC/orchestrata-orchestrator/src/orchestrata/orchestrator/__init__.py $ULT/orchestrator/__init__.py

• Apply standard import translation to ALL files
• intent_metrics.py (620 LOC) — metrics collection
• Update $ULT/orchestrator/__init__.py

Full file inventory (35 files, 11,332 LOC — all now covered):

Steps 168: intent_parser, intent_dispatcher, intent_broker, intent_types,
           intent_enums, intent_template, intent_results, intent_validator
Steps 169: fact_manager, fact_store, fact_neo4j, redis_state,
           intent_lifecycle, intent_history
Steps 170: neo4j_audit, nlp, impact/ (7 files)
Steps 171: policy_registry, prolog_bridge, prolog_worker,
           ambiguity_resolver, parameter_extractor, intent_workflow, intent_security
Steps 172: engine, orchestrator, intent_router, intent_metrics, __init__

Verify: python -c "from orchestrata_ultimate.orchestrator import *; print('ORCHESTRATOR OK')"

Step 173: 🚪 Orchestrator Gate Check

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.orchestrator import *
print('ORCHESTRATOR OK')
"

Step 173b: Port Tier 2 test files (with isolation transformations)

Goal: Port test files for governance, postman, kernel, orchestrator — heaviest transformation tier.

Actions:

1. Copy test directories:

   for dir in governance postman kernel cli spike infra; do
       if [ -d /home/mohamed/workspace/orchestrata/tests/$dir ]; then
           cp -r /home/mohamed/workspace/orchestrata/tests/$dir/* $TESTS/$dir/ 2>/dev/null
       fi
   done
   

2. T1: Apply standard import translation
3. T2 (HEAVY): Remove bare os.environ mutations — pass values explicitly (monkeypatch is BANNED). These files are the worst offenders:
   • tests/kernel/test_config_manager.py — 20 reads
   • tests/postman/test_postman_config.py — 18 reads
   • tests/core/test_config_manager_unified.py — 15 reads
   • tests/postman/test_coverage_postman_config.py — 6 reads
   • Also rework the clean_env() fixtures in postman tests to explicit parameter passing
4. T3: Downscope ALL module-scope fixtures in kernel and orchestrator conftest files
5. T4: Remove globals from governance conftest (Prolog cleanup counters, loaded module tracking)
6. T9 (CRITICAL for governance): Prolog tests — replace global Prolog singleton with per-test prolog_engine fixture. Remove xdist_group("prolog") markers (no longer needed with per-test instances).
7. T5: Fix hardcoded ports in kernel integration tests
8. Parallel safety check:

   cd /home/mohamed/workspace/orchestrata-ultimate && uv run pytest tests/governance tests/postman tests/kernel -n auto -x --timeout=120 -q
   

Expect: Cumulative ~7,000+ tests passing with -n auto (85% of ~8,000 ported)

Step 174: 🚪 Tier 2 Full Gate Check

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.knowledge_graph.neo4j_client import *
from orchestrata_ultimate.agents.runtime import AgentRuntime
from orchestrata_ultimate.verification.constraints import *
from orchestrata_ultimate.governance.policy_engine import *
from orchestrata_ultimate.postman.postman import *
from orchestrata_ultimate.kernel.kernel import OrchestrataKernel
from orchestrata_ultimate.orchestrator import *
print('TIER 2 ALL OK')
" && uv run pytest tests/ -q

Step 175: 🚪 Tier 2 Commit

cd /home/mohamed/workspace/orchestrata-ultimate
git add -A
git commit -m "Tier 2: Knowledge subset, agent infra, verification, governance, postman, kernel, orchestrator"

Tier 3: Knowledge and Memory (Steps 176–204)

Goal: Code understanding, persistent memory, session management. ~18,000 LOC.

Sub-phase 3.1: Knowledge Remainder (Steps 176–186)

Step 176: Port code_parser.py

Source: $SRC/orchestrata-knowledge/src/orchestrata/knowledge/code_parser.py Destination: $ULT/knowledge_graph/code_parser.py

Actions: Copy, translate

Verify: python -c "from orchestrata_ultimate.knowledge_graph.code_parser import *; print('OK')"

Step 177: Port anomaly_detector.py

Source: $SRC/orchestrata-knowledge/src/orchestrata/knowledge/anomaly_detector.py Destination: $ULT/knowledge_graph/anomaly_detector.py

Actions: Copy, translate

Verify: python -c "from orchestrata_ultimate.knowledge_graph.anomaly_detector import *; print('OK')"

Step 178: Port AST analysis modules

Source: $SRC/orchestrata-knowledge/src/orchestrata/knowledge/ (ast_analyzer.py, class_extractor.py, function_extractor.py) Destination: $ULT/knowledge_graph/

Actions: Copy all three, translate

Verify: python -c "from orchestrata_ultimate.knowledge_graph.ast_analyzer import *; print('OK')"

Step 179: Port dependency_analyzer.py

Actions: Copy, translate

Verify: python -c "from orchestrata_ultimate.knowledge_graph.dependency_analyzer import *; print('OK')"

Step 180: Port file_watcher.py

Actions:

1. Copy, translate
2. Requires watchfiles package (added in Step 36)

Verify: python -c "from orchestrata_ultimate.knowledge_graph.file_watcher import *; print('OK')"

Step 181: Port search.py and query_engine.py

Actions: Copy both, translate

Verify: python -c "from orchestrata_ultimate.knowledge_graph.search import *; print('OK')"

Step 182: Port kg_design.py, schema.py, relationships.py

Actions: Copy all three, translate

Verify: python -c "from orchestrata_ultimate.knowledge_graph.kg_design import *; print('OK')"

Step 183: Port type modules

Source: types.py, types_nodes.py, types_enums.py, nodes.py, neo4j_node_mixins.py Destination: $ULT/knowledge_graph/

Actions: Copy all 5, translate

Verify: python -c "from orchestrata_ultimate.knowledge_graph.types import *; print('OK')"

Step 184: Port remaining knowledge files

Source: history.py, portfolio.py, temporal.py, test_results_store.py, graph_context_validator.py, pam_integration.py, exceptions.py, interfaces.py Destination: $ULT/knowledge_graph/

Actions:

1. Copy all remaining .py files
2. Translate imports
3. Convert interfaces.py ABCs to Protocols
4. Update $ULT/knowledge_graph/__init__.py

Verify: python -c "from orchestrata_ultimate.knowledge_graph import *; print('OK')"

Step 185: Delete knowledge_graph/graph.py stub

Actions: Delete $ULT/knowledge_graph/graph.py Verify: python -c "from orchestrata_ultimate.knowledge_graph import *; print('OK')"

Step 186: 🚪 Knowledge Gate Check

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.knowledge_graph.code_parser import *
from orchestrata_ultimate.knowledge_graph.anomaly_detector import *
from orchestrata_ultimate.knowledge_graph.search import *
from orchestrata_ultimate.knowledge_graph.file_watcher import *
print('KNOWLEDGE FULL OK')
"

Sub-phase 3.2: Session (Steps 187–199)

Step 187: Create session/ package

mkdir -p $ULT/session
touch $ULT/session/__init__.py

Step 188: Port session — core lifecycle (7 files, ~2,675 LOC)

Actions:

for f in session.py context.py models.py types.py constants.py exceptions.py interfaces.py; do
    cp $SRC/orchestrata-session/src/orchestrata/session/$f $ULT/session/$f
done

• Apply standard import translation
• session.py (1,016 LOC) is the main session controller
• context.py (746 LOC) is session context management
• models.py (373 LOC) defines WorkItem, Goal, GoalProgress — stay as dataclasses
• Convert interfaces.py ABCs to Protocols

Verify: python -c "from orchestrata_ultimate.session.session import *; print('OK')"

Step 189: Port session — stores (2 files, ~915 LOC)

Actions:

cp $SRC/orchestrata-session/src/orchestrata/session/redis_store.py $ULT/session/redis_store.py
cp $SRC/orchestrata-session/src/orchestrata/session/neo4j_store.py $ULT/session/neo4j_store.py

• Fix os.environ["X"] reads in both files
• Make Redis optional with in-memory fallback in redis_store.py
• Make Neo4j conditional in neo4j_store.py

Verify: python -c "from orchestrata_ultimate.session.redis_store import *; print('OK')"

Step 190: Port session — knowledge graph integration (2 files, ~1,800 LOC)

Actions:

cp $SRC/orchestrata-session/src/orchestrata/session/kg_sync.py $ULT/session/kg_sync.py
cp $SRC/orchestrata-session/src/orchestrata/session/kg_context.py $ULT/session/kg_context.py

• kg_sync.py is 1,507 LOC — the largest session file. Fix os.environ["X"] reads (3 reads).
• kg_context.py (293 LOC) — fix os.environ["X"] reads (3 reads).

Verify: python -c "from orchestrata_ultimate.session.kg_sync import *; print('OK')"

Step 191: Port session — hooks system (5 files, ~826 LOC)

Actions:

mkdir -p $ULT/session/hooks
for f in __init__.py session_fact_hook.py session_pre_close_hook.py session_auto_start_hook.py; do
    cp $SRC/orchestrata-session/src/orchestrata/session/hooks/$f $ULT/session/hooks/$f
done
cp $SRC/orchestrata-session/src/orchestrata/session/hook_registry.py $ULT/session/hook_registry.py

• Guard Prolog with if self._prolog_bridge: in hook implementations

Verify: python -c "from orchestrata_ultimate.session.hook_registry import *; print('OK')"

Step 192: Port session — facts and Prolog (3 files, ~647 LOC)

Actions:

for f in facts.py fact_emitter.py prolog_facts.py; do
    cp $SRC/orchestrata-session/src/orchestrata/session/$f $ULT/session/$f
done

• Make pyswip conditional in prolog_facts.py

Verify: python -c "from orchestrata_ultimate.session.facts import *; print('OK')"

Step 193: Port session — Prolog interface and spec parser (2 files, ~801 LOC)

Actions:

cp $SRC/orchestrata-session/src/orchestrata/session/prolog_interface.py $ULT/session/prolog_interface.py
cp $SRC/orchestrata-session/src/orchestrata/session/spec_parser.py $ULT/session/spec_parser.py

• Make pyswip conditional in prolog_interface.py (477 LOC)

Verify: python -c "from orchestrata_ultimate.session.spec_parser import *; print('OK')"

Step 194: Port session — checkpoint, carryover, archive, recovery (4 files, ~723 LOC)

Actions:

for f in checkpoint.py carryover.py archive.py recovery.py; do
    cp $SRC/orchestrata-session/src/orchestrata/session/$f $ULT/session/$f
done

Verify: python -c "from orchestrata_ultimate.session.checkpoint import *; print('OK')"

Step 195: Port session — portfolio, handover, sync, MCP tools (4 files, ~881 LOC)

Actions:

for f in portfolio.py handover.py sync.py mcp_tools.py; do
    cp $SRC/orchestrata-session/src/orchestrata/session/$f $ULT/session/$f
done

Verify: python -c "from orchestrata_ultimate.session.portfolio import *; print('OK')"

Step 195b: Copy session Jinja2 templates

Goal: Port template files that context.py and archive.py depend on at runtime.

Actions:

mkdir -p $ULT/session/templates
cp $SRC/orchestrata-session/src/orchestrata/session/templates/*.j2 $ULT/session/templates/

Files: context.md.j2, portfolio.md.j2, session.md.j2

Verify: ls $ULT/session/templates/ → 3 .j2 files

Step 196: Port session — CLI and event controller (3 files, ~757 LOC)

Actions:

for f in cli.py event_emitting_session_controller.py fireflies_tools.py; do
    cp $SRC/orchestrata-session/src/orchestrata/session/$f $ULT/session/$f
done

Verify: python -c "from orchestrata_ultimate.session.cli import *; print('OK')"

Step 197: Port session — examples (optional, 3 files, ~506 LOC)

Actions:

mkdir -p $ULT/session/examples
for f in __init__.py basic_usage.py portfolio_usage.py session_start_hook.py; do
    cp $SRC/orchestrata-session/src/orchestrata/session/examples/$f $ULT/session/examples/$f
done

Verify: ls $ULT/session/examples/*.py | wc -l → 4 files

Step 198: Update session/init.py and verify

Actions:

1. Copy $SRC/orchestrata-session/src/orchestrata/session/__init__.py → $ULT/session/__init__.py
2. Apply standard import translation
3. Bulk audit for any remaining untranslated imports:

   grep -rn "from orchestrata\." $ULT/session/ | grep -v orchestrata_ultimate
   

   Fix any remaining matches.

Full file inventory (37 files, 10,595 LOC — all now covered):

Step 188: session.py, context.py, models.py, types.py, constants.py, exceptions.py, interfaces.py
Step 189: redis_store.py, neo4j_store.py
Step 190: kg_sync.py, kg_context.py
Step 191: hooks/ (4 files), hook_registry.py
Step 192: facts.py, fact_emitter.py, prolog_facts.py
Step 193: prolog_interface.py, spec_parser.py
Step 194: checkpoint.py, carryover.py, archive.py, recovery.py
Step 195: portfolio.py, handover.py, sync.py, mcp_tools.py
Step 196: cli.py, event_emitting_session_controller.py, fireflies_tools.py
Step 197: examples/ (4 files)
Step 198: __init__.py

Verify: python -c "from orchestrata_ultimate.session import *; print('SESSION OK')"

Step 199: 🚪 Session Gate Check

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.session import *
print('SESSION OK')
"

Sub-phase 3.3: Memory (Steps 200–203)

Step 200: Create memory/ package and port core

mkdir -p $ULT/memory
cp $SRC/orchestrata-memory/src/orchestrata/memory/__init__.py $ULT/memory/__init__.py
cp $SRC/orchestrata-memory/src/orchestrata/memory/memory_engine.py $ULT/memory/memory_engine.py
cp $SRC/orchestrata-memory/src/orchestrata/memory/hot_store.py $ULT/memory/hot_store.py
cp $SRC/orchestrata-memory/src/orchestrata/memory/cold_store.py $ULT/memory/cold_store.py

Apply standard import translation to all files. Fix env vars.

Verify: python -c "from orchestrata_ultimate.memory.memory_engine import MemoryEngine; print('OK')"

Step 201: Port compressor, embedding, token_counter

cp $SRC/orchestrata-memory/src/orchestrata/memory/compressor.py $ULT/memory/compressor.py
cp $SRC/orchestrata-memory/src/orchestrata/memory/embedding.py $ULT/memory/embedding.py
cp $SRC/orchestrata-memory/src/orchestrata/memory/token_counter.py $ULT/memory/token_counter.py

Apply standard import translation. Update $ULT/memory/__init__.py.

Verify: python -c "from orchestrata_ultimate.memory import *; print('OK')"

Step 202: Wire KG context size limits

Goal: Add max_context_tokens to context injection (fix from implementation plan 8.13).

File: $ULT/knowledge_graph/context_injector.py

Actions:

1. Add parameter to inject_context():

   async def inject_context(self, ..., max_context_tokens: int = 4000) -> str:
       context = await self._fetch_context(...)
       # Truncate if over budget
       from orchestrata_ultimate.memory.token_counter import count_tokens
       if count_tokens(context) > max_context_tokens:
           context = context[:max_context_tokens * 4]  # rough char estimate
       return context
   

Verify: python -c "from orchestrata_ultimate.knowledge_graph.context_injector import *; print('OK')"

Step 203: 🚪 Memory Gate Check

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.memory.memory_engine import MemoryEngine
from orchestrata_ultimate.memory.hot_store import *
from orchestrata_ultimate.memory.cold_store import *
from orchestrata_ultimate.memory.token_counter import *
print('MEMORY OK')
"

Step 203b: Port Tier 3 test files (with isolation transformations)

Goal: Port test files for knowledge, session, memory — triple-infra tests (Redis + Neo4j + Prolog).

Actions:

1. Copy test directories:

   for dir in knowledge session; do
       if [ -d /home/mohamed/workspace/orchestrata/tests/$dir ]; then
           cp -r /home/mohamed/workspace/orchestrata/tests/$dir/* $TESTS/$dir/ 2>/dev/null
       fi
   done
   

2. T1: Apply standard import translation
3. T2: Fix os.environ reads:
   • tests/knowledge/test_real_neo4j_knowledge.py — 5 reads
   • tests/knowledge/test_anomaly_detector.py — 5 reads
   • tests/knowledge/test_code_intelligence_neo4j.py — 3 reads
   • tests/session/test_redis_store_real.py — Redis env vars
   • tests/spike/test_kg_context.py — 3 reads
4. T7 (CRITICAL for knowledge): ALL Neo4j tests must use test_id isolation:
   • Replace session.run("CREATE (n:X {name: 'test'})") with UUID-tagged nodes
   • Cleanup pattern: MATCH (n {test_id: $tid}) DETACH DELETE n
   • Remove any session.run("MATCH (n) DELETE n") (global wipes — BREAKS parallel)
5. T8: Redis session tests — verify per-worker DB isolation is active
6. T9: Session Prolog tests — per-test engine, not global singleton
7. T3: Downscope _neo4j_checked session fixture in knowledge/conftest.py
8. Parallel safety check:

   cd /home/mohamed/workspace/orchestrata-ultimate && uv run pytest tests/knowledge tests/session -n auto -x --timeout=120 -q
   

Expect: Cumulative ~10,000+ tests passing with -n auto

Step 204: 🚪 Tier 3 Gate Check + Commit

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.knowledge_graph.code_parser import *
from orchestrata_ultimate.session import *
from orchestrata_ultimate.memory import *
print('TIER 3 ALL OK')
" && uv run pytest tests/ -q

cd /home/mohamed/workspace/orchestrata-ultimate
git add -A
git commit -m "Tier 3: Full knowledge graph, session management, memory engine"

Tier 4: External Surface (Steps 205–224)

Goal: WebSocket API, plugin system, external integrations. ~8,000 LOC.

Sub-phase 4.1: Gateway (Steps 205–213)

Step 205: Create gateway/ package

mkdir -p $ULT/gateway/handlers
touch $ULT/gateway/__init__.py
touch $ULT/gateway/handlers/__init__.py

Step 206: Port server.py (adapt to FastAPI)

Source: $SRC/orchestrata-gateway/src/orchestrata/gateway/server.py Destination: $ULT/gateway/server.py

Actions:

1. Copy, translate
2. Adapt WebSocket setup to work with FastAPI (already a dependency)
3. Keep JSON-RPC 2.0 protocol

Verify: python -c "from orchestrata_ultimate.gateway.server import *; print('OK')"

Step 207: Port auth.py and auth_handler.py

Actions:

1. Copy both, translate
2. JWT auth requires pyjwt (added in Step 36)

Verify: python -c "from orchestrata_ultimate.gateway.auth import *; print('OK')"

Step 208: Port protocol.py, models.py, config.py

Actions: Copy all three, translate, fix env vars

Verify: python -c "from orchestrata_ultimate.gateway.protocol import *; print('OK')"

Step 209: Port rpc.py, ring_buffer.py, pubsub.py

Actions: Copy all three, translate

Verify: python -c "from orchestrata_ultimate.gateway.rpc import *; print('OK')"

Step 210: Port session.py, audit.py, exceptions.py, cli.py

Actions: Copy all, translate

Verify: python -c "from orchestrata_ultimate.gateway.session import *; print('OK')"

Step 211: Port handlers/ (11 handler files)

Source: $SRC/orchestrata-gateway/src/orchestrata/gateway/handlers/ Destination: $ULT/gateway/handlers/

Actions:

1. Copy all handler files:

   cp $SRC/orchestrata-gateway/src/orchestrata/gateway/handlers/*.py $ULT/gateway/handlers/
   

2. Apply standard import translation to all:

   for f in $ULT/gateway/handlers/*.py; do
       # Apply sed chain
   done
   

3. Fix handlers/volk.py: rename Volk references to Agent

Verify: python -c "from orchestrata_ultimate.gateway.handlers import *; print('OK')"

Step 212: Delete integrations/vizint.py stub

Actions: Delete $ULT/integrations/vizint.py Verify: No import references remain

Step 213: 🚪 Gateway Gate Check

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.gateway.server import *
from orchestrata_ultimate.gateway.auth import *
from orchestrata_ultimate.gateway.rpc import *
print('GATEWAY OK')
"

Sub-phase 4.2: Plugin SDK (Steps 214–220)

Step 214: Create plugin/ package

mkdir -p $ULT/plugin
touch $ULT/plugin/__init__.py

Step 215: Port loader.py and registry.py (fix plugin prefix!)

Source: $SRC/orchestrata-plugin/src/orchestrata/plugin/loader.py and registry.py Destination: $ULT/plugin/

Actions:

1. Copy both, translate
2. CRITICAL: Fix plugin security allowlist in loader.py (line ~28):

   # Before:
   ALLOWED_PREFIXES = ["orchestrata.plugins."]
   # After:
   ALLOWED_PREFIXES = ["orchestrata_ultimate.plugins."]
   

3. Fix entry point prefix in config.py:

   # Before:
   "orchestrata_plugin_"
   # After:
   "orchestrata_ultimate_plugin_"
   

Verify:

grep "orchestrata\." $ULT/plugin/loader.py | grep -v orchestrata_ultimate

Expect: 0 matches

Step 216: Port manager.py and discovery.py

Actions: Copy both, translate

Verify: python -c "from orchestrata_ultimate.plugin.manager import *; print('OK')"

Step 217: Port config.py, context.py, manifest.py

Actions:

1. Copy all three, translate
2. Fix plugin prefix strings in config.py (see Step 215)
3. Fix logger name in context.py (~line 20): f-string with orchestrata_ultimate

Verify: python -c "from orchestrata_ultimate.plugin.config import *; print('OK')"

Step 218: Port interfaces.py, governance.py, sdk.py, exceptions.py, registration.py

Actions: Copy all 5, translate

Verify: python -c "from orchestrata_ultimate.plugin.sdk import *; print('OK')"

Step 219: Update plugin/init.py

Actions: Add key exports

Verify: python -c "from orchestrata_ultimate.plugin import *; print('OK')"

Step 220: 🚪 Plugin Gate Check

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.plugin.loader import *
from orchestrata_ultimate.plugin.registry import *
from orchestrata_ultimate.plugin.sdk import *
print('PLUGIN OK')
"

Sub-phase 4.3: Integrations (Steps 221–223)

Step 221: Build real CheetahClaws integration

Goal: Replace the stub with a real TUI integration.

Actions:

1. Create $ULT/integrations/cheetahclaws/ package:

   mkdir -p $ULT/integrations/cheetahclaws
   touch $ULT/integrations/cheetahclaws/__init__.py
   

2. Build real integration based on the stub's API surface:
   • Read $ULT/integrations/cheetahclaws.py to understand expected interface
   • Implement real TUI connection (or mark as TODO with working no-op)
3. Delete old stub: $ULT/integrations/cheetahclaws.py

Verify: python -c "from orchestrata_ultimate.integrations.cheetahclaws import *; print('OK')"

Step 222: Build real Todoist integration

Goal: Replace the stub with a real API client.

Actions:

1. Create $ULT/integrations/todoist/ package:

   mkdir -p $ULT/integrations/todoist
   touch $ULT/integrations/todoist/__init__.py
   

2. Read $ULT/integrations/todoist.py for expected interface
3. Implement real Todoist API client (uses httpx)
4. Delete old stub: $ULT/integrations/todoist.py

Verify: python -c "from orchestrata_ultimate.integrations.todoist import *; print('OK')"

Step 223: Clean up integrations/

Actions:

1. Verify all stubs deleted:

   ls $ULT/integrations/
   

   Should show: __init__.py, cheetahclaws/, todoist/ (openrouter.py deleted in Step 59, vizint.py in Step 212)
2. Update $ULT/integrations/__init__.py

Step 224: 🚪 Tier 4 Final Gate Check + Commit

cd /home/mohamed/workspace/orchestrata-ultimate && python -c "
from orchestrata_ultimate.gateway.server import *
from orchestrata_ultimate.plugin.sdk import *
from orchestrata_ultimate.integrations import *
print('TIER 4 ALL OK')
" && uv run pytest tests/ -q

cd /home/mohamed/workspace/orchestrata-ultimate
git add -A
git commit -m "Tier 4: Gateway, plugin SDK, real integrations"

Appendix A: Import Translation Reference

Module Mapping (complete)

Class Rename Map

Dynamic Import Locations (15 total)

Appendix B: Environment Variable Defaults

Required infra endpoints are resolved from the active ORCHESTRATA_ENV_PROFILE (env/{dev,test,prod}.env, endpoint-only) layered over secrets-only .env — via core.redis_factory.resolve_redis_host()/resolve_redis_port() and core.graph_factory.resolve_uri()/resolve_kg_database(), all of which raise when unset.

Appendix C: Circular Dependency Resolutions

NOTE: The main entry files (kernel.py, policy_engine.py, orchestrator.py, postman.py) do NOT have cross-package imports — they all import only from core.interfaces and core.traceability. The circular dependencies exist in sub-files within those packages:

Architecture insight: Orchestrata achieves separation through the core.interfaces layer. All major components depend on shared Protocol definitions in core, not on each other directly. The circular deps are primarily in infrastructure wiring code (runtime, registry, pipeline), not in business logic.

Appendix D: Files to Skip (gRPC)

Do NOT port these files (gRPC unavailable on Python 3.14t):

• $SRC/orchestrata-cxp/src/orchestrata/cxp/proto/ (entire directory)
• $SRC/orchestrata-cxp/src/orchestrata/cxp/grpc_client.py
• $SRC/orchestrata-cxp/src/orchestrata/cxp/grpc_server.py
• $SRC/orchestrata-cxp/src/orchestrata/cxp/binary_serializer.py
• $SRC/orchestrata-cxp/src/orchestrata/cxp/prolog_bridge.py

The kernel dispatcher (Step 154) handles gRPC absence with conditional import.

Post-Tier: CLI Unification (Steps 225–231)

Goal: Wire ported CLIs (kernel=Click, postman=Click, session=Click, gateway=argparse) into ultimate's main Typer CLI.

Step 225: Adapt kernel CLI to typer subcommand

File: $ULT/kernel/cli.py (ported in Step 165, currently Click-based)

Actions:

1. Read $ULT/kernel/cli.py — it uses @click.group() and @cli.command()
2. Convert to a typer app:

   import typer
   kernel_app = typer.Typer(name="kernel", help="Kernel management commands")
   
   @kernel_app.command()
   def start(...): ...
   

3. Or keep Click and use typer.main.get_group(kernel_app) for interop

Verify: python -c "from orchestrata_ultimate.kernel.cli import kernel_app; print('OK')"

Step 226: Adapt postman CLI to typer subcommand

Same pattern as Step 225 for $ULT/postman/cli.py.

Step 227: Adapt session CLI to typer subcommand

Same pattern for $ULT/session/cli.py.

Step 228: Adapt gateway CLI to typer subcommand

$ULT/gateway/cli.py uses argparse (not Click). Convert to typer or wrap.

Step 229: Register all subcommands in main cli.py

File: $ULT/cli.py

Actions:

1. Read current $ULT/cli.py — it has typer commands: init, session, achieve, task, complete, etc.
2. Add subcommand groups:

   from orchestrata_ultimate.kernel.cli import kernel_app
   from orchestrata_ultimate.postman.cli import postman_app
   from orchestrata_ultimate.session.cli import session_app
   from orchestrata_ultimate.gateway.cli import gateway_app
   
   app.add_typer(kernel_app, name="kernel")
   app.add_typer(postman_app, name="postman")
   app.add_typer(session_app, name="session-mgr")  # Avoid conflict with existing "session" command
   app.add_typer(gateway_app, name="gateway")
   

3. Resolve command name conflicts (e.g., existing session vs session_app)

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && python -m orchestrata_ultimate --help

Expect: Shows all subcommand groups (kernel, postman, session-mgr, gateway) plus existing commands

Step 230: Add entry point to pyproject.toml

File: /home/mohamed/workspace/orchestrata-ultimate/pyproject.toml

Actions:

1. Add under [project.scripts]:

   [project.scripts]
   ultimate = "orchestrata_ultimate.cli:app"
   

Verify:

cd /home/mohamed/workspace/orchestrata-ultimate && uv run ultimate --help

Step 231: 🚪 Final CLI Integration Gate Check + Commit

cd /home/mohamed/workspace/orchestrata-ultimate && python -m orchestrata_ultimate --help && uv run pytest tests/ -q

git add -A
git commit -m "Post-tier: Unified CLI with kernel, postman, session, gateway subcommands"

Generated from implementation-plan.md (13 adversarial review rounds) + ast-deep-comparison.json (34 pairs, 240 import translations) Reviewed through 4 rounds of adversarial subagent review (19 fixes applied) Total: ~231 steps across Phase 0 + 4 Tiers + CLI Unification

Related

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