# Phase 22 — full import-idiom flip + 13-site sanctioned-fallback scrub

**Captured:** 2026-05-07 (BUILD_SPEC console-v2-overhaul Phase 22 deferred)
**Driver:** scope-boundary deferral (Law 14)

## Decision
DEFERRED to a dedicated future build. Tag `cp-d-cleanup` is NOT placed.

## Why deferred (not rejected)

Phase 22 is the largest single-phase scope in the entire BUILD_SPEC:
- ~90 files have `from core.X` or `from pipeline.X` imports that need rewriting to `from recoil.core.X` / `from recoil.pipeline.X`.
- The `PROJECTS_ROOT` module-level constant in `recoil/core/paths.py` is removed (and the `_emit_projects_root_deprecation` helper Phase 1 added becomes dead code).
- 13 enumerated sanctioned-fallback scrub sites in `api/adapters/beats.py`, `api/system_status.py`, `workspace/sidecar.py`, `workspace/verdict.py`, `core/ref_resolver.py`, `execution/providers/registry.py`, `execution/providers/gemini_vision.py` — each replaces a silent fallback with either a typed exception, a sanctioned-registry entry, or `Optional[T]` return type with UI handling None.
- CI grep guard suite must stay green throughout the sweep.
- Full pytest -x must pass after each batch.

Doing this at the tail end of a long context-burdened harness build is high-risk: the rename is mechanical but fan-out across ~90 files compounds with the 4 deferred items already accumulated this build. Bundling them all into a fresh dedicated build with full context budget is the safer path.

## Resolution path

1. Verify CP-A through CP-C tags + commits are clean and pushed.
2. New harness build sourcing from `BUILD_SPEC.md` Phase 22 sections (lines 2387-2487).
3. Sub-phases (atomic batches):
   a. `from core.X` → `from recoil.core.X` sweep (use sed on grep-listed file set; full pytest after).
   b. `from pipeline.X` → `from recoil.pipeline.X` (excluding `from pipeline._lib.X` from Phase 21 if that landed).
   c. Delete `PROJECTS_ROOT` constant + `_emit_projects_root_deprecation` from `recoil/core/paths.py`. Verify no callers remain (grep).
   d. 13-site sanctioned-fallback scrub (one site per commit; spec § Phase 22 enumerates them).
   e. Run CI grep guards + full pytest suite + place `cp-d-cleanup` tag.

## Deferrals from this CP that Phase 22 picks up

The following items accumulated during this build and are bundled here:

1. `@lru_cache(maxsize=64)` on `recoil.core.project.get_project` (Phase 2 deferred — needs co-update of two tests that assert non-cached behavior).
2. `Project._config_path` and `_migrate_legacy` use the legacy `PROJECTS_ROOT` constant rather than `projects_root()` callable (Phase 2 deferred — needs test fixture rewrite from `monkeypatch.setattr(paths, "PROJECTS_ROOT", ...)` to `monkeypatch.setenv("RECOIL_PROJECTS_ROOT", ...)`).
3. Sibling `_recoil_root()` shims in `api/adapters/memory.py` + `api/adapters/events.py` still emit `recoil_paths_import_fallback_literal` (Phase 4 explicit out-of-scope; fold into the swap sweep).
4. `ci_grep_guards.sh` silent-pass when rg is missing as a binary (Phase 7 documented hazard; add `command -v rg` precondition to fail loud).
5. Guard 2 narrow regex doesn't catch fully-split-path forms — known violations in `pipeline/tools/{prompt_ab_test,seedance_zh_ab_test,reclaim_orphans}.py` (Phase 7 documented; Phase 22 widens regex AND fixes the 3 hits).
6. atomic_write 5-site migration: only `beats.py` migrated in Phase 20. The remaining 4 sites (`workspace/verdict.py`, `workspace/sidecar.py`, `core/sidecar_writer.py`, `api/workspace_state_report.py`) are Phase 22 sweep candidates.
7. `workspace/verdict.py:_projects_root` test-shim still exists (Phase 5 preserved as test compatibility; Phase 22 retires after test-fixture co-update).
8. `pipeline/core/persistence.py:_projects_root` test-shim still exists (Phase 3 preserved; same co-update).
9. ~~afterimage + afterimage-anime project configs need aspect_ratio backfill (Phase 12 dry-run gate FAIL — JT must decide aspect value).~~ **RESOLVED** — both configs already have `"aspect_ratio": "9_16"` (confirmed 2026-05-08). Not a blocker for Phase 22.

## Cited by
- BUILD_SPEC §Phase 22
- Build log entry for Phase 22 (DEFERRED)
- `cp_a_audit_verdict.md` (Option B hand-review GO with deferrals)
- `cp_b_dry_run_failures.md` (afterimage backfill needed)
- `phase-21-pipeline-lib-rename.md` (companion deferral)

## Status
- [x] Substantive deferral with bundled deferrals catalog (Law 14)