Knowledge Wiki Orchestrata Ultimate

Orchestrata Ultimate › Plans › stage2_port_plan

Stage 2 Porting Plan: Fix, Verify, and Production-Ready

Source: plans/stage2_port_plan.md at 8a2cb42ad · last changed 2026-07-27 · first committed 2026-04-19 · 316 lines.

Prose pending.

Plan text

Stage 2 Porting Plan: Fix, Verify, and Production-Ready

Previous Plan: plans/execution-plan.md (238 steps, 5 phases) — MARKED DONE as of 2026-04-19. Status: The bulk port produced 481 source files and 190 test files, but 54 source files have syntax errors and 29 test modules fail collection. Coverage is 24%, not 92%. Goal: Move from "bulk ported" to "production-ready" — all code compiles, all tests pass in parallel, coverage ≥90%, AST parity verified, requirements traceability validated.

How to Use This Plan

  1. Work top-to-bottom within a phase. Do not start Phase N+1 until Phase N gate checks pass.
  2. After each sub-phase, update plans/stage2_tracker.md with DONE/PENDING/IN_PROGRESS.
  3. Run gate check commands exactly as written. If they fail, stop and fix.
  4. Commit at every gate check (🚪) with a meaningful message.

Phase 0: Syntax Error Blitz (Critical Path)

Goal: All 481 source files must compile with py_compile.

Sub-phase 0.1: CXP Protocol (21 files)

Verification:

python -c "import py_compile; [py_compile.compile(f'dsrc/orchestrata_ultimate/cxp/{f}', doraise=True) for f in __import__('os').listdir('src/orchestrata_ultimate/cxp') if f.endswith('.py')]"
# Must exit 0

Sub-phase 0.2: Providers (12 files)

Verification:

python -c "import py_compile, os; [py_compile.compile(os.path.join(r,f), doraise=True) for r,_,files in os.walk('src/orchestrata_ultimate/providers') for f in files if f.endswith('.py')]"

Sub-phase 0.3: Core, DI, Drivers, LLM, Postman, Orchestrator (6 files)

Verification:

python -c "
import py_compile, os
errors = []
for r, _, files in os.walk('src/orchestrata_ultimate'):
    for f in files:
        if f.endswith('.py'):
            p = os.path.join(r, f)
            try:
                py_compile.compile(p, doraise=True)
            except py_compile.PyCompileError as e:
                errors.append(p)
print(f'Total syntax errors: {len(errors)}')
for e in errors: print(' ', e)
exit(1 if errors else 0)
"

🚪 Gate 0: Zero Syntax Errors

Command:

python -c "import py_compile, os; errors=0; [py_compile.compile(os.path.join(r,f), doraise=True) or None for r,_,files in os.walk('src/orchestrata_ultimate') for f in files if f.endswith('.py')]"

Expected: Exit 0, no output.

Phase 1: Test Collection Recovery

Goal: All 190 test files must import successfully (pytest --co exits 0 with zero ERRORs).

Sub-phase 1.1: Fix Test Import Errors (29 modules)

The following test modules fail during collection because they import broken source modules:

Approach:

  1. Fix the underlying source module syntax error (Phase 0).
  2. If test still fails collection, check for broken imports in the test file itself.
  3. Check for os.environ["X"] mutations in test files (T2 violation) and replace with monkeypatch.setenv().

🚪 Gate 1: Zero Collection Errors

Command:

uv run pytest tests/ --co -q

Expected: Exit 0, zero ERROR lines.

Phase 2: Test Failure Remediation

Goal: pytest -n auto --timeout=120 passes with 0 failures, 0 errors.

Sub-phase 2.1: Fix Runtime Failures (55 failed + 49 error)

Run the full suite, categorize failures:

Approach:

  1. Run uv run pytest tests/ -n auto --timeout=120 --tb=short 2>&1 | tee /tmp/test-failures.txt
  2. Group failures by root cause.
  3. Fix Category A and B first (no external deps).
  4. Fix Category C (fixture/infrastructure).
  5. Fix Category D (environmental) last — ensure in-memory fallbacks work.

🚪 Gate 2: Zero Test Failures

Command:

uv run pytest tests/ -n auto --timeout=120

Expected: Exit 0, all green.

Phase 3: Coverage Drive

Goal: Coverage ≥90% (currently 24%).

Sub-phase 3.1: Baseline and Gap Analysis

Sub-phase 3.2: Fill Coverage Gaps

🚪 Gate 3: 90% Coverage

Command:

uv run pytest tests/ -n auto --timeout=120 --cov=src/orchestrata_ultimate --cov-fail-under=90

Expected: Exit 0, coverage ≥90%.

Phase 4: AST Parity and Deep Compare

Goal: Source code semantically matches the frozen orchestrata monorepo.

Sub-phase 4.1: Regenerate AST Artifacts

Sub-phase 4.2: Fix AST Gaps

🚪 Gate 4: AST Parity

Command:

python -c "
import json
with open('plans/ast-deep-comparison.json') as f:
    d = json.load(f)
needs_creation = [p for p in d.get('paired_classes',[]) if p.get('readiness') == 'needs_creation']
stubs = [p for p in d.get('paired_classes',[]) if p.get('readiness') == 'stub']
print(f'needs_creation: {len(needs_creation)}, stubs: {len(stubs)}')
exit(1 if needs_creation or stubs else 0)
"

Expected: Exit 0, zero needs_creation and zero stub classes.

Phase 5: Requirements Traceability and Production Readiness

Goal: Every spec requirement is traceable to code and tests.

Sub-phase 5.1: RTM Generation and Validation

Sub-phase 5.2: Code Quality Gates

Sub-phase 5.3: Git and Release

🚪 Gate 5: Production Ready

Commands:

uv run pytest tests/ -n auto --timeout=120 --cov=src/orchestrata_ultimate --cov-fail-under=90
uv run ruff check src/ tests/
python scripts/architecture_checker.py

Expected: All exit 0.

Current Status (2026-04-27):

Summary

Phase Goal Estimated Files Touched Gate Check
0 Fix 54 syntax errors ~54 source files py_compile clean
1 Fix 29 test collection errors ~29 test files + deps pytest --co clean
2 Fix 104 runtime test failures source + tests pytest -n auto clean
3 Drive coverage 24% → 90%+ ~50+ new test files --cov-fail-under=90
4 AST parity with orchestrata ~50 source files Zero stubs/needs_creation
5 RTM + quality + release docs + metadata All gates pass

Files to Update During Stage 2

File Purpose
plans/stage2_tracker.md Live task tracker — update after every sub-phase
plans/stage2_port_plan.md This plan — amend if scope changes
context.json Session state — update on session close
projectstatus.md High-level status — update at each gate