KArtSell.Aegis/src/KArtSell.Modules.ModelOperations/ShadowRun/PHASE_SEGMENTATION_CONTRACT.md

Phase Segmentation: Bull/Bear/Sideways/Volatility Analysis (AGENTS.md v16.0)

1. SOURCE (Requirements)

From README.md:

• "복수 국면 OOS" (Multiple market phase out-of-sample validation)

From research/K-ArtSell_12_2_quant_review_ko.md:

• Strategy performance varies by market regime
• Bull/Bear/Sideways/Volatility phases require separate analysis
• Robustness proof: positive returns across all phases

From CLAUDE.md:

• § "Validation Gates": Phase breakdown with separate metrics
• § "Shadow Run Design": PhaseBreakdown record with Bull/Bear/Sideways/HighVolatility

Business Logic:

• Strategy must work across all market conditions
• Failure in any phase → production rejection
• PBO/DSR must hold in each phase independently

---

2. SLICE SPEC (Vertical Slice)

Goal

Segment shadow run portfolio returns by market regime; compute phase-specific metrics.

Non-Goal

• Real-time regime detection (historical only)
• Regime switching strategy (static classification)
• Multi-period lookahead (single-period PIT)

Workflow

1. Input: Daily returns + trading sessions (shadow run replay result)
2. Detect regimes: Classify each day into Bull/Bear/Sideways/Volatility
   • Bull: 30-day MA trending up
   • Bear: 30-day MA trending down
   • Sideways: 30-day MA flat (±5% band)
   • Volatility: Realized volatility > 2σ
3. Aggregate: Group returns by regime
4. Calculate: Per-regime metrics (Sharpe, Calmar, Max DD, Win Rate)
5. Output: PhaseMetrics{TradingDays, Return%, Sharpe, WinRate, MaxDD}

---

3. CONTRACT (Input/Output/Status)

Input

ReplayResult {
  DailyReturns: List<(DateOnly, decimal)>,
  PortfolioHistory: List<Portfolio>
}

OHLCV Bars {
  Date, Ticker, Close, Volume
}

Output

PhaseBreakdown {
  BullMarket: PhaseMetrics,
  BearMarket: PhaseMetrics,
  Sideways: PhaseMetrics,
  HighVolatility: PhaseMetrics
}

PhaseMetrics {
  TradingDays: int,
  Return: decimal,
  Sharpe: decimal,
  WinRate: decimal,
  MaxDrawdown: decimal
}

Idempotency

• Same input → same regime classification (deterministic)
• PIT safety: No lookahead bias (classify using data available at time t only)

Error Handling

Scenario	Action
No bull days	PhaseMetrics with TradingDays=0
Insufficient data for Sharpe	Return default 0m
Single-day regime	Skip (Sharpe undefined)

---

4. DATA (Schema + Calculation)

Regime Classification Logic

For each trading day t:
  price_30d_ma = EMA(close[t-30:t], span=30)
  
  IF price_30d_ma trending up (slope > 0 for last 5 days)
    CLASSIFY: Bull
  ELSE IF price_30d_ma trending down (slope < 0 for last 5 days)
    CLASSIFY: Bear
  ELSE IF ABS(price - price_30d_ma) / price_30d_ma < 0.05
    CLASSIFY: Sideways
  ELSE IF realized_vol[t] > mean_vol + 2*std_vol
    CLASSIFY: HighVolatility
  ELSE
    CLASSIFY: Sideways (default)

Metrics Calculation (Per Phase)

-- Phase 1: Collect returns by regime
phase_returns = filter(daily_returns, regime == phase)

-- Phase 2: Calculate metrics
total_return = (product(1 + r for r in phase_returns) - 1)
sharpe = mean(phase_returns) / std(phase_returns) * sqrt(252)
win_rate = count(r > 0) / len(phase_returns)
max_dd = calculate_max_drawdown(cumulative_returns)
calmar = total_return / max_dd

Storage

• No database persistence (computed on-demand)
• Included in ShadowRunResult.phase_analysis_json
• Immutable after shadow run completion

---

5. TESTS (Verification)

Unit Tests

Test	Scenario	Expected
Regime_BullTrend	30-day MA rising consistently	All days → Bull
Regime_BearTrend	30-day MA falling consistently	All days → Bear
Regime_Sideways	Price oscillates ±5% around MA	All days → Sideways
Regime_HighVolatility	Realized vol > mean + 2σ	All days → HighVolatility
Metrics_SinglePhase	All returns in Bull phase	Sharpe ≤ 5, WinRate [0,1]
Metrics_MultiPhase	Mixed returns across phases	Each phase computed separately
Metrics_EmptyPhase	No returns in Bear phase	TradingDays=0, Return=0

Integration Tests

Test	Scenario	Expected
PhaseBreakdown_SumsDays	Sum(TradingDays across phases)	= Total trading days
PhaseBreakdown_Consistency	Bull + Bear + Sideways + Vol days	= Portfolio history length
PhaseBreakdown_NoLookahead	Regime known only from t-30 data	Classification deterministic

Data Tests

Test	Scenario	Expected
Sharpe_Calculation	Known returns + vol	Matches manual calculation
MaxDD_Calculation	Simulated drawdown sequence	Matches cumulative peak-to-trough

---

6. OPS (Deployment + Monitoring)

Startup

• Phase segmentation runs after replay (inside ShadowRunJob)
• No external dependencies (uses replay results + OHLCV bars from backfill)
• Deterministic: No randomness, no API calls

Monitoring

• Alert if any phase has 0 trading days (data gap)
• Alert if Sharpe calculation fails (log error, use default 0)
• Metrics validation: WinRate ∈ [0,1], Sharpe ∈ [-5,5]

Rollback

• Phase segmentation is read-only compute (no state changes)
• If calculation fails: return zeros for that phase
• Job continues (non-blocking)

---

7. OUTPUT RULE (Deliverables)

Changed files:

src/KArtSell.Modules.ModelOperations/
  ShadowRun/
    PhaseSegmentation.cs          (Main calculator)
    RegimeClassifier.cs           (Bull/Bear/Sideways/Vol logic)
    PhaseMetricsCalculator.cs     (Sharpe, Calmar, etc.)

tests/KArtSell.Integration.Tests/
  PhaseSegmentationTests.cs       (Unit tests)
  PhaseSegmentationIntegrationTests.cs (Integration tests)

Verification:

dotnet test --filter "PhaseSegmentation" -c Release
# Expected: All tests green

---

8. AGENTS.md v16.0 CHECKLIST

Criterion	Status	Evidence
SOLID	✅ Design	RegimeClassifier (single responsibility), DI ready
Complexity	✅ Design	Regime logic cyclomatic < 10, metrics calc < 10
Audit	✅ Design	PIT safety: classify using only historical data
Necessity	✅ Sourced	README.md: "복수 국면 OOS" requirement
Normalization	✅ Design	Read-only compute, immutable output in JSONB
Simplicity	✅ Design	Clear regime rules, deterministic classification
Pattern	✅ Design	Vertical component (Segmenter → Classifier → Metrics)
Guardrails	✅ Design	No lookahead, error handling (empty phases), bounds checking
Traceability	✅ Design	Regime per-day logged, metrics tagged with phase name
Safety	✅ Design	Idempotent (same input = same regime), read-only
Maturity	✅ Design	Contract → Test → Implementation sequencing
Right Way	✅ Design	PIT-safe classification, no shortcuts
Debt	✅ Design	Zero new tech debt, uses existing infrastructure

---

NEXT STEPS (Sequenced)

Step 1: RegimeClassifier

• Implement regime detection logic (Bull/Bear/Sideways/Vol)
• Unit tests: Each regime type

Step 2: PhaseMetricsCalculator

• Calculate Sharpe, Calmar, Max DD, Win Rate per phase
• Unit tests: Metric calculations

Step 3: PhaseSegmentation (Orchestrator)

• Integrate classifier + metrics calculator
• Integration tests: Full phase breakdown

Step 4: ShadowRunJob Integration

• Call PhaseSegmentation after MetricsCalculator
• Populate result.PhaseAnalysis
• Tests: End-to-end shadow run with phase breakdown

Step 5: Validation

• Build passes, tests 100% green
• Commit & push