Files
aetherbound-guild/docs/plans/M28_KNOCKOUT_REVIEW_CONTROLLER_PILOT.md
T

7.4 KiB

M28 Knockout Review Controller Pilot

Status

  • Plan: M28_KNOCKOUT_REVIEW_CONTROLLER_PILOT
  • Status: COMPLETE
  • Activated: 2026-08-25
  • Baseline: aa8d63b (M27_BATTLE_RESULT_CONTROLLER_PILOT_COMPLETE)
  • Owner authorization: the Owner requested autonomous continuation toward the MVP after the M27 Result Controller closure.

Objective

Move the OUT-002 Knockout Review view-data boundary onto an explicit, UI-independent controller while preserving battle-local knockout identity, same-Company return semantics, reward/recovery continuation and the existing acknowledgement route. This is a structural Controller/View migration, not a knockout, reward or recovery policy change.

Player/System Stopping Point

  • Knockout Review opens only from the settled Battle Result and keeps the same affected Recruit identity, Profession, Trait, level, XP and equipment facts;
  • the controller owns copied Company/Contract facts, settled Battle/result identity, knockout identities, battle-local/return rules, reward-draft status and acknowledgement target eligibility;
  • the existing OUT-002 View keeps its accepted composition, node names, hit areas, focus order, localization helpers, tooltips and callbacks;
  • BattleService remains the only authority for settlement, reward, recovery and persistence; acknowledgement remains a route decision and does not mutate Company;
  • no accepted page, route, visual, input, economy, Save or Battle rule changes.

Architecture Contract

BattleService settled Company/Battle snapshot
  -> KnockoutReviewPageController (view-data assembly)
  -> KnockoutReviewViewData (deep-copied snapshot)
  -> Existing Godot OUT-002 View composition
  -> Existing acknowledgement route to OUT-003 or OUT-004

The controller receives Company, settled Battle/result, optional notice and locale facts. It validates the settled-result and knockout identity boundary, deep-copies returned facts and exposes only view state and command eligibility. It never loads, saves or mutates persistence and never accesses Godot nodes, current_screen, facade or Entry Shell globals. It does not duplicate settlement, reward, recovery or route rules.

Ordered Steps

M28-A — Plan and boundary (COMPLETE)

  • Record the OUT-002 stopping point, invariants and forbidden scope.
  • Inventory settled Battle/result, knockout identity, reward-pending and acknowledgement branches before product code.
  • Commit and push this activation boundary before Knockout Review product code.

Closure: the plan/checkpoint activation is pushed at source 8b81de7. The settled-result, knockout identity, battle-local return and reward/recovery continuation invariants are now frozen for the additive controller step.

M28-B — Additive controller (COMPLETE)

Add runtime/entry/knockout_review_page_controller.gd and a focused test covering:

  • missing/invalid Company, settled Battle/result and knockout boundaries;
  • copied knockout Recruit identity/facts and battle-local return semantics;
  • reward-draft open/closed/absent classification;
  • acknowledgement target eligibility (battle_reward_choice or battle_recovery);
  • deep-copy isolation and duplicate/unknown knockout rejection.

Closure: source a7d7d05 adds ABGKnockoutReviewPageController and the focused ABG_M28_KNOCKOUT_REVIEW_CONTROLLER_OK test. The controller validates the settled Battle/result and one matching settlement receipt, copies Company, Contract, Battle, knockout Recruit identities, battle-local gap/return facts and reward-draft status, and exposes acknowledgement targets without Godot nodes, persistence or BattleService transaction dependencies. The source-bound focused attempt is /private/tmp/aetherbound-guild-test-evidence/m28-knockout-review-controller-focused/20260825T110121Z-11067; the marker appears exactly once, strict diagnostics are 0, and the owned workspace/process cleanup passes.

M28-C — View integration (COMPLETE)

  • Inject one controller through Entry Shell/AppServices.
  • Make OUT-002 rendering and acknowledgement target consume controller output.
  • Preserve the accepted composition, node names, focus, touch targets, localization and callbacks.
  • Keep all BattleService settlement/reward/recovery calls unchanged.

Closure: source 0171a7f injects ABGKnockoutReviewPageController through Entry Shell/AppServices, refreshes copied BattleKnockoutViewData at the OUT-002 entry boundary and makes the accepted Knockout Review Recruit facts, battle-local gap and acknowledgement target consume controller-owned data. Existing OUT-002 composition, node names, focus, touch targets, localization, callbacks and BattleService calls remain unchanged. The focused Result/ Knockout/Recovery route assertions pass.

M28-D — Verification and handoff (COMPLETE)

  • Run focused controller, Result, Knockout, Reward, Recovery, BAT-002, BAT-003/004, Risk Commitment, Risk, Readiness, Party, Guild, Market and Hire regressions.
  • Run normal 100% Knockout Review captures at the required landscape fixtures.
  • Run the full MVP first-cycle audit and require strict diagnostics 0.
  • Close with a focused pushed commit and update the checkpoint.

Closure: source-bound verification closes at 3e573d8. The focused controller attempt /private/tmp/aetherbound-guild-test-evidence/m28-knockout-review-controller-source-bound/20260825T110651Z-16277 passes ABG_M28_KNOCKOUT_REVIEW_CONTROLLER_OK exactly once with strict diagnostics 0. The final DEV-5 candidate attempt /private/tmp/aetherbound-guild-test-evidence/m28-knockout-review-candidate-final/20260825T110706Z-16573 passes ABG_DEV5_CANDIDATE_SUITE_OK exactly once with strict diagnostics 0, 24 normal capture frames and owned workspace/process cleanup. The full first-cycle audit /private/tmp/aetherbound-guild-test-evidence/m28-mvp-audit/20260825T110840Z-18171 passes ABG_MVP_FIRST_CYCLE_AUDIT_OK exactly once with 180 evidence files, 128 normal 100% frames across zh_CN/en and 760x360, 844x390, 1280x720, strict diagnostics 0, parsed touch coverage, restart-to-Market and owned workspace/process cleanup. M28 closes without changing accepted OUT-002 composition, knockout/reward/recovery semantics or any frozen neighboring page.

Frozen Scope

  • No visual redesign or new assets/audio/animation.
  • No changes to settlement, reward, recovery, battle receipts, BattleService, Risk Commitment, FormationRiskService, Company, Contract, Save or economy semantics.
  • No migration of Reward Choice or Recovery pages in this plan.
  • No new knockout, reward, recovery or automatic-route policy.
  • No mass rewrite or deletion of compatibility/history files.
  • No packaging, signing, store or release work.

Acceptance Checks

  • ABG_M28_KNOCKOUT_REVIEW_CONTROLLER_OK exactly once.
  • Existing ABG_DEV5_RESULT_OK, ABG_DEV5_RECOVERY_OK, BAT-002, BAT-003/004, Risk Commitment, Risk, Readiness, Party, Guild, Market and Hire markers remain green.
  • Normal 100% Knockout Review captures, stable Recruit identity, explicit acknowledgement and reward/recovery continuation remain green.
  • ABG_MVP_FIRST_CYCLE_AUDIT_OK remains green.

Commit Boundaries

  • M28-A: plan/checkpoint activation.
  • M28-B: controller and focused unit test.
  • M28-C: Entry Shell integration.
  • M28-D: evidence and closure.

Each boundary must pass its narrowest focused verification and be pushed before the next step becomes IN_PROGRESS; a failed check keeps the current step active.

Final Handoff

ABG M28 KNOCKOUT REVIEW CONTROLLER MIGRATION READY