PS12 — Engineering Streamline (final phase)

Status: Archived

Owner directive (2026-07-11): "Once we have finished all the slices, E2E verified each one … we are going to streamline the app from an engineering perspective. That means the correct architecture, adherence to best engineering practices (separation of concerns, single source of truth) and accompanying test suites to ensure we have a robust pre-production app. It's important that we don't rely on custom implementations."

This space runs last — after PS1–PS11's slices are shipped AND E2E-confirmed. It is authored during synthesis (not by a research agent) because its scope is the residue of everything else: the duplication, the bespoke code, and the coverage gaps that the remediation either exposes or leaves behind. It is deliberately NOT a speculative rewrite — every item is anchored to a concrete finding already surfaced by the audit.

Why this is a phase, not a sweep

The audit repeatedly found the same shape of problem: a thing implemented more than once, the copies drifting apart. Five "overdue" definitions (PS5). Three hand-rolled region-filter bars (PS9). Two currency formatters that disagree (PS5/U8). A 3-way admin-count divergence (PS8). Two independent notification-scheduling producers for the same reminder (PS8). Push-tap and in-app routing deriving destinations separately (PS8). Each PS collapses its own instance to a single source of truth; PS12 verifies no new duplication was introduced by the remediation itself, and sweeps the structural residue that no single PS owned.

Problem statement (anchored to audit findings)

1. Single-source-of-truth violations confirmed across the audit — dues "overdue" (PS5-D3), region filters (PS9), currency format (PS5), admin-count (PS8), notification scheduling (PS8), route derivation (PS8). Each PS fixes its own; PS12 owns the cross-PS consistency check + the ones too small to belong anywhere (currency formatter unification).
2. Custom-where-a-library-fits — the audit surfaced hand-rolled code where a mature library or an existing internal primitive already exists (e.g. the 3 bespoke region bars vs one component; raw RN Views in tier-info-sheet vs Tamagui primitives, PS10; hand-rolled unused-export detection absent, PS11 recommends knip). PS12 audits for the remaining instances against the prefer-libraries-over-custom rule and the single-implementation-per-pattern rule.
3. Separation-of-concerns drift — CTA-in-Card in 4 screens (U3), adapter imports inside presentation (U7 DM near-miss), the useMatchBoard 513-line orphan hook (U4), dead pipelines (join-request, referee-transfer, invites, role_configs, payment_history) that blur which layer owns what. PS12 does the hexagonal-architecture conformance pass once the live code has settled.
4. Test-coverage gaps — the audit found zero test coverage on several load-bearing paths (push-tap routing, U1; score-call reject, U4; the whole payment-hold lifecycle). Each PS adds tests for its own slices; PS12 backfills the integration/E2E layer that proves the fixed flows stay fixed, and raises the baseline.

Solution design

PS12 is four conformance passes, each producing a mechanical guard where possible (so the streamline can't regress) — this dovetails with PS11, which builds the guard infrastructure; PS12 is where the guards get applied to the now-settled codebase.

12A — Single-source-of-truth conformance

• Enumerate every "one concept, N implementations" case the audit named; verify each PS collapsed its instance; sweep the leftovers (currency formatter → one formatWon; confirm one region-filter component consumed by all three discovery surfaces; one admin-count helper; one route-derivation).
• Guard: an arch-test / lint asserting the canonical util is the only one (extend the existing single-source patterns).

12B — Prefer-libraries / one-implementation-per-pattern

• Audit the codebase against the prefer-libraries-over-custom rule for the residual bespoke code the remediation exposed. For each: adopt the library / the existing internal primitive, or document why custom is justified (the rule permits custom with a documented reason).
• Introduce knip (PS11-6) to find dead exports; retire or wire each (join-request UI wired by PS6, referee-transfer decided by PS4, invites/role_configs/payment_history decided by their PS).

12C — Hexagonal architecture + separation of concerns

• Run the ArchUnitTS conformance suite after all slices land; close any new violations. Specifically: no adapter imports in presentation (fix the DM near-miss), presentation reaches Supabase only via @/registry, features import only @twomore/app/@twomore/ui, domain/ imports zero outer layers.
• Move CTA-in-Card cases (U3) to the canonical BottomCtaBand/row pattern or formalize the exception in docs/canon/components.md + the lint rule so it's not just a code-comment escape hatch.
• Delete confirmed-orphan code (useMatchBoard, dead gender-tier code U5, legacy club_alerts reminder path once PS8's retire lands).

12D — Test-suite robustness for pre-prod

• Backfill the integration/E2E coverage the audit found missing, prioritized by the criticals: payment-hold lifecycle (seeded scenario), settle-before-play match gate, waitlist promotion under concurrency, account-deletion completeness, the push-tap route map (PS8 adds the unit test; PS12 adds the device/Maestro flow), join-request approval flow.
• Raise the yarn check baseline; add the seeded-scenario chains (scripts/run-scenario.mjs) for each remediated critical flow so E2E proof is repeatable, not one-shot.
• Ratchet down the ESLint waiver baseline as touched files are migrated.

Slices

PS12 slices are defined after PS1–PS11 ship, because their exact content is the measured residue. The roadmap reserves PS12 as the final wave with these provisional slices:

Slice	Type	Scope	Verification
PS12-A	arch-test + refactor	SSoT conformance sweep + guards	the new arch-tests pass; grep shows one impl per concept
PS12-B	refactor + tooling	prefer-libraries pass + knip dead-export retirement	knip clean or documented; libs adopted
PS12-C	refactor	hexagonal/SoC conformance; orphan deletion	ArchUnitTS green; CTA-in-Card resolved
PS12-D	tests	integration/E2E backfill for every remediated critical + scenario chains	yarn check at raised baseline; Maestro flows green; each critical flow has a repeatable seeded E2E

Dependencies

PS12 depends on all of PS1–PS11 being shipped and E2E-confirmed. It consumes PS11's guard infrastructure (arch-tests, lint rules, pgTAP) and applies it to the settled codebase. It must not start early — a conformance pass on half-migrated code produces churn, not robustness.