KArtSell.Aegis/GATE_3_PREFLIGHT_CHECKLIST.md

# Gate 3 Pre-Flight Checklist

**Purpose:** Verify all prerequisites are in place before executing 252-day shadow run  
**Estimated Time:** 15 minutes  
**Success Criteria:** All items checked ✅

---

## ✅ Section 1: Infrastructure Setup (Estimated 5 min)

### 1.1 Database Connectivity

- [ ] **SSH Port Forwarding Active**
  ```bash
  # Check if tunnel is alive
  telnet localhost 5432
  # Expected: Connected (if not, restart tunnel)
  ```

- [ ] **PostgreSQL Connection Verified**
  ```bash
  psql -h localhost -p 5432 -U kartsell -d kartsell -c "SELECT version();"
  # Expected: PostgreSQL version output
  ```

- [ ] **Environment Variables Set**
  ```bash
  # PowerShell
  $env:KARTSELL_POSTGRES; $env:KRX_API_KEY
  # Expected: Connection string and API key populated
  ```

### 1.2 KArtSell.Host Service

- [ ] **Service Running on Port 5000**
  ```bash
  curl -s http://localhost:5000/health | jq .
  # Expected: 200 OK response
  ```

- [ ] **Hangfire Dashboard Accessible**
  - Navigate to http://localhost:5000/hangfire
  - Expected: Dashboard loads with 0 jobs in queue

- [ ] **Authentication Token Available**
  - JWT token with Admin or Researcher role
  - Save as environment variable for curl commands

---

## ✅ Section 2: Database State (Estimated 5 min)

### 2.1 Schema Validation

- [ ] **Shadow Run Table Exists**
  ```sql
  SELECT EXISTS (
    SELECT 1 FROM information_schema.tables
    WHERE table_schema = 'model_operations' 
    AND table_name = 'shadow_run'
  );
  # Expected: true
  ```

- [ ] **Approval Queue Table Exists**
  ```sql
  SELECT EXISTS (
    SELECT 1 FROM information_schema.tables
    WHERE table_schema = 'model_operations'
    AND table_name = 'approval_queue'
  );
  # Expected: true
  ```

- [ ] **Outbox/Inbox Tables Exist**
  ```sql
  SELECT EXISTS (
    SELECT 1 FROM information_schema.tables
    WHERE table_schema IN ('building_blocks', 'outbox')
  );
  # Expected: true
  ```

### 2.2 Data Validation

- [ ] **Active Model Exists**
  ```sql
  SELECT COUNT(*) FROM model_operations.model 
  WHERE status = 'Active';
  # Expected: > 0 (at least one active model)
  ```

- [ ] **No Pending Shadow Runs**
  ```sql
  SELECT COUNT(*) FROM model_operations.shadow_run
  WHERE status IN ('Pending', 'DataBackfill', 'Replay');
  # Expected: 0 (clean state)
  ```

- [ ] **No Pending Approvals**
  ```sql
  SELECT COUNT(*) FROM model_operations.approval_queue
  WHERE status = 'Pending';
  # Expected: 0 (ready for new run)
  ```

---

## ✅ Section 3: Market Data (Estimated 3 min)

### 3.1 KRX API Configuration

- [ ] **API Key Available**
  ```bash
  echo $env:KRX_API_KEY  # PowerShell
  # Expected: Non-empty API key
  ```

- [ ] **API Endpoint Reachable**
  ```bash
  curl -s -H "Authorization: Bearer $env:KRX_API_KEY" \
    "https://openapi.krx.co.kr/homeurl/service/rest/Stock/GetStockMarketIndex" \
    | jq .
  # Expected: 200 OK with market data
  ```

- [ ] **Historical Data Available**
  ```bash
  # Check KRX has data for 2024-01-02 to 2024-08-31
  # (The date range for shadow run)
  # Expected: Data exists for all trading sessions
  ```

### 3.2 Fallback (Stub Data)

- [ ] **Understand Stub Mode**
  - If KRX API unavailable, can use `StubKrxData` for testing
  - Modify KrxDataService to use stub if needed
  - Useful for local testing before production execution

---

## ✅ Section 4: Execution Readiness (Estimated 2 min)

### 4.1 Test Model Identification

- [ ] **Model Selected**
  ```sql
  SELECT id, name, status FROM model_operations.model
  WHERE status = 'Active'
  LIMIT 1;
  # Save the ID as $MODEL_ID
  ```

- [ ] **Model ID Noted**
  - Store in variable for later use
  - Example: `MODEL_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890"`

### 4.2 Date Range Verified

- [ ] **Window Start Date Chosen**
  - Typical: 2024-01-02 (first KRX trading day of 2024)
  - Save as: `WINDOW_START="2024-01-02"`

- [ ] **Window End Date Chosen**
  - Typical: 2024-08-31 (end of period for testing)
  - Save as: `WINDOW_END="2024-08-31"`
  - Ensure: Start < End, both dates are valid trading days

### 4.3 Monitoring Setup

- [ ] **Hangfire Dashboard Open**
  - Keep http://localhost:5000/hangfire open in browser
  - Watch q-research queue for job execution

- [ ] **Polling Script Ready**
  ```bash
  # Save this as gate3_poll.sh (or poll.ps1)
  # Will use to check shadow run status every 30 seconds
  ```

- [ ] **Log File Monitoring**
  - Know where KArtSell.Host logs are written
  - Can tail them to watch execution progress

---

## ✅ Section 5: Success Criteria (Estimated 0 min - just verify understanding)

### 5.1 Validation Gates

- [ ] **Understand PBO Gate**
  - PBO ≤ 20% means backtest not overfit
  - Expected result: pbo_under_20 = true

- [ ] **Understand DSR Gate**
  - DSR ≥ 95th percentile means daily Sharpe is robust
  - Expected result: dsr_above_95 = true

- [ ] **Understand Cost 2x Gate**
  - Returns should survive if fees double
  - Expected result: cost_2x_positive = true

- [ ] **Understand Phase Gate**
  - All phase metrics should be non-zero
  - Bull, Bear, Sideways all populated

### 5.2 Approval Workflow Readiness

- [ ] **Understand Approval Flow**
  - Shadow run completion → approval queue auto-populated
  - Status changes: Pending → Approved/Rejected

- [ ] **Know Approval Command**
  ```bash
  curl -X POST http://localhost:5000/api/v1/approval-queue/{id}/approve \
    -H "Authorization: Bearer <token>"
  ```

---

## ✅ Pre-Flight Summary

**Checklist Status:**
- [ ] Infrastructure ready (database, service, auth)
- [ ] Schema validated (all tables exist)
- [ ] Data clean (no hanging runs or approvals)
- [ ] Market data available (KRX or stub)
- [ ] Model selected and ID noted
- [ ] Date window chosen (start → end)
- [ ] Monitoring setup (dashboard + logs)
- [ ] Success criteria understood

**Ready to Execute?**
- If all ✅: Proceed to GATE_3_EXECUTION_GUIDE.md
- If any ❌: Fix issue, re-verify, then proceed

---

## Troubleshooting During Pre-Flight

**Issue: PostgreSQL Connection Fails**
- Verify SSH tunnel is running: `ssh -L 5432:127.0.0.1:5432 kjh2064@178.104.200.7`
- Check credentials in $env:KARTSELL_POSTGRES
- Verify firewall allows localhost:5432

**Issue: KArtSell.Host Not Running**
- Start with: `dotnet run --project src/KArtSell.Host -c Release`
- Check for port 5000 conflicts: `netstat -tulpn | grep 5000`

**Issue: No Active Models**
- Create test model via script (see GATE_3_SETUP_SCRIPTS.md)
- Or manually insert via SQL

**Issue: KRX API Unreachable**
- Verify API key in environment
- Check internet connectivity
- Use stub data mode for local testing

---

## Next Steps

Once all ✅ checked:
1. Open GATE_3_EXECUTION_GUIDE.md
2. Execute shadow run via POST /api/shadow-runs
3. Monitor via Hangfire + polling endpoint
4. Validate results via SQL queries
5. Trigger approval workflow