ZAIXOS Engineering Platform — Repository Extraction Plan
Document type: Extraction Planning Specification
Version: 1.0 · Phase: 12-4
Status: Permanent execution authority
Architecture authority: technical/TECHNICAL_ARCHITECTURE.md (unchanged)
Purpose
Define the complete extraction strategy for moving embedded ZEP from Dental Clinic Revenue Operating System into standalone repository zaixos-engineering-platform.
This document answers: How do we execute the extraction safely?
Extraction objective
| Attribute | Definition |
|---|---|
| Source | Dental Clinic ROS repo (embedded ERP + platform docs + adapter workspace) |
| Target | zaixos-engineering-platform repository |
| Distribution | Composer package zaixos/engineering-platform @ 1.0.0 |
| First consumer | Dental Clinic ROS (Consumer #1) |
| Semantic baseline | ERP v1.0 / contracts@1 / Cursor Adapter 1.0.0-phase-11-9 |
| GA tag | zaixos-platform@v1.0.0 at Phase 12-9 |
Extraction principles
| ID | Principle |
|---|---|
| EP-01 | No semantic change — byte-equivalent baseline at 1.0.0 unless documented parity exception |
| EP-02 | Documentation first — extraction phases produce Format B reports |
| EP-03 | Validate at every gate — see VALIDATION_PLAN.md |
| EP-04 | Dual-run before cutover — embedded + vendored parity during 12-6–12-8 |
| EP-05 | Rollback always available — see ROLLBACK_PLAN.md |
| EP-06 | No architecture redesign — layout follows REPOSITORY_LAYOUT_PLAN.md |
| EP-07 | Product domain never extracted — app/Modules/, product architecture stay |
| EP-08 | Git operations by Developer only — per existing freeze policy |
Repository split graph
┌─────────────────────────────────────────────────────────────────────────────┐
│ DENTAL CLINIC ROS (today) │
├──────────────────────────────┬──────────────────────────────────────────────┤
│ EXTRACTS TO PLATFORM REPO │ REMAINS IN PRODUCT REPO │
├──────────────────────────────┼──────────────────────────────────────────────┤
│ docs/development/ (ERP/EOS) │ app/Modules/ │
│ .cursor/ (adapter workspace)│ docs/architecture/ │
│ docs/platform/ (authority) │ docs/product/ · docs/compliance/ · etc. │
│ tests/Architecture/ │ tests/Architecture/ModuleBoundaryTest.php │
│ Engineering*Integrity* │ (+ domain architecture tests) │
│ ErpIntegritySupport │ tests/Unit/ Feature/ │
│ EosIntegritySupport (→) │ AGENTS.md (product sections) │
│ │ .zaixos/ (created at 12-7 — consumer config) │
└──────────────────────────────┴──────────────────────────────────────────────┘
│
│ Phase 12-6 extraction
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ zaixos-engineering-platform (target) │
│ core/ · contracts/ · runtime/ · adapters/ · validation/ · docs/ · schemas/ │
│ composer.json → zaixos/engineering-platform │
└─────────────────────────────────────────────────────────────────────────────┘
│
│ Phase 12-7 consumer migration
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ DENTAL CLINIC ROS (consumer) │
│ composer require zaixos/engineering-platform │
│ .zaixos/platform.yml · platform.lock · extensions/ │
│ .cursor/ → materialized from package │
│ docs/development/ → removed (redirect stubs only until 12-9 cleanup) │
└─────────────────────────────────────────────────────────────────────────────┘Extraction strategy (phased)
| Stage | Phase | Outcome |
|---|---|---|
| Plan | 12-4 | This planning suite — complete |
| Scaffold | 12-5 | Empty platform repo matching REPOSITORY_LAYOUT_PLAN.md |
| Extract | 12-6 | Assets copied to platform repo; parity tests green in platform CI |
| Consume | 12-7 | Dental Clinic pins package; dual-run parity vs embedded |
| Validate | 12-8 | Consumer + platform + compatibility validation |
| Freeze | 12-9 | Platform v1.0.0 GA; embedded copies sunset |
Dual-maintenance model (12-6 → 12-8)
During dual-run:
| Copy | Location | Authority |
|---|---|---|
| Embedded (legacy) | docs/development/, .cursor/ in Dental Clinic | Frozen at extraction baseline SHA |
| Platform (canonical) | vendor/zaixos/engineering-platform + .zaixos/ | Content authority D-P |
Rule: Fixes that affect platform semantics apply to platform repo first, then sync to embedded only if rollback window requires — prefer forward migration.
Extraction dependency graph
12-4 Planning (complete)
↓
12-5 Scaffold (repo structure, composer skeleton, CI skeleton — no asset copy yet)
↓
12-6 Extraction Wave 1: governance + contracts + runtime specs (docs/platform/, contracts prose)
↓
12-6 Extraction Wave 2: methodology + templates (docs/development/ methodology subset)
↓
12-6 Extraction Wave 3: adapter (.cursor/ → adapters/cursor-adapter-v1/)
↓
12-6 Extraction Wave 4: validation tests + support classes
↓
12-6 Extraction Wave 5: schemas/config (from technical spec)
↓
12-7 Consumer: composer require + platform.yml + lock + materialize
↓
12-8 Parity validation (embedded vs vendored)
↓
12-9 Remove embedded duplicates + GA tagDetail: EXTRACTION_SEQUENCE.md.
Risk summary
| Risk | Mitigation | Phase |
|---|---|---|
| Semantic drift during copy | Checksum + parity tests | 12-6, 12-8 |
| Broken cross-references | Link rewrite matrix in PACKAGE_SPLIT_PLAN | 12-6 |
| CI regression | Validation gates before merge | All |
| Developer confusion | ERP_DEVELOPER_GUIDE → platform developer-guide redirect | 12-7 |
| Rollback need | LOCK + tag restore procedure | 12-6+ |
Full matrix: MIGRATION_MATRIX.md.
Success criteria (extraction complete at 12-9)
- [ ] Platform repo tagged
zaixos-platform@v1.0.0 - [ ] Dental Clinic on
platform.lock@ 1.0.0 only (no authoritative embedded ERP) - [ ] All Layer 0–5 validation green in product CI
- [ ] KPI-10 governance duplication index → 0
- [ ] Embedded
docs/development/ERP authority docs removed or stub-only - [ ]
.cursor/materialized from package checksum matches lock
Out of scope (this plan does not execute)
- Repository creation (12-5)
- Composer package publish (12-6/12-7)
- Git push/tag (Developer at 12-9)
- Runtime Contract amendments
- New adapter certification beyond cursor-adapter-v1 baseline
Repository Extraction Plan v1.0 — Phase 12-4.