nt8-sdk/.kilocode/rules/project_context.md

# Project Context - Phase 2

You are working on the **NT8 SDK** - an institutional-grade trading SDK for NinjaTrader 8.

## Project Purpose

This is production trading software used for automated futures trading (ES, NQ, MES, MNQ, CL, GC). Code quality is critical because:
- Bugs can cause real financial losses
- System runs 24/5 during market hours
- Performance requirements are strict (<200ms latency)
- This is institutional-grade, not hobbyist code

## Current Phase: Phase 2 - Enhanced Risk & Sizing

You are implementing **advanced risk management and intelligent position sizing**.

### Phase 2 Responsibilities
- Advanced risk rules (Tiers 2-3)
- Optimal-f position sizing (Ralph Vince method)
- Volatility-adjusted sizing
- Enhanced OMS features (partial fills, retry, reconciliation)

### What Phase 2 Does NOT Do (Other Components Handle)
- Basic risk validation (BasicRiskManager handles this - Phase 1)
- Strategy logic (IStrategy handles this - Phase 1)
- Order lifecycle management (BasicOrderManager handles this - Phase 1)
- Direct NT8 calls (NT8Adapter handles this - Future)

## Architecture Overview

```
Strategy Layer (IStrategy) - Phase 1 ✅
        ↓ generates StrategyIntent
Risk Layer (IRiskManager)
        ├─ BasicRiskManager - Phase 1 ✅
        └─ AdvancedRiskManager - Phase 2 ← YOU ARE HERE
        ↓ validates and produces RiskDecision
Sizing Layer (IPositionSizer)
        ├─ BasicPositionSizer - Phase 1 ✅
        └─ EnhancedPositionSizer - Phase 2 ← YOU ARE HERE
        ↓ calculates contracts and produces SizingResult
OMS Layer (IOrderManager) - Phase 1 ✅ (enhancing in Phase 2)
        ↓ manages order lifecycle
NT8 Adapter Layer (INT8OrderAdapter) - Future
        ↓ bridges to NinjaTrader 8
NinjaTrader 8 Platform
```

## Your Current Task

Implement **Enhanced Risk & Sizing** with these deliverables:

### Phase 2 Deliverables
**Risk Management:**
1. ✅ `AdvancedRiskModels.cs` - Weekly tracking, drawdown, exposure
2. ✅ `AdvancedRiskManager.cs` - All Tier 2-3 risk rules
3. ✅ Update `RiskConfig.cs` - Add new configuration properties

**Position Sizing:**
4. ✅ `SizingModels.cs` - Optimal-f, volatility models
5. ✅ `OptimalFCalculator.cs` - Ralph Vince algorithm
6. ✅ `VolatilityAdjustedSizer.cs` - ATR/StdDev sizing
7. ✅ `EnhancedPositionSizer.cs` - All advanced sizing methods

**Enhanced OMS:**
8. ✅ `OrderStateMachine.cs` - Formal state machine
9. ✅ Update `OrderModels.cs` - Add partial fill models
10. ✅ Update `BasicOrderManager.cs` - Add enhanced methods

**Testing:**
11. ✅ Comprehensive unit tests (90+ tests total)
12. ✅ Integration tests (risk + sizing flow)
13. ✅ Performance benchmarks (<5ms risk, <3ms sizing)

### Out of Scope (Future Phases)
- ❌ Market microstructure (Phase 3)
- ❌ Advanced order types (Phase 3)
- ❌ Confluence scoring (Phase 4)
- ❌ ML-based features (Phase 6)

## Key Design Principles

### 1. Risk-First Architecture
ALL trading operations flow through risk management before execution.
The pattern is: Strategy → Risk → Sizing → OMS → NT8
**NEVER bypass risk checks.**

### 2. Backward Compatibility
Phase 2 MUST NOT break Phase 1:
- BasicRiskManager still works
- BasicPositionSizer still works
- BasicOrderManager still works
- No interface signature changes

### 3. Thread Safety
This system will run with:
- Multiple strategies executing simultaneously
- Multiple NT8 callbacks firing
- UI queries happening during trading
- State changes from external events

ALL shared state MUST be protected with locks.

### 4. Performance Targets
- Risk validation: <5ms (was <10ms in Phase 1)
- Sizing calculation: <3ms (was <5ms in Phase 1)
- Overall tick-to-trade: <200ms (unchanged)
- No degradation to Phase 1 performance

### 5. Determinism
All calculations must be deterministic for:
- Backtesting accuracy
- Replay debugging
- Audit trails

## Technology Constraints

### Language & Framework
- C# 5.0 syntax ONLY (no C# 6+)
- .NET Framework 4.8 (not .NET Core/5+/6+)
- Target: Windows desktop environment

### Libraries
- ✅ Newtonsoft.Json (for serialization)
- ✅ Microsoft.Extensions.Logging (for logging)
- ✅ Microsoft.Extensions.DependencyInjection (for DI)
- ❌ System.Text.Json (not available)
- ❌ Any .NET Core/5+/6+ libraries

### Testing
- xUnit for test framework
- FluentAssertions for assertions
- Bogus for test data generation (if needed)
- Mock adapters for isolation

## Reference Documents

You have access to these design documents:
- `Phase2_Implementation_Guide.md` - Step-by-step tasks
- `nt8_phasing_plan.md` - Overall project plan
- `nt8_dev_spec.md` - Technical specifications

When uncertain about design decisions, reference these documents.

## Success Criteria

Your implementation is complete when:
- [ ] All 15 Phase 2 files created
- [ ] `verify-build.bat` passes
- [ ] >90 total tests passing
- [ ] >80% test coverage for new code
- [ ] No C# 6+ syntax
- [ ] Thread safety verified
- [ ] Performance targets met
- [ ] No breaking changes to Phase 1
- [ ] Integration tests pass
- [ ] Documentation complete

## Phase 1 Foundation (What You're Building On)

### Already Complete ✅
- OrderModels with all enums
- IOrderManager interface
- BasicOrderManager with state machine
- BasicRiskManager with Tier 1 rules
- BasicPositionSizer with fixed methods
- 34 passing unit tests
- Mock adapters for testing

### Phase 1 Code You Can Reference
- `src/NT8.Core/Risk/BasicRiskManager.cs` - Pattern to follow
- `src/NT8.Core/Sizing/BasicPositionSizer.cs` - Pattern to follow
- `src/NT8.Core/OMS/BasicOrderManager.cs` - Pattern to extend
- `tests/NT8.Core.Tests/Risk/BasicRiskManagerTests.cs` - Test pattern

## Communication

When you need clarification:
1. Check `Phase2_Implementation_Guide.md` first
2. Check existing Phase 1 code patterns
3. If still uncertain, ask before implementing

**Remember:** This is production trading code. When in doubt, ask rather than guess.

## Current Status

**Completed:**
- ✅ Phase 0: Foundation
- ✅ Phase 1: Basic OMS, Risk, Sizing (34 tests passing)

**In Progress:**
- 🔄 Phase 2: Enhanced Risk & Sizing ← **YOU ARE HERE**

**Next:**
- ⏭️ Phase 3: Market Microstructure
- ⏭️ Phase 4: Intelligence & Grading
- ⏭️ Phase 5: Analytics
- ⏭️ Phase 6: Advanced Features

**Progress:** ~10% → ~20% (Phase 2 will double completed functionality)