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)