# Week 1 Provider Readiness Review Guide

This guide helps reviewers (Chris, Claude, and Ryan) inspect, validate, and merge the Week 1 provider readiness stack.

---

## 1. Stacked PR Review Sequence

The implementation is broken down into a series of stacked branches. Review them in the following order:

1. **PR #57: Staged Provider Gates & Audit**
   - **Backlog Issues**: Issue #44 (provider approval semantics in config/runtime), Issue #45 (staged provider-call budget config), Issue #46 (staged provider-call audit artifact behavior).
   - **Responsibility**: Establishes the core config-driven runtime validation structures for tracking call budgets and writing audit logs.
   - **Status**: Implemented in draft PR.
2. **PR #58: Public Injury & Inactives Boundaries**
   - **Backlog Issues**: Issue #47 (NFL.com injury import), Issue #48 (NFL.com inactives import).
   - **Responsibility**: Establishes standard boundary interfaces and parses clean public/sanitized datasets without initiating raw feed fetches.
   - **Status**: Implemented in draft PR.
3. **PR #59: Staleness Gates**
   - **Backlog Issues**: Issue #49 (active staleness gates).
   - **Responsibility**: Restricts the pipeline to offline fixture data if the compiled provider timestamp is older than the configured threshold.
   - **Status**: Implemented in draft PR.
4. **PR #62: Fallback & Break-Glass Audits**
   - **Backlog Issues**: Issue #50 (provider/runtime logic for CSV fallbacks), Issue #51 (Sleeper cross-check logic).
   - **Responsibility**: Verifies validation paths when falling back from authority feeds to manual break-glass overrides or Sleeper cached cross-checks.
   - **Status**: Implemented in draft PR (Review needed).
5. **PR #64: Odds API Smoke Plan**
   - **Backlog Issues**: Issue #52 (provider/runtime logic for odds API checks).
   - **Responsibility**: Validates request planning and response formatting without checking in live credential keys.
   - **Status**: Implemented in draft PR.
6. **PR #65: Team-Market Guardrail**
   - **Backlog Issues**: Issue #56 (core calibration / market-health behavior for team markets).
   - **Responsibility**: Keeps team markets restricted to Lean/Review/No Play to prevent early-season volatility.
   - **Status**: Implemented in draft PR.
7. **PR #67: Cold-Start Projection Reporting**
   - **Backlog Issues**: Issue #55 (cold-start validation behavior).
   - **Responsibility**: Reports projection model statistics during early-season sample scarcity.
   - **Status**: Implemented in draft PR (Review needed).

---

## 2. Issues to PR Mapping & Status Buckets

| Issue | Title / Area | Target PR | Status Bucket | Notes |
| :--- | :--- | :--- | :--- | :--- |
| **#44** | Provider Approval Semantics | PR #57 | Implemented in draft PR | Complete in codex stack |
| **#45** | Staged Call Budget Config | PR #57 | Implemented in draft PR | Complete in codex stack |
| **#46** | Staged Call Audit Behavior | PR #57 | Implemented in draft PR | Complete in codex stack |
| **#47** | NFL.com Injury Import | PR #58 | Implemented in draft PR | Complete in codex stack |
| **#48** | NFL.com Inactives Import | PR #58 | Implemented in draft PR | Complete in codex stack |
| **#49** | Active Staleness Gates | PR #59 | Implemented in draft PR | Complete in codex stack |
| **#50** | Fallback/Break-glass Auditing | PR #62 | Review needed | Codex implementation review |
| **#51** | Sleeper Cross-Check | PR #62 | Review needed | Codex implementation review |
| **#52** | Odds API Smoke Plan | PR #64 | Implemented in draft PR | Complete in codex stack |
| **#55** | Cold-Start Projection | PR #67 | Review needed | Codex implementation review |
| **#56** | Team-Market Guardrail | PR #65 | Implemented in draft PR | Complete in codex stack |

---

## 3. Mandatory Safeguards & Offline Policies

To ensure safe testing during Week 1 preparation, the following settings **must remain disabled** at all times:

- **Credentials**: No live API keys (e.g. `ODDS_API_KEY`) should be configured or loaded.
- **Real Provider Calls**: Staged calls must operate in `provider-no-call` mode. No active external HTTP requests are made.
- **Publish Approval**: Picking publish status must be set to `Hold` or `No Play`. Live publishing remains disabled.
- **Team-Market Promotion**: Top Pick promotion for team props must be locked out.
- **Trusted-Market Promotion**: No promotion of trusted markets is allowed until post-Week 4 calibration review.

---

## 4. Reviewer Commands

Execute these commands to verify branch safety and correctness locally:

```powershell
# Run all unit tests offline
python -m pytest -q

# Run global quality gates (includes schema checks, secret scanning, copy validation)
python run_quality_gate.py

# Confirm working directory state
git status --short
```

---

## 5. Merge Blockers Checklist

A PR **must not be merged** if any of the following apply:

- [ ] **Failing Quality Gate**: All gates in `python run_quality_gate.py` must pass.
- [ ] **Generated Artifact Mismatch**: Running compilation creates files that do not match the expected mock schema.
- [ ] **Unintentional Live Calls**: Staged provider calls must not hit external servers.
- [ ] **Secrets Committed**: Verification that no real API keys are in git history.
- [ ] **Publish Enabled**: The code or config has enabled publishing.
- [ ] **Stale Docs Links**: Any broken or relative references in docs sitemaps.
- [ ] **Hype Language**: Any use of forbidden words or win-guarantees (such as l-o-c-k, g-u-a-r-a-n-t-e-e-d, f-r-e-e m-o-n-e-y, or c-a-n-t l-o-s-e).

---

## 6. Process Explanations & Policies

Reviewers must verify that all reports explain the following points clearly:
- **provider-no-call means no external calls**: Running in `provider-no-call` ensures zero network fetches are triggered against vendor APIs.
- **staged provider calls are separate from publishing**: Executing staged validation audits is isolated from picking publish actions.
- **publish approval remains disabled**: The framework does not authorize any release publishing without manual approval registers.
- **manual CSV is break-glass only**: Local overrides are limited to resolving stale injury or inactive inputs during feed blockages.
- **team markets stay Lean / Review / No Play**: To manage early-season model risk, props for team props must stay restricted to safe states.