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

7.6 KiB

M40 Recruit Review Page View Refactor

Status

  • Plan: M40_RECRUIT_REVIEW_PAGE_VIEW_REFACTOR
  • Status: COMPLETE
  • Activated: 2026-08-25
  • Baseline: bd2bf45 (M39_PARTY_LINE_PAGE_VIEW_REFACTOR_COMPLETE)
  • Owner authorization: the Owner asked to continue decomposing Entry pages into the layered Passive View + Presenter/ViewData + Domain/Application Service architecture. Recruit Review is the next bounded extraction from the M32 handoff map, before the larger Market surface.

Objective

Extract the accepted SHP-002 Recruit Review page from entry_shell.gd into a passive, UI-only ABGRecruitReviewPageView while preserving the portrait-led hand-drawn composition, static master, stable offer identity, generated Profession/Trait/attribute/item/history facts, Company/Line impact, price, Hire eligibility, Cancel return-to-same-offer behavior, Settings hit area and normal 100% output.

This is a structural View migration, not a hire/economy, Market, Save, localization or visual redesign.

Target boundary

EntryShell / composition root
  -> RecruitReviewPageController.snapshot()
  -> presentation-ready ViewData
  -> ABGRecruitReviewPageView.render(ViewData)
  -> explicit View intents
  -> EntryShell application command boundary
  -> existing Cancel / Hire / Settings commands

Ownership rules

  1. ABGRecruitReviewPageView owns only Godot nodes, the static master, portrait/detail presentation, focus and explicit intent emission. It may retain an invisible RecruitReviewSettings hit target required by the approved SHP-002 hit-area contract; it must not add visible chrome or alter the accepted normal captures.
  2. The View does not import or call GuildContractService, Save, RuntimeContentRegistry, the compatibility facade, current_screen or EntryShell globals.
  3. ABGRecruitReviewPageController remains the authority for copied offer, stable identity, facts, availability, impact, price and Hire eligibility.
  4. EntryShell remains the composition root and translates only deferred cancel, hire and settings intents through the existing application commands.
  5. GuildContractService remains the only Hire transaction/receipt authority; Cancel keeps the same source_offer_id and Market focus restoration.

Player-visible stopping point

  • The player sees the same SHP-002 static field, portrait/identity, ledger facts, Company impact, price and command rail as the M18-accepted page.
  • Cancel returns to Market with the same offer selected and focused.
  • Hire is enabled only when the controller says the stable offer is available, opening hires are not complete and Coin covers the sourced price. A successful Hire still writes exactly one existing receipt; retries remain duplicate-safe.
  • The approved Settings hit area emits the existing caller-context route; its visibility and pixels remain unchanged from the accepted page.
  • Invalid supplied ViewData renders a deterministic non-interactive boundary.

Ordered steps

M40-A — Architecture contract and inventory (COMPLETE)

  • Freeze the SHP-002 stopping point, dependency direction and forbidden imports before product code changes.
  • Inventory the static master, framed/content safe areas, exact node names, portrait source, seven fact slots, impact/price semantics, command eligibility and approved RecruitReviewSettings hit area.
  • Record the M18 normal-capture equivalence target at 760x360/zh_CN, 844x390/en, 1280x720/zh_CN and 1280x720/en with text scale 100%; 130% is explicitly non-blocking.
  • Commit and push this activation boundary before Runtime product changes.

Closure: source 24579e6 records the frozen boundary in this plan, CURRENT_CHECKPOINT.md and docs/06_DEVELOPMENT_AND_REVIEW.md, and makes M40 the sole active plan.

M40-B — Passive View extraction (COMPLETE)

  • Add runtime/entry/views/recruit_review_page_view.gd and its isolated View contract test.
  • Reuse ABGPageView/ABGPageContext and the existing EntryChrome/button grammar without changing the static master or normal geometry.
  • Mount the View from EntryShell and translate only deferred cancel, hire and settings intents.
  • Remove only Recruit Review UI builders/helpers from EntryShell; keep controller, GuildContractService, Market selection, Save and route semantics intact.

Closure: source 0cf4ffb adds ABGRecruitReviewPageView, mounts it from EntryShell, removes the former Recruit Review static-master/UI builder and wires deferred cancel/hire/settings intents. The isolated View contract, M18 controller and SHP-002/Market/Hire regressions pass with strict diagnostics 0; the four normal fixture captures are byte-equivalent to the M18 baseline.

M40-C — Focused verification (COMPLETE)

  • Run the View contract, M18 controller, SHP-002, Market and Hire regressions through tools/run_test_attempt.py with exact-once markers and strict diagnostics.
  • Run the DEV-3 candidate and full MVP first-cycle audit.
  • Compare normal Recruit Review captures with the M18 baseline at the four required fixtures/locales and confirm byte-equivalence for the visible page.

Closure: source-bound attempts at source 4f995d2bee35e4e3665e7c4a22ef9cec63422141 pass the View contract, M18/ SHP-002/Market/Hire regressions, DEV-3 candidate and full MVP first-cycle audit with strict diagnostics 0. The four normal 100% Recruit Review captures are byte-equivalent to the M18 baseline. Evidence is recorded in docs/runtime/M40_RECRUIT_REVIEW_PAGE_VIEW_VISUAL_AUDIT.md.

M40-D — Handoff (COMPLETE)

  • Record source-bound evidence and visual equivalence in docs/runtime/M40_RECRUIT_REVIEW_PAGE_VIEW_VISUAL_AUDIT.md.
  • Close only Recruit Review. Market, Contract Choice, Guild, Battle, Economy, Save, packaging and release remain outside this plan.
  • Update the checkpoint and development ledger, then push the focused closure.

Closure: source 9da7cac records the source-bound audit, strict diagnostics, four-fixture byte-equivalence and ordered scope boundary. M40 is complete; Market, Contract Choice, Guild, Battle, Economy, Save, packaging and release remain outside this plan and require a new owner-authorized plan.

Frozen scope

  • No GuildContractService, Market, Company, Contract, Economy, Battle, Save or localization semantic changes.
  • No visible visual redesign, asset generation, static-master editing or 130% scope.
  • No mass rewrite of entry_shell.gd and no global event bus/binding layer.
  • No deletion of compatibility/history files, .uid, .import or prototype_incremental/.
  • No packaging, iOS export, signing, deployment, store or release work.

Acceptance checks

  • ABG_M40_RECRUIT_REVIEW_VIEW_CONTRACT_OK exactly once.
  • Existing ABG_M18_RECRUIT_REVIEW_CONTROLLER_OK, SHP-002/Market/Hire regressions, DEV-3 candidate and ABG_MVP_FIRST_CYCLE_AUDIT_OK remain green.
  • Extracted View has no forbidden service/content/route imports and emits only cancel, hire and settings intents.
  • Recruit Review normal 100% captures remain visually equivalent to the M18 baseline at all four required fixtures/locales; the invisible Settings hit area does not alter pixels.
  • Focused source is committed, pushed and tracked files are clean.

Commit boundaries

  • M40-A: plan/checkpoint activation.
  • M40-B: View and EntryShell integration.
  • M40-C: focused verification/evidence.
  • M40-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 M40 RECRUIT REVIEW VIEW PILOT COMPLETE