Orchestrata Ultimate › Plans › briefs › spec-110-s2-builder
SPEC-110 packet S2 — builder brief (REQ-110-031 / REQ-110-032)
Source: plans/briefs/spec-110-s2-builder.md at 8a2cb42ad · last changed 2026-10-06 · first committed 2026-10-06 · 81 lines.
Prose pending.
Plan text
SPEC-110 packet S2 — builder brief (REQ-110-031 / REQ-110-032)
Contract: plans/contracts/spec-110-codemod-engine.contract.json (committed 9f7ee385d) — sections
classes (FR-011: BlastRadiusAnalyzer, BreakingChangeDetector, ComplexityAnalyzer, TestCoverageMapper,
AbstractionAnalyzer, CouplingAnalyzer, DeadCodeDetector, AnalysisResultEncoder, AnalysisPass protocol),
analysis_cig_mapping, analysis_gaps (GAP-1..6), s2_s3_wiring (S2 items), design_decisions D24,
test_plan TST-110-015..020 and DOD-S2-1..5. Plan: plans/spec-110-completion-plan.md §1 D2, D8, D9; §2 row S2.
Base state: S1 shipped 2026-10-06 (master fba554e98 + the ship-log record commit); the branch
feat/spec-110-completion in wt-SPEC-110 equals master at dispatch. _Operation, commit_changes
(_replace_file), default_observers() and scripts/codemod.py run --observe are the shipped shapes;
build on them, do not reshape them.
DESIGN_WAIVER: RUL-022 contract plans/contracts/spec-110-codemod-engine.contract.json (9f7ee385d) is the
settled design for every S2 class and signature; plan decisions D2/D8/D9 settle the CIG-adapter rule and
the backlog rule. Scope beyond the contract is a STOP, not a guess.
GOAL: Build the seven read-only analysis passes as one submodule each under
src/orchestrata_ultimate/refactor/codemod/analysis/ (blast_radius.py, breaking_change.py,
complexity.py, metrics.py, test_coverage.py, abstraction.py, coupling.py, dead_code.py,
encode.py, protocol.py, __init__.py) exactly as the contract's class table names them, with the
constructor and analyze() signatures the contract gives; add the four frozen dataclasses
FunctionComplexity, ComplexityReport, TestCoverageMap, DeadCodeReport to
refactor/codemod/_types.py; extend scripts/codemod.py analyze per D24 (append --query choices
breaking_changes, complexity, test_coverage, dead_code, all-passes, add --json,
breaking_changes takes --module <path> --base <git ref>; route blast_radius, coupling_score,
abstraction_level through the analyzers with unchanged text output). Each analyzer is a thin adapter over
the existing CodeIntelligenceGraph method in analysis_cig_mapping (D2); where the mapping names a gap,
compute from the forest's ast overlay when the contract says the analyzer can (GAP-3 name heuristic,
GAP-6 complexity metrics) and otherwise return the documented reduced result (GAP-1/2 module granularity,
GAP-4 edge scope documented, GAP-5 no signature diff) — do NOT add CodeIntelligenceGraph methods; record
each owed graph method in the plan's S5 findings paragraph as backlog (D9).
FILES: new src/orchestrata_ultimate/refactor/codemod/analysis/*.py; edit
src/orchestrata_ultimate/refactor/codemod/_types.py, scripts/codemod.py; new
tests/refactor/codemod/analysis/test_*.py (one per analyzer plus test_encode.py and
test_read_only.py), extend tests/scripts/test_codemod_cli.py; edit
specs/110-codemod-engine/checklists/requirements.md (REQ-110-031/032 rows and the totals line),
docs/codemod-observability.md or a new docs/codemod-analysis.md (pick one, say which),
plans/spec-110-completion-plan.md (§3 ship-log S2 row; D9 backlog list), the contract's
design_decisions status entries for the S2 classes ('designed' → 'built' + sha), and
reports/rtm-evidence.{md,json} (regenerated). Do not touch workspace.py, review.py,
review_*.py, or anything S3 owns.
CONSTRAINTS: Worktree /home/mohamed/workspace/orchestrata-ultimate-worktrees/wt-SPEC-110, branch
feat/spec-110-completion; never cd into the main checkout. Read Python only through the AST toolkit
(.venv/bin/python scripts/serialize_codebase_ast.py source|symbols|refs <qname> --no-daemon; qualified
names omit orchestrata_ultimate.). No mocking/fakes/monkeypatch, no skip/xfail, no pytest-xdist,
function-scope fixtures, absolute imports, os.environ.get, uv only, every new dependency declared
(none expected). Tests use real CodemodWorkspace.load() over a tmp fixture repo — TST-110-015..020 are
the required behaviours, one test function per TST id named in its docstring. @traces on every new
class, method and test citing ONLY REQ-110-031 / REQ-110-032 (RUL-013; DOD-S2-1). Commit as
git -c user.name=Mohamed -c user.email=msamy@sufigeeks.org commit, no AI attribution, no "should" in
any text. Before each commit run git checkout -- docs/CODEBASE_MAP.md docs/CODEBASE_MAP_FULL.md plans/ast-ultimate.json plans/ast-deep-comparison.json plans/ast-tests.json reports/.ship-verified
(hook litter). Cap interactive pytest at timeout 300, targeted modules only, invoked as
OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1 MKL_NUM_THREADS=1 PYTHONPATH=scripts timeout 300 .venv/bin/python -m pytest <module> -p orchestrata_pytest_observer -p orchestrata_ultimate.core.threading.pytest_live_observer. If a genuine design fork appears that the
contract and D2/D8/D9 do not settle, STOP and report it; do not guess.
DONE WHEN: (1) all seven analyzers + encoder + protocol exist with the contract signatures and
AnalysisResultEncoder.encode round-trips every result through json.dumps; (2) TST-110-015..020 pass;
(3) scripts/codemod.py analyze --query <each new choice> --json exits 0 with parseable JSON on the
fixture repo; (4) read-only proof (TST-110-019): CIG node/edge counts and every forest module's bytes
identical before/after all seven; (5) Definition of Done (ADR-0069): @traces on every added symbol/test
(spec ids only), RTM regenerated with uv run python scripts/generate_rtm_evidence.py (no --verify
needed from the builder; the orchestrator runs the verified regen pre-ship) and scripts/trace_intel.py untraced-reqs before/after no longer lists REQ-110-031/032, checklist rows flipped + totals corrected +
docs page + plan ship-log row + contract status entries in the same commit series, ≥90% line coverage
per new/changed source file measured with the DOD-S2-5 command and the numbers written into the ship-log
row; (6) uv run python scripts/gate.py run exit 0, .venv/bin/python scripts/serialize_codebase_ast.py check-deps --include-tests exit 0, uv run python scripts/check_spec_authority.py exit 0, uv run ruff check and uv run black --check clean on touched files; (7) all commits made, tree clean except hook
litter, and a report listing each commit sha, each gate's exit code, the per-file coverage numbers, the
D9 backlog items you recorded, and any deviation from the contract with its reason. The knowledge-wiki
update (DOD-S2-4) is done by the orchestrator after review GO; say so in the report, do not touch the
wiki repo.
VERIFY: pytest output for tests/refactor/codemod/analysis/ and tests/scripts/test_codemod_cli.py
(counts, zero skips); the --json output of one all-passes run; the coverage table; the three gate
exit codes; git log --oneline origin/master..HEAD and git status --short.