> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pcm.game/llms.txt
> Use this file to discover all available pages before exploring further.

# Sprint 11: Progression & Ranked Play

> Implementation of Post-Match Resolution, ELO systems, and Technical Stabilization.

# Sprint 11: Progression & Ranked Play

With the continuous poker table loop and simultaneous reveal mechanics locked in (Sprint 10), Sprint 11 focuses on the macro-economy and player progression. Before adding new features, we must stabilize the local development environment by fixing timestamp miscalculations and API error boundaries.

## 🛠 Context & Required Skills for AI Agents

When working on this sprint, agents must adhere to the following technical contexts:

1. **Firebase Timestamps:** Firestore stores timestamps as objects containing seconds and nanoseconds. To compare them to frontend JavaScript `Date.now()`, the agent MUST convert the Firebase timestamp properly (e.g., `timestamp._seconds * 1000` or `timestamp.toMillis()` depending on the SDK object type) to avoid instant-timeout bugs.
2. **Graceful Failures:** Edge-cached API routes fetching from Firestore must NEVER throw unhandled 500s. If a document (like `GlobalState/macro_state`) is missing, return a `200 OK` with a safe baseline fallback payload.
3. **The Currencies:** Faction-specific native currencies are: AuthRight (Dinars), AuthLeft (Collective Labor), LibLeft (Pronouns), LibRight (Monke).
4. **Standard Operating Procedure:** The 5-Step "Definition of Done" found in `task.md` remains in full effect.

***

## 🗺 Sprint 11 Roadmap

### \[x] Phase 0: Technical Stabilization (Hotfixes)

* **Objective:** Fix integration bugs preventing local playtesting.
* **Tasks:**
  * `frontend/app/api/macro-state/route.ts`: Catch Firebase Admin initialization and missing document errors. Return fallback baseline: `{"AuthRight": 2500, "AuthLeft": 2500, "LibLeft": 2500, "LibRight": 2500}` instead of throwing HTTP 500.
  * `frontend/app/arena/[lobbyId]/page.tsx`: Fix the 30-second Shot Clock. Correctly parse the Firebase `startedAt` timestamp to milliseconds before calculating `Date.now()` differences. Ensure the auto-play fallback ONLY triggers if `tableState.status === 'DEBATE_PHASE'`.

### \[x] Phase 1: Post-Match Math & Economy Payouts

* **Objective:** Award the victors and punish the losers.
* **Tasks:**
  * Build `backend/src/routes/resolve.js` logic to calculate the Euclidean distance of played cards against the News Stub target vector.
  * Distribute ELO points (+/-) to the players based on ranking.
  * Distribute native currency based on the "Based/Cringe" prisoner's dilemma matrix.
  * Update the backend to funnel a portion of the matched currency into the Global GIP pool, altering the `GlobalState/macro_state`.

### \[x] Phase 2: Player Profile & Prestige UI

* **Objective:** Visualize the progression state globally.
* **Tasks:**
  * Update `frontend/components/WalletOverlay.tsx` to fetch and dynamically display the player's current ELO tier (e.g., Bronze, Silver, Gold).
  * Add visual animations for currency payouts upon returning from an Arena match.

### \[x] Phase 3: ELO-Based Matchmaking Gates

* **Objective:** Prevent high-tier players from farming low-tier bots.
* **Tasks:**
  * `[x]` Update `POST /debate/inject-ghosts` to query the human player's ELO.
  * `[x]` Scale the Euclidean precision (difficulty) of the generated Ghost Players' hands based on the human's ELO bracket.

***

### \[ ] Tech Debt: Migrate Content Factory to Gemini Interactions API (GA)

* **Objective:** Lower Cloud Run container execution windows by offloading 3D coordinate vector assignments to Google-hosted background infrastructure.
* **Tasks:**
  * [ ] Upgrade `services/content-factory/requirements.txt` to `google-generativeai>=0.6.0`.
  * [ ] Refactor `processor.py` to replace `model.generate_content` with structured `genai.Interaction` sequences.
  * [ ] Enforce the `background=True` parameter on execution blocks to guarantee immediate asynchronous HTTP handshakes.
  * [ ] Verify Pydantic schema validation parity using local `dev_mode` prefab test fixtures before triggering the Cloud Build pipeline.