AutoFilm-ESP32/docs/megaplans/REFACTOR-MEGAPLAN.md

REFACTOR MEGAPLAN — AutoFilm-ESP32 IDF modular UI

Audience: coding agent. One phase = one session. Do not start the next phase in the same session.

Protocol (every session)

1. git checkout refactor/esp-idf-modular-ui && git pull --ff-only
2. Read only: AGENTS.md, this file (status table), the assigned phase file. Open docs/TARGET_ARCHITECTURE.md / docs/CURRENT_STATE.md / docs/CICD.md only if the phase READ: list says so.
3. Execute IN only. Honour OUT and FORBIDDEN.
4. Run VERIFY exactly. Do not push if any verify item fails.
5. Commits: messages listed in the phase. Imperative. No secret tokens.
6. Push origin refactor/esp-idf-modular-ui. PR target is develop, not main.
7. Set phase STATUS: to DONE in the phase file and this table. One-line Notes if you diverged (API name only — do not silently change behaviour).

If blocked: stop, commit nothing broken, write BLOCKED: at top of the phase file with the exact error.

Frozen constraints (never reinterpret)

• Recipe values (times s, CW, CCW, temp min/pref/max) for C41 E6 ECN-2 B&W Custom B&WREV = src/devSequence.cpp / docs/CURRENT_STATE.md. Changing values requires explicit user order + doc update same commit.
• Stop while running: Esc 'X' (keypad r4c4) and later touch STOP. Immediate motor EN HIGH (disabled). Then Resume or ReturnToStepSelect. Short beep Stop and Resume.
• UI never blocks on motor, OneWire, or tone().
• No Arduino types in ui_cmd, app_process, app_machine public headers.
• Watchdog stays on. No vTaskDelete of long-lived workers. No vTaskDelete of motor task.
• Session time edits ±5 s RAM only. No NVS profiles. No Custom editor. No pumps/valves/heaters (command IDs reserved only).
• auto_advance default false (after StepComplete wait for Start). Do not restore silent auto-chain unless a later phase says so.

Branch

refactor/esp-idf-modular-ui → PR → develop. Rebase onto develop if requested; do not retarget main.

Status

ID	File	Session goal	STATUS
P00	refactor/P00-docs-lock.md	Architecture docs already on branch	DONE
P01	refactor/P01-idf-skeleton.md	Dual-board IDF project compiles	BLOCKED
P02	refactor/P02-ui-cmd-process.md	ui_cmd + app_process + golden tests	DONE
P03	refactor/P03-machine-host.md	app_machine + stub HAL + SM tests	DONE
P04	refactor/P04-gitea-ci.md	.gitea/workflows/ci.yml live	DONE
P05	refactor/P05-hal-wroom-motion.md	WROOM motor/temp/audio HAL	BLOCKED
P06	refactor/P06-ui-wroom-cutover.md	2004 UI + keypad + Stop/Resume cutover	TODO
P07	refactor/P07-board-s3-ui.md	JC4827W543 display+GT911+STOP	TODO
P08	refactor/P08-idf-debt.md	Replace Arduino drivers (RMT etc.)	TODO

P04 Notes: merge_bin uses ${{ gitea.sha }} (not github.sha); runner unverified (no Actions run).

P05 Notes: BLOCKED — no app_machine + HAL headers from P03 (branch @ 415c13a). Not implemented.

Dependency

P00 → P01 → P02 → P03 → P04
                ↘ P05 → P06 → P07 → P08
P04 may start after P01 (hashFiles guards) but must not be required-on-develop until P03 VERIFY is green.
P05 requires P03 APIs. P06 requires P05. P07 requires P06 screen contract. P08 requires P06 behaviour-identical.

Tree (end state; create only what the current phase lists)

main/                          IDF entry, spawn tasks
components/ui_cmd/             cmds/events C structs
components/app_process/        const recipes + session overlay
components/app_machine/        state machine
components/app_ui/             screens → commands
components/hal_{motor,temp,input,display,audio}/
components/board_{wroom,jc4827w543}/
tests/host/                    CMake+CTest, stub HAL
.gitea/workflows/ci.yml
sdkconfig.defaults  sdkconfig.wroom  sdkconfig.s3
src/ include/                  legacy; shrink after P06

IDF pin

espressif/idf:v5.4. Bump only in P04/CICD together.

Do not

• Expand scope (LVGL, NVS profiles, pumps, heater, PlatformIO CI).
• Disable TWDT.
• Add Arduino libraries beyond AccelStepper, Keypad, LiquidCrystal_I2C, OneWire, DallasTemperature (P05–P07 only).
• Commit sdkconfig (generated), build/, tokens.