aetherbound-guild/docs/plans/M37_READINESS_PAGE_VIEW_REFACTOR.md

# M37 Readiness Page View Refactor

## Status

- Plan: `M37_READINESS_PAGE_VIEW_REFACTOR`
- Status: `COMPLETE`
- Activated: 2026-08-25
- Baseline: `deb0707` (`M36_RISK_COMMITMENT_PAGE_VIEW_REFACTOR_COMPLETE`)
- Owner authorization: the Owner asked to continue decomposing the Entry
  pages into the layered Passive View + Presenter/ViewData +
  Domain/Application Service architecture. Readiness is the next bounded
  extraction in the M36 handoff map.

## Objective

Extract the PTY-002 Readiness Review page from `entry_shell.gd` into a
passive, UI-only `ABGReadinessPageView` while preserving the accepted custom
16:9 composition, static master artwork, complete four-member formation,
coverage/warning/receipt facts, command eligibility, focus order, touch
surfaces, localization and normal `100%` visual output.

This is a structural View migration, not a Formation, Risk, Battle, Economy,
Save or visual redesign.

## Target boundary

```text
EntryShell / composition root
  -> ReadinessPageController.snapshot()
  -> presentation-ready ViewData
  -> ABGReadinessPageView.render(ViewData)
  -> explicit View intents
  -> EntryShell application command boundary
  -> existing readiness/party/risk/settings commands
```

### Ownership rules

1. `ABGReadinessPageView` owns only Godot nodes, normalized layout, focus,
   local text/portrait presentation and intent emission.
2. The View does not import or call FormationRiskService, Save, the
   compatibility facade, RuntimeContentRegistry, `current_screen` or
   EntryShell globals.
3. `ABGReadinessPageController` remains the authority for copied Company,
   Contract, Formation, ordered Recruit, warning, receipt and command facts.
4. EntryShell remains the composition root and translates only explicit
   `settings`, `review_member`, `review_warnings`, `revise`, `back`, `accept`
   and `risk` intents through deferred connections.
5. FormationRiskService remains the only order/readiness transaction and
   persistence authority. Party, Risk, Battle, Save and route semantics stay
   unchanged.

## Player-visible stopping point

- The player sees the same PTY-002 parchment/master frame, frozen Company and
  Contract header, four positioned Recruit portraits, relation cord/effects,
  coverage band, warning rows, knockout/receipt facts and command rail as the
  M22-accepted page.
- Member and warning review actions update the existing local notice without
  changing saved formation facts.
- `Revise` returns to Party Line; `Back` returns to Guild; `Accept` records the
  existing idempotent readiness receipt and stays on Readiness; `Risk` opens
  the existing Risk Board only when the controller says it is eligible.
- Settings opens through the existing caller context. Invalid controller data
  renders the existing invalid-state boundary.

## Ordered steps

### M37-A — Architecture contract and inventory (`COMPLETE`)

- Freeze the PTY-002 stopping point, dependency direction and forbidden
  imports before product code changes.
- Inventory the existing normalized canvas, static master, `PartyLineTrack`
  z-order, UI-only formatting helpers, exact semantic node names and the
  seven-intent command boundary.
- Record the M22 normal-capture equivalence target at
  `760x360`/`zh_CN`, `844x390`/`en`, `1280x720`/`zh_CN` and
  `1280x720`/`en`.
- Commit and push this activation boundary before Runtime product changes.

Closure: source `8fc239f` activates this plan and freezes the PTY-002
composition, dependency direction, exact node/layer contract, seven-intent
boundary and M22 normal-capture equivalence target.

### M37-B — Passive View extraction (`COMPLETE`)

- Add `ABGReadinessPageView` under `runtime/entry/views/`.
- Reuse `ABGPageView` and `ABGPageContext` while retaining the custom 16:9
  normalized canvas, static master, portrait mapping and PartyLineTrack
  layer semantics.
- Preserve every accepted Readiness node name and command hit area.
- Mount the View from EntryShell and translate only the seven explicit
  intents.
- Remove only the Readiness UI builder/helpers from EntryShell; keep all
  service/controller/application commands intact.

Closure: source `a83963f` adds `ABGReadinessPageView`, mounts it from EntryShell
with deferred seven-intent translation, removes the former Readiness UI
builder/helpers and adds the isolated View contract test. Existing Readiness
behavior passes, and the four normal Readiness fixtures are pixel-equivalent
to the M22 baseline.

### M37-C — Focused verification (`COMPLETE`)

- Add `ABG_M37_READINESS_VIEW_CONTRACT_OK`.
- Run the focused Readiness controller/View and DEV-4/M22 route regressions,
  DEV-4 candidate and full MVP first-cycle audit through the owned
  test-attempt runner with strict diagnostics and exact-once markers.
- Compare normal Readiness captures with the M22 baseline at the four required
  fixtures/locales.

Closure: source `7da8d05` passes the source-bound View contract, Readiness and
route regressions, DEV-4 candidate, four-fixture normal capture set and full
MVP audit. All required markers are exact-once with strict diagnostics `0`,
and the four Readiness captures are byte-equivalent to the M22 baseline. Full
evidence is recorded in
`docs/runtime/M37_READINESS_PAGE_VIEW_VISUAL_AUDIT.md`.

### M37-D — Handoff (`COMPLETE`)

- Record source-bound evidence and visual equivalence in
  `docs/runtime/M37_READINESS_PAGE_VIEW_VISUAL_AUDIT.md`.
- Close only Readiness; Party Line, Risk Board, Battle and later Views remain
  outside this plan.
- Update the checkpoint and development ledger, then push the focused closure.

Closure: source `6c9259b` records the source-bound audit, exact marker
evidence and four-fixture byte-equivalence handoff. M37 closes only Readiness
Review; no downstream page or gameplay scope is implied.

## Frozen scope

- No Formation/Risk/Battle/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_M37_READINESS_VIEW_CONTRACT_OK` exactly once.
- Existing `ABG_M22_READINESS_CONTROLLER_OK`, `ABG_DEV4_READY_OK`, DEV-4
  candidate and `ABG_MVP_FIRST_CYCLE_AUDIT_OK` remain green.
- Extracted View has no forbidden service/content/route imports and emits only
  the seven explicit intents.
- Readiness normal `100%` captures remain visually equivalent to the M22
  baseline at all four required fixtures/locales.
- Focused source is committed, pushed and tracked files are clean.

## Commit boundaries

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

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

## Final handoff

`ABG M37 READINESS VIEW PILOT COMPLETE`

M37 is closed. Any later View migration requires a separately activated plan.