Orchestrata Ultimate › Plans › briefs › spec-110-s3-builder
SPEC-110 packet S3 — builder brief (REQ-110-033 / REQ-110-034 / REQ-110-035)
Source: plans/briefs/spec-110-s3-builder.md at 8a2cb42ad · last changed 2026-10-06 · first committed 2026-10-06 · 89 lines.
Prose pending.
Plan text
SPEC-110 packet S3 — builder brief (REQ-110-033 / REQ-110-034 / REQ-110-035)
Authority: ADR-0068 (Accepted 2026-10-06) amending REQ-110-034; contract
plans/contracts/spec-110-codemod-engine.contract.json (9f7ee385d) sections classes (FR-012:
ReviewCheck, CheckCategory, CheckDescriptor, CheckRegistry, ReviewContext, ReviewPhaseRunner,
InMemoryReviewEngine, IssueAdapter, ReusedCheck and the named check classes), check_catalogue
(40 ids, per-category 4/6/4/6/10/6/4, 8 shared-impl groups → 30 distinct implementations, phase 1 = 30
ids incl. Safety, phase 2 = 10), s2_s3_wiring (S3 item), design_decisions D23, test_plan
TST-110-021..026 and DOD-S3-1..5. Plan: plans/spec-110-completion-plan.md §1 D5, D6, D7; §2 row S3.
Spec: specs/110-codemod-engine/spec.md REQ-110-033 (the 40-check list), REQ-110-034 (as amended),
REQ-110-035, ERR-110-002.
Base state: S1 and S2 shipped; the branch feat/spec-110-completion in wt-SPEC-110 equals master at
dispatch. commit() already runs the existing reviews loop before any write-back and writes through
txn.commit_changes; the S3 wiring sits in front of that loop.
DESIGN_WAIVER: ADR-0068 (Accepted) for REQ-110-034; RUL-022 contract
plans/contracts/spec-110-codemod-engine.contract.json (9f7ee385d) for every S3 class, the 40-check
catalogue and the commit wiring (D23); plan decisions D5/D6/D7. Scope beyond them is a STOP, not a guess.
GOAL: Build the in-memory review engine in three new modules
src/orchestrata_ultimate/refactor/codemod/review_catalogue.py (CheckCategory, CheckDescriptor,
ReviewCheck protocol, CheckRegistry with default() building the 40 descriptors and their 30
implementations), review_checks.py (IssueAdapter, ReusedCheck wrapping the 20 mapped
verification/review/check_* functions per the contract reuse table, and the named new check classes),
and review_engine.py (ReviewContext, ReviewPhaseRunner, InMemoryReviewEngine with
baseline='absolute'|'delta' defaulting to 'absolute' per D6, without_phase3(), phase 1 parallel
per file, phase 2 after phase 1 with populated ReviewContext.cig, phase 3 = the existing
PrologSemanticReview). Every check reads only LosslessModule.tree (ast overlay) or
LosslessModule.stream (ctok tokens) of the MUTATED forest — no disk re-read, no subprocess, no external
linter. Wire CodemodWorkspace.commit() per D23/D7: new parameters review_engine: InMemoryReviewEngine | None = None and run_review_engine: bool = True after the existing ones; with reviews=None and
run_review_engine=True commit builds the default engine and runs it before the existing reviews loop and
before any write-back; its findings join all_findings; an error finding yields
CommitReport(success=False, files_written=()) (ERR-110-002); the engine counts as one review in
REVIEW_STARTED.review_count; when the caller's reviews already contains a PrologSemanticReview, use
engine.without_phase3(). BannedConstructs stays unchanged.
FILES: new src/orchestrata_ultimate/refactor/codemod/review_catalogue.py, review_checks.py,
review_engine.py; edit src/orchestrata_ultimate/refactor/codemod/workspace.py (commit wiring only),
src/orchestrata_ultimate/refactor/codemod/__init__.py (exports); new
tests/refactor/codemod/test_review_catalogue.py, test_review_checks.py, test_review_engine.py,
test_review_engine_commit_wiring.py; edit specs/110-codemod-engine/checklists/requirements.md
(REQ-110-033/034/035 rows + totals), docs page (docs/codemod-observability.md gains a review section,
or a new docs/codemod-review-engine.md; say which), plans/spec-110-completion-plan.md (§3 ship-log
S3 row; D7 measurement of which existing commit tests gained findings), contract design_decisions
status entries for the S3 classes ('designed' → 'built' + sha), reports/rtm-evidence.{md,json}
(regenerated). Do not touch analysis/ (S2 owns it), review.py's existing passes, or
core/patterns/observer.py.
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. TST-110-021..026 are required
behaviours, one test function per TST id named in its docstring; TST-110-022 means 40 violating + 40
clean real LosslessModule fixtures (parsed, not mocked). When wiring the engine into commit() makes an
EXISTING commit test fail with a real finding, fix the fixture CODE the test commits, never weaken the
test or the check (RUL-002); list every such test in the plan D7 note. @traces on every new class,
method and test citing ONLY REQ-110-033 / REQ-110-034 / REQ-110-035 (RUL-013; DOD-S3-1). Commit as
git -c user.name=Mohamed -c user.email=msamy@sufigeeks.org commit, no AI attribution, no "should".
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.
Cap pytest at timeout 300, targeted modules, 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. A fork the
contract and D5/D6/D7 do not settle → STOP and report; do not guess. Flipping the baseline default is a
spec amendment and is NOT yours to make (D6).
DONE WHEN: (1) CheckRegistry.default().descriptors() has 40 entries with the contract's per-category
counts, unique ids, phases 1 (30) and 2 (10); (2) TST-110-021..026 pass; (3) the substrate proof
(TST-110-023) shows no check opens a file, spawns a subprocess or imports an external linter; (4)
commit() with default arguments runs the engine before write-back and a dry_run commit reports its
findings; the mutated-forest proof (TST-110-025) shows a finding from the in-memory tree while disk is
clean and the error finding aborts with disk untouched; (5) the existing codemod suite
(tests/refactor/codemod/, tests/scripts/test_codemod_cli.py) is green after the wiring, with every
fixture-code fix listed; (6) Definition of Done (ADR-0069): @traces spec-ids-only, RTM regenerated
(uv run python scripts/generate_rtm_evidence.py; orchestrator runs the verified regen pre-ship) and
scripts/trace_intel.py untraced-reqs no longer lists REQ-110-033/034/035, checklist rows flipped +
totals corrected + docs + plan ship-log row + contract status entries in the same commit series, ≥90%
line coverage per new/changed file measured with the DOD-S3-5 command and written into the ship-log row;
(7) uv run python scripts/gate.py run, .venv/bin/python scripts/serialize_codebase_ast.py check-deps --include-tests, uv run python scripts/check_spec_authority.py all exit 0; ruff and black clean on
touched files; (8) commits made, tree clean except hook litter, report with shas, gate exit codes,
coverage table, D7 measurement list, and deviations with reasons. Wiki update (DOD-S3-4) is the
orchestrator's after GO; do not touch the wiki repo.
VERIFY: pytest output for the four new test modules plus tests/refactor/codemod/ (counts, zero
skips); the 40-row descriptor table printed from CheckRegistry.default(); the coverage table; the
three gate exit codes; git log --oneline origin/master..HEAD and git status --short.