Document Phase B execution framework

docs/PROJECT-STRUCTURE.md

@@ -67,6 +67,7 @@ S:\Game Hacking\Eushully\Himegari\           ← workspace root (three siblings)
     │   ├── global-memory-re.md                 runtime global observation RE (SHELVED; future starting point)
     │   ├── remake-architecture-and-roadmap.md  THE direction doc (phases A–E)
     │   ├── phase-a-slice-plan.md               the current slice (A0/A1/A2)
+    │   ├── phase-b-framework.md                natural boot/menu/session → first-gameplay framework
     │   ├── platform-portability.md             OS dependencies + future cross-platform readiness
     │   ├── vm-mapping-plan.md                  the phased decode plan
     │   ├── himegari-port-reference.md          master reference + engine background

docs/phase-b-framework.md

@@ -0,0 +1,202 @@
+# Phase B Framework — Natural Boot to First Gameplay
+
+Phase B broadens the proven ADV vertical slice into a naturally booted, stateful play session and then into
+the first narrow gameplay loop. This document is a sequencing framework, not a task-level implementation
+plan. Phase A remains active until SC0000 meets its completion criteria.
+
+The architectural preference is:
+
+```
+complete SC0000
+  -> persistent session and scene coordinator
+  -> faithful system/data boot
+  -> title and New Game happy path
+  -> SC0000 under naturally initialized state
+  -> natural first-dungeon transition
+  -> bounded first-dungeon gameplay slice
+```
+
+This order makes gameplay failures attributable to gameplay rather than to missing boot state, discarded
+globals, or manually inherited host state.
+
+## Entry criteria from Phase A
+
+Phase B may begin when SC0000 is a reliable presentation baseline:
+
+- A normal windowed playthrough is visually and audibly coherent from entry to natural exit.
+- Reproducible presentation inconsistencies have been resolved or explicitly classified with evidence.
+- Every SC0000-executed effectful opcode is implemented, or its lack of a host-visible effect is supported
+  by native/script evidence. Remaining unrelated corpus gaps do not block entry.
+- The run no longer relies on unexplained timing, input, layer, or resource workarounds.
+- Automated VM/host regressions and a repeatable manual playthrough form the acceptance baseline.
+- SC0000's terminal global state and control-flow boundary can be captured for comparison once natural
+  scene chaining exists.
+
+The Phase A implementation/result history remains in `docs/phase-a-slice-plan.md`.
+
+## Principles
+
+1. **State correctness before systems breadth.** Dungeon logic depends on initialized unit, item, skill,
+   progression, configuration, and heroine state. Establish their natural producers before debugging their
+   consumers.
+2. **Follow script control flow.** The bytecode owns game rules. Implement the effectful operations and
+   lifecycle services it calls; do not replace dungeon/combat logic with a parallel rules engine.
+3. **One natural path first.** Boot → title → New Game → SC0000 → first dungeon is the initial spine.
+   Alternate menu branches and broad gameplay coverage grow from it later.
+4. **Persistent session, replaceable scenes.** Globals and game/profile state survive scene changes while
+   script frames, retained presentation state, and scene-owned resources observe proven lifecycle rules.
+5. **Demand-driven opcode work.** Investigate an unknown opcode when the chosen path executes it or evidence
+   connects it to a reproduced defect.
+6. **Bound every slice by an observable transition.** Each stage starts from a known state and ends at a
+   visible screen, input boundary, scene handoff, or gameplay action.
+
+## Stage B0 — Ground-truth reconnaissance
+
+Before changing runtime architecture, record the original game's path from process start through the first
+meaningful dungeon interaction. The goal is an answer key, not exhaustive reverse engineering.
+
+Capture:
+
+- Script/load order across system boot, title, New Game, SC0000, and first dungeon entry.
+- Which initialization scripts run and which global banks or native/profile values they establish.
+- Retained graphics/audio state that survives each boundary.
+- The title selection and New Game dispatch path.
+- SC0000's natural terminal decision and the corresponding next loaded script.
+- The first dungeon's executed opcode/call-script families, assets, and obvious state dependencies.
+
+Detailed progression semantics remain canonical in `docs/scjump-progression.md`; native loader findings
+belong in `docs/engine-re.md` and `docs/name-resolution.md`.
+
+## Stage B1 — Persistent session and scene coordinator
+
+Replace the single-root-scene assumption with an application-owned session that can run one script scene,
+observe its terminal request, and start the next without discarding persistent state.
+
+Required responsibilities:
+
+- Own global integer/string banks and any proven external/profile state across scenes.
+- Distinguish nested `call-script` frames from top-level scene replacement.
+- Define scene-owned versus session-owned host state and tear each down at the correct boundary.
+- Preserve intentional system-owned surfaces, configuration, and audio while releasing scene-local state.
+- Expose deterministic transition evidence: outgoing scene, reason/decision, incoming scene, and state
+  summary suitable for tests.
+
+Completion evidence: a synthetic or small real sequence transitions between two top-level scripts while
+preserving selected globals and correctly releasing scene-local presentation state.
+
+## Stage B2 — Faithful full boot
+
+Replace `--boot`'s diagnostic seeding and separately injected inherited surfaces with normal boot execution.
+First prove the installed game's actual ordering; do not assume the current helper lists are complete.
+
+The boot path must cover two existing categories:
+
+- System/session initialization currently approximated by `INITCONFIG`, `INIT2`, and `INIT`, including
+  host-visible side effects that `CaptureHost` discards.
+- Game-data initialization represented by the `*INIT` family used by the headless boot/session tools.
+
+Completion evidence:
+
+- A fresh application reaches the same initial title state without `--boot`, `--seed`, or manual surface
+  injection.
+- Required globals come from executed scripts or clearly identified profile/native defaults.
+- Inherited retained state has a traceable owner and lifecycle.
+- A boot snapshot is reproducible for tests, but the shipped path performs the real boot rather than loading
+  a developer snapshot.
+
+This stage may reveal platform/install-selection work; track that separately in
+`docs/platform-portability.md` rather than folding cross-platform export into Phase B.
+
+## Stage B3 — Title and New Game happy path
+
+Implement only enough menu behavior to choose New Game naturally and enter the story. This is primarily a
+state-initialization and dispatch slice, not a mandate to complete every submenu.
+
+In scope:
+
+- Title/main-menu presentation required by the executed path.
+- Keyboard/mouse selection and the menu-specific coroutine/hotspot forms actually reached.
+- Configuration defaults that affect New Game or the subsequent runtime.
+- New Game initialization and its transition request.
+- Natural empty-save-state behavior when no saves exist.
+
+Deferred to bounded follow-ups unless the happy path requires them:
+
+- Full configuration UI and every setting.
+- Load/save implementation and save-format reversal.
+- Extras, galleries, replay modes, and unrelated submenus.
+- Menu visual polish that does not obstruct correct selection or state production.
+
+Completion evidence: launching the application, selecting New Game, and reaching SC0000 with no manual
+state seeds. The resulting SC0000 opening state must match the Phase A visual/audio baseline.
+
+## Stage B4 — Natural progression through SC0000
+
+Run the completed scene inside the persistent session and honor its real terminal transition. This stage
+closes the currently unidentified decision-to-scene boundary described in `docs/scjump-progression.md`.
+
+Completion evidence:
+
+- Title/New Game reaches SC0000 through actual script/native dispatch.
+- SC0000 completes without the developer auto-advance harness.
+- The outgoing decision, selected next script, and persistent global changes agree with the original run.
+- The first dungeon scene starts without reconstructing the VM or reseeding state.
+
+## Stage B5 — First-dungeon vertical slice
+
+Do not scope “gameplay” as maps + units + items + magic + combat + AI + win/loss all at once. After B0
+identifies the first real interaction, select the smallest end-to-end loop that exercises authoritative
+script state. A likely target is:
+
+- Load and render the first map and its initial UI.
+- Populate the units required for the opening state.
+- Select one unit and display its relevant state.
+- Perform one legal move or scripted action.
+- Resolve one combat or event interaction if the natural opening reaches one.
+- End one player action/turn and return to a stable input boundary.
+
+The exact acceptance path must follow the installed game's first dungeon rather than forcing this example
+shape. Items, skills, magic, AI, win/loss, deployment, and progression are added only as the selected path
+requires them.
+
+Completion evidence combines original-game observation, executed-opcode/call traces, visible map/UI output,
+and before/after global-state comparisons for the action.
+
+## Later Phase B breadth
+
+Once the natural spine and first gameplay loop are trustworthy, broaden in independent tracks:
+
+- Remaining title/configuration/load/save branches.
+- Save-file format and restoration of a persistent session.
+- Map navigation, camera, terrain, deployment, and turn lifecycle.
+- Unit statistics, equipment, inventory, skills, magic, heroine forms, and progression.
+- Combat resolution presentation, enemy turns/AI services, and win/loss transitions.
+- A full chapter of ADV and the scene types encountered between gameplay segments.
+- `STINIT` and other data schemas when their runtime consumers make them necessary.
+
+The high-level Phase B direction remains canonical in `docs/remake-architecture-and-roadmap.md`; this file
+only provides the execution framework.
+
+## Slice record template
+
+When a stage becomes active, add its concrete plan/results to this document or the then-current slice plan
+without pre-planning all later systems. Record:
+
+- Starting state and exact reproduction path.
+- One observable end condition.
+- Executed unknown/effectful opcode families.
+- Required global/profile/host state and its producer.
+- Native/original evidence to capture.
+- Explicit non-goals.
+- Automated regression gates and manual acceptance check.
+- Result, remaining discrepancies, and the next decision gate.
+
+## Decision gates
+
+- After B0: confirm or revise the boot/title/SC0000/dungeon sequence using observed load order.
+- After B2: decide whether session state is trustworthy enough to remove the diagnostic boot path from
+  ordinary runs.
+- After B3: choose whether save/config work blocks natural SC0000 entry; otherwise defer it.
+- After B4: use the actual first-dungeon trace to write the concrete B5 slice rather than guessing its
+  systems in advance.
+- After B5: choose breadth based on the next natural blocker, not opcode coverage percentage alone.

docs/remake-architecture-and-roadmap.md

@@ -138,6 +138,8 @@ Forces, and thereby de-risks, every core unknown at once:
 - Treat the classified no-op markers as skips; validate the tentative-no-op ops via the dialogue diff.
 
 ### Phase B — Broaden coverage (playable ADV, then systems)
+Execution order and decision gates are tracked in `docs/phase-b-framework.md`; Phase A completion remains
+the entry condition.
 - Implement the remaining effectful ops; Frida sessions for the opaque ones (the shortlist in
   `build/opcode-coverage.md`); Unicorn for `0x215`-style computational ops.
 - Grow the **global-var map** (side-task 2.5: `*MES` writers → record-table readers → Frida field