Orchestrata Ultimate › Plans › codemod-engine-execution-plan

SPEC-110 Codemod Engine — Execution Plan (Revised)

Source: plans/codemod-engine-execution-plan.md at 8a2cb42ad · last changed 2026-07-27 · first committed 2026-07-27 · 924 lines.

Prose pending.

Plan text

SPEC-110 Codemod Engine — Execution Plan (Revised)

Date: 2026-07-27
Status: Ready for Implementation
Total Estimated Time: ~2.5 hours (145 minutes)
Parallel Agents: Yes (W1 and W2 use parallel agents)

Overview

This execution plan implements the SPEC-110 In-Memory Code Intelligence Platform across 7 phases (W0-W6). The plan is optimized for:

Parallel execution where possible (W1: Forest+Sentinel, W2: Architect+Reviewer)
Scoped test runs — only tests/refactor/codemod/ (not full suite)
Incremental verification — each phase runs its own tests before integration
Realistic time estimates based on agent speed and test execution time

Test Strategy

Test Scope

Only run codemod tests:

pytest tests/refactor/codemod/ -v

Or use batched executor:

python scripts/run_tests.py tests/refactor/codemod/ --skip-gates

Never run full suite (27,844 tests) during implementation — only in W6 final quality check if needed.

Test Execution Time Estimates

Test Category	Files	Tests	Estimated Time
W0 (skeleton)	1	5	30 seconds
W1 (forest+sentinel)	4	30	2-3 minutes
W2 (passes+review)	5	40	3-4 minutes
W3 (integration)	3	20	2 minutes
W4 (persistence)	1	10	1 minute
W5 (c extension)	1	10	1 minute
W6 (full codemod)	15	126	5-8 minutes

Total test time: ~15-20 minutes across all phases

Phase 1: Foundation (W0 — Scaffold)

Agent: Haiku (fast, cheap, mechanical tasks)
Duration: ~15 minutes
Dependencies: None (first phase)
Parallel Execution: No (single agent)

Tasks

Add dependencies (2 min)

cd ~/workspace/wt-QWEN
uv add libcst xxhash
uv run python -c "import libcst; import xxhash; print('OK')"

Generate skeletons from Mermaid contract (3 min)

uv run python scripts/serialize_codebase_ast.py gen-skeleton \
  --input plans/contracts/spec-110-codemod-engine.mmd \
  --output src/orchestrata_ultimate/refactor/codemod/ \
  --format python

Split monolithic output (3 min)

uv run python scripts/split_skeleton.py \
  --input src/orchestrata_ultimate/refactor/codemod/codemod.py \
  --output-dir src/orchestrata_ultimate/refactor/codemod/ \
  --mapping plans/contracts/skeleton-mapping.json

Create package structure (1 min)

mkdir -p src/orchestrata_ultimate/refactor/codemod/{analysis,observability,persistence}
touch src/orchestrata_ultimate/refactor/codemod/{analysis,observability,persistence}/__init__.py

Write conftest.py (3 min)
- Create tests/refactor/codemod/conftest.py with shared fixtures
- Fixtures: codemod_repo, sample_workspace, sample_changes

Verify skeleton code (2 min)

# Check syntax
uv run python -m py_compile src/orchestrata_ultimate/refactor/codemod/report.py
uv run python -m py_compile src/orchestrata_ultimate/refactor/codemod/observability/events.py
uv run python -m py_compile src/orchestrata_ultimate/refactor/codemod/persistence/repository.py

# Check imports
uv run python -c "from orchestrata_ultimate.refactor.codemod.report import ChangeEntry, ChangeSet, Finding"

# Check @traces decorators
grep -n "@traces" src/orchestrata_ultimate/refactor/codemod/report.py

Run Gate 0 smoke test (1 min)

uv run python -c "
from orchestrata_ultimate.refactor.codemod.report import ChangeEntry, ChangeSet, Finding
from orchestrata_ultimate.refactor.codemod.observability.events import CodemodEventType, CodemodEvent
from orchestrata_ultimate.refactor.codemod.persistence.repository import CodemodRun, CodemodPass
print('All skeleton classes can be instantiated!')
"

Tests

pytest tests/refactor/codemod/conftest.py -v

Expected: 5 tests pass (fixture validation)

Deliverables

src/orchestrata_ultimate/refactor/codemod/report.py (skeleton)
src/orchestrata_ultimate/refactor/codemod/observability/events.py (skeleton)
src/orchestrata_ultimate/refactor/codemod/persistence/repository.py (skeleton)
src/orchestrata_ultimate/refactor/codemod/__init__.py (exports)
src/orchestrata_ultimate/refactor/codemod/{analysis,observability,persistence}/__init__.py (empty)
tests/refactor/codemod/conftest.py (shared fixtures)

Success Criteria

[ ] Dependencies installed (libcst, xxhash)
[ ] Skeleton files generated with correct type hints
[ ] @traces decorators present on all public classes/methods
[ ] All skeleton files are syntactically valid
[ ] All skeleton files can be imported
[ ] All skeleton classes can be instantiated
[ ] Package structure created
[ ] conftest.py created with shared fixtures

Commit

git add -A
git commit -m "SPEC-110 W0: scaffold — skeletons, types, conftest, libcst+xxhash deps"

Phase 2: Core Infrastructure (W1 — Forest + Sentinel, Parallel)

Agents:

FOREST (Qwen Max): workspace.py, _csr_index.py, _cig.py, _cig_builder.py
SENTINEL (Sonnet): txn.py
Duration: ~25 minutes (20 min parallel + 5 min integration)
Dependencies: W0 (skeleton code)
Parallel Execution: Yes (FOREST and SENTINEL work in parallel)

MANDATORY: Agent Context Document

ALL agents MUST read and follow plans/codemod-engine-briefs/W1-AGENT-CONTEXT.md before starting implementation.

This document contains:

Complete standards reference (architecture rules, test standards, code style, security, performance)
All available tools and gates (checking scripts, linting tools, verification commands)
W1-specific requirements and success criteria
Skeleton code structure and dependencies
Test infrastructure (BDD configuration, fixtures, step definitions)
Execution workflow and common pitfalls

Agents that do not read this document will violate project standards and fail gates.

FOREST Agent (Qwen Max, ~20 min)

Tasks

Implement _csr_index.py (5 min)
- _CSRIndex class with CSR adjacency arrays
- Methods: from_edges(), dependencies(), dependents(), transitive_closure()
- O(1) lookups via array indexing
Implement _cig_builder.py (5 min)
- build_cig() function to extract nodes and edges from CST forest
- Node extraction: Module, Class, Function, Method, Parameter, Test, Import
- Edge extraction: IMPORTS, CALLS, INHERITS, DEFINES, TESTED_BY, OVERRIDES
Implement _cig.py (7 min)
- CodeIntelligenceGraph class with 11 query methods
- Algorithms: Tarjan's SCC (cycles), Kahn's (topological sort), BFS (blast radius, affected tests)
- Metrics: coupling score, abstraction level, centrality, impact score
Implement workspace.py (3 min)
- CodemodWorkspace class with load(), run(), commit() methods
- Eager parse with parallel ThreadPoolExecutor (12 cores)
- Properties: forest, unparsable, cig, stats()

Tests

pytest tests/refactor/codemod/test_workspace_load.py -v
pytest tests/refactor/codemod/test_workspace_index.py -v
pytest tests/refactor/codemod/test_code_intelligence_graph.py -v
pytest tests/refactor/codemod/test_csr_index.py -v

Expected: 30 tests pass (7 + 6 + 10 + 7)

Deliverables

src/orchestrata_ultimate/refactor/codemod/workspace.py
src/orchestrata_ultimate/refactor/codemod/_csr_index.py
src/orchestrata_ultimate/refactor/codemod/_cig.py
src/orchestrata_ultimate/refactor/codemod/_cig_builder.py
tests/refactor/codemod/test_workspace_load.py
tests/refactor/codemod/test_workspace_index.py
tests/refactor/codemod/test_code_intelligence_graph.py
tests/refactor/codemod/test_csr_index.py

SENTINEL Agent (Sonnet, ~20 min)

Tasks

Implement txn.py (15 min)
- commit_changes() function with atomic writes and rollback
- Helper functions: _snapshot_files(), _check_concurrent_edits(), _write_atomic(), _batch_fsync(), _verify_post_write(), _rollback()
- Security: O_NOFOLLOW (symlink prevention), fcntl.flock (advisory locking)
- Performance: batch fsync (5 dirs instead of 100 files)
Write tests (5 min)
- BDD scenarios from transactional_writeback.feature
- Test atomic write, batch fsync, post-write verification, rollback, concurrent-edit guard

Tests

pytest tests/refactor/codemod/test_transactional_writeback.py -v

Expected: 6 tests pass

Deliverables

src/orchestrata_ultimate/refactor/codemod/txn.py
tests/refactor/codemod/test_transactional_writeback.py

Integration (5 min)

After both agents complete:

Merge results

# Both agents write to same directory, no conflicts expected
# Verify all files exist
ls -la src/orchestrata_ultimate/refactor/codemod/*.py

Run all W1 tests

pytest tests/refactor/codemod/test_workspace_load.py \
       tests/refactor/codemod/test_workspace_index.py \
       tests/refactor/codemod/test_code_intelligence_graph.py \
       tests/refactor/codemod/test_csr_index.py \
       tests/refactor/codemod/test_transactional_writeback.py \
       -v

Fix any integration issues
- Import errors
- Type mismatches
- Missing dependencies

Success Criteria

[ ] _csr_index.py implemented with O(1) lookups
[ ] _cig_builder.py extracts all node and edge types
[ ] _cig.py implements all 11 query methods
[ ] workspace.py loads codebase in <120s (parallel)
[ ] txn.py implements atomic writes with rollback
[ ] Batch fsync reduces I/O overhead
[ ] Concurrent-edit guard detects modifications
[ ] All 36 W1 tests pass

Commit

git add -A
git commit -m "SPEC-110 W1: forest + sentinel — workspace, CIG, CSR, txn"

Phase 3: Passes and Reviews (W2 — Architect + Reviewer, Parallel)

Agents:

ARCHITECT (Qwen Max): passes.py, analysis/*.py
REVIEWER (Sonnet): review.py, observability/*.py
Duration: ~25 minutes (20 min parallel + 5 min integration)
Dependencies: W1 (workspace, CIG, txn)
Parallel Execution: Yes (ARCHITECT and REVIEWER work in parallel)

MANDATORY: Agent Context Document

ALL agents MUST read and follow plans/codemod-engine-briefs/W1-AGENT-CONTEXT.md before starting implementation.

This document contains all project standards, tools, gates, and verification commands. Agents that do not read this document will violate project standards and fail gates.

ARCHITECT Agent (Qwen Max, ~20 min)

Tasks

Implement passes.py (10 min)
- TransformPass ABC with apply() and apply_file() methods
- 5 built-in passes:
  - ReplaceStringLiteralPass (exact and regex modes)
  - AddImportPass (LibCST AddImportVisitor pattern)
  - RemoveUnusedImportPass (CIG IMPORTS edge analysis)
  - DocstringSweepPass (docstrings and comments)
  - RenameSymbolPass (consumes WorkspaceEditPlan from SPEC-109)
- Per-file parallel dispatch for embarrassingly-parallel passes
Implement analysis/*.py (10 min)
- 7 analysis modules:
  - blast_radius.py (BFS blast radius computation)
  - breaking_changes.py (API breaking change detection)
  - complexity.py (cyclomatic + nesting + cognitive complexity)
  - coverage.py (test-to-source mapping)
  - abstraction.py (abstraction level analysis)
  - coupling.py (efferent/afferent coupling metrics)
  - centrality.py (betweenness centrality)
- All analysis passes are read-only (no mutations)
- Return structured results (dataclasses)

Tests

pytest tests/refactor/codemod/test_transform_passes.py -v
pytest tests/refactor/codemod/test_analysis_passes.py -v

Expected: 16 tests pass (8 + 8)

Deliverables

src/orchestrata_ultimate/refactor/codemod/passes.py
src/orchestrata_ultimate/refactor/codemod/analysis/__init__.py
src/orchestrata_ultimate/refactor/codemod/analysis/blast_radius.py
src/orchestrata_ultimate/refactor/codemod/analysis/breaking_changes.py
src/orchestrata_ultimate/refactor/codemod/analysis/complexity.py
src/orchestrata_ultimate/refactor/codemod/analysis/coverage.py
src/orchestrata_ultimate/refactor/codemod/analysis/abstraction.py
src/orchestrata_ultimate/refactor/codemod/analysis/coupling.py
src/orchestrata_ultimate/refactor/codemod/analysis/centrality.py
tests/refactor/codemod/test_transform_passes.py
tests/refactor/codemod/test_analysis_passes.py

REVIEWER Agent (Sonnet, ~20 min)

Tasks

Implement review.py (12 min)
- ReviewPass ABC with review() method
- 40 in-memory review checks organized into 7 categories:
  - Complexity (4): cyclomatic, nesting, function length, parameter count
  - Style (6): line length, trailing whitespace, tab indentation, final newline, naming conventions, import ordering
  - Quality (4): type hints, docstrings, mutable defaults, god objects
  - Structure (6): stub methods, placeholders, function arguments, file length, nesting depth, error handling
  - Safety (10): bare os.environ, mock patterns, eval/exec, hardcoded secrets, banned libraries, flushdb/flushall, unscoped DETACH DELETE, TODO comments, broad raise, print outside main
  - Correctness (6): relative imports, imported module existence, entry point guard, third-party import declaration, file completeness, dependency declaration
  - Test Isolation (4): flushdb/flushall, unscoped DETACH DELETE, module-scoped fixtures, global mutable state
- All checks operate on LibCST trees (no ast.parse, no subprocess.run)
- Three-phase execution: fast structural (parallel), graph-dependent, Prolog semantic
Implement observability/*.py (8 min)
- 5 observer classes:
  - TracingObserver (structured JSON spans via core.tracing.Tracer)
  - MetricsObserver (Prometheus counters/histograms)
  - DebugPanelObserver (NDJSON trace files)
  - ErrorDetector (pattern alerts via EventBus)
  - GraphWriterObserver (async writes to graph DB, batched, non-blocking)
- CodemodEvent dataclass and CodemodEventType enum
- SyncObservable[CodemodEvent] integration

Tests

pytest tests/refactor/codemod/test_review_before_write.py -v
pytest tests/refactor/codemod/test_in_memory_review.py -v
pytest tests/refactor/codemod/test_observability.py -v

Expected: 24 tests pass (8 + 8 + 8)

Deliverables

src/orchestrata_ultimate/refactor/codemod/review.py
src/orchestrata_ultimate/refactor/codemod/observability/__init__.py
src/orchestrata_ultimate/refactor/codemod/observability/events.py (update existing)
src/orchestrata_ultimate/refactor/codemod/observability/tracing.py
src/orchestrata_ultimate/refactor/codemod/observability/metrics.py
src/orchestrata_ultimate/refactor/codemod/observability/debug_panel.py
src/orchestrata_ultimate/refactor/codemod/observability/error_detector.py
src/orchestrata_ultimate/refactor/codemod/observability/graph_writer.py
tests/refactor/codemod/test_review_before_write.py
tests/refactor/codemod/test_in_memory_review.py
tests/refactor/codemod/test_observability.py

Integration (5 min)

After both agents complete:

Merge results

ls -la src/orchestrata_ultimate/refactor/codemod/passes.py
ls -la src/orchestrata_ultimate/refactor/codemod/review.py
ls -la src/orchestrata_ultimate/refactor/codemod/analysis/*.py
ls -la src/orchestrata_ultimate/refactor/codemod/observability/*.py

Run all W2 tests

pytest tests/refactor/codemod/test_transform_passes.py \
       tests/refactor/codemod/test_analysis_passes.py \
       tests/refactor/codemod/test_review_before_write.py \
       tests/refactor/codemod/test_in_memory_review.py \
       tests/refactor/codemod/test_observability.py \
       -v

Fix any integration issues

Success Criteria

[ ] passes.py implements 5 built-in transform passes
[ ] Per-file parallel dispatch works for embarrassingly-parallel passes
[ ] analysis/*.py implements 7 analysis modules (all read-only)
[ ] review.py implements 40 in-memory review checks
[ ] All checks operate on LibCST trees (no subprocess calls)
[ ] observability/*.py implements 5 observer classes
[ ] All 40 W2 tests pass

Commit

git add -A
git commit -m "SPEC-110 W2: architect + reviewer — passes, analysis, review, observability"

Phase 4: Integration (W3 — Integrator)

Agent: Qwen Max
Duration: ~20 minutes
Dependencies: W1 + W2 (all previous waves)
Parallel Execution: No (single agent)

MANDATORY: Agent Context Document

The agent MUST read and follow plans/codemod-engine-briefs/W1-AGENT-CONTEXT.md before starting implementation.

This document contains all project standards, tools, gates, and verification commands. Agents that do not read this document will violate project standards and fail gates.

Tasks

Implement scripts/codemod.py (8 min)
- CLI with argparse
- 4 subcommands:
  - load-bench: Measure workspace load time, RSS delta, file count
  - run --pass <name> [--arg k=v]... [--apply]: Execute named passes
  - report <path>: Pretty-print CommitReport JSON
  - analyze --query <type> [--module <path>]: Execute CIG queries
- Exit codes: 0 success, 1 review-abort, 2 usage error
- --auto-start flag for daemon (W3 only, daemon implementation in W4)
Implement RenameSymbolPass (5 min)
- Add to passes.py (or create passes_rename.py)
- Consume WorkspaceEditPlan from orchestrata_ultimate.refactor.rename.models
- Convert LSP text edits to LibCST mutations via libcst.metadata.PositionProvider
- No second rename resolver (consumes SPEC-109 output only)
Write benchmark tests (5 min)
- test_benchmark_load.py: Measure parse time, RSS delta, query latency
- Verify performance targets from spec.md
Write CLI and interop tests (2 min)
- test_cli.py: BDD scenarios from cli.feature
- test_spec109_interop.py: BDD scenarios from spec109_interop.feature

Tests

pytest tests/refactor/codemod/test_cli.py -v
pytest tests/refactor/codemod/test_spec109_interop.py -v
pytest tests/refactor/codemod/test_benchmark_load.py -v

Expected: 12 tests pass (5 + 4 + 3)

Deliverables

scripts/codemod.py
src/orchestrata_ultimate/refactor/codemod/passes.py (update with RenameSymbolPass)
tests/refactor/codemod/test_cli.py
tests/refactor/codemod/test_spec109_interop.py
tests/refactor/codemod/test_benchmark_load.py

Success Criteria

[ ] CLI works with all 4 subcommands
[ ] Exit codes correct (0/1/2)
[ ] RenameSymbolPass consumes WorkspaceEditPlan from SPEC-109
[ ] LSP text edits converted to LibCST mutations
[ ] Byte-identical results between EditApplier and RenameSymbolPass
[ ] Benchmarks meet performance targets
[ ] All 12 W3 tests pass

Commit

git add -A
git commit -m "SPEC-110 W3: integrator — CLI, SPEC-109 interop, benchmarks"

Phase 5: Persistence (W4 — Persistence)

Agent: Qwen Max
Duration: ~20 minutes
Dependencies: W1 + W2 + W3 (all previous waves)
Parallel Execution: No (single agent)

MANDATORY: Agent Context Document

The agent MUST read and follow plans/codemod-engine-briefs/W1-AGENT-CONTEXT.md before starting implementation.

This document contains all project standards, tools, gates, and verification commands. Agents that do not read this document will violate project standards and fail gates.

Tasks

Extend canonical_schema.py (3 min)
- Add new labels: CodemodRun, CodemodPass, CodemodFinding, CodeChange
- Add new relationships: HAS_CODEMOD_RUN, HAS_PASS, HAS_FINDING, ABOUT, PRODUCED_BY, BREAKING_CHANGE
- CodeChange reuses existing Change label as sub-label
Implement persistence/repository.py (5 min)
- CodemodGraphRepository Protocol
- Methods: save_run(), save_pass(), save_findings(), save_changes(), query_runs(), query_findings(), query_affected_code()
Implement persistence/bolt_repository.py (10 min)
- BoltSyncCodemodRepository class
- Use SyncGraphRepository.unit_of_work() for transactional writes
- Cypher MERGE patterns for all node and edge types
- Batch writes for performance
Write tests (2 min)
- test_graph_persistence.py: BDD scenarios from graph_persistence.feature

Tests

pytest tests/refactor/codemod/test_graph_persistence.py -v

Expected: 5 tests pass

Deliverables

src/orchestrata_ultimate/knowledge_graph/canonical_schema.py (update)
src/orchestrata_ultimate/refactor/codemod/persistence/__init__.py (update)
src/orchestrata_ultimate/refactor/codemod/persistence/repository.py
src/orchestrata_ultimate/refactor/codemod/persistence/bolt_repository.py
tests/refactor/codemod/test_graph_persistence.py

Success Criteria

[ ] canonical_schema.py extended with new labels and relationships
[ ] CodemodGraphRepository Protocol implemented
[ ] BoltSyncCodemodRepository writes to graph DB
[ ] Cypher MERGE patterns correct
[ ] All 5 W4 tests pass

Commit

git add -A
git commit -m "SPEC-110 W4: persistence — repository, graph writer, ontology"

Phase 6: C Extension (W5 — C Extension)

Agent: Qwen Max
Duration: ~25 minutes
Dependencies: W1 (CSR index)
Parallel Execution: No (single agent)

MANDATORY: Agent Context Document

The agent MUST read and follow plans/codemod-engine-briefs/W1-AGENT-CONTEXT.md before starting implementation.

This document contains all project standards, tools, gates, and verification commands. Agents that do not read this document will violate project standards and fail gates.

Tasks

Create sub-package structure (2 min)

mkdir -p scripts/_codemod_fast/codemod_fast

Write pyproject.toml and setup.py (3 min)
- setuptools build-backend
- Extension declaration for codemod_fast._native
Implement csr_index.c (8 min)
- CSR build in C (10x faster than Python array.array)
- BFS transitive closure
- Python C API bindings
Implement content_hash.c (4 min)
- xxhash3 wrapper (5 GB/s vs SHA-256 500 MB/s)
- Python C API bindings
Implement mmap_loader.c (4 min)
- mmap file loading for zero-copy parse source
- Python C API bindings
Implement module.c (2 min)
- PyModuleDef with Py_mod_gil = Py_MOD_GIL_NOT_USED declaration
- CRITICAL: This ensures free-threading compatibility

Wire in root pyproject.toml (1 min)

[tool.uv.sources]
codemod-fast = { path = "scripts/_codemod_fast" }

[tool.uv]
no-build-isolation-package = ["janus-swi", "codemod-fast"]

Write parity tests (1 min)
- test_c_extension.py: Verify C and Python implementations produce identical results

Tests

uv sync --dev  # Build C extension
pytest tests/refactor/codemod/test_c_extension.py -v

Expected: 6 tests pass

Deliverables

scripts/_codemod_fast/pyproject.toml
scripts/_codemod_fast/setup.py
scripts/_codemod_fast/codemod_fast/__init__.py
scripts/_codemod_fast/codemod_fast/csr_index.c
scripts/_codemod_fast/codemod_fast/content_hash.c
scripts/_codemod_fast/codemod_fast/mmap_loader.c
scripts/_codemod_fast/codemod_fast/module.c
pyproject.toml (update)
tests/refactor/codemod/test_c_extension.py

Success Criteria

[ ] C extension builds successfully
[ ] Py_MOD_GIL_NOT_USED declared in module.c
[ ] C and Python implementations produce identical results
[ ] Performance improvement measured (CSR build 10x faster, xxhash 10x faster)
[ ] All 6 W5 tests pass

Commit

git add -A
git commit -m "SPEC-110 W5: c extension — _codemod_fast sub-package"

Phase 7: Quality (W6 — Quality)

Agent: Claude (me)
Duration: ~15 minutes
Dependencies: All previous waves
Parallel Execution: No (single agent)

MANDATORY: Agent Context Document

I MUST read and follow plans/codemod-engine-briefs/W1-AGENT-CONTEXT.md before running quality gates.

This document contains all project standards, tools, gates, and verification commands.

Tasks

Run all gates (5 min)

.venv/bin/ruff check src tests scripts
.venv/bin/black --check src/orchestrata_ultimate/refactor/codemod tests/refactor/codemod scripts/codemod.py
PYTHONPATH=src .venv/bin/python scripts/serialize_codebase_ast.py standards
PYTHONPATH=src .venv/bin/python scripts/serialize_codebase_ast.py check-deps --include-tests
PYTHONPATH=src .venv/bin/python scripts/test-review.py tests/refactor/codemod/ --stdout
PYTHONPATH=src .venv/bin/python scripts/pyright_ratchet.py --max 283

Run coverage (3 min)

PYTHONPATH=src .venv/bin/python -m pytest tests/refactor/codemod/ \
  --cov=orchestrata_ultimate.refactor.codemod --cov-report=term-missing \
  -p orchestrata_ultimate.core.threading.pytest_live_observer \
  -o addopts=""

Target: ≥90% per file

Run skeleton-diff (2 min)

PYTHONPATH=src .venv/bin/python scripts/serialize_codebase_ast.py skeleton-diff \
  <skeleton> <final> --leafmap <leafmap>

Run all codemod tests (3 min)
```
pytest tests/refactor/codemod/ -v
```
Expected: 126 tests pass
Generate final report (2 min)
- Summary of all waves
- Test results
- Coverage report
- Performance benchmarks
- Known issues / deferred features

Success Criteria

[ ] All 6 gates pass (ruff, black, standards, check-deps, test-review, pyright_ratchet)
[ ] Coverage ≥90% per file
[ ] Skeleton-diff shows no unexpected structural changes
[ ] All 126 codemod tests pass
[ ] Final report generated

Commit

git add -A
git commit -m "SPEC-110 W6: quality — gates, coverage, skeleton-diff, final report"

Execution Timeline

Phase	Wave	Agents	Duration	Cumulative
1	W0 (Scaffold)	Haiku	15 min	15 min
2	W1 (Forest+Sentinel)	Qwen Max + Sonnet (parallel)	25 min	40 min
3	W2 (Architect+Reviewer)	Qwen Max + Sonnet (parallel)	25 min	65 min
4	W3 (Integrator)	Qwen Max	20 min	85 min
5	W4 (Persistence)	Qwen Max	20 min	105 min
6	W5 (C Extension)	Qwen Max	25 min	130 min
7	W6 (Quality)	Claude	15 min	145 min

Total Estimated Time: ~2.5 hours (145 minutes)

Parallel Execution Strategy

Phase 2 (W1): Forest + Sentinel

Dispatch both agents simultaneously:

# Agent 1: FOREST (Qwen Max)
task_forest = dispatch_agent(
    model="qwen-max",
    brief="plans/codemod-engine-briefs/BRIEF-W1.md#forest",
    files=[
        "src/orchestrata_ultimate/refactor/codemod/workspace.py",
        "src/orchestrata_ultimate/refactor/codemod/_csr_index.py",
        "src/orchestrata_ultimate/refactor/codemod/_cig.py",
        "src/orchestrata_ultimate/refactor/codemod/_cig_builder.py",
        "tests/refactor/codemod/test_workspace_load.py",
        "tests/refactor/codemod/test_workspace_index.py",
        "tests/refactor/codemod/test_code_intelligence_graph.py",
        "tests/refactor/codemod/test_csr_index.py",
    ]
)

# Agent 2: SENTINEL (Sonnet)
task_sentinel = dispatch_agent(
    model="sonnet",
    brief="plans/codemod-engine-briefs/BRIEF-W1.md#sentinel",
    files=[
        "src/orchestrata_ultimate/refactor/codemod/txn.py",
        "tests/refactor/codemod/test_transactional_writeback.py",
    ]
)

# Wait for both to complete
wait(task_forest, task_sentinel)

# Integration: merge results, run tests, fix issues
integrate_w1()

Phase 3 (W2): Architect + Reviewer

Dispatch both agents simultaneously:

# Agent 1: ARCHITECT (Qwen Max)
task_architect = dispatch_agent(
    model="qwen-max",
    brief="plans/codemod-engine-briefs/BRIEF-W2.md#architect",
    files=[
        "src/orchestrata_ultimate/refactor/codemod/passes.py",
        "src/orchestrata_ultimate/refactor/codemod/analysis/*.py",
        "tests/refactor/codemod/test_transform_passes.py",
        "tests/refactor/codemod/test_analysis_passes.py",
    ]
)

# Agent 2: REVIEWER (Sonnet)
task_reviewer = dispatch_agent(
    model="sonnet",
    brief="plans/codemod-engine-briefs/BRIEF-W2.md#reviewer",
    files=[
        "src/orchestrata_ultimate/refactor/codemod/review.py",
        "src/orchestrata_ultimate/refactor/codemod/observability/*.py",
        "tests/refactor/codemod/test_review_before_write.py",
        "tests/refactor/codemod/test_in_memory_review.py",
        "tests/refactor/codemod/test_observability.py",
    ]
)

# Wait for both to complete
wait(task_architect, task_reviewer)

# Integration: merge results, run tests, fix issues
integrate_w2()

Risk Mitigation

Risk	Mitigation
LibCST 1.8.6 native parser crashes on 3.14t	`LIBCST_PARSER_TYPE=pure` fallback; verify in W0
gen-skeleton `<<component>>` unsupported	Use `<<class>>` in .mmd (already planned)
gen-skeleton outputs monolithic file	Split by namespace manually after generation
C extension re-enables GIL	`Py_MOD_GIL_NOT_USED` in module.c; `tests/conftest.py` fast-fails if GIL re-enabled
Agent produces code that doesn't match shared types	Verify imports + type compatibility at integration
Prolog not available in test environment	`PrologSemanticReview` gracefully degrades to empty findings list
xxhash not FT-compatible	Pure-Python fallback via `hashlib`; xxhash is optional optimization
TOCTOU race conditions in concurrent-edit guard	`O_NOFOLLOW` + `fcntl.flock` added to txn.py design
Graph DB write bottleneck	Batching + buffer-overflow-drop semantics in GraphWriterObserver

Success Criteria (Overall)

[ ] All 140 requirements (REQ-110-001 through REQ-110-140) implemented and traced
[ ] All 14 acceptance tests (TST-110-001 through TST-110-014) pass
[ ] All 126 BDD scenarios pass
[ ] All 15 non-BDD tests pass
[ ] Coverage ≥90% per file
[ ] All gates pass (ruff, black, standards, check-deps, test-review, pyright_ratchet)
[ ] Performance targets met (parse time, query latency, RSS delta)
[ ] Graph ontology additions committed to canonical_schema.py
[ ] C extension builds and passes parity tests
[ ] Prolog semantic review integrates with codemod_review.pl
[ ] Observer architecture emits all 14 event types
[ ] CLI accepts all subcommands (load-bench, run, report, analyze)
[ ] SPEC-109 interop verified (RenameSymbolPass consumes WorkspaceEditPlan)
[ ] Transactional write-back passes all rollback and concurrent-edit guard tests
[ ] 40-check in-memory review executes without subprocess calls
[ ] Daemon architecture implemented (long-running service, Unix socket IPC, JSON-RPC 2.0, inotify file watching)

Next Steps

After W6 completes:

Review final report
Address any remaining issues
Update documentation (README, CHANGELOG)
Tag release (v110.0.0)
Merge to main branch

Appendix: Test File Inventory

Test File	Type	Tests	Phase
`conftest.py`	Fixtures	5	W0
`test_workspace_load.py`	BDD	7	W1
`test_workspace_index.py`	BDD	6	W1
`test_code_intelligence_graph.py`	BDD	10	W1
`test_csr_index.py`	Plain pytest	7	W1
`test_transactional_writeback.py`	BDD	6	W1
`test_transform_passes.py`	BDD	8	W2
`test_analysis_passes.py`	BDD	8	W2
`test_review_before_write.py`	BDD	8	W2
`test_in_memory_review.py`	BDD	8	W2
`test_observability.py`	BDD	8	W2
`test_cli.py`	BDD	5	W3
`test_spec109_interop.py`	BDD	4	W3
`test_benchmark_load.py`	Plain pytest	3	W3
`test_graph_persistence.py`	BDD	5	W4
`test_c_extension.py`	Plain pytest	6	W5

Total: 16 test files, 126 tests

SPEC-110 Codemod Engine — Execution Plan (Revised)

Plan text

SPEC-110 Codemod Engine — Execution Plan (Revised)

Overview

Test Strategy

Test Scope

Test Execution Time Estimates

Phase 1: Foundation (W0 — Scaffold)

Tasks

Tests

Deliverables

Success Criteria

Commit

Phase 2: Core Infrastructure (W1 — Forest + Sentinel, Parallel)

MANDATORY: Agent Context Document

FOREST Agent (Qwen Max, ~20 min)

Tasks

Tests

Deliverables

SENTINEL Agent (Sonnet, ~20 min)

Tasks

Tests

Deliverables

Integration (5 min)

Success Criteria

Commit

Phase 3: Passes and Reviews (W2 — Architect + Reviewer, Parallel)

MANDATORY: Agent Context Document

ARCHITECT Agent (Qwen Max, ~20 min)

Tasks

Tests

Deliverables

REVIEWER Agent (Sonnet, ~20 min)

Tasks

Tests

Deliverables

Integration (5 min)

Success Criteria

Commit

Phase 4: Integration (W3 — Integrator)

MANDATORY: Agent Context Document

Tasks

Tests

Deliverables

Success Criteria

Commit

Phase 5: Persistence (W4 — Persistence)

MANDATORY: Agent Context Document

Tasks

Tests

Deliverables

Success Criteria

Commit

Phase 6: C Extension (W5 — C Extension)

MANDATORY: Agent Context Document

Tasks

Tests

Deliverables

Success Criteria

Commit

Phase 7: Quality (W6 — Quality)

MANDATORY: Agent Context Document

Tasks

Success Criteria

Commit

Execution Timeline

Parallel Execution Strategy

Phase 2 (W1): Forest + Sentinel

Phase 3 (W2): Architect + Reviewer

Risk Mitigation

Success Criteria (Overall)

Next Steps

Appendix: Test File Inventory

Related