aetherbound-guild/docs/plans/M16_COMPANY_PAGE_PILOT.md

M16 Company Page Controller Pilot

Status

• Plan: M16_COMPANY_PAGE_PILOT
• Status: IN_PROGRESS
• Activated: 2026-08-25
• Baseline: 8cf67ff (M15_RUNTIME_FOUNDATION_COMPLETE)
• Owner authorization: the Owner authorized the Runtime architecture refactor and delegated intermediate implementation review.

Objective

Prove the next migration seam on the unaccepted Company-management pages: Roster and Recruit Detail. Move their Company-to-view-data decisions behind a page-specific controller while keeping the existing Godot composition, input, visuals and dismissal semantics unchanged. This is a bounded architecture pilot, not a page redesign or a rewrite of entry_shell.gd.

Player/System Stopping Point

At the end of this plan's boundary:

• Roster and Recruit Detail still render the same player-visible states and controls at the existing normal fixtures;
• a UI-independent CompanyPageController produces stable, copied view data for roster members, selection, detail facts and dismissal eligibility;
• the Entry Shell consumes that controller output at the page boundary rather than re-deriving selection/eligibility rules in multiple view functions;
• the controller has no dependency on Control, Label, TextureRect, facade, current_screen or Save files;
• the next migration can reuse the same controller/view pattern for Market or Recruit Review without changing accepted page semantics.

Architecture Contract

Entry Shell / route callback
  -> CompanyPageController (view-model assembly)
  -> Company snapshot supplied by the caller
  -> Roster / Recruit Detail view composition

The controller may inspect a supplied Company snapshot, but it must not load, save or mutate it. It returns deep-copied dictionaries and stable IDs. Views continue to own Godot nodes, localization, textures, layout and user-intent callbacks.

Ordered Steps

M16-A — Pilot contract and inventory (COMPLETE)

• Record the bounded Roster/Recruit Detail stopping point and forbidden scope.
• Inventory the current show_roster, show_recruit_detail, selection and dismissal eligibility branches.
• Update CURRENT_CHECKPOINT.md before product code changes.

Acceptance: this plan is the only active implementation plan and no accepted MVP page, Save rule or generated asset is changed.

M16-B — Additive Company page controller (COMPLETE)

Add a UI-independent controller under runtime/entry/ with focused checks for:

• stable member snapshots and selected Recruit fallback;
• detail lookup and missing-ID rejection;
• level/XP, equipment and battle-history facts;
• dismissal eligibility and explicit reason;
• deep-copy isolation from the supplied Company dictionary.

Closure: source c8af889 adds ABGCompanyPageController and the focused ABG_M16_COMPANY_PAGES_OK test. The controller is UI-independent and returns copied stable-ID view data.

M16-C — Entry Shell integration (COMPLETE)

• Inject one controller instance through the Entry Shell.
• Make Roster and Recruit Detail consume controller output while preserving existing helper formatting and authored layout.
• Keep compatibility with existing tests and direct page calls.

Closure: source 14b0461 injects one ABGCompanyPageController into the Entry Shell. Roster and Recruit Detail now consume copied controller output for member lists, selected facts and dismissal eligibility while retaining the existing authored composition and callbacks. The focused normal capture test records four landscape fixtures × two states without changing page visuals.

M16-D — Focused verification and handoff (COMPLETE)

• Run the controller test, DEV-6 Roster regression and normal capture checks.
• Run the MVP first-cycle audit to prove no accepted-route regression.
• Record the migration boundary and create a focused pushed commit before any Market or Recruit Review migration.

Closure: source-bound focused attempt m16-company-pages-focused from source fa525e6c705d1b416dd94b2173094ad20c575abd passed ABG_M16_COMPANY_PAGES_OK, ABG_DEV6_ROSTER_OK and ABG_M16_COMPANY_CAPTURE_OK exactly once. It retained eight normal 100% frames across the four landscape fixtures and reported strict diagnostics 0, process-group cleanup and workspace cleanup. The archive SHA-256 is b53bc90cea66f8c13849c706fa060817f1580489296a48c852f8db2a0339f1fa. The full first-cycle audit from the same source also passed ABG_MVP_FIRST_CYCLE_AUDIT_OK exactly once with 128 normal 100% frames, strict diagnostics 0 and complete cleanup; its retained archive is /private/tmp/aetherbound-guild-test-evidence/m16-mvp-audit/20260825T023618Z-1488 with SHA-256 ee560774e9701999ec9a83e1b5aa0e1dfd3bbf31eba977445a2ce71ac22d8851.

Frozen Scope

• No visual redesign, new art, animation or audio generation.
• No changes to dismissal, equipment, Company, Contract, Save or economy semantics.
• No mass rewrite of main.gd or entry_shell.gd.
• No migration of accepted Battle, Risk, Party, Result or Recovery pages.
• No .uid, .import, cache, prototype_incremental/ or provenance cleanup.
• No iOS/export/package/signing/release work.

Required Evidence

• Strict Godot diagnostics 0.
• ABG_M16_COMPANY_PAGES_OK exactly once.
• Existing ABG_DEV6_ROSTER_OK exactly once.
• Normal 100% Roster/Recruit Detail captures inside the viewport.
• Existing ABG_MVP_FIRST_CYCLE_AUDIT_OK remains green.

Issue Register

• M16-ISSUE-01 — current Roster and Detail views repeat Company-derived selection and dismissal checks. This pilot centralizes only those decisions; localization and visual formatting remain in the view until a later step.
• M16-ISSUE-02 — DEV-6 pages are historical/unaccepted presentation surfaces. They are safe pilots because this plan freezes their visuals and does not promote them to visual authority.

Commit Boundaries

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

Each boundary must pass its focused checks before the next step becomes active.

Final handoff

M16 is closed. The controller/view seam is proven on the unaccepted Roster/Recruit Detail pilot. The next migration may target Market or Recruit Review only after a new durable plan is activated; accepted MVP pages remain frozen until then.