From 58d09ac8d30c4eabd5fb4c656af5d84ed93067bc Mon Sep 17 00:00:00 2001 From: null Date: Sat, 27 Jun 2026 14:51:23 -0500 Subject: [PATCH] docs(qa): cross-reference Engineering Reference Manual by Pass with anchor links --- ClaudeQAPlan.md | 41 ++++++++++++++++++++++++++++++++--------- 1 file changed, 32 insertions(+), 9 deletions(-) diff --git a/ClaudeQAPlan.md b/ClaudeQAPlan.md index 84c9dcd9..bb4cae33 100644 --- a/ClaudeQAPlan.md +++ b/ClaudeQAPlan.md @@ -8,6 +8,25 @@ > parity β†’ **Part 3** = run these same passes on iOS + a cross-platform (Android↔iOS) pass. **Parts 2 & 3 live in > `ClaudeiOSPlan.md`** (note: iOS build/run/QA requires macOS β€” not possible from this Linux box). +## πŸ“– Architecture reference (read BEFORE testing the matching area) + +For each Pass below, before you start, read the relevant section of [`docs/Engineering_Reference_Manual.md`](docs/Engineering_Reference_Manual.md) β€” it documents the architecture, the wire-format contracts, the security invariants, and the [Known landmines](docs/Engineering_Reference_Manual.md#known-landmines-and-recent-fixes) (bugs that cost real debugging time and are easy to re-introduce). + +| Pass | Manual section to read first | +|---|---| +| A β€” Couple-shared premium | [Premium-gated features and gate pattern](docs/Engineering_Reference_Manual.md#premium-gated-features-and-gate-pattern) Β· [Billing](docs/Engineering_Reference_Manual.md#billing) | +| B β€” Games lifecycle | [Game session push semantics (idempotent flag-claim)](docs/Engineering_Reference_Manual.md#game-session-push-semantics-idempotent-flag-claim) Β· [Foreground game-alert banner](docs/Engineering_Reference_Manual.md#foreground-game-alert-banner-r10) Β· [F-RACE-001](docs/Engineering_Reference_Manual.md#f-race-001--duplicate-game-start-push-on-rapid-partner-update) | +| C β€” Visual (light+dark) | [Daily question lifecycle](docs/Engineering_Reference_Manual.md#daily-question-lifecycle) Β· [C-NAV-001](docs/Engineering_Reference_Manual.md#c-nav-001--back-from-home-resurfaces-onboardingauth) Β· [Back-stack gotchas](docs/Engineering_Reference_Manual.md#back-stack-gotchas-c-nav-002-c-nav-003) Β· [C-HOME-001](docs/Engineering_Reference_Manual.md#home-duplicate-pending-action-card-c-home-001) | +| D β€” Security & encryption | [End-to-end encryption model](docs/Engineering_Reference_Manual.md#end-to-end-encryption-model) Β· [Firestore security rules](docs/Engineering_Reference_Manual.md#firestore-security-rules) Β· [Encryption versions](docs/Engineering_Reference_Manual.md#encryption-versions) | +| E β€” Notifications | [Notifications](docs/Engineering_Reference_Manual.md#notifications) Β· [Notification deep-link routing](docs/Engineering_Reference_Manual.md#notification-deep-link-routing) Β· [E-GAME-001](docs/Engineering_Reference_Manual.md#e-game-001--notification-deep-link-landed-in-stalefinished-game) Β· [E-GAME-002](docs/Engineering_Reference_Manual.md#e-game-002--game-start-push-easy-to-miss-when-app-is-foreground) | +| F β€” Resilience | [End-to-end encryption model](docs/Engineering_Reference_Manual.md#end-to-end-encryption-model) Β· [Known limitation: single-device keys](docs/Engineering_Reference_Manual.md#known-limitation-single-device-keys) | +| G β€” Account creation / fake-account | [Authentication and pairing flow](docs/Engineering_Reference_Manual.md#authentication-and-pairing-flow) Β· [Rate limiting on accept](docs/Engineering_Reference_Manual.md#rate-limiting-on-accept) | +| H β€” Branding & artwork | `ClaudeBrandingReview.md` (this repo) Β· `docs/brand/visual-identity.md` | +| I β€” Performance | [Engineering conventions](docs/Engineering_Reference_Manual.md#engineering-conventions) Β· [Where to look first](docs/Engineering_Reference_Manual.md#where-to-look-first) | +| J β€” Accessibility | [CloserTheme](docs/Engineering_Reference_Manual.md#ios-specific-notes) Β· [Engineering conventions](docs/Engineering_Reference_Manual.md#engineering-conventions) | + +**If you find a bug that LOOKS like it might be a re-introduction of a known landmine** (above table or [Known landmines](docs/Engineering_Reference_Manual.md#known-landmines-and-recent-fixes)), stop and verify the fix is still in place before filing a new ID β€” it may be a regression on a known issue, not a new bug. + ## Where every finding goes (route it here β€” exactly one home each) | What you found | Where it goes | Form | |---|---|---| @@ -358,12 +377,13 @@ Account); Paywall; Your Progress/Activity; Recovery. - **SOFT EDGES β€” art must fade into the screen, not show a hard tile edge (mandatory):** every displayed illustration should **blend/feather softly into the background**, not sit as a hard-edged rounded rectangle/card with a visible boundary or border line. Inspect each illustration's edges against the screen on **both themes** β€” a crisp tile edge, - outline/border, or a pale block floating on the surface is a finding (C-ART-EDGE-001). (Current state: `BrandIllustration` - hard-`clip`s to `RoundedCornerShape` + a hairline `border`, and `EmptyState` renders raw, so the art's near-white tile - shows a hard edge.) Fix pattern: feather the edges to transparent (radial/linear fade mask via - `Modifier.graphicsLayer{compositingStrategy=Offscreen}` + `drawWithContent` `BlendMode.DstIn` gradient), or a vignette - matching the surface, or ship transparent-edged art β€” applied in the shared `BrandIllustration`/`EmptyState` helpers so - it's consistent everywhere. + outline/border, or a pale block floating on the surface is a finding (C-ART-EDGE-001). (**Fixed R11:** `BrandIllustration` + now feathers its 4 edges to transparent via `Modifier.graphicsLayer{compositingStrategy=Offscreen}` + `drawWithContent` + `BlendMode.DstIn` linear gradients β€” `clip`+`border` removed β€” and `EmptyState` routes its illustration through + `BrandIllustration`, so all tiled art melts into the surface. Recurring check: verify it still holds and that any NEW art + helper / direct `painterResource` tile also feathers.) Fix pattern (if it regresses): feather the edges to transparent, + or a vignette matching the surface, or ship transparent-edged art β€” applied in the shared `BrandIllustration`/`EmptyState` + helpers so it's consistent everywhere. - **Probe:** `ui/theme/Theme.kt` hardcoded brand colors + chat's custom `closerBackgroundBrush` β€” verify dark mode truly adapts; grep screens for hardcoded `Color(0x...)`. - **THEME-VARIANT ART must follow the IN-APP theme, not just the system (mandatory β€” RUN THE DECOUPLED STATE):** the app @@ -378,9 +398,12 @@ Account); Paywall; Your Progress/Activity; Recovery. History, Date Match (empty + success), Connection Challenges header, Pairing success, Messages empty, Past Games, Quiet-hours, Account-deletion, + any new `illustration_*` added to `drawable-night-nodpi/`. **Restore `cmd uimode night auto` after.** Light art on a dark screen (or vice-versa) when the in-app theme is switched = bug (P2 theme-not-adapting; - see C-DARKART-001). Fix pattern: drive the resource `uiMode` from the in-app theme (e.g. a themed `Resources` in the - shared `BrandIllustration` helper, or `AppCompatDelegate.setDefaultNightMode`/config override) so `painterResource` - picks `-night` per the app's own setting. + see C-DARKART-001). (**Fixed R11:** `CloserTheme` provides `LocalAppInDarkTheme`; `BrandIllustration` loads each drawable + through `context.createConfigurationContext(cfg)` whose `UI_MODE_NIGHT_*` is set from `LocalAppInDarkTheme`, so the + `-night` variant follows the IN-APP theme, not the system. Verified live R11 both decoupled directions. Recurring check: + re-run the decoupled state and confirm it still holds, including any newly added `-night` art.) Fix pattern (if it + regresses): drive the resource `uiMode` from the in-app theme as above, or `AppCompatDelegate.setDefaultNightMode`/config + override, so `painterResource` picks `-night` per the app's own setting. - **States, not just happy path:** empty / loading / error / not-paired / locked-premium / signed-out / stale-or-deleted-target / populated-with-many where they exist; many need data setup (seeding is user-gated) β€” note unreachable states in coverage rather than skipping silently.