---
id: PX-PHASE-RWV8BKS1
type: phase
title: Architecture Migration
label: arch-mig
---

## Sub-mission

Reduce architecture-driven workflow friction while keeping daily Pi use reliable.
Make package boundaries, verification, and compatibility explicit rather than dependent on workspace accidents.
This serves the [mission](../../MISSION.md): Pi fits the way I work.

## Ranked priorities

1. Coherent architectural contracts and self-contained runtime boundaries.
2. Preserved observable behavior and a working installation throughout migration.
3. Trustworthy public-API tests and complete maintained TypeScript checking.
4. Fast focused iteration and less accidental complexity.

## Decision defaults

| Concern | Default |
| --- | --- |
| Authority | Preserve [core law](../../SYSTEM.md): root installation unit, one version, isolated siblings; reconcile conflicting [architecture spec](../../specs/PX-SPEC-DZLVGRW4-pi-extension-architecture/index.md) claims through approved document changes. |
| Migration | Bounded replacements with behavior parity; preserve the last complete usable build. |
| Compatibility | Preserve declared support until evidence justifies an explicitly approved change. |
| Quality | Test observable contracts through public Pi APIs; dependency patching and private-API fixtures are migration debt, not precedent. |
| Speed | Prefer the smallest decisive check during iteration; complete verification at integration boundaries. |
| Experimentation and debt | Isolate experiments; remove superseded paths rather than accumulating permanent dual implementations. |

## Non-goals

Feature expansion, unrelated rewrites, speculative abstractions, and test-score targets.
Independent release units or unapproved changes to core law, specifications, or approved plans.

## Observable exit criteria

- [ ] Core and architecture specification agree on installation, package, and release boundaries.
- [ ] Runtime artifacts operate without undeclared workspace or sibling dependencies.
- [ ] Tests prove public contracts without dependency patching; maintained TypeScript is checked.
- [ ] Declared compatibility and verified artifact identity have reproducible evidence.
- [ ] Superseded migration paths are removed; daily Pi workflows remain usable.