docs(codex-prep): Pan Herbatka's epic recovery plan for RS2000 cutover (sign-off needed) #250

Merged

pdurlej merged 1 commit from claude/orders/recovery-plan-cutover-2026-05-12-evening into main

2026-05-12 22:17:35 +02:00

claude commented

2026-05-12 22:12:31 +02:00

Collaborator

Tier per ADR-0007: Lite — single new doc file, 477 LoC additive, no sacred paths, no schema/runtime, no code changes. Operator-merge.

Why now

Operator's mandate 2026-05-12 evening (after Codex's morning session stopped at cutover blocker):

"Codex pokazał, że tutaj klęknął, delegowanie teraz wszystkiego na niego jest dalej robieniem tego samego. Pan Herbatka dolewa coś mocniejszego do filiżanki."

This PR ships the mocniejsze. Pan Herbatka audited Codex's morning failure, web-researched the multi-compose + dotenv-quoting bug classes, and synthesized 5 architectural calls so the next session executes, not explores.

What ships

Single file: state/codex-prep/RECOVERY-PLAN-CUTOVER-2026-05-12-evening.md (477 lines)

Contents:

§ 1 Why the morning failed (1-paragraph diagnosis)
§ 2 Three root causes with repo-grep evidence
§ 3 Pan Herbatka's 5 architectural calls (operator sign-off needed)
§ 4 Six-phase execution plan
§ 5 First 3 commands to run
§ 6 Risk matrix
§ 7 Operator decision points (checklist)
§ 8 What next Codex session must read (in order, ~15 min)
§ 9 References (web research + repo evidence)

The 5 calls (need operator sign-off in § 7)

Use docker compose include: directive (not multi--f, not COMPOSE_FILE env)
Read legacy /opt/vps-home-platform-infra/env/ files via --env-file (not reconstruct from docker inspect)
Runner-local direct PAT tonight; Universal Auth Infisical migration as separate post-cutover epic
First smoke = dashboard (stateless, low blast, already running)
Cutover is transparent — legacy stack remains live 7+ days for rollback symmetry

Plus: Pan Herbatka recommends execution tomorrow morning, not tonight. 12-hour overnight session is the wrong context for cutover.

What this PR does NOT do

Does NOT execute any cutover action
Does NOT touch RS2000
Does NOT modify compose/*, apply.py, or any production-touching path
Does NOT auto-trigger next Codex session (operator dispatches when ready)
Does NOT close any cutover-gate issue (#238 stays open until Phase 4 smoke proves green)

Test plan

Operator reads § 3 (5 calls) — sign-off or override each
Operator decides § 7 'when to execute' (Pan Herbatka rec: tomorrow morning)
Operator merge → plan lives in repo for next Codex session
Codex's next session reads § 8 list → executes Phase 1+2+3 per plan
Operator approves Phase 4 smoke trigger explicitly

Spec sources read

state/codex-prep/rs2000-closeout-handover-2026-05-12.md (Codex's morning handover; cited extensively)
compose/apps/compose.yaml, compose/base/compose.yaml, compose/core/compose.yaml, compose/edge/compose.yaml (full structural read)
control-plane/platformctl/apply.py (lines 316-665; especially compose_apply_command + apply_plan)
docs/ci/runner-contract.md (deploy runner contract)
scripts/forgejo/deploy-runner-install-infisical-token-auth (to understand Codex's Infisical attempt)
compose/README.md + state/reports/rs2000-compose-inventory-2026-05-12/README.md
All 64 module.yaml runtime mappings (grep verified)
Web research (4 targeted searches): docker compose include directive, multi-file production, dotenv escape bugs, undefined network errors — see § 9 References

Operator's North Star check

Reduces attention cost:

Codex's next session has 5 decisions pre-made — execution path obvious
Operator's role narrowed to sign-off + Phase 4 trigger approval + final review
Rollback path is symmetric (legacy stack remains live → reverting one service is one SSH command)
Pan Herbatka explicit rec: tomorrow morning, not tonight — protects family-time North Star

Verdict: ship.

🍵 — Pan Herbatka, ostatnia linia doradztwa przed ⚛️, 2026-05-12 evening

Tier per ADR-0007: **Lite** — single new doc file, 477 LoC additive, no sacred paths, no schema/runtime, no code changes. Operator-merge. ## Why now Operator's mandate 2026-05-12 evening (after Codex's morning session stopped at cutover blocker): > *"Codex pokazał, że tutaj klęknął, delegowanie teraz wszystkiego na niego jest dalej robieniem tego samego. Pan Herbatka dolewa coś mocniejszego do filiżanki."* This PR ships the mocniejsze. Pan Herbatka audited Codex's morning failure, web-researched the multi-compose + dotenv-quoting bug classes, and synthesized 5 architectural calls so the next session executes, not explores. ## What ships Single file: `state/codex-prep/RECOVERY-PLAN-CUTOVER-2026-05-12-evening.md` (477 lines) Contents: - § 1 Why the morning failed (1-paragraph diagnosis) - § 2 Three root causes with repo-grep evidence - § 3 **Pan Herbatka's 5 architectural calls** (operator sign-off needed) - § 4 Six-phase execution plan - § 5 First 3 commands to run - § 6 Risk matrix - § 7 Operator decision points (checklist) - § 8 What next Codex session must read (in order, ~15 min) - § 9 References (web research + repo evidence) ## The 5 calls (need operator sign-off in § 7) 1. Use docker compose **`include:` directive** (not multi-`-f`, not COMPOSE_FILE env) 2. Read legacy `/opt/vps-home-platform-infra/env/` files via `--env-file` (not reconstruct from `docker inspect`) 3. Runner-local **direct PAT tonight**; Universal Auth Infisical migration as separate post-cutover epic 4. First smoke = **`dashboard`** (stateless, low blast, already running) 5. Cutover is **transparent** — legacy stack remains live 7+ days for rollback symmetry Plus: Pan Herbatka recommends **execution tomorrow morning**, not tonight. 12-hour overnight session is the wrong context for cutover. ## What this PR does NOT do - Does NOT execute any cutover action - Does NOT touch RS2000 - Does NOT modify `compose/*`, `apply.py`, or any production-touching path - Does NOT auto-trigger next Codex session (operator dispatches when ready) - Does NOT close any cutover-gate issue (#238 stays open until Phase 4 smoke proves green) ## Test plan - [ ] Operator reads § 3 (5 calls) — sign-off or override each - [ ] Operator decides § 7 'when to execute' (Pan Herbatka rec: tomorrow morning) - [ ] Operator merge → plan lives in repo for next Codex session - [ ] Codex's next session reads § 8 list → executes Phase 1+2+3 per plan - [ ] Operator approves Phase 4 smoke trigger explicitly ## Spec sources read - `state/codex-prep/rs2000-closeout-handover-2026-05-12.md` (Codex's morning handover; cited extensively) - `compose/apps/compose.yaml`, `compose/base/compose.yaml`, `compose/core/compose.yaml`, `compose/edge/compose.yaml` (full structural read) - `control-plane/platformctl/apply.py` (lines 316-665; especially `compose_apply_command` + `apply_plan`) - `docs/ci/runner-contract.md` (deploy runner contract) - `scripts/forgejo/deploy-runner-install-infisical-token-auth` (to understand Codex's Infisical attempt) - `compose/README.md` + `state/reports/rs2000-compose-inventory-2026-05-12/README.md` - All 64 module.yaml runtime mappings (grep verified) - Web research (4 targeted searches): docker compose include directive, multi-file production, dotenv escape bugs, undefined network errors — see § 9 References ## Operator's North Star check Reduces attention cost: - Codex's next session has 5 decisions pre-made — execution path obvious - Operator's role narrowed to sign-off + Phase 4 trigger approval + final review - Rollback path is **symmetric** (legacy stack remains live → reverting one service is one SSH command) - Pan Herbatka explicit rec: **tomorrow morning, not tonight** — protects family-time North Star Verdict: ship. 🍵 — *Pan Herbatka, ostatnia linia doradztwa przed ⚛️, 2026-05-12 evening*

claude added 1 commit

2026-05-12 22:12:31 +02:00