diff --git a/autostory/plza/UPSTREAM_PLAN.md b/autostory/plza/UPSTREAM_PLAN.md index a529082fac..abe3f921e7 100644 --- a/autostory/plza/UPSTREAM_PLAN.md +++ b/autostory/plza/UPSTREAM_PLAN.md @@ -1,456 +1,86 @@ -# PLZA AutoStory: plan for the upstream PR chain and the verification runs +# PLZA AutoStory: upstream plan (lean slices) -## Your TODOs +Updated by: the main session, 2026-11-15. It updates this file whenever a slice PR is opened, +merged or passes on console. Detail notes: `~/BDSPLab/notes/plza-slice1-plan.md` (local). -State on 2026-11-15. Agents never open upstream PRs or write their descriptions: every upstream -step below is yours. Each item says what to do and what we recommend. +## Your TODOs -1. **Answer the eleven plan questions** (details in section 5). Reply "agree" or give your call: - 1. Q1 split S2? Already done finer than planned: S1 is #529-#534, S2 is #535-#545. Recommend: keep that split. - 2. Q2 one PR per Main Mission? Recommend: yes, keep #565, #566, #567 separate. - 3. Q3 fault sweep upstream? Recommend: yes, as one shared PR after #567, once its two known-failing rows (warp_no_op, 03.06 and 03.08) are fixed. It is not in today's chain. - 4. Q4 `BREAKPOINTS` option upstream? Recommend: no option on the upstream panel; keep the small engine hook. - 5. Q5 dev-folder override upstream? Recommend: no folder scan upstream; keep the `dev_files` span as the test seam. - 6. Q6 pass rule? Recommend: 3/3 for walks and scenes, 2/3 for the battles 01.03 (Andi) and 03.02 (Taunie). - 7. Q7 who opens the CommandLineTests PR (C1)? Recommend: you, from a branch an agent prepares on dayfine/CommandLineTests. - 8. Q8 branch names? Already `plza/upstream/`. Recommend: keep; set `upstream-bound` on each branch before its handoff. - 9. Q9 old fork PRs? Recommend: close #416, #354, #355, #356, #335 and the umbrella drafts #522, #524, #525 with a link to the re-split chain; keep #492 until the fault sweep PR (Q3) replaces it, and #418 (CFR) on the fork. - 10. Q10 S0b on S0a? Moot: both merged into fork main today (#519 shared stats, #520 `CheckpointId`). Recommend: hand them upstream in that order. - 11. Q11 which branch the verification runs use? Recommend: today's tip `plza/fault-sweep`; carry the records over as the test notes of the P and M PRs. -2. **Review the shared PRs yourself before each handoff.** All 17 shared PRs (#529-#545) are - infra, which upstream reviews strictly; read each one in full. The agent review left every one - at NEEDS_REWORK, each at an older SHA than its tip; ask for a re-review at the tip and wait - for a clean one first. For the PLZA PRs (#555-#569) the API review says LGTM with nits on half of - them; read at least #559 (console backend), #563 (catches) and #568 (story game, +4.2k), the - ones that drive the console. -3. **Land the test frames upstream (C1) before #544.** CI on #544 and every PR above it fails - only with `FileException`: the frames in `NintendoSwitch/HomeTileReader`, - `PokemonLZA/AutoStoryDetectors` and `PokemonLZA/AutoStoryScreenEvents` (plus the five folders - in section 2) are on dayfine/CommandLineTests, not PokemonAutomation/CommandLineTests. Open - that PR on PokemonAutomation/CommandLineTests; an agent prepares the branch and file list. -4. **Open the upstream PRs, one at a time, under the three-open limit.** Two of yours are open - upstream now (#1881 FRLG free party slots, #1845 command-line test mode), so one slot is free. - Order: #519 (shared stats) first, then #520 (`CheckpointId`), then #529 and up the chain - bottom first, always the lowest unopened one as a slot frees. Each upstream PR targets `main`; - you write its description (the fork draft's body is the factual handoff note to draw on). -5. **Before each handoff, ask for the pre-flight**: an agent merges `main` into the branch, fixes - every code-health finding (advisory ones too; CI's code-health fails today on 13 PRs, listed - below), confirms Fork Draft CI green, and reports the tested SHA. You then open the PR. -6. **Console verification (section 4.2)** is ours, but tell us when console B is free for the - 3x runs per checkpoint; the P/M PRs link their results. +You open every upstream PR and write its description; agents never do. + +1. **Review the slice PRs** bottom first: #572, then #573 to #577 (slice 1), then #580, #582. +2. **Hand upstream, one at a time, under the three-open limit:** #572 first (shared with SV), then + #573 up the chain. Before each one, ask for the pre-flight: an agent merges `main` in, fixes + every code-health finding, gets the unit tests green and reports the tested SHA. +3. **Land the test frames upstream before #575.** dayfine/CommandLineTests#18 (`plza/all-frames`) + holds every frame the PLZA tests read; open its PR on PokemonAutomation/CommandLineTests. Nine + AutoStoryScreenEvents frames are missing and need a recapture on console B (ours): `za2_m3o_s1`, + `za2_m3p_s1`, `za2_m2q_s1`, `za2_hud_s3`, `za2_m2n_s1`, `za2_hud_s1`, `za2_m3s_s1`, + `za2_m3w_s2`, `za2_m2m_s1`. +4. **Close the old PRs** listed at the bottom, when you're ready. + +No open questions right now. + +## Decisions (2026-11-15) + +- A checkpoint's save field is `autosave` | `unverified` | `absent`. +- #520's `CheckpointId` is dropped from the chain. +- #572 `StoryRangeOptions` is its own early PR, shared with SV. +- Rebuild as lean vertical slices: cut unused code, add a piece when it is first needed (battle at + the first battle, catch at the first catch), and put shared code in shared locations with more + tests. +- `plza/autostory` (#576) is the long-lived branch: it always builds and should end up equal to + `main`. +- Sharing with upstream PLZA programs: + - Slice 4 has no fly (you can't fly at that story point); `fly_from_map` is dropped. + - The gate walk tries upstream's `run_towards_gate_with_A_button` first; our gate-reader steering + stays only if a console run shows the need. + - Leaving a zone uses upstream's `leave_zone_gate`. + - A shared throw helper (lock on, optional ball scroll, throw), used by our catch, + InPlaceCatcher and PostKillCatcher, goes in its own PR before slice 5. +- The 01.00 save is `autosave` (a run log showed the badge). ## Chain -Fork drafts on dayfine/Arduino-Source, bottom first. #519 and #520 merged into fork `main` today -and #529 was retargeted to `main` (its branch is 2 commits behind `main`; merge `main` in before -handoff). CI: "pass" = Fork Draft CI (Ubuntu build + unit tests), code-health and tabs all -pass; failing checks are named. "frames" = Ubuntu build fails only on test frames not yet on -upstream's CommandLineTests (TODO 3). Review = last agent verdict. All are open drafts. +Fork drafts on dayfine/Arduino-Source, linear, bottom first. Lines added, from the PR file list +(test = unit tests and fakes). CI: Fork Draft CI only runs on PRs into `main`, so the slice PRs +got a dispatched Ubuntu run at their tip; failures are named. -| PR | Branch | Base | What | Size (+lines, files) | CI | Review | +| PR | Branch | Base | Purpose | Code / test (+lines) | CI (2026-11-15) | Console | |---|---|---|---|---|---|---| -| #519 | `autostory/shared-stats` | `main` | shared AutoStory stats, Runs, clearer labels (S0a) | +210/-62, 48 | - | approved; merged into fork main then reverted (a4debbe5e) — hand upstream from the branch | -| #520 | `autostory/checkpoint-id` | `main` | `CheckpointId` value type (S0b) | +496, 6 | - | approved; merged into fork main then reverted (a4debbe5e) — hand upstream from the branch | -| #529 | `plza/upstream/s1-01` | `autostory/checkpoint-id` | tile grid, step kinds, action args, built-in action table | +924, 19 | pass | NEEDS_REWORK | -| #530 | `plza/upstream/s1-02` | s1-01 | story log, failure classes, step outcome | +1307, 14 | code-health | NEEDS_REWORK | -| #531 | `plza/upstream/s1-03` | s1-02 | steps, checkpoints, breakpoints, save modes as data | +954, 16 | code-health | NEEDS_REWORK | -| #532 | `plza/upstream/s1-04` | s1-03 | checkpoint as story events, outcome classes, tile poses | +1454, 10 | code-health | NEEDS_REWORK | -| #533 | `plza/upstream/s1-05` | s1-04 | tile-game step executor, story JSON readers | +1525, 10 | code-health | NEEDS_REWORK | -| #534 | `plza/upstream/s1-06` | s1-05 | CommonTools screen events | +816, 9 | pass | NEEDS_REWORK | -| #535 | `plza/upstream/s2-01` | s1-06 | checkpoint attempts, story segments | +2112/-3, 16 | code-health | NEEDS_REWORK | -| #536 | `plza/upstream/s2-02` | s2-01 | read a story from checkpoint files | +1365, 13 | pass | NEEDS_REWORK | -| #537 | `plza/upstream/s2-03` | s2-02 | frame coverage, covered watches, scene judges | +1193, 15 | code-health | NEEDS_REWORK | -| #538 | `plza/upstream/s2-04` | s2-03 | story backend interface | +606, 11 | pass | NEEDS_REWORK | -| #539 | `plza/upstream/s2-05` | s2-04 | action registry, built-in actions, step runner | +1362, 12 | pass | NEEDS_REWORK | -| #540 | `plza/upstream/s2-06` | s2-05 | postcondition checks, engine save policy | +813, 8 | code-health | NEEDS_REWORK | -| #541 | `plza/upstream/s2-07` | s2-06 | CommonTools screen machine and step trace | +935, 10 | code-health | NEEDS_REWORK | -| #542 | `plza/upstream/s2-08` | s2-07 | the story engine | +1743, 10 | code-health | NEEDS_REWORK | -| #543 | `plza/upstream/s2-09` | s2-08 | run options, language and checkpoint range dropdowns | +1051, 17 | pass | NEEDS_REWORK | -| #544 | `plza/upstream/s2-10` | s2-09 | NintendoSwitch: which HOME tile is selected | +309, 4 | frames | NEEDS_REWORK | -| #545 | `plza/upstream/s2-11` | s2-10 | launch a game to its save through Switch prompts | +987, 8 | frames | NEEDS_REWORK | -| #555 | `plza/upstream/p1-01` | s2-11 | LZA lock-on bracket and party bar detectors | +982, 7 | frames | none yet | -| #556 | `plza/upstream/p1-02` | p1-01 | story scene detectors | +2492, 27 | frames | LGTM with nits | -| #557 | `plza/upstream/p1-03` | p1-02 | dialog, choice, Confirm Choices, objective marker readers | +1464/-1, 22 | frames | none yet | -| #558 | `plza/upstream/p2-01` | p1-03 | screen readings, failure classes, screen events | +798, 9 | frames | LGTM with nits | -| #559 | `plza/upstream/p2-02` | p2-01 | console backend: dialogs, scenes, battles | +1491/-1, 14 | frames | none yet | -| #560 | `plza/upstream/p2-03` | p2-02 | the scene machine | +730, 3 | frames | LGTM with nits | -| #561 | `plza/upstream/p2-04` | p2-03 | timed walks, walk screen checks, step checks | +714, 8 | frames | none yet | -| #562 | `plza/upstream/p2-05` | p2-04 | start load, launch, Confirm Choices, zone gate walk | +1337, 16 | frames, code-health | LGTM with nits | -| #563 | `plza/upstream/p3-01` | p2-05 | catch plan, catch stop, lock-on watch | +2146, 16 | frames | LGTM with nits | -| #564 | `plza/upstream/p3-02` | p3-01 | Wild Zone 1 catches, objective marker walks | +1353, 5 | frames, code-health | none yet | -| #565 | `plza/upstream/m1-01` | p3-02 | Main Mission 01 plans (01.01-01.03) | +180, 4 | frames | LGTM with nits | -| #566 | `plza/upstream/m2-01` | m1-01 | Main Mission 02 plans (02.01-02.07) | +351, 7 | frames | none yet | -| #567 | `plza/upstream/m3-01` | m2-01 | Main Mission 03 plans (03.01-03.11) | +602, 11 | frames | LGTM with nits | -| #568 | `plza/upstream/p4-01` | m3-01 | the story game and its table | +4175, 17 | frames, code-health | LGTM with nits | -| #569 | `plza/upstream/p4-02` | p4-01 | the program | +342, 4 | frames | none yet | - -Totals (added lines): S0 #519-#520 +0.7k; S1 #529-#534 +7.0k; S2 #535-#545 +12.5k; P #555-#564, #568-#569 +18.0k; M #565-#567 +1.1k; whole chain 34 PRs, +39.3k. Largest: #568 +4.2k, #556 +2.5k, #563 +2.1k, #535 +2.1k. - -Not in the chain: #522 (`plza/upstream/s1`, base `autostory/checkpoint-id`, CI code-health), -#524 (`s2a`, pass) and #525 (`s2b`, pass) are the earlier three-PR cut that #529-#545 re-split; -close them (Q9). #418 (CFR actions) and #492 (fault sweep) stay fork-only for now. - -The rest of this doc is the plan of 2026-11-14 that the chain above was built from. - - -Status: **proposal for the user to approve, 2026-11-14.** The fork chain was rebuilt on 2026-11-15 (see Chain above). -Written after the user's call: "PLZA -- this is done, so next step is to tidy things up and -get every PR in a good shape: have the proper PR chain structure for what we really need (for -upstream); have a clear testing instruction (which we will also execute again in the next couple -testing runs, e.g. in verification mode that runs 3x each checkpoint)". - -Rules this plan follows: `AGENTS.md` and `pokemon_sv/PR_WORKFLOW.md` on this branch (fork -drafts only; the user opens every upstream PR and writes its description; at most three open -upstream PRs; a stacked upstream PR targets `main` and shows all its parents' commits), and the -PR-shape decision of 2026-11-12 (3 shared + 3 per-game foundation PRs, then one PR per segment, -one linear stack per game; fixes land on the tip and are folded into the owning PR). - -Numbers below (files, +/-) are GitHub's for each fork PR on 2026-11-14 unless a `git diff` -command is given. Checkpoint ids are the ones on the tip after the renumber that landed today -(`a6e32757b`, "drop 03.07d, renumber 03.08b-03.09b to 03.09-03.11"): 01.00-01.03, 02.01-02.07, -03.01-03.11, 22 checkpoints, dropdown indices 0-21. In MM03's tail: 03.07d dropped, 03.08 kept, -03.09 (was 03.08b), 03.10 (was 03.09), 03.11 (was 03.09b); indices 18-21. 03.08 has no save of -its own at its start, so rerunning 03.08 needs 03.07 first (user, 2026-11-14). If the user -renumbers again, every id in section 4 moves with it. - -The user's addition of 2026-11-14 (relayed by the coordinator): the chain starts with two -standalone shared PRs off `main`, before anything PLZA (S0a, S0b in section 3), and then a clean -chain the user reviews closely one PR at a time. So **every PR is self-contained: one purpose, an -explicit scope (what is in, what is not), and its own test notes** (which suites, which console -runs, how to run them). - -## 1. Today's PLZA fork stack - -Bases followed from the tip down to `main`. Tips at the time of writing: -`plza/story-detectors` bfea2d536, `plza/story-base` fcb1074c3, `plza/story-mm1` 961911268, -`plza/story-mm2` 26c021902, `plza/story-engine` a6e32757b, `plza/fault-sweep` 24133e149, -`plza/cfr-actions-v2` 4c568833d, `nav/shared` 3df87aa4e. - -``` -main -└─ #62 switch/system-keyboard +702/-1 8 f open Switch on-screen keyboard (PLZA does not use it; the chain passes through it) - └─ #45 autostory/r3-shared-stats +438/-2 8 f open shared run report (AutoStoryStats) - └─ #325 autostory/story-range-options +390/-49 10 f open START/END checkpoint options - └─ #391 autostory/sv-retry-core +32762/-130 259 f open share SV's checkpoint retry loop; nav/shared (#114) merged into it - └─ nav/shared (integration branch, no PR of its own since #114 merged) - merged into it: #312 story step types + engine (+4788), #313 ScreenEvents (+793), - #332 engine over a backend (+17220, 154 f), #360 tile navigation (+5135), - #361 scene judges (+2280), #362 story actions/interrupts (+3972), #419 sim goldens, - #422 fault counters, #448 breakpoints (+467), #474 shared story files + dev folder - (+1080), #477 launch from HOME (+1182), #479 failure classes (+1439), - #490/#494/#495/#497 review fixes, #227, #390, #399 - └─ #416 plza/story-detectors +1947/-0 22 f base autostory/story-breakpoints (= nav/shared after #448 merged) - └─ #354 plza/story-base +6269/-0 50 f program, StoryEngine backend, actions glue, 01.00 - └─ #355 plza/story-mm1 +762/-35 17 f 01.01-01.03 - └─ #356 plza/story-mm2 +474/-23 18 f 02.01-02.06 (02.07 came later, in #335) - └─ #335 plza/story-engine +16866/-1877 228 f 03.01-03.11, Wild Zone 1 catches, PartyBar/MinimapZone/CaughtMark/DexRegistered detectors - ├─ #492 plza/fault-sweep +1298/-30 16 f failure classes + fault sweep tests (03.06, 03.08) - └─ plza/cfr-base-v2 (no PR) = story-engine + lab/main (#103) + switch/system-keyboard + build/headless-tests (#207) - └─ #418 plza/cfr-actions-v2 +5301/-195 64 f Command File Runner: lza_* actions, type, steps file -``` - -Sizes that matter for the restructure: - -| Range | `git diff --shortstat A...B` | Meaning | -|---|---|---| -| `main...nav/shared` | 276 files, +34248/-173 | everything shared the PLZA chain sits on (incl. the SV retry core and tile navigation PLZA does not use) | -| `main...plza/fault-sweep` | 419 files, +53279/-175 | the whole chain to the PLZA tip | -| `nav/shared...plza/story-detectors` | 22 files, +1947 | #416's own change | -| `plza/story-mm2...plza/story-engine` | 256 files (three-dot, several merge bases) | #335 shows nav/shared commits mm2 has not taken: its own part is `VideoGames/PokemonLZA/Programs/AutoStory` (132 files) and six `Inference/` files (PartyBarDetector, ...) | - -So the PLZA-only code is about 19k lines in ~140 files (53.3k - 34.2k), and the shared base it -depends on is 34k lines. #335 also shows +1912/-229 in `Pokemon/AutoStory`, +2305/-378 in -`Pokemon/AutoStory/Engine` and +1197/-89 in `Pokemon/AutoStory/Data`: those are #474/#477/#332 -commits merged in, not PLZA changes; they vanish once #356 takes nav/shared. - -`plza/story-engine` is 0 commits behind `main`, `nav/shared` and `autostory/story-breakpoints`, -1 behind `autostory/r3-shared-stats` (#45 review fix) and 4 behind `autostory/sv-retry-core`. - -## 2. What upstream needs for PLZA AutoStory 01.00 -> 03.11, and what stays on the fork - -### Needed (what the PLZA code includes) - -PLZA's AutoStory sources include, outside their own folder, only: - -- `Pokemon/AutoStory/Engine/*` (StoryEngine, StoryBackend, StoryGame, StoryLaunch, CoveredWatch, - ScreenObservation, StoryActionRegistry, StoryFakeBackend, StoryActionNotImplemented); -- `Pokemon/AutoStory/*` (StoryStepExecutor, SceneJudges, StoryOutcome(+Class), StoryLog, - StoryFailureClasses, StoryFaultSweep, StorySwitchPrompts, BuiltinStoryActions, AutoStorySelect, - AutoStoryStats); -- `Pokemon/AutoStory/Data/*` (AuthoredCheckpointJson, StoryFiles, StoryDevFiles, StoryRowExecution); -- `Pokemon/AutoStory/Types/*` (StoryCheckpoint, StoryStep, StoryActionSpec, StoryCheckLevel, - StoryBreakpoints); -- `Pokemon/Options/Pokemon_StoryRunOptions.h`, `Pokemon_GameLanguages.h`; -- `CommonTools/ScreenEvents` (#313), `NintendoSwitch/Inference` additions from #335 - (3 files, +306), `cmake/EmbedTextFiles.cmake` (shared, on `nav/shared` as b426f749f - "pa_embed_text_files", with #474's story files; it embeds the plan JSON into the binary). - -It does **not** include `Pokemon/Navigation` tile navigation (#360/#361/#362/#419/#440/#464), the -on-screen keyboard (#62: the user types the name by hand before 01.00), or anything from -`VideoGames/PokemonSV`. The first task of the restructure is therefore a **dependency-closure -build**: `main` + the shared story engine subset + the PLZA folder, built and unit-tested, to prove -the list above is complete and to find what in #391 (sv-retry-core, 32k lines) PLZA really pulls -(`AutoStorySelect`, `StoryRunOptions` and the retry loop are the suspects). - -Resources: PLZA AutoStory adds **no** `RESOURCE_PATH()` or Packages files. The platform reference -cells (`ReferenceData/plza-platform.json`) and the 22 plan files are embedded at build time; the -`CategoryIcons/PokemonLZA.png` and `PokemonLZA/LocationName.json` resources already exist upstream. -Confirm with `git grep RESOURCE_PATH -- SerialPrograms/Source/VideoGames/PokemonLZA/Programs/AutoStory` -on the final chain (today: only the test helper's `RESOURCE_PATH(), test.input.folder`). - -Test images: `CommandLineTests/PokemonLZA/AutoStoryDetectors/` (811 frames) is already on -dayfine/CommandLineTests `main`. The fork CI pin (`cpp-ci-serial-programs-base.yml` on the PLZA -branches checks out `dayfine/CommandLineTests` at `02f2c8e3e…`, branch `plza/story-engine-pin`) -adds 82 fork-only files in five folders that must go to PokemonAutomation/CommandLineTests before -the matching code PR: `AutoStoryConfirmChoices` (30), `LockOnBracketDetector` (30), -`AutoStoryLookPicker` (18, only if the intro picks go upstream; see below), `PartyBarDetector` (3), -`AutoStoryDialogChoices` (1). The `.github/workflows` edits that point CI at the fork's -CommandLineTests never go upstream; the upstream chain keeps `PokemonAutomation/CommandLineTests`. - -### Dependency closure, measured 2026-11-14 (batch 1) - -Include closure of `VideoGames/PokemonLZA/Programs/AutoStory` on `plza/fault-sweep` 24133e149, -tests and the fault sweep left out: **121 files, +12.0k lines** outside the PLZA folder (vs -`autostory/checkpoint-id`). Nothing from `Pokemon/Navigation` tile navigation, the SV retry core -(#391: `CheckpointRetry`, `StoryRun`, interrupts, `StoryActions`) or the keyboard is in it. It does -pull `Pokemon/Navigation/{Pokemon_Direction,Pokemon_Grid}` and `Pokemon_TilePose`: the backend's -`tap(Direction)`, `GridPose` (woven into the step executor, postcondition check and step JSON) and -the engine's `GridPose` instantiations need them; cutting them is a rewrite, so they stay. - -Rebuilt fork PRs, each one's own change with its tests: - -| PR | Branch, tip | Own size | Of it, tests | -|---|---|---|---| -| S1 #522 | `plza/upstream/s1` 5236786c6 | 72 files, +7.5k | +2.8k | -| S2a #524 | `plza/upstream/s2a` 5f5f6d205 | 69 files, +9.4k (loader +1.0k of it) | +4.4k | -| S2b #525 | `plza/upstream/s2b` 00c6ceb84 | 25 files, +2.3k | +0.9k | - -S2a is under 10k with the loader, so no S2a'. Where the cut differs from section 3: -- Failure classes are in S1, not S2b: `Outcome` carries `std::optional`. Their - sim-fault mapping (`injected_by`, `story_failure_class_of(FaultClass)`) is cut, which drops - `Pokemon_SimFaults`; it returns with the fault sweep (S3, after M3). -- `record_story_counts()` writes #520's stats (Segments Started, Checkpoints Started, Resets); - a segment report now counts checkpoints started, not passed. -- The `BREAKPOINTS` option is out of `StoryRunOptions`; the engine's pause hook and - `StoryBreakpoints` type stay (S1). PLZA's `Moves.h` still includes the type. -- `Pokemon_StoryDevFiles.h` keeps only the `StoryDevFile` struct (the loader's test seam); the - folder scan (`story_dev_folder`, `read_story_dev_files`) is out, so P2's `StoryFiles` passes none. -- `cmake/EmbedTextFiles.cmake` waits for P2, its first caller. -- The shared suites register through `Pokemon_AutoStory_Tests.h` (`add_tests_AutoStory()`). -- C1 needs `NintendoSwitch/HomeTileReader/` (6 frames) too: S2b's HomeTileReader test reads them, - so S2b's fork CI pins `dayfine/CommandLineTests` at 0195f3b0c as `plza/fault-sweep` does. - -### Fork- or lab-only, stays out +| #572 | `autostory/story-range-options-sv` | `main` | start/end checkpoint range options, shared with SV | +168 / +261 | rerunning at 7078725ae | - | +| #573 | `plza/slice1/b` | #572 | story checkpoint data and its JSON reader | +1882 / +1071 | 1 unit test fails (StoryFiles: trailing space) | - | +| #574 | `plza/slice1/c` | #573 | story engine for a zone game | +1671 / +1190 | 4 fail (StoryFiles; StoryEngine expects `Home`, gets `HOME`) | - | +| #575 | `plza/slice1/d` | #574 | PLZA opening detectors; CI pins CLT #18 | +1167 / +997 | same 4 | - | +| #577 | `plza/slice1/e` | #575 | new game to leaving the platform (01.00, 01.01 start) | +1627 / +371 | same 4 | 01.00 1/1, 01.01 3/3 (below) | +| #580 | `plza/slice2/a` | #577 | 01.01 arrival scenes to Main Mission 01 | +1141 / +984 | not run | - | +| #582 | `plza/slice2/b` | #580 | 01.02, Pancham's chase to the battle area | +554 / +690 | 10 fail (same 4 + 6) | - | +| #576 | `plza/autostory` | `main` | long-lived branch (+54k, 425 files) | - | Fork Draft CI fails on the 9 missing frames; code-health fails | - | +| CLT #18 | `plza/all-frames` | `main` | every frame the PLZA tests read (84 files) | - | - | 9 frames missing | -| Item | Where today | Why it stays | -|---|---|---| -| Command File Runner LZA actions, `type`, steps file, `cfr_steps_to_story.py` | #418 and its base `plza/cfr-base-v2` | lab recording tool; its base carries `lab/main` (#103, HttpServer, Sockets, lab channel) | -| the lab channel, lab device ownership, `set_story_pause_wait()` lab wait | `lab/main` | lab infrastructure | -| `BREAKPOINTS` run option | #448 (shared), surfaced in PLZA's panel | "only a lab build waits": a no-op option upstream (question Q4) | -| dev-folder override (`story_dev_folder("plza")`, `Pokemon_StoryDevFiles.h`, `dev_files` span) | #474 (shared), PLZA reader in #354/#335 | lab tuning of plan files without a rebuild; upstream's program would pass an empty span (question Q5) | -| intro picks + 00.00 (language, look, name by program) and `AutoStoryLookPicker` frames | dev-only branch #471 | the user does the new-game setup by hand; 01.00 starts at Confirm Choices | -| CI pins to `dayfine/CommandLineTests` | `.github/workflows` edits in #335, #418 | fork only | -| fault sweep **known-failing** rows (warp_no_op on 03.06 and 03.08) | #492 | fix or drop before upstream; the sweep itself is worth upstreaming (see S3) | -| run records, `segments.tsv`, this plan | `agents` branch | notes | - -## 3. Proposed upstream chain - -Eleven Arduino-Source PRs (two standalone shared PRs off `main`, three shared foundation, three -PLZA foundation, three segments) plus one CommandLineTests PR, in this order. Each upstream PR -targets `main` and shows its parents, so sizes below are each PR's **own** change. The user writes -every upstream description; the fork draft that mirrors each one carries the factual handoff note -(branch, tested revision, tests, dependencies) for the user to draw on. Each PR's row names its -purpose and scope; its test notes are the unit suites it adds (4.1) and, for P2 onward, the -console runs of 4.2 it needs. - -| # | PR | Own files | Own size | Purpose and contents | -|---|---|---|---|---| -| S0a | Shared AutoStory stats (standalone, off `main`) | `Pokemon/AutoStory/Pokemon_AutoStoryStats.{h,cpp}` moved from SV, SV's program using it, stats tests | ~0.5k (#45's +438, reshaped) | SV's `AutoStoryStats` moves to `Pokemon/AutoStory/` and is shared; adds "Runs"; renames labels with `StatsTracker` aliases (Segment -> Segments Started, Checkpoint -> Checkpoints Passed, Reset -> Resets). No PLZA code. Tests: the stats/alias unit test; SV's panel still loads its saved stats. | -| S0b | `CheckpointId` value type (standalone, off `main`, after S0a) | `Pokemon/AutoStory/Types/Pokemon_CheckpointId.{h,cpp}` + tests, loader change, log line | ~0.5-1k | parses "03.08" -> {segment 3, checkpoint 8}; the loader rejects malformed or suffixed ids (so the renumber above is a prerequisite); logs read "[Segment] 03" (not the game's name); Segments Started counts each new segment number; the order test checks ids are unique and increasing. Tests: parse/reject table, order test, a log-line test. Depends on S0a for the stat it feeds (or stub it if the user wants S0b independent; Q10). | -| S1 | Screen events + story step types and engine | `CommonTools/ScreenEvents`, `Pokemon/AutoStory/Types`, `Pokemon/AutoStory/Engine` core, `Pokemon/AutoStory/Pokemon_Story{Step,StepExecutor,Outcome,Log}` | ~5.6k (#313 + #312) | what the screen is doing since when; the step vocabulary and the executor. Already reviewed on the fork (#312, #313 and their nits #490/#497). | -| S2 | Engine over a backend, story files, run options, launch, failure classes | rest of `Pokemon/AutoStory/Engine`, `Pokemon/AutoStory/Data`, `Pokemon/Options/Pokemon_StoryRun*Options`, `Pokemon_AutoStoryStats`, `Pokemon_StorySwitchPrompts`, `Pokemon_StoryFailureClasses`, `cmake/EmbedTextFiles.cmake` | 10-20k; **measure with the closure build** | #332 (17k) is the elephant: the closure build says how much of it PLZA needs. Folds #45, #325, #448 (minus lab wait), #474 (minus dev folder, Q5), #477, #479 and the parts of #391 PLZA includes. Split in two if the closure is above ~12k (S2a engine+data, S2b options+launch+failure classes). | -| S3 | Story fault sweep (shared) | `Pokemon_StoryFaultSweep.*`, shared fault counters (#422's `Pokemon/Navigation/Simulation` part if PLZA's sweep uses it) | ~1-2k | unit-test-only infrastructure that found two real bugs (timed walk replay, `press_a_first`). Can wait until after P3 if the user prefers fewer shared PRs first (Q3). | -| C1 | **CommandLineTests**: PLZA AutoStory frames | the five folders above (82 files) | images | before P1 opens; the pin on the fork chain then returns to upstream's repo. | -| P1 | PLZA AutoStory detectors | #416's 19 files + the later detectors now in #335: `PartyBarDetector`, `LockOnBracketDetector` changes, `MinimapZoneDetector`, `CaughtMarkReader`, `DexRegisteredDetector`, `ObjectiveMarkerReader`, `ConfirmChoicesReader`, `DialogChoiceBox` | ~3-4k | pixel readers, no presses; tests on synthetic frames and `CommandLineTests/PokemonLZA/*`. | -| P2 | PLZA AutoStory program and new game | #354 as is: program, `PlzaConsoleBackend`, `ScreenObserver`, `SceneMachine`, `StoryFiles` (built-in plans only), `StartLoad`, `Launch`, `Table`, 01.00 | ~6k | runs 01.00 end to end; its table/engine/scene-machine tests. | -| P3 | PLZA AutoStory actions | `Actions/*` beyond what P2 needs for 01.00: Moves, MarkerWalks, GateWalk, Zone1Road, Catches/CatchPlan/CatchStop, SpeciesCheck, BracketWatch, WalkScreenChecks, battle entry | ~5-7k | the per-game "battles/actions/setup" foundation; tests `AutoStoryGateWalk`, `AutoStoryCatchPlan`, `AutoStoryCatchStop`. | -| M1 | Main Mission 01 (01.01-01.03) | three plan files + their table rows and any MM01-only action | ~0.8k | #355 as is | -| M2 | Main Mission 02 (02.01-02.07) | seven plan files + hotel elevator/corridor actions | ~0.6k | #356 + 02.07 from #335 | -| M3 | Main Mission 03 (03.01-03.11) + Wild Zone 1 | eleven plan files, catch routines' wiring, `AutoStoryFailures` classes, PLZA `FaultSweep_Tests` | ~3-5k | the rest of #335 + #492 | - -Order under the three-open-PR limit (C1 is on another repo and does not count against it, but it -must merge before P1): - -1. Open S0a and S0b first (standalone off `main`, the user's call of 2026-11-14), plus C1. S1 is - prepared meanwhile, based on S0b. -2. As S0a/S0b merge: open S1, then S2 (or S2a). The fork drafts for P1-M3 are rebuilt meanwhile. -3. When S1 merges: open S2b or S3. When S2 merges: open P1. -4. Then P2, P3, M1, M2, M3 one at a time as slots free up: at most three open, always the - lowest unopened one next. - -Expected: at least six waves. M1 and M2 are small enough to merge into one "Main Missions 01-02" -PR if the user wants a shorter chain (Q2). S1 and everything after it take the shared stats and -`CheckpointId` from S0a/S0b, so the rebuilt fork branches base on them, not on today's #45. - -How the fork restructure prepares this (not started; the user approves first): rebuild fresh -squashed branches bottom-up from the current tip, one agent at a time, so the final tree equals -`plza/fault-sweep`'s tree and the unit tests match (the PR-shape decision of 2026-11-12). The old -PRs #416/#354/#355/#356/#335/#492 close with a link to their replacement. #418 and -`plza/cfr-base-v2` stay fork drafts, rebased by merge onto the new tip. - -Shared PRs that must land first: S1 and S2 before P1 (P1's tests use `ScreenEvents` frames and -the story types); S3 before M3 (its `FaultSweep_Tests`). C1 before P1. - -## 4. Testing instructions - -### 4.1 Unit tests - -PLZA AutoStory suites (`PokemonLZA_Tests.cpp` registers them under `PokemonLZA::`): -`AutoStoryDetectors`, `AutoStoryConfirmChoicesReader`, `AutoStoryObjectiveMarkerReader`, -`AutoStoryZoneGateReader`, `AutoStoryGateWalk`, `AutoStory_StoryTable`, `AutoStoryScreenEvents`, -`AutoStoryFailures`, `AutoStoryFaultSweep`, `AutoStoryCatchPlan`, `AutoStoryCatchStop`, -`AutoStorySceneMachine`, `AutoStoryEngine`, `AutoStoryStartLoad`; plus the Inference suites -`LockOnBracketDetector` and `PartyBarDetector`. Shared: `Pokemon::StoryRunOptions`, -`Pokemon::StoryRangeOptions`, the engine and story-data tests of S1/S2. - -Run them as upstream CI does (`.github/workflows/cpp-ci-serial-programs-base.yml`): - -1. Build `SerialPrograms` (CMake preset `default`, Ninja, `-j4`). -2. Check out `CommandLineTests` next to the program (`SerialPrograms/bin/../../CommandLineTests`). -3. From `SerialPrograms/bin`: `./SerialPrograms --profile unit-tests --command-line-test-mode` - (headless Linux adds `QT_QPA_PLATFORM=offscreen` and `TESSDATA_PREFIX=/Resources/Tesseract`). - On the lab Mac never run the binary without `--profile`: the default profile opens console A's - serial port. Wait for "Tests Finished" in the log, then stop the process. -4. Pass = every `PokemonLZA::*` and `Pokemon::*` suite reports 0 failures. Until C1 lands, - the frames of the five fork-only folders fail with `FileException` on upstream's - CommandLineTests; on the fork chain they pass through the pin. - -On the fork, Fork Draft CI runs this on every push of a draft; marking the draft ready runs the -six upstream workflows. - -### 4.2 The console verification run +Console records, lab build e36a816a4 (slice 1 E + lab tooling), 2026-11-15: -One checkpoint at a time, from its own start save, three runs, then the postcondition check. -Phases and saves follow `autostory/SAVE_POLICY.md`; the program options are the shared -`StoryRunOptions` (`Pokemon_StoryRunOptions.h`). +- 01.00 passed once: new game to the platform, autosave badge seen. +- 01.01 3/3; runs 2 and 3 reloaded the latest save and walked to the plaza fade. -Before the run (precondition): -- Console B shows the title screen with the checkpoint's start save as the newest save, read on - the save card. PLZA autosaves (catches, check-in, scenes): if a later autosave moved the save, - load the backup save (title screen: hold Up, press B + X) and read the BACKUP card first, or - set `START_FROM_BACKUP_SAVE` on the panel. Never save by hand from a position nothing checked. -- Previous checkpoint is verification-passed (`segments.tsv`); N+1 never starts after a hand - recovery of N. -- Panel: `LANGUAGE` = the save's game language; `STARTER` as the save has it; `RUN`: - `START_CHECKPOINT` = `END_CHECKPOINT` = the checkpoint; `VERIFY` on, `RUNS` = 3, `PASSES` = 3 - (battle checkpoints: `PASSES` = 2, Q6); `SAVE_MODE` = After verification; `RELOAD_AT_START` on; - `POSTCONDITIONS_ONLY` off; `BREAKPOINTS` off; `CHECKS` = the default level. +## Later slices -The run: the engine reloads the save, plays the checkpoint, reloads, plays it again, three times. -Only the last run may save, and only when every run passed (the engine enforces this). A failed -run never saves. - -After the run (postcondition, a separate step): run once more with `POSTCONDITIONS_ONLY` on, and -confirm by screenshot the end position (zone/place and heading), the party (species count on the -party bar, registered count on the Pokedex where the checkpoint catches), and the mission state -(the next main mission's banner or objective marker). Write the result in `segments.tsv` and the -run record. - -What counts as a pass: three runs each ending with the engine's verdict `passed` for the -checkpoint (log line per step with its verdict, no `(class=...)` failure line), no hand input, -no error dialog, the postcondition check passed, and the save afterwards reloads at the next -checkpoint's start. 2/3 is a pass only for a battle checkpoint, under the battle rule (Q6). - -Start save per checkpoint (place from each plan's `start`; `-` = the checkpoint has no spot of -its own, the autosave before it is the start). These are the ids after today's renumber; they move -again if the user renumbers once more. - -| Id | Title | Starts from | +| Slice | Checkpoints | Adds | |---|---|---| -| 01.00 | New game from Confirm Choices to the station platform | a new game, set up by hand to the Confirm Choices screen; no save | -| 01.01 | The platform to Main Mission 01 | Lumiose City, the station platform autosave | -| 01.02 | Main Mission 01: chase Pancham to the battle area | Lumiose City autosave after 01.01 | -| 01.03 | Main Mission 01: the starter and Andi | Lumiose City autosave after 01.02 (battle checkpoint) | -| 02.01 | Main Mission 02: Battle Zone to Brigitte | Lumiose City, 01.03's menu save | -| 02.02 | Main Mission 02: after Brigitte to Hotel Z | Lumiose City autosave after Brigitte | -| 02.03 | Main Mission 02: into the Hotel Z lobby | Lumiose City autosave outside Hotel Z | -| 02.04 | Main Mission 02: Hotel Z check-in | the lobby autosave (before the AZ talk) | -| 02.05 | Main Mission 02: Hotel Z elevator to Room 202 | autosave after check-in | -| 02.06 | Main Mission 02: the night in Room 202 | autosave in Room 202 | -| 02.07 | Main Mission 02: the first evening to Main Mission 03 | autosave after the night | -| 03.01 | Down to the lobby | Hotel Z, Room 202 autosave | -| 03.02 | Out of Hotel Z, battle Taunie | Hotel Z lobby autosave (battle checkpoint) | -| 03.03 | Over the rooftops to Station Front | Lumiose City autosave after Taunie | -| 03.04 | Pokemon Center, the Pokedex | Lumiose City, Station Front autosave | -| 03.05 | Heal at the Pokemon Center | Pokemon Center autosave | -| 03.06 | To Wild Zone 1 | the heal's save at the Pokemon Center counter | -| 03.07 | Wild Zone 1: first catches | Wild Zone 1 entry autosave | -| 03.08 | Five species, out of Wild Zone 1 | Wild Zone 1 autosave after 03.07's catches (3/5 registered); no save of its own, so rerunning 03.08 means running 03.07 first (START = 03.07, END = 03.08) | -| 03.09 | From Wild Zone 1's gate into the Research Lab | Lumiose City, the zone's gate autosave | -| 03.10 | Up the Research Lab's elevator to the Director's Office | Pokemon Research Lab autosave | -| 03.11 | Mable's research, the Rock Smash TM | Pokemon Research Lab autosave | - -The "Starts from" column is from the plan files' `start` and the console notes; confirm each on -console during the first verification pass and record the observed autosave spot in the plan's -source note (the 2026-11-13 rule: a checkpoint's start equals where its autosave reloads). - -### 4.3 Checklist for PR descriptions to link - -``` -PLZA AutoStory verification (link: agents:autostory/plza/UPSTREAM_PLAN.md#43-checklist-for-pr-descriptions-to-link) -[ ] Unit tests: PokemonLZA::* and Pokemon::* suites, 0 failures (Fork Draft CI or local run per 4.1) -[ ] Code health: 0 findings, advisory ones included (upstream-bound) -[ ] Console: each checkpoint this PR adds or changes ran 3x in VERIFY mode from its own save -[ ] Each run: engine verdict passed, no hand input, no (class=...) line, no error dialog -[ ] Postconditions checked separately (POSTCONDITIONS_ONLY + screenshot): position, party, mission state -[ ] Save after verification reloads at the next checkpoint's start -[ ] segments.tsv and the run record updated (agents branch), checkpoint ids as renumbered -[ ] No fork-only pins: CommandLineTests is PokemonAutomation's, frames landed upstream -``` - -## 5. Open questions for the user - -**Q1. Split S2 or keep #332 whole?** #332 is 17k lines. Recommendation: run the dependency-closure -build first; if PLZA's closure of #332 + #474 + #477 + #391 is under ~12k lines, one S2; else S2a -(engine over a backend + story data) and S2b (run options, launch from HOME, failure classes). - -**Q2. One PR per Main Mission, or merge M1+M2?** They are ~0.8k and ~0.6k. Recommendation: keep -one per segment as decided on 2026-11-12; the chain is already short and each shows one mission. - -**Q3. Fault sweep upstream?** The sweep is unit-test-only and found two real bugs, but two rows are -known-failing (warp_no_op). Recommendation: upstream it (S3 + the PLZA `FaultSweep_Tests` in M3) -after fixing the two rows, S3 opened after P1 so the first wave is S1, S2, C1. - -**Q4. `BREAKPOINTS` option upstream?** It only pauses in a lab build. Recommendation: leave the -option out of the upstream panel (keep the engine hook; it is small), so users do not see a -setting that does nothing. - -**Q5. Dev-folder override upstream?** `story_dev_folder("plza")` lets the lab replace plan files -without a rebuild. Recommendation: keep the `dev_files` span in the loader (it is the test seam) -but no folder scan in the upstream program; the scan stays on the fork, re-added by the lab branch. - -**Q6. Pass criterion: 3/3 everywhere, or 2/3 for battle checkpoints?** The battle rule -(2026-11-03) allows 2 of 3 for a battle that lost twice; the user's wording today is "3x each". -Recommendation: `PASSES` = 3 for walks and scenes; `PASSES` = 2 for 01.03 (Andi) and 03.02 -(Taunie), and record the loss. - -**Q7. Who opens C1 (CommandLineTests)?** The frames are console captures of the game's screens. -Recommendation: the user opens it, like every upstream PR; an agent prepares the branch on -dayfine/CommandLineTests with the five folders and a file list. +| 2c | 01.03 | starter, TALK, first battle, MissionComplete | +| 3 | Main Mission 02 | | +| 4 | 03.01-03.06 | map, ladder, gate (no fly) | +| throw helper | - | shared PLZA throw helper (own PR) | +| 5 | 03.07-03.11 | catches and objective marker walks | +| later | - | stats (#519), captures, fault sweep | -**Q8. Branch naming of the rebuilt stack.** Recommendation: `plza/upstream/` -on the fork, each fork draft marked ready only when its upstream twin opens, and -`git config branch..upstream-bound true` on each so the pre-push code-health gate blocks. +## Old PRs to close (your call) -**Q9. The old fork PRs.** Recommendation: close #416/#354/#355/#356/#335/#492 with a link to the -rebuilt PR once its tests match the old tip; #418 stays open on the fork, merged onto the new tip. +Still open on 2026-11-15: -**Q10. S0b on S0a, or independent?** `CheckpointId` feeds "Segments Started", which S0a adds. -Recommendation: S0b based on S0a (both small, reviewed back to back); if the user wants them -truly independent, S0b counts segments in its own test only and S1 wires the stat. +- Old shared chain S1/S2: #529-#543 (#544 and #545 are already closed). +- Old PLZA chain: #555-#569. +- Umbrella drafts: #522, #524, #525. +- Older PLZA PRs: #335, #354, #355, #356, #416. -**Q11. Which fork branch is "done" for the verification runs?** The runs of 4.2 happen before the -restructure (next couple of runs) on today's tip, `plza/fault-sweep` 24133e149 or later. -Recommendation: run them on the current tip, record per checkpoint in `segments.tsv`, and carry the -records over as the test notes of P2/P3/M1-M3; a rebuilt branch whose tree equals the tip needs -no rerun, only the unit tests. +Also open, kept for now: #492 (fault sweep, until the fault-sweep slice replaces it) and #418 +(CFR actions, stays on the fork).