aetherbound-guild/docs/runtime/p9_1/IMPLEMENTATION_PLAN.md

P9.1 Five-Battle First-Session Implementation Plan

Status: ACTIVE Active step: P9.1-STEP-1 REAL_FORMATION_UI Active source baseline: 8cfbc1460e7c8f4747548c795051f667cdc33fd2 Goal: docs/goals/PHASE9_1_ARBITRARY_PARTY_FIRST_SESSION_GOAL.md Contract: docs/runtime/PHASE9_1_ARBITRARY_PARTY_FIRST_SESSION_CONTRACT.md Evidence ledger: docs/reviews/PHASE9_GODOT_VERTICAL_SLICE_LEDGER.md

1. Player-Visible Stopping Point

P9.1 ends when the owner can open one landscape H5 build and complete this unbroken first session:

Title -> Main Menu -> New Game -> choose any two Recruits
-> automatic formation -> battle 1 -> choose one adaptation
-> battle 2 -> choose one Guild response -> battle 3
-> choose and review one route -> battle 4
-> choose and review one current member for Lv.2 -> battle 5
-> first-session result -> restart or Home

The player must be able to explain who acted, what changed, why each choice was rational, and how the final result followed from the four decisions. P9.1 is not complete merely because the domain matrix or old preview pages pass.

The milestone stops after one owner playthrough and one bounded repair round. It does not continue into chapter production.

2. Current Reality

Complete and pushed

• Front door: Boot, Title, Main Menu, Introduction and Settings.
• Any two of four current Recruits can be selected; the system assigns order.
• Five deterministic battles and four intervening decisions exist in the domain layer.
• Guild addition performs real automatic re-formation.
• Member HP, member levels, battle times, Coin and result identity are tracked by stable member ID.
• The source at 8cfbc14 passes a 180-path matrix across six pairs, two adaptations, two Guild responses, three routes and every current growth candidate. It also preserves the declared P9.0 focused regressions.

Not complete

• Several later pages still render historical front/rear/added slots rather than the current field_order.
• Battle 3-5 animations, health bars, captions and feedback are not yet proven to follow the same real member identity in every re-formed line.
• The five result pages do not yet all use the frozen five-line causal grammar.
• There is no current full-session parsed-touch test from Title through the final result for an exceptional re-formation path.
• There is no current source-bound normal-render matrix or H5 delivery for the completed five-battle flow.
• Human understanding, fun, listening and willingness to continue remain open.

3. Frozen Scope

P9.1 must not add or redesign:

• authoritative combat, difficulty or economy;
• save/load, offline progress, casualty or recovery;
• Market, permanent inventory, promotion or levels above this bounded Lv.2;
• more professions, enemies, equipment, regions or chapters;
• bulk/final art, generated audio, packaging, TestFlight, stores or release.

Findings in these areas go into the issue register or the next milestone. They do not expand the active P9.1 step.

4. Execution Rules

1. Exactly one step below is IN_PROGRESS.
2. Before editing, identify the current step's owned files and acceptance checks. Do not edit a later step's files speculatively.
3. Run focused checks first. Run the declared regression set only after the focused boundary passes.
4. Each completed step gets a focused commit and push. The plan and checkpoint are updated in the same commit only when their status actually changes.
5. A failed check keeps the current step active. Record the earliest boundary in the issue register and repair it before advancing.
6. Do not describe a step as complete until HEAD == upstream, the worktree is clean and no owned Godot process remains.
7. Deployment begins only after Steps 1-4 are complete. Packaging is not part of this plan.

5. Ordered Delivery Plan

Step	Status	Player outcome	Required verification	Commit boundary
P9.1-STEP-0 Domain five-battle foundation	COMPLETE	Every legal party/decision path reaches a truthful final snapshot.	180 paths; exact HP/Coin/time/order/levels/actions; foundation atomicity; P9.0 focused regressions.	Pushed 8cfbc14.
P9.1-STEP-1 Real formation UI	IN_PROGRESS	Guild re-formation immediately and consistently shows the actual lead, second and third members. No actor, health bar, action caption, feedback or training card refers to the wrong person.	Focused FS+KH -> add HG -> HG,FS,KH UI test; standard two-person regression; compile/static checks.	One UI-focused commit and push.
P9.1-STEP-2 Decision and result comprehension	PENDING	Adaptation, Guild, route and growth pages open unselected, show exact gain/cost/foregone state, and all five results use outcome/cause/difference/change/next-action order in Chinese and English.	Copy/state contract test; invalid/disabled states; zh_CN/en at 100% and 130%; no overflow at 844x390.	One comprehension-focused commit and push.
P9.1-STEP-3 Battle readability and continuity	PENDING	Battles 1-5 visibly show approach, pressure, each profession's one action, damage/heal numbers, defeat and victory without identity swaps or dead time.	Event-to-animation/VFX binding test; reduced-motion/mute/low-power invariance; fixed normal-render interaction recording.	One battle-presentation commit and push.
P9.1-STEP-4 Full first-session runtime gate	PENDING	A player can use real touch from Title to final result and restart without hidden helper calls.	Parsed ScreenTouch/ScreenDrag; five profiles and decision timestamps; 844x390 plus reference/large layouts; strict log scan; representative captures.	One verification/repair commit and push if product code changes.
P9.1-STEP-5 H5 owner delivery	PENDING	The exact accepted source is available through one stable landscape mobile URL. Refresh starts cleanly and Restart is visible.	Runtime-only Web export; local browser launch; remote bytes/MIME/CSP; phone viewport; no browser errors.	Delivery record commit only; Web build remains ignored.
P9.1-STEP-6 Owner play and bounded repair	PENDING	Owner completes one uncoached first session and reports whether formation, decisions, battles and result are understandable and worth continuing.	Owner observations; one ranked repair batch; rerun affected Step 4 checks; republish only if code changed.	Final P9.1 closure commit and push.

6. Current Step Contract

P9.1-STEP-1 REAL_FORMATION_UI

Current owned product file:

runtime/compat/p9_0_root_facade.gd

Allowed new focused tests:

runtime/tests/p9_1/real_formation_ui_test.gd

Required behavior:

• Farstring + Kindhand, followed by Guild addition of Hearthguard, previews and renders Hearthguard -> Farstring -> Kindhand.
• The UI states that Hearthguard becomes the lead while the original pair keeps relative order.
• Battle 3-5 actors, health bars, number feedback and role animations resolve by actual member ID and current field position.
• Route, growth and result pages show current order and origin. Historical button node names may remain as compatibility keys but must not determine member identity.
• Existing standard pair behavior and touch targets remain available.

Step 1 is complete only when the focused re-formation test and affected P9.0 regressions pass, the diff is reviewed, the commit is pushed and the worktree is clean.

7. Known Issue Register

ID	Status	Boundary	Disposition
P91-I01	ACTIVE	Later UI can display stale historical slots after Guild re-formation.	Owned by Step 1.
P91-I02	OPEN	Later decision/result copy still uses legacy front/rear language and incomplete causal grammar.	Step 2.
P91-I03	OPEN	No complete Title-to-final parsed-touch path on the new five-battle domain.	Step 4.
P91-I04	OPEN	Godot 4.6.1 Dummy-audio touch runs can intermittently emit exit-only ObjectDB cleanup warnings while functional markers pass; audio lifecycle focused test passes.	Do not loosen strict scans or rewrite product audio inside Step 1. Isolate and resolve before the Step 4 candidate claim.
P91-I05	OPEN	Existing Web payload is large and cold loading is slow.	Step 5 delivery optimization only; it must not change gameplay.

8. P9.1 Completion Checklist

P9.1 may be closed only when all are true:

• Steps 0-6 are COMPLETE.
• One exact pushed source revision owns the latest H5 delivery.
• The first session is playable from Title through final result and Restart.
• No visible party member, action, HP, level, reward or result contradicts the domain snapshot.
• Automated, runtime, agent visual and machine audio evidence are reported at their actual levels.
• Owner understanding/fun/listening are recorded only from owner evidence.
• The repository is clean/upstream and no owned process remains.

Anything beyond this checklist begins a new milestone plan rather than silently extending P9.1.

9. Next Milestones After P9.1

These are sequencing notes, not current authorization:

• P9.2: one owner-driven comprehension/feel repair milestone if more than the bounded Step 6 batch is required.
• P9.3: authoritative combat, failure/recovery and persistence vertical slice.
• P9.4: scalable profession/enemy/equipment authoring and chapter production.
• P9.5: final presentation, device performance, packaging and release gates.