Phase 0 completion: NT8 SDK core framework with risk management and position sizing

2025-09-09 17:06:37 -04:00
parent 97e5050d3e
commit 92f3732b3d
109 changed files with 38593 additions and 380 deletions
--- a/AI_DEVELOPMENT_GUIDELINES.md
+++ b/AI_DEVELOPMENT_GUIDELINES.md
@@ -0,0 +1,192 @@
+# NT8 SDK - AI Development Guidelines
+
+## 🚨 CRITICAL: .NET Framework 4.8 Compatibility Requirements
+
+This project MUST maintain compatibility with NinjaTrader 8, which requires:
+- **.NET Framework 4.8** (NOT .NET Core/.NET 5+)
+- **C# 5.0 language features only**
+- **Traditional class syntax** (NO records, nullable references, etc.)
+
+## Language Restrictions (C# 5.0 Only)
+
+### ❌ FORBIDDEN FEATURES
+- `record` types → Use `class` with constructors
+- Nullable reference types (`string?`) → Use `string`
+- String interpolation (`$"Hello {name}"`) → Use `String.Format("Hello {0}", name)`
+- Dictionary initializers (`new Dictionary<string, object> { ["key"] = value }`) → Use `dict.Add("key", value)`
+- Pattern matching → Use `switch` statements or `if/else`
+- Auto-property initializers → Initialize in constructor
+- Expression-bodied members → Use full method bodies
+- `nameof` operator → Use string literals
+- Exception filters → Use try/catch blocks
+- Async Main → Use traditional Main methods
+
+### ✅ ALLOWED FEATURES
+- Traditional classes with properties and methods
+- Constructors with parameters
+- Standard interfaces and inheritance
+- LINQ (System.Linq)
+- Generics
+- Extension methods
+- Lambda expressions
+- Anonymous types
+- var keyword
+- Traditional async/await (with Task)
+
+## Project Structure Rules
+
+### Framework Targeting
+ALL projects must target `net48`:
+```xml
+<TargetFramework>net48</TargetFramework>
+<LangVersion>5.0</LangVersion>
+```
+
+### Package Restrictions
+- **NO Microsoft.Extensions.*** packages (use custom implementations)
+- **NO System.Text.Json** (use Newtonsoft.Json)
+- **NO modern testing frameworks** (use MSTest for .NET Framework)
+
+### Required Using Statements
+Always include these for basic functionality:
+```csharp
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading.Tasks; // if async needed
+```
+
+## Architecture Rules
+
+### 1. Risk-First Design
+- ALL trading intents MUST pass through IRiskManager
+- Risk validation happens BEFORE position sizing
+- No strategy can bypass risk controls
+
+### 2. Thin Strategy Pattern
+- Strategies implement ONLY signal generation
+- No direct market access from strategies
+- All execution goes through SDK framework
+
+### 3. Deterministic Behavior
+- Same inputs MUST produce same outputs
+- No random number generation without seeds
+- All calculations must be reproducible
+
+## Code Style Requirements
+
+### Class Structure
+```csharp
+// ✅ Correct C# 5.0 class
+public class StrategyIntent
+{
+    public string Symbol { get; set; }
+    public OrderSide Side { get; set; }
+    
+    public StrategyIntent(string symbol, OrderSide side)
+    {
+        Symbol = symbol;
+        Side = side;
+    }
+}
+
+// ❌ FORBIDDEN - Record syntax
+public record StrategyIntent(string Symbol, OrderSide Side);
+```
+
+### Dictionary Initialization
+```csharp
+// ✅ Correct C# 5.0 syntax
+var metrics = new Dictionary<string, object>();
+metrics.Add("trade_risk", riskAmount);
+metrics.Add("daily_pnl", dailyPnL);
+
+// ❌ FORBIDDEN - Dictionary initializer
+var metrics = new Dictionary<string, object> 
+{ 
+    ["trade_risk"] = riskAmount,
+    ["daily_pnl"] = dailyPnL 
+};
+```
+
+### String Formatting
+```csharp
+// ✅ Correct C# 5.0 syntax
+_logger.LogDebug("Order approved: {0} {1} risk=${2:F2}", 
+    intent.Symbol, intent.Side, tradeRisk);
+
+// ❌ FORBIDDEN - String interpolation
+_logger.LogDebug($"Order approved: {intent.Symbol} {intent.Side} risk=${tradeRisk:F2}");
+```
+
+## Testing Requirements
+
+### Use MSTest Framework
+```csharp
+[TestClass]
+public class BasicRiskManagerTests
+{
+    [TestMethod]
+    public void ValidateOrder_ShouldPass()
+    {
+        // Test implementation
+        Assert.IsTrue(result.Allow);
+    }
+}
+```
+
+### Test Coverage Requirements
+- Minimum 80% code coverage for core components
+- All risk scenarios must be tested
+- All position sizing calculations must be validated
+
+## Build Verification
+
+Before committing ANY code, run:
+```bash
+.\verify-build.bat
+```
+
+This MUST pass with zero errors and warnings.
+
+## Phase Development Rules
+
+### Phase 1 Focus Areas (ONLY)
+- NT8 adapter implementations
+- Market data integration
+- Order execution system
+- Enhanced risk controls (Tier 2)
+
+### DO NOT IMPLEMENT
+- Advanced features from later phases
+- Modern C# language features
+- Complex UI components
+- Performance optimizations (until Phase 3)
+
+## Common Pitfalls to Avoid
+
+1. **Using modern C# syntax** - Stick to C# 5.0 only
+2. **Adding .NET Core packages** - Use .NET Framework compatible only
+3. **Bypassing risk management** - All trades must go through IRiskManager
+4. **Complex inheritance hierarchies** - Keep design simple and testable
+5. **Hardcoding values** - Use configuration classes
+
+## AI Agent Checklist
+
+Before implementing ANY feature:
+- [ ] Does this maintain .NET Framework 4.8 compatibility?
+- [ ] Does this use only C# 5.0 language features?
+- [ ] Does this follow the risk-first architecture?
+- [ ] Does this include appropriate error handling?
+- [ ] Does this include unit tests?
+- [ ] Does this compile without warnings?
+
+## Emergency Contacts
+
+If agents encounter compatibility issues:
+1. Check this document first
+2. Review existing working code patterns
+3. Test with `.\verify-build.bat`
+4. Flag for human review if unsure
+
+Remember: **Compatibility with NT8 is non-negotiable.** When in doubt, use simpler, more traditional code patterns.