B6/RAG-5: cross-game habit aggregation (the Pro story on every platform)

[ber4444]

Summary

Cross-game habit aggregation (B6/RAG-5): the app already stores a
MoveAssessment on every ply of every saved game, and nothing has ever read
across them. This does — "You've hung a piece in 4 of your last 10 games" —
and it is the sentence no single-move coach can produce, on the axis the field
is weakest on (DecodeChess and Dr. Wolf both lose the thread between sessions).

It is also what Pro adds now. The Move Coach is deterministic on every
platform (#137 measured both phone runtimes against the same 100 golden
positions; neither was more truthful than the computed line), so Pro can no
longer mean "a model phrases the coach" anywhere. This is the replacement, and a
better one: it is a surface the free tier genuinely doesn't have, rather than a
nicer rendering of one it does.

Nothing here runs a model or touches the network, on any platform.

What's in it

• HabitAggregator — a pure function over GameHistoryRepository.games.
  Walks the player's assessed MISTAKE/BLUNDER moves across the most recent
  games, groups by a recurring costly motif (currently hangs-piece — the one
  motif DeterministicCoach treats as describing the player's own mistake
  rather than something going right), with a general-rate fallback when no
  specific tactic clears its own bar. Requires the pattern to recur across
  multiple games, not multiple times in one bad game — a single rough game is
  not a habit.
• HabitNarrator — deterministic text from a HabitSummary. Code detects;
  nothing narrates it into being. A model, where one exists, could later rephrase
  the two strings this produces, but the counts and the motif are never its to
  invent. That contract binds harder here than on a single move: an aggregate
  carries more claims per sentence, and both failures ML Kit on Android: availability was a client-config bug, and the "repetition loop" was ours #137's device run found
  were a supplied fact reattached to the wrong subject.
• Practice positions — each HabitOccurrence carries fenBefore (the exact
  position) and bestMoveSan (the engine's alternative), both already computed
  by MoveAssessor/MotifDetector when the ply was assessed. Nothing new is
  computed; data already persisted is reprojected.
• HabitsScreen + HabitsManager, wired into AppRoot as Screen.HABITS
  with a "Habits" button next to History in the game screen's menu row.
  Pro-gated the way Rules Q&A is (an explicit branch rather than ProGate,
  since the screen supplies its own SubScreenScaffold), with available =
  gameHistory != null.
• HabitsManager needs no platform runtime, model or engine, so unlike the
  AI managers AppRoot constructs it directly from the gameHistory it already
  has. No entry-point wiring changed on any platform.
• The paywall lists it, keyed off a new LocalHabitsManager — the same
  signal Screen.HABITS branches on, so the advertised list cannot drift from
  what a purchase actually unlocks. PaywallScreen.proFeatures() already had to
  avoid selling a surface the build can't show (ML Kit on Android: availability was a client-config bug, and the "repetition loop" was ours #137's coach line); gating one
  the build can show while never listing it is the same bug pointing the other
  way, and both are refund-shaped. Availability is a property of the build, which
  LocalEntitlements cannot know, so it stays a separate signal.

A prerequisite bug found and fixed

GameActions hardcoded White as the human regardless of
AppSettings.playerSide — a leftover from before the player-side setting
(#112) existed, never updated when it shipped. Two consequences:

• Every saved PGN and SavedGame mislabelled the colours for a Black-side game
  ([White "Player"] even when the human played Black).
• GameHistoryBackfiller had no way to know which plies were the player's,
  so on a Black-side game it silently backfilled assessments for the engine's
  moves — fatal for this feature, which would then have reported the engine's
  mistakes as the user's habits.

Fixed by adding SavedGame.playerSide (defaulting to "WHITE", which is correct
for data saved before the field existed — that was the only side selectable then)
and threading it through GameActions.pgnTags/toSavedGame and
GameHistoryBackfiller.

A second, independent bug surfaced while fixing the backfiller: its
evaluate() fallback path negated a value that ChessEngine.evaluate() already
returns from White's perspective (confirmed against both UCI transports —
UciEvaluation.toWhitePerspective is applied before the value ever reaches the
caller), silently inverting every assessment that hit it — any game played
without a live-attached engine, e.g. the CPU fallback.
GameHistoryBackfillerTest pins both fixes.

What I could not verify

• No Compose UI test for HabitsScreen. Comparable coverage
  (GameHistoryScreen) lives in androidDeviceTest and needs an emulator this
  environment doesn't have running. The aggregation and narration logic — the
  part that can be wrong in a way that matters — is covered by
  HabitAggregatorTest/HabitNarratorTest in commonTest, which did run.
• The paywall entry is hand-test-only by construction. Per CLAUDE.md,
  isProUnlocked() treats a null LocalEntitlements as unrestricted, so no
  Compose UI test can catch a paywall regression on any surface.
• Practice positions are plain FEN text, matching GameHistoryDetail's
  existing PGN-block precedent, not loaded into an interactive practice board —
  there is no FEN-import/practice-mode flow to hand them to, and building one is
  a materially larger feature. That is the honest scope of "suggest a practice
  position" here.
• No [move-N]-style citation for cross-game occurrences.
  ui/CitationSanitizer deliberately preserves that syntax for the current
  game's board-jump affordance (B16); a habit spans multiple saved games, so
  reusing it would be ambiguous — and this feature never routes through a model
  or the sanitizer at all, so nothing forced the question. Occurrences are listed
  in plain text with a recency label.

Composes with the Maia-3 spike (not wired here)

HabitSummary/HabitOccurrence are plain data so a future Maia-3 signal
("players at your level play X here") can sit alongside a detected habit without
a redesign, per that spike's own note that the two compose: habits say you keep
doing X, Maia says players above you do Y. Nothing Maia-related is wired in.

Verification

./gradlew :chess-core:check :ondeviceai:check :app:check :androidApp:assembleDebug

Green, including :ondeviceai:iosSimulatorArm64Test,
:app:iosSimulatorArm64Test and :app:wasmJsBrowserTest. No :onDeviceAi
public API touched.

🤖 Generated with Claude Code