Home / Projects / Orchestrata Ultimate / Decisions / ADR index / ADR-0068

ADR-0068: SPEC-110 in-memory review checks run on the ctok lossless layer and CPython ast, not LibCST

← ADR-0067 · ADR-0069 →

The record

Status: Accepted (ruling, Mohamed, 2026-10-06: "go with recommendatio . build s3'") · Date: 2026-10-06

Context

SPEC-110 (specs/110-codemod-engine/spec.md) FR-012 defines the in-memory review engine: 40 checks in 7 categories (REQ-110-033), three execution phases over the MUTATED forest (REQ-110-035), and a substrate clause, REQ-110-034, which reads verbatim:

REQ-110-034: All 40 checks SHALL operate on LibCST trees (no ast.parse, no subprocess.run, no external linters). Checks SHALL be implemented as CSTTransformer or CSTVisitor subclasses.

Measured in wt-SPEC-110 on 2026-10-06 (recorded in plans/spec-110-completion-plan.md §0):

• LibCST is gone from the tree: 0 hits in pyproject.toml, 0 hits in uv.lock, 0 imports under src/ and scripts/. The parser was replaced by the ctok lossless layer (refactor/ctok/: CTokenizer, TokenStream, LosslessModule, NodeIndex, EditBuffer) under REQ-110-120..127; the LibCST requirement REQ-110-107 is recorded as superseded in specs/110-codemod-engine/checklists/requirements.md.
• Every transform pass already built (refactor/codemod/passes.py: ReplaceStringLiteralPass, AddImportPass, RemoveUnusedImportPass, DocstringSweepPass, RenameSymbolPass) and every existing review pass (refactor/codemod/review.py: ParseIntegrity, BannedConstructs, DiffBudget, PrologSemanticReview) operates on CPython ast nodes (_OsEnvironVisitor(ast.NodeVisitor), _BannedImportVisitor(ast.NodeVisitor)) over the ctok forest. No CSTVisitor exists anywhere.
• 22 reusable check_* functions exist in verification/review/ (checks_structure.py, checks_quality.py, checks_safety.py, checks_correctness.py); they take CPython ast trees and source text.
• Nothing in FR-012 is built: no InMemoryReviewEngine, no 40-check catalogue, no phase runner. REQ-110-033/034/035 are the three NOT IMPLEMENTED FR-012 rows in the checklist.

REQ-110-034 is therefore unmeetable as worded: it mandates a library the project removed by a later, accepted requirement set. Building FR-012 on either reading without a ruling would be a self-issued spec amendment. Several of the 40 checks are lexical, not structural (line length, trailing whitespace, tab indentation, final newline, TODO/FIXME comments, 14 regex mock patterns, hardcoded-secret patterns): no AST visitor of any library can see them; they need the token array or raw text.

Decision (proposed)

Amend REQ-110-034 to read:

REQ-110-034: All 40 checks SHALL operate on the engine's in-memory lossless layer: the ctok token array (LosslessModule / TokenStream) and the CPython ast overlay the forest already holds (NodeIndex). No check SHALL re-parse source from disk, call subprocess.run, or invoke an external linter. Structural checks SHALL be implemented as ast.NodeVisitor subclasses over the MUTATED forest's ast overlay; lexical checks (line length, whitespace, tabs, final newline, comment and pattern scans) SHALL be implemented as scanners over the MUTATED forest's token array. A check SHALL reuse the matching verification/review/ check_* function where one exists rather than re-implement it.

REQ-110-033 and REQ-110-035 are unchanged. The spec file is edited only after this ADR is Accepted; until then FR-012 stays unbuilt (packet S3 of plans/spec-110-completion-plan.md is blocked on this ruling).

Alternatives rejected

• Re-add LibCST as a dependency and build FR-012 on CSTVisitor. Reintroduces the parser the ctok migration (REQ-110-120..127) removed, doubles parse cost and memory for every loaded module, and leaves two trees (ctok + LibCST) that must agree after every mutation. Nothing else in the engine would consume the LibCST tree.
• Drop FR-012. The 40-check review is the gate that stands between an in-memory mutation and the transactional write-back (REQ-110-013, ERR-110-002 aborts commit on an error-severity finding). Removing it removes the engine's safety property.
• Shell out to ruff/flake8/pyright for the checks. Forbidden by the clause the amendment keeps ("no subprocess.run, no external linters"): the review must see the MUTATED in-memory forest, which no external tool can read.
• Keep the LibCST wording and mark FR-012 "superseded" without a replacement. Leaves 3 requirements permanently unmeetable and the checklist permanently at 7 NOT IMPLEMENTED; hides a real gap.

Consequences

• FR-012 becomes buildable on the substrate every other SPEC-110 component already uses; no new dependency enters pyproject.toml.
• The 22 existing verification/review/check_* functions become the implementation of roughly half the catalogue; the rest (god-object sizes, import ordering, test-isolation scans) are new ast.NodeVisitor or token-scanner classes in refactor/codemod/.
• Lexical checks are explicitly allowed to read the token array; the "visitor-only" phrasing of the original clause is retired because it could never cover line length or trailing whitespace.
• RUL-013 (scripts/check_spec_authority.py) continues to govern: tests for FR-012 cite REQ-110-033/034/035 as the spec defines them after the edit. scripts/check_adr_graph_sync.py must report this id OK in sync.
• On Accepted: edit REQ-110-034 in specs/110-codemod-engine/spec.md, flip the three FR-012 checklist rows as S3 lands, record the ruling date and words in this file's Provenance.

Provenance

• Directive: Mohamed, 2026-10-06: "build spec 110".
• Measurement: plans/spec-110-completion-plan.md §0 (LibCST absence, 22 check_* functions, FR-012 unbuilt), 2026-10-06, worktree wt-SPEC-110 on feat/spec-110-completion (base origin/master 83c604886).
• Prior decisions: REQ-110-107 superseded by REQ-110-120..127 (ctok migration); contract plans/contracts/ctok-parser.*.
• Proposed 2026-10-06 with the recommendation above (orchestrator's).
• Ruled Accepted, Mohamed, 2026-10-06, verbatim: "go with recommendatio . build s3'" — option 1 (amend REQ-110-034). REQ-110-034 in specs/110-codemod-engine/spec.md edited to the Decision text in the same commit; packet S3 of plans/spec-110-completion-plan.md unblocked.

Related ADRs

No other ADR is named in this record.

Rulings cited

• RUL-013: RUL-013 — Specs are authoritative — resolve decisions from them, not guesses

Specs cited

• SPEC-110