aetherbound-guild/docs/plans/M34_KNOCKOUT_REVIEW_PAGE_VIEW_REFACTOR.md

M34 Knockout Review Page View Refactor

Status

• Plan: M34_KNOCKOUT_REVIEW_PAGE_VIEW_REFACTOR
• Status: COMPLETE
• Activated: 2026-08-25
• Baseline: f609464 (M33_REWARD_CHOICE_PAGE_VIEW_REFACTOR_COMPLETE)
• Owner authorization: the Owner asked to continue splitting page Views after the M33 Reward Choice pilot. This plan is the next bounded extraction in the ordered M33 handoff map.

Objective

Extract the OUT-002 Knockout Review page from entry_shell.gd into a passive, UI-only ABGKnockoutReviewPageView while preserving the M28-accepted settled result identity, battle-local knockout explanation, Recruit portrait and identity text, Back/Acknowledge controls, focus order, touch targets, localization, and Reward Choice/Recovery continuation.

This is a structural View migration, not a battle, result, reward, economy, Save or visual redesign.

Target boundary

EntryShell / composition root
  -> KnockoutReviewPageController.snapshot()
  -> presentation-enriched ViewData
  -> ABGKnockoutReviewPageView.render(ViewData)
  -> explicit back / acknowledge intents
  -> EntryShell application command boundary
  -> show_battle_result(...) / show_battle_reward_choice(...) /
     show_battle_recovery(...)

Ownership rules

1. ABGKnockoutReviewPageView owns only Godot nodes, layout, focus, local text/portrait presentation and intent emission.
2. The View does not import or call BattleService, Save, the compatibility facade, RuntimeContentRegistry, current_screen or EntryShell globals.
3. The View may use the existing UI-only InitialCompanyArt.texture_for() for the supplied copied Recruit facts; all identity/content values are read from the copied snapshot/presentation data and no service lookup occurs.
4. ABGKnockoutReviewPageController remains the authority for copied settled result, knockout identity, battle-local gap, receipt and acknowledgement target facts.
5. EntryShell remains the composition root and translates back and acknowledge intents through deferred connections. Battle/Reward/Recovery services and route semantics remain unchanged.

Player-visible stopping point

• The player sees the same Knockout Review frame, heading, receipt status, member portrait/name/Profession/Trait/level/XP/equipment details, current battle gap, return rule and footer controls as the M28-accepted page.
• Back still returns to the settled Result page.
• Acknowledge still routes to Reward Choice when a reward draft is open and to Recovery when it is closed.
• A controller-invalid snapshot still renders the existing invalid-state message without introducing a fallback route.

Ordered steps

M34-A — Architecture contract and inventory (COMPLETE)

• Freeze the Knockout Review stopping point, dependency direction and forbidden imports before product code changes.
• Inventory the current OUT-002 composition, _readiness_member() portrait treatment, identity/content text paths and Back/Acknowledge command boundary.
• Record the M28 normal-capture equivalence target and exact node names.
• Commit and push this activation boundary before Runtime product changes.

M34-B — Passive View extraction (COMPLETE)

• Add ABGKnockoutReviewPageView under runtime/entry/views/.
• Reuse ABGPageView and ABGPageContext from M32/M33.
• Preserve the existing node names and normal 100% layout, including the ReadinessPosition* member presentation and InitialCompanyArt portraits.
• Mount the View from EntryShell, pass a copied snapshot plus presentation values, and translate only back and acknowledge intents.
• Keep controller, BattleService, receipt and continuation semantics unchanged.
• Complete at source 7a4c1ca; the source-bound documentation update is recorded at d6208d8.

M34-C — Focused verification (COMPLETE)

• Add ABG_M34_KNOCKOUT_REVIEW_VIEW_CONTRACT_OK.
• Run the focused Knockout controller/View and M12/M28/M29/M30 route regressions.
• Run the DEV-5 candidate and full MVP first-cycle audit through the owned test-attempt runner with strict diagnostics and exact-once markers.
• Compare normal Knockout Review captures with the M28 baseline at the four required fixtures/locales.
• Complete at source 4c7a0ac; evidence is recorded in docs/runtime/M34_KNOCKOUT_REVIEW_PAGE_VIEW_VISUAL_AUDIT.md.

M34-D — Handoff (COMPLETE)

• Record source-bound evidence and visual equivalence in a runtime audit.
• Close only Knockout Review; do not claim Battle Result, Risk, Market or live Battle Views are migrated.
• Leave the next extraction as a separately activated plan.
• Complete at source 5b811fb; the final durable status closure is recorded in the subsequent docs-only closure commit.

Next extraction map

1. M35 Battle Result View — causal/result presentation after the Knockout command rail is proven.
2. M36 Risk Commitment and Readiness Views — reuse the explicit command rail after another passive result View.
3. M37 Party Line and Risk Board Views — selection-heavy preparation pages.
4. M38 Market, Recruit Review, Contract Choice and Guild Views — larger content and route/context surfaces.
5. M39 Battle Opening and Live Battle Views — defer lifecycle/timeline coupling until the passive View boundary is mature.

Each item requires its own durable activation plan, focused equivalence check and pushed commit. No project-wide binding/event-bus layer is introduced by this handoff.

Frozen scope

• No battle/result/reward/recovery/economy/Save semantic changes.
• No visual redesign, asset generation, localization rewrite or 130% scope.
• No mass rewrite of entry_shell.gd.
• No deletion of compatibility/history files, .uid, .import or prototype_incremental/.
• No packaging, iOS export, signing, deployment, store or release work.

Acceptance checks

• ABG_M34_KNOCKOUT_REVIEW_VIEW_CONTRACT_OK exactly once.
• Existing ABG_M28_KNOCKOUT_REVIEW_CONTROLLER_OK, M12/DEV-5 candidate and ABG_MVP_FIRST_CYCLE_AUDIT_OK remain green.
• Extracted View has no forbidden service/content/route imports and emits only back/acknowledge intents.
• Knockout Review normal 100% captures remain visually equivalent to the M28 baseline at required fixtures and locales.
• Focused source is committed, pushed and tracked files are clean.

Commit boundaries

• M34-A: plan/checkpoint activation.
• M34-B: View and EntryShell integration.
• M34-C: focused verification/evidence.
• M34-D: handoff/closure.

Final handoff

ABG M34 KNOCKOUT REVIEW VIEW PILOT COMPLETE

M34 is closed. No M35 plan is active; the next extraction requires a new Owner-authorized durable plan.