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

  # Check if tunnel is alive
  telnet localhost 5432
  # Expected: Connected (if not, restart tunnel)
  

• PostgreSQL Connection Verified

  psql -h localhost -p 5432 -U kartsell -d kartsell -c "SELECT version();"
  # Expected: PostgreSQL version output
  

• Environment Variables Set

  # 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

  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

  SELECT EXISTS (
    SELECT 1 FROM information_schema.tables
    WHERE table_schema = 'model_operations' 
    AND table_name = 'shadow_run'
  );
  # Expected: true
  

• Approval Queue Table Exists

  SELECT EXISTS (
    SELECT 1 FROM information_schema.tables
    WHERE table_schema = 'model_operations'
    AND table_name = 'approval_queue'
  );
  # Expected: true
  

• Outbox/Inbox Tables Exist

  SELECT EXISTS (
    SELECT 1 FROM information_schema.tables
    WHERE table_schema IN ('building_blocks', 'outbox')
  );
  # Expected: true
  

2.2 Data Validation

• Active Model Exists

  SELECT COUNT(*) FROM model_operations.model 
  WHERE status = 'Active';
  # Expected: > 0 (at least one active model)
  

• No Pending Shadow Runs

  SELECT COUNT(*) FROM model_operations.shadow_run
  WHERE status IN ('Pending', 'DataBackfill', 'Replay');
  # Expected: 0 (clean state)
  

• No Pending Approvals

  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

  echo $env:KRX_API_KEY  # PowerShell
  # Expected: Non-empty API key
  

• API Endpoint Reachable

  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

  # 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

  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

  # 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

  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