aetherbound-guild/docs/runtime/PHASE9_0R9_FIRST_COMPANY_CONTRACT.md

Phase 9.0R9 First Company Runtime Contract

State Map

MAIN_MENU -> FIRST_MISSION
FIRST_MISSION -> FRONT_SELECTION
FRONT_SELECTION -> REAR_SELECTION
REAR_SELECTION -> FORMATION_REVIEW
FORMATION_REVIEW -> FRONT_SELECTION
FORMATION_REVIEW -> REAR_SELECTION
FORMATION_REVIEW -> BATTLE
onboarding Home/confirmed Restart -> MAIN_MENU

These are separate page states. The old YARD state may remain as a historical enum value for regression compatibility, but New Game may not route through its all-at-once four-Recruit dock.

Stable Controls

Page	Required controls
First mission	OpenFrontSelectionButton
Front selection	Front_Hearthguard, Front_Wayrunner, ContinueRearSelectionButton
Rear selection	Rear_Farstring, Rear_Kindhand, ReviewFormationButton
Formation review	ReviseFrontButton, ReviseRearButton, CommitFormationButton

Every page also keeps the existing Home, Restart and sound controls. Continue, Review and Commit are disabled until their required choices exist.

Role Copy Authority

• Hearthguard / shield guard: steady front response; blocks the first heavy hit and finishes with more health than the evasive alternative.
• Wayrunner / runner: evasive front response; avoids part of the strike and counters instead of relying on a shield.
• Farstring / archer: rear damage; fires an early ranged hit that shortens the enemy's remaining health.
• Kindhand / healer: rear recovery; restores the front after the enemy hit.

Copy must describe the visible first-battle behavior without introducing unimplemented stats, percentages, equipment or promotion promises.

Transaction Semantics

• start_new_game clears the previous transient experience once and opens FIRST_MISSION with both choices empty and commit count zero.
• The mission page mutates no Recruit choice.
• Front selection rejects every non-front profession. Rear selection rejects every non-rear profession.
• Selecting another legal profession replaces only that slot.
• Moving forward and backward does not commit or clear valid choices.
• Review has no default action and displays both chosen members.
• Commit is legal only on review with both valid choices and commit count zero.
• One legal commit increments the count once, resets first-battle runtime state and opens the preserved automatic BATTLE; repeats are rejected.
• Home and confirmed Restart run full transient cleanup, including the commit counter, and return to Main Menu.

Formation Review

The review must answer, without requiring stat knowledge:

1. Who stands in front and what response will be visible?
2. Who stands behind and what support will be visible?
3. What happens after commit? Combat runs automatically and tests the line.
4. How can the player change the plan? Revise Front or Revise Rear before committing.

Presentation

• Use the accepted illustrated Guild Yard as the world surface.
• Each selection page shows only its two relevant Recruit choices, large role portraits and one short cause-and-effect explanation.
• Selected state uses a visible gold border/check mark and never depends on color alone.
• Review composes the two selected actors in front/rear spatial order rather than presenting only a text form.
• Primary landscape is 844x390, with no scrolling and 44px minimum actions.
• English at 130% must remain fully visible. Portrait keeps the rotate prompt.

Evidence

• Domain test covers invalid professions, no preselection, replacement, preserved Back behavior, both commit prerequisites, exactly-once commit, all four legal formations and Home/Restart cleanup.
• Parsed-ScreenTouch test covers mission -> front -> rear -> review -> revise -> review -> commit without direct callbacks or fallback interaction.
• Normal-render capture covers mission, both unselected/selected role pages, review, English/130% review and Home/Restart confirmation layout.
• R8 front door and R3-R7 focused regressions remain green.