# PHASE_NUMBERING_MAP.md

**Two authoritative documents number the phases differently. This file maps between them.**
Created 2026-08-25 in the **D10** repository.

> ⚠️ **NEITHER SOURCE DOCUMENT HAS BEEN ALTERED.** No phase has been renamed or renumbered in
> `CLAUDE.md` or `PHASE_3_IMPLEMENTATION_PLAN.md`. This is a **reading aid only**. Both documents
> remain authoritative in their own terms, exactly as instructed.

`CLAUDE.md` §43 lists *"two authoritative documents conflict"* as a STOP condition. The conflict is
**reported here, not resolved.** Resolving it — if you ever want it resolved — is your decision.

---

## 1. Why this matters

The numbering overlap is not cosmetic. It **hid three blocking spikes**:

- `CLAUDE.md` **§38 Phase 3.1** = *"D10 foundation"* — composer, DDEV, install, read-only connection.
- `PHASE_3_IMPLEMENTATION_PLAN.md` **§24 phase 3.1** = ***"Spikes (blocking)"*** — a different body
  of work entirely, with the exit gate *"**Stop if ① or ② fails**"*.

`PHASE_3_1_TASKS.md` (tasks 01–12) implements the **CLAUDE.md** sense of 3.1 and contains **no
spikes**. Work proceeded correctly against that task list, so the plan's blocking spikes were never
scheduled by anyone. See `SPIKE_FINDINGS.md`.

---

## 2. Mapping table

| Document | Phase / task no. | Actual work represented | Dependency / gate | State |
|---|---|---|---|---|
| `PHASE_3_IMPLEMENTATION_PLAN.md` §24 | **3.1** | **Spikes (blocking):** ① `acl` ^2.0 write API for 33,003 grants ② `commerce_authnet` on Commerce 3 ③ Quiz platform | Gates plan-3.8, 3.9, 3.10. **"Stop if ① or ② fails"** | ① ✅ **RESOLVED** · ② ⏳ not run · ③ 🛑 approval needed |
| `CLAUDE.md` §38 | **3.1** | **D10 foundation** — composer, DDEV, empty install, read-only D7 connection, module skeletons, reconcile scripts, tests, backups | 6 gates, all met | ✅ **COMPLETE** (tasks 01–11; 12 pending freeze) |
| `PHASE_3_IMPLEMENTATION_PLAN.md` §24 | **3.2** | **Foundation** — composer project, PHP 8.3, second DDEV env, CI, config workflow, read-only D7 connection, `ce_migrate` skeleton. *Exit gate: empty D10 site deploying through CI* | — | ✅ **substantially = the work done as CLAUDE.md 3.1.** ⚠️ **CI is NOT set up** — see §3 |
| `CLAUDE.md` §38 | **3.2** | **D10 module / configuration foundation** | after 3.1 | ⏳ next (`field_ui` D3-8 prepared) |
| `PHASE_3_IMPLEMENTATION_PLAN.md` §24 | **3.3** | **Content model** — 10 content types, 71 fields, 6 vocabularies, 5 roles, ~240 permissions, exported from the D7 database. *Gate: field-by-field diff vs D7* | after plan-3.2 | ⏳ not started |
| `CLAUDE.md` §38 | **3.3** | **Custom module architecture** | after 3.2 | ⏳ skeletons only (9 modules, 0 routes, 0 services) |
| `PHASE_3_IMPLEMENTATION_PLAN.md` §24 | **3.4** | **Contrib install + config** — 54 D10-ready modules, 25 replacements, 4 stalled resolved | after plan-3.3 | ⏳ packages installed via composer, **not enabled** |
| `CLAUDE.md` §38 | **3.4** | **Theme / UI migration** | after 3.3 | ⏳ audit complete (`D10_FRONTEND_MIGRATION.md`), no implementation |
| `PHASE_3_IMPLEMENTATION_PLAN.md` §24 | **3.5** | **Migration stages 1–7** — users, user fields, taxonomy, nodes, files, aliases. *Gate: R-1, R-10 pass* | needs plan-3.3 + 3.4 | 🛑 blocked — freeze |
| `CLAUDE.md` §38 | **3.5** | **Migration implementation** | needs the D7 freeze | 🛑 blocked — freeze |
| `PHASE_3_IMPLEMENTATION_PLAN.md` §24 | **3.6** | **Custom modules** — `ce_core` → `ce_users` → `ce_course` → `ce_wistia` → `ce_referral` → `ce_certificate` → `ce_reports` | needs plan-3.5 uid/nid maps | ⏳ |
| `PHASE_3_IMPLEMENTATION_PLAN.md` §24 | **3.7** | **Rules re-implementation** — code + configuration | needs plan-3.5 | ⏳ 6 test classes / 32 methods written, all `markTestIncomplete()` |
| `PHASE_3_IMPLEMENTATION_PLAN.md` §24 | **3.8** | **Commerce** — build + stages 8–11. *Gate: R-2, R-3, R-4* | **gated by spike ②** | 🛑 |
| `PHASE_3_IMPLEMENTATION_PLAN.md` §24 | **3.9** | **⭐ Entitlement** — stage 12, ACL + flags. *Gate: R-5, R-6, R-13, R-14, R-15* | **gated by spike ①** ✅ now resolved | ⏳ unblocked by ① |
| `PHASE_3_IMPLEMENTATION_PLAN.md` §24 | **3.10** | **Learning subsystems** — stages 13–17: video, quiz, evaluations, certificates. *Gate: R-7, R-8, R-9, R-11* | **gated by spike ③** | 🛑 |
| `PHASE_3_IMPLEMENTATION_PLAN.md` §24 | **3.11** | **Remaining data** — stages 18–20: referral ledger, custom tables, views/reports. *Gate: R-12, R-16* | | ⏳ |
| `PHASE_3_IMPLEMENTATION_PLAN.md` §24 | **3.12** | **Theme** — Twig rebuild, certificate generator extraction. *Gate: visual parity agreed* | ≈ `CLAUDE.md` 3.4 | ⏳ audit only |
| `PHASE_3_IMPLEMENTATION_PLAN.md` §24 | **3.13** | **Golden-master + regression** — full `TEST_PLAN.md` | ≈ `CLAUDE.md` Phase 5 | ⏳ |
| `PHASE_3_IMPLEMENTATION_PLAN.md` §24 | **3.14** | **Rehearsals** — two timed full runs from fresh dumps | ≈ `CLAUDE.md` Phase 7 prep | ⏳ |
| `CLAUDE.md` §38 | **4 / 5 / 6 / 7** | Data migration · functional+regression testing · final reconciliation · production deployment planning | | ⏳ |

---

## 3. Where they genuinely diverge, not just relabel

Most rows are the **same work under different labels**. Three are real differences:

1. **Plan-3.1 "Spikes" has no `CLAUDE.md` equivalent phase.** `CLAUDE.md` §17 mandates the Quiz
   spike inside its Phase 3 narrative, but never as a distinct gated phase. **This is the gap that
   let all three spikes go unscheduled.**

2. **Plan-3.2's exit gate requires CI** — *"empty D10 site deploying through CI"*. **No CI exists**
   (no `.github/`, no pipeline). Under `CLAUDE.md` numbering, Phase 3.1's six gates make no mention
   of CI, and all six are met. **So the same body of work passes one document's gate and fails the
   other's.** Recorded, not resolved — adding CI is unapproved scope.

3. **Theme ordering.** `CLAUDE.md` puts theme at **3.4**, before migration implementation (3.5).
   The plan puts it at **3.12**, after all data migration. The plan's ordering is the safer one
   (content must exist before visual parity can be judged), but the documents disagree and I have
   changed neither.

---

## 4. Working rule applied until you direct otherwise

- **`CLAUDE.md` governs sequencing** — it is the project instruction set, and its §38 is what the
  executed task lists follow.
- **`PHASE_3_IMPLEMENTATION_PLAN.md` governs content and gates** — it holds the detailed exit
  criteria, stage lists and the blocking spikes.
- Where they conflict, **both are reported and neither is edited**.

This rule is a reading convention I am following to keep working. **It is not a decision**, and it
changes nothing in either document.