diff --git a/.kilocode/rules/Compile error guidance.md b/.kilocode/rules/Compile error guidance.md index 73a546d..7dd0b35 100644 --- a/.kilocode/rules/Compile error guidance.md +++ b/.kilocode/rules/Compile error guidance.md @@ -1,204 +1,35 @@ -ALWAYS verify with the live Ninjascript reference available on the web at https://developer.ninjatrader.com/docs/desktop before making final edits. - -This third file confirms a recurrence of CS0246 compiler errors in VWAP_Pro.cs, specifically related to undefined types like ModeType and AnchorModeType. - -πŸ” CS0246 - "The type or namespace name 'X' could not be found" -Line Column Missing Type -371 28 ModeType -371 43 AnchorModeType -391 39 ModeType -391 54 AnchorModeType -376 51 ModeType -βœ… How to Fix It -πŸ”§ 1. Define Missing Enums (Recommended Fix) - -It seems that ModeType and AnchorModeType are custom enums that were expected to exist in the code but were never declared. - -Create a separate file or include this in the same VWAP_Pro.cs file near the top: - -public enum ModeType -{ - Standard, - Aggressive, - Conservative -} - -public enum AnchorModeType -{ - SessionStart, - FixedTime, - Custom -} - - -You’ll need to customize the enum values (Standard, Aggressive, etc.) to match your strategy logic. These names are placeholders based on typical VWAP settings. - -πŸ”§ 2. OR Add Missing using Directives - -If these types exist in another NinjaTrader script or add-on you've imported before, ensure you include the right namespace: - -using NinjaTrader.NinjaScript.AddOns.MyVWAPEnums; // Example - - -But since these errors suggest the types are completely undefined, it's much more likely they are simply not declared anywhere. - -πŸ”§ 3. Verify File Inclusion in NinjaTrader - -If these enums are defined in another file (e.g., VWAPTypes.cs), make sure: - -It's saved in the same directory as VWAP_Pro.cs - -It's added to the NinjaScript Editor, not just sitting in the file system - -You can add it using: - -Tools > NinjaScript Editor > Right-click > Add > Existing Item... - -🧼 Suggested Organization - -If these enums are used across multiple indicators/strategies, you should centralize them: - -VWAP_Enums.cs - -namespace NinjaTrader.NinjaScript.VWAP -{ - public enum ModeType - { - Standard, - Aggressive, - Conservative - } - - public enum AnchorModeType - { - SessionStart, - FixedTime, - Custom - } -} - - -Then use: - -using NinjaTrader.NinjaScript.VWAP; - - - -These are occurring in VWAP_Pro.cs, mainly on lines 132–134: - -Line Error Message (Truncated) -132 Argument 2: cannot convert from 'int' to 'NinjaTrader.Gui.Tools.SimpleFont' -132 Argument 3: cannot convert from 'NinjaTrader.Gui.Tools.SimpleFont' to 'System.Windows.Media.Brush' -133 Same as above -134 Same as above -πŸ”§ Interpretation: - -It looks like a method (likely a drawing method like Draw.Text() or Draw.TextFixed()) is being called with the wrong argument types β€” specifically: - -An int is being passed where a SimpleFont is expected. - -A SimpleFont is being passed where a Brush is expected. - -This suggests that arguments are out of order or misassigned. - -βœ… Proper Fix - -Let’s consider the proper usage of Draw.Text() in NinjaTrader 8: - -Draw.Text(NinjaScriptBase owner, string tag, bool isAutoScale, string text, int barsAgo, double y, Brush textBrush, SimpleFont font, TextAlignment alignment, Brush outlineBrush, int outlineWidth); - - -Or for simpler usage: - -Draw.Text(this, "tag1", "Hello", 0, Close[0], Brushes.White); - - -Your issue likely looks like this: - -Draw.Text(this, "tag1", true, "Label", 0, 100, 12, someFont, ...); - - -Where 12 (int) is mistakenly passed as a font or brush, causing the error. - -πŸ”§ Corrected Example: - -Assuming you want to draw text with a specific font and color: - -SimpleFont font = new SimpleFont("Arial", 12); -Draw.Text(this, "tag1", true, "VWAP Label", 0, Close[0], Brushes.White, font, TextAlignment.Center, Brushes.Black, 1); - - -Brushes.White β†’ text color - -font β†’ SimpleFont object - -TextAlignment.Center β†’ alignment - -Brushes.Black β†’ outline brush - -1 β†’ outline width - -βœ… Steps to Fix: - -Replace the integer (e.g., 12) with a SimpleFont: - -new SimpleFont("Arial", 12) - - -Ensure arguments are in the correct order: -Double-check the method signature from the NinjaTrader 8 Help Guide -. - -Use Brushes for colors, not fonts. - - - - - - -Summary of Errors: -Line Column Missing Type -403 39 ModeType -403 54 AnchorModeType -408 63 ModeType -408 78 AnchorModeType -367 28 ModeType -βœ… Fixes: - -These types β€” ModeType and AnchorModeType β€” are not recognized. Here are the likely causes and solutions: - -πŸ” 1. Missing using Directive - -These types might be defined in a different namespace. If they are from a custom or NinjaTrader add-on: - -Fix: Add the appropriate using statement at the top of your file. - -Example: - -using NinjaTrader.NinjaScript.AddOns.VWAP; - - -Adjust according to where ModeType and AnchorModeType are defined. - -πŸ” 2. Missing Class Definitions - -If they are not in any existing libraries, they might be custom enum types that should be defined in your project but are missing. - -Fix: Add enum declarations like these (if applicable): - -public enum ModeType -{ - Standard, - Aggressive, - Conservative -} - -public enum AnchorModeType -{ - SessionStart, - FixedTime, - Custom -} - - -Only do this if you know what the enum values should be. These names are placeholders β€” you should match them with how your indicator/strategy is designed. \ No newline at end of file +# Compile Error Guidance - Reusable Protocol +**Last Updated:** 2026-04-05 + +Apply this protocol for all compile issues. + +## 1) Verify First +- [ ] Verify exact NinjaScript/API signature against official NT8 docs before editing: `https://developer.ninjatrader.com/docs/desktop`. +- [ ] Confirm file is in scope before making any change. + +## 2) Classify the Error +- [ ] Missing type/namespace (e.g., `CS0246`). +- [ ] Invalid override/signature/access modifier (e.g., `CS0115`, `CS0507`). +- [ ] Argument mismatch or wrong overload (e.g., `CS1503`). +- [ ] C# language version incompatibility (C# 6+ syntax in C# 5 project). + +## 3) Apply Smallest Safe Fix +- [ ] Prefer minimal edits in scoped files only. +- [ ] Fix root cause, not symptom chaining. +- [ ] Preserve existing architecture/contracts unless task explicitly requires change. + +## 4) Re-Run Verification +- [ ] Run `.\verify-build.bat`. +- [ ] Run required tests for changed area. +- [ ] If NinjaScript touched, run NT8 compile check in NinjaScript Editor. + +## 5) Capture Durable Learning +For non-trivial compile failures, add concise entries to: +- [ ] `docs/00-governance/common_failures.md` (error fingerprint + fix). +- [ ] `docs/00-governance/compile_guardrails.md` (prevention rule). +- [ ] `docs/00-governance/patterns_and_antipatterns.md` (good vs bad pattern). + +## Do Not +- [ ] Do not guess signatures, overloads, enums, or attributes. +- [ ] Do not invent placeholder enums/types unless confirmed by domain/task requirements. +- [ ] Do not keep one-off incident dumps in this rule file; store incidents in `common_failures.md`. diff --git a/.kilocode/rules/coding_patterns.md b/.kilocode/rules/coding_patterns.md index e123b0c..cfaea93 100644 --- a/.kilocode/rules/coding_patterns.md +++ b/.kilocode/rules/coding_patterns.md @@ -1,252 +1,33 @@ -# Coding Patterns β€” NT8 SDK Required Patterns -**Last Updated:** 2026-03-27 +# Coding Patterns - NT8 SDK Required Patterns +**Last Updated:** 2026-04-05 -All code in the NT8 SDK MUST follow these patterns without exception. +All production code must use these implementation patterns. ---- +## Scope Discipline and Minimum Diff +- [ ] Edit only files in task scope. +- [ ] Make the smallest safe change that resolves the issue. +- [ ] Do not change interfaces/contracts unless explicitly required. +- [ ] Do not mix functional changes with style-only cleanup. -## 0. C# 5.0 Hard Constraints (NinjaScript Compiler) +## C# 5.0 and .NET 4.8 Compatibility +- [ ] Use C# 5.0 syntax only. +- [ ] Avoid C# 6+ features (`$""`, `?.`, `nameof`, expression-bodied members, `out var`, etc.). +- [ ] Keep compatibility with .NET Framework 4.8. +- [ ] Use `string.Format` style logging/messages. -```csharp -// ❌ PROHIBITED β€” compiler will fail silently or error -$"Hello {name}" // no string interpolation -obj?.Method() // no null-conditional -public int Prop => _value; // no expression body -nameof(SomeClass) // no nameof -await SomeAsync() // no async/await +## Core Implementation Patterns +- [ ] Validate inputs at method entry. +- [ ] Wrap public method logic in `try/catch` with meaningful logging. +- [ ] Protect shared mutable collections/state with `lock (_lock)`. +- [ ] Do not raise events while holding locks. +- [ ] Keep public members documented with XML comments where required by project standards. -// βœ… REQUIRED -string.Format("Hello {0}", name) -obj != null ? obj.Method() : null -public int Prop { get { return _value; } } -"SomeClass" // string literal -// synchronous only -``` +## NinjaScript Coding Patterns (When Applicable) +- [ ] Keep `OnStateChange` responsibilities separated by state. +- [ ] Guard `OnBarUpdate` by `BarsInProgress` and bar readiness. +- [ ] In managed order flow, set stop/target before entry on the same bar. ---- - -## 0b. NT8-Specific Critical Rules - -```csharp -// SetStopLoss/SetProfitTarget MUST come BEFORE EnterLong/EnterShort -// Calling them after is silently ignored in backtest -SetStopLoss(signalName, CalculationMode.Ticks, stopTicks, false); // FIRST -SetProfitTarget(signalName, CalculationMode.Ticks, targetTicks); // SECOND -EnterShort(qty, signalName); // THIRD - -// OnBarUpdate must guard secondary series -protected override void OnBarUpdate() -{ - if (BarsInProgress != 0) return; // CRITICAL: ignore daily bar series updates - // ... -} - -// State guard in ProcessStrategyIntent -// Allows Historical (backtest), blocks Realtime replay burst: -if (State == State.Realtime && !_realtimeBarSeen) - return; -``` - ---- - -## Sizing Formula - -``` -contracts = floor(RiskPerTrade / (StopTicks Γ— TickValue)) -NQ tick value = $5.00 -$100 / (8 Γ— $5) = 2 contracts -$200 / (8 Γ— $5) = 5 contracts (capped at MaxContracts) -Always verify: RiskPerTrade ≀ MaxTradeRisk -``` - ---- - -## 1. Thread Safety β€” Lock Everything Shared - -Every class with shared state must have a lock object: -```csharp -private readonly object _lock = new object(); -``` - -Every access to shared `Dictionary`, `List`, `Queue`, or any field touched by multiple threads: -```csharp -// ❌ NEVER -_activeOrders[orderId] = status; - -// βœ… ALWAYS -lock (_lock) -{ - _activeOrders[orderId] = status; -} -``` - -### Read-then-write must be atomic -```csharp -// ❌ WRONG β€” race condition between check and write -if (!_orders.ContainsKey(id)) - _orders[id] = newOrder; - -// βœ… CORRECT -lock (_lock) -{ - if (!_orders.ContainsKey(id)) - _orders[id] = newOrder; -} -``` - ---- - -## 2. Error Handling β€” Try-Catch on All Public Methods - -```csharp -public ReturnType MethodName(Type parameter) -{ - // 1. Validate parameters first - if (parameter == null) - throw new ArgumentNullException("parameter"); - - // 2. Wrap the main logic - try - { - // Implementation - return result; - } - catch (SpecificException ex) - { - _logger.LogError("Specific failure in MethodName: {0}", ex.Message); - throw; - } - catch (Exception ex) - { - _logger.LogError("Unexpected failure in MethodName: {0}", ex.Message); - throw; - } -} -``` - ---- - -## 3. Logging β€” Always string.Format, Never $"" - -```csharp -// ❌ NEVER β€” C# 6 syntax, breaks NT8 compile -_logger.LogInformation($"Order {orderId} filled"); - -// βœ… ALWAYS -_logger.LogInformation("Order {0} filled", orderId); -_logger.LogWarning("Risk check failed for {0}: {1}", symbol, reason); -_logger.LogError("Exception in {0}: {1}", "MethodName", ex.Message); -_logger.LogCritical("Emergency flatten triggered: {0}", reason); -``` - -### Log level guide -| Level | When to use | -|---|---| -| `LogTrace` | Entering/exiting methods, fine-grained flow | -| `LogDebug` | State reads, normal data flow | -| `LogInformation` | Important events: order submitted, filled, cancelled | -| `LogWarning` | Recoverable issues: validation failed, limit approaching | -| `LogError` | Failures: exceptions, unexpected states | -| `LogCritical` | System integrity issues: emergency flatten, data corruption | - ---- - -## 4. Events β€” Never Raise Inside Locks - -Raising events inside a lock causes deadlocks when event handlers acquire other locks. - -```csharp -// ❌ DEADLOCK RISK -lock (_lock) -{ - _state = newState; - OrderStateChanged?.Invoke(this, args); // handler may try to acquire _lock -} - -// βœ… CORRECT -OrderState newState; -lock (_lock) -{ - newState = CalculateNewState(); - _state = newState; -} -// Raise AFTER releasing lock -RaiseOrderStateChanged(orderId, previousState, newState); -``` - ---- - -## 5. Constructor β€” Validate All Dependencies - -```csharp -public MyClass(ILogger logger, ISomeDependency dep) -{ - if (logger == null) - throw new ArgumentNullException("logger"); - if (dep == null) - throw new ArgumentNullException("dep"); - - _logger = logger; - _dep = dep; - - // Initialize collections - _activeOrders = new Dictionary(); - - _logger.LogInformation("MyClass initialized"); -} -``` - ---- - -## 6. XML Documentation β€” Required on All Public Members - -```csharp -/// -/// Brief one-line description of what this does. -/// -/// The trading intent to validate. -/// Current strategy context with account state. -/// Risk decision indicating allow or reject. -/// Thrown when intent or context is null. -public RiskDecision ValidateOrder(StrategyIntent intent, StrategyContext context) -{ - ... -} -``` - ---- - -## 7. NT8-Specific Patterns (NinjaScript) - -When writing code that runs inside NinjaTrader (in `NT8.Adapters/`): - -```csharp -// Always guard OnBarUpdate -protected override void OnBarUpdate() -{ - if (BarsInProgress != 0) return; - if (CurrentBar < BarsRequiredToTrade) return; - // ... -} - -// Managed order pattern β€” set stops BEFORE entry -SetStopLoss("SignalName", CalculationMode.Ticks, stopTicks, false); -SetProfitTarget("SignalName", CalculationMode.Ticks, targetTicks); -EnterLong(contracts, "SignalName"); - -// Use string.Format for Print() too -Print(string.Format("Order submitted: {0} contracts at {1}", qty, price)); -``` - ---- - -## 8. Checklist Before Marking Any Method Complete - -- [ ] Parameter null checks at the top -- [ ] `try-catch` wrapping the body -- [ ] All `Dictionary`/collection access inside `lock (_lock)` -- [ ] All logging uses `string.Format()` (no `$""`) -- [ ] XML `/// ` on every public method, property, class -- [ ] No C# 6+ syntax -- [ ] Events raised outside lock blocks -- [ ] `verify-build.bat` passes +## Authoritative Rule References (Do Not Duplicate) +- Syntax constraints: `.kilocode/rules/csharp_50_syntax.md` +- NT8 compile and API constraints: `.kilocode/rules/nt8compilespec.md` +- Verification commands and gates: `.kilocode/rules/verification_requirements.md` diff --git a/.kilocode/rules/development_workflow.md b/.kilocode/rules/development_workflow.md index 9d739a5..67516d7 100644 --- a/.kilocode/rules/development_workflow.md +++ b/.kilocode/rules/development_workflow.md @@ -1,344 +1,46 @@ -# NT8-SDK β€” Kilocode Development Workflow -**Last Updated:** 2026-03-27 - -This is the authoritative workflow for all development work on NT8-SDK using Kilocode. - ---- - -## Division of Labor - -| Role | Responsibility | -|---|---| -| **Claude** | Architecture, diagnosis, Kilocode prompt authoring, sequencing | -| **Kilocode** | ALL code implementation β€” zero exceptions | -| **Mo** | Strategy direction, backtest execution, log collection, go/no-go | - ---- - -## Per-Task Workflow - -1. **Claude writes Kilocode prompt** β€” exact Find/Replace, both file paths, build command, validation checklist -2. **Mo runs Kilocode** β€” pastes prompt, Kilocode executes -3. **Kilocode reports** β€” build output + files changed -4. **Mo brings results to Claude** β€” Kilocode report + session log + CSV -5. **Claude diagnoses** β€” confirms or issues follow-up prompt -6. **Mo commits:** `git add` β†’ `git commit` β†’ `git push` -7. **Update SPRINT_BOARD** β€” task to Done or Blocked - ---- - -## Kilocode Prompt Template - -``` -TASK: [one-line description] - -CONTEXT: -[1-3 sentences explaining why] - -FILES TO MODIFY: -1. C:\dev\nt8-sdk\src\... [repo path] -2. C:\Users\billy\...\Strategies\... [NT8 path β€” same change] - -CHANGE 1 β€” [description]: -File: [path] -Find: -[exact existing code] -Replace with: -[new code] - -BUILD & DEPLOY: -1. dotnet build NT8-SDK.sln --configuration Release -2. deployment\deploy-to-nt8.bat -3. NT8: Tools β†’ Edit NinjaScript β†’ open NT8StrategyBase.cs β†’ save - -VALIDATION: -- Run Strategy Analyzer: NQ JUN26, Jan 1 2026 β†’ Mar 27 2026 -- Look for in session log: [specific confirmation lines] -``` - ---- - -## Guardrails β€” Kilocode MUST NEVER - -1. Modify files outside the task spec -2. Use C# 6+ syntax -3. Remove existing comments or XML documentation -4. Change interface signatures -5. Deploy without building first -6. Edit NT8 path without also updating repo path -7. Guess NT8 API signatures -8. Introduce async/await - ---- - -## Log Analysis Quick Reference - -**Healthy dual-leg trade in session log:** -``` -SIGNAL Sell | Grade=A | Score=0.820 -SUBMIT Scaler=1 Runner=1 Stop=8 Target=20 -FILL Short 1 @ XXXXX <- scaler fill -PNL_UPDATE Position=Short Qty=1 -FILL Short 1 @ XXXXX <- runner fill -PNL_UPDATE Position=Short Qty=2 <- CRITICAL: Qty=2 = runner entered -``` - -**Warning signs:** -- SUBMIT then only 1 FILL β†’ runner blocked (check EntriesPerDirection + MaxOpenPositions) -- Multiple SIGNALs in milliseconds β†’ replay burst (_realtimeBarSeen not working) -- SIGNAL then nothing β†’ ProcessStrategyIntent guard blocking backtest - ---- - -## Commit Message Format - -``` -feat: description <- new feature -fix: description <- bug fix -refactor: description <- no behavior change -test: description <- tests only -docs: description <- documentation only -``` - ---- - -## Original Archon Workflow (2025, archived below) - -## Archon Workflow Principles - -The development process follows these core principles adapted from the Archon workflow: - -### 1. Check Current Task -Before beginning any work, clearly define what needs to be accomplished: -- Review requirements and specifications -- Understand success criteria -- Identify dependencies and blockers - -### 2. Research for Task -Conduct thorough research before implementation: -- Review existing code and documentation -- Understand best practices and patterns -- Identify potential challenges and solutions - -### 3. Implement the Task -Execute the implementation with focus and precision: -- Follow established patterns and conventions -- Write clean, maintainable code -- Include comprehensive error handling -- Add structured logging for observability - -### 4. Update Task Status -Track progress and document completion: -- Mark tasks as completed in the todo list -- Document any issues or deviations -- Note lessons learned for future reference - -### 5. Get Next Task -Move systematically through the implementation: -- Prioritize tasks based on dependencies -- Focus on one task at a time -- Ensure quality before moving forward - -## Development Process - -### Phase 1: Planning and Design -1. Review specifications and requirements -2. Create architecture diagrams and documentation -3. Identify core components and their interactions -4. Plan implementation approach and timeline - -### Phase 2: Environment Setup -1. Create project structure and configuration files -2. Set up build and test infrastructure -3. Configure CI/CD pipeline -4. Verify development environment - -### Phase 3: Core Implementation -1. Implement core interfaces and models -2. Develop risk management components -3. Create position sizing algorithms -4. Build supporting utilities and helpers - -### Phase 4: Testing and Validation -1. Create comprehensive unit tests -2. Implement integration tests -3. Run validation scripts -4. Verify all success criteria - -### Phase 5: Documentation and Delivery -1. Create developer documentation -2. Write user guides and examples -3. Prepare release notes -4. Conduct final validation - -## Code Quality Standards - -### 1. Code Structure -- Follow established naming conventions -- Use consistent formatting and style -- Organize code into logical modules -- Maintain clear separation of concerns - -### 2. Error Handling -- Validate all inputs and parameters -- Provide meaningful error messages -- Handle exceptions gracefully -- Log errors for debugging - -### 3. Testing -- Write unit tests for all public methods -- Include edge case testing -- Validate error conditions -- Maintain >90% code coverage - -### 4. Documentation -- Include XML documentation for all public APIs -- Add inline comments for complex logic -- Document configuration options -- Provide usage examples - -## Git Workflow - -### Branching Strategy -- Use feature branches for all development -- Create branches from main for new features -- Keep feature branches short-lived -- Merge to main after review and testing - -### Commit Guidelines -- Write clear, descriptive commit messages -- Make small, focused commits -- Reference issues or tasks in commit messages -- Squash related commits before merging - -### Pull Request Process -- Create PRs for all feature work -- Include description of changes and testing -- Request review from team members -- Address feedback before merging - -## Development Environment - -### Required Tools -- .NET 6.0 SDK -- Visual Studio Code or Visual Studio -- Git for version control -- Docker Desktop (recommended) - -### Recommended Extensions -- C# for Visual Studio Code -- EditorConfig for VS Code -- GitLens for enhanced Git experience -- Docker extension for container management - -## Build and Test Process - -### Local Development -1. Restore NuGet packages: `dotnet restore` -2. Build solution: `dotnet build` -3. Run tests: `dotnet test` -4. Run specific test categories if needed - -### Continuous Integration -- Automated builds on every commit -- Run full test suite on each build -- Generate code coverage reports -- Deploy to test environments - -## Debugging and Troubleshooting - -### Common Issues -1. **Build Failures** - - Check for missing NuGet packages - - Verify .NET SDK version - - Ensure all projects reference correct frameworks - -2. **Test Failures** - - Review test output for specific errors - - Check test data and setup - - Verify mock configurations - -3. **Runtime Errors** - - Check logs for error details - - Validate configuration settings - - Review dependency injection setup - -### Debugging Tools -- Visual Studio debugger -- Console logging -- Structured logging with correlation IDs -- Performance profiling tools - -## Release Process - -### Versioning -- Follow semantic versioning (MAJOR.MINOR.PATCH) -- Increment version in Directory.Build.props -- Update release notes with changes -- Tag releases in Git - -### Deployment -- Create NuGet packages for SDK components -- Publish to internal package repository -- Update documentation with release notes -- Notify stakeholders of new releases - -## Best Practices - -### 1. Code Reviews -- Review all code before merging -- Focus on correctness, maintainability, and performance -- Provide constructive feedback -- Ensure adherence to coding standards - -### 2. Performance Considerations -- Minimize allocations in hot paths -- Use efficient data structures -- Cache expensive operations -- Profile performance regularly - -### 3. Security -- Validate all inputs -- Sanitize user data -- Protect sensitive configuration -- Follow secure coding practices - -### 4. Maintainability -- Write self-documenting code -- Use meaningful variable and method names -- Keep methods small and focused -- Refactor regularly to improve design - -## Task Management Without Archon - -Since we're not using the Archon MCP server, we'll manage tasks using: -1. **Todo Lists**: Track progress using markdown checklists -2. **Documentation**: Maintain detailed records of implementation decisions -3. **Git**: Use commits and branches to track work progress -4. **Issue Tracking**: Use GitHub Issues or similar for task management - -### Task Status Tracking -- **Todo**: Task identified but not started -- **In Progress**: Actively working on task -- **Review**: Task completed, awaiting validation -- **Done**: Task validated and completed - -## Communication and Collaboration - -### Team Coordination -- Hold regular standups to discuss progress -- Use collaborative tools for communication -- Document architectural decisions -- Share knowledge and best practices - -### Knowledge Sharing -- Conduct code walkthroughs for complex features -- Create technical documentation -- Share lessons learned from issues -- Mentor new team members - -## Conclusion - -This development workflow ensures consistent, high-quality implementation of the NT8 Institutional SDK. By following these principles and practices, we can deliver a robust, maintainable, and scalable trading platform that meets institutional requirements for risk management and performance. - -The workflow emphasizes systematic progress, quality assurance, and continuous improvement. Each task should be approached with thorough research, careful implementation, and comprehensive validation to ensure the highest quality outcome. \ No newline at end of file +# NT8-SDK Development Workflow +**Last Updated:** 2026-04-05 + +Operational workflow for Kilo/Codex-assisted development. + +## Per-Task Workflow (Required) +1. **Confirm scope** + - [ ] Confirm exact files allowed by task spec. + - [ ] Cross-check `.kilocode/rules/file_boundaries.md`. +2. **Set task state** + - [ ] Move task status from `todo` -> `doing` before edits. +3. **Implement** + - [ ] Make minimum-diff changes only in scoped files. +4. **Verify** + - [ ] Run `.\verify-build.bat` per `.kilocode/rules/verification_requirements.md`. + - [ ] Run focused tests required by changed area. +5. **NT8 compile/deploy checks** (when NinjaScript files are touched) + - [ ] Validate signatures against official NT8 docs. + - [ ] Run repo build/deploy sequence required for NT8. + - [ ] Compile in NinjaScript Editor (authoritative NT8 check). +6. **Documentation updates** + - [ ] Update `docs/00-governance/active_work.md` when task status or blockers changed. + - [ ] Update `docs/00-governance/roadmap.md` when sequencing/scope changed. + - [ ] Update `docs/00-governance/decisions.md` when durable architecture decisions were made. + - [ ] Update `CLEANUP_LOG.md` when cleanup debt status changed. +7. **Compile-learning capture** (if any compile issue occurred) + - [ ] Add prevention rule to `docs/00-governance/compile_guardrails.md`. + - [ ] Add error fingerprint + fix to `docs/00-governance/common_failures.md`. + - [ ] Add pattern/anti-pattern to `docs/00-governance/patterns_and_antipatterns.md`. +8. **Set task state and report** + - [ ] Move task status from `doing` -> `review`. + - [ ] Report changed files and verification evidence. + +## Definition of Done (Required) +- [ ] Only scoped files changed. +- [ ] Verification gates passed. +- [ ] NT8 compile checks completed when relevant. +- [ ] Relevant governance docs updated. +- [ ] Compile learnings captured when applicable. +- [ ] Task moved to `review` with evidence. + +## Out-of-Scope Safety +- [ ] Do not modify files outside task scope. +- [ ] Do not apply opportunistic refactors. +- [ ] Do not modify historical/contextual docs unless explicitly requested. +- [ ] If a real fix needs out-of-scope changes, stop and report a scope blocker. diff --git a/.kilocode/rules/docs_maintenance.md b/.kilocode/rules/docs_maintenance.md new file mode 100644 index 0000000..a8c43e2 --- /dev/null +++ b/.kilocode/rules/docs_maintenance.md @@ -0,0 +1,31 @@ +# Governance Docs Maintenance Policy +**Last Updated:** 2026-04-05 + +## Canonical Source Rule +- [ ] `docs/00-governance/*` is the canonical planning and execution source. +- [ ] Prefer updating canonical governance docs over duplicating guidance elsewhere. + +## Historical/Contextual Docs (Read-Only by Default) +Treat these as non-canonical unless explicitly requested by task scope: +- `README.md` +- `docs/README.md` +- `PROJECT_HANDOVER.md` +- `DESIGNED_VS_IMPLEMENTED_GAP_ANALYSIS.md` +- `docs/INDEX.md` + +## Update Triggers +- [ ] Update `docs/00-governance/active_work.md` when priorities, status, blockers, or ownership change. +- [ ] Update `docs/00-governance/roadmap.md` when milestone sequence, scope, or timing changes. +- [ ] Update `docs/00-governance/decisions.md` when durable architecture tradeoffs/decisions are made. +- [ ] Update `CLEANUP_LOG.md` when cleanup debt is created, resolved, or deferred. + +## Compile Knowledge Capture (Concise and Durable) +When a compile issue occurs, record: +- [ ] Prevention rule in `docs/00-governance/compile_guardrails.md`. +- [ ] Error fingerprint + fix in `docs/00-governance/common_failures.md`. +- [ ] Reusable pattern and anti-pattern in `docs/00-governance/patterns_and_antipatterns.md`. + +## Documentation Hygiene +- [ ] Keep entries concise, actionable, and dated. +- [ ] Link to authoritative rules instead of duplicating long guidance. +- [ ] Do not update unrelated docs in the same task. diff --git a/.kilocode/rules/ninjascript_guardrails.md b/.kilocode/rules/ninjascript_guardrails.md new file mode 100644 index 0000000..ee7de09 --- /dev/null +++ b/.kilocode/rules/ninjascript_guardrails.md @@ -0,0 +1,35 @@ +# NinjaScript Guardrails - Operational Checklist +**Last Updated:** 2026-04-05 + +Use this checklist whenever touching NinjaScript-facing files. + +## Pre-Edit Checks (Required) +- [ ] Confirm file is in task scope and allowed by `.kilocode/rules/file_boundaries.md`. +- [ ] Verify exact API signatures against official NT8 docs: `https://developer.ninjatrader.com/docs/desktop`. +- [ ] Confirm C# 5.0 compatibility using `.kilocode/rules/csharp_50_syntax.md`. + +## Lifecycle and Safety Rules (Required) +- [ ] Use `OnStateChange` correctly: `State.SetDefaults`, `State.Configure`, `State.DataLoaded`. +- [ ] Keep runtime logic out of `SetDefaults` and `Configure`. +- [ ] Guard `OnBarUpdate` for series and readiness (`BarsInProgress`, `CurrentBar`/`CurrentBars`). +- [ ] In managed order flow, set stop/target before entry on the same bar. +- [ ] Do not mix managed and unmanaged order models unless explicitly required. + +## API Integrity Rules (Required) +- [ ] Do not guess method signatures, enum members, attributes, or overloads. +- [ ] Do not use unsupported attributes (example: `[Optimizable]`). +- [ ] Do not invent placeholder types/enums unless explicitly confirmed by task/domain requirements. + +## Compile Validation Sequence +- [ ] Run `.\verify-build.bat`. +- [ ] Run required deploy step when NinjaScript source must be synced to NT8. +- [ ] Compile in NT8 NinjaScript Editor (authoritative NinjaScript compile gate). + +## Compile Failure Learning Loop +If any compile issue occurs: +- [ ] Capture error fingerprint (`code`, file, line, root cause). +- [ ] Apply the smallest safe fix and re-run validation sequence. +- [ ] Record durable learning in: + - `docs/00-governance/common_failures.md` (symptom + fix) + - `docs/00-governance/compile_guardrails.md` (preventive rule) + - `docs/00-governance/patterns_and_antipatterns.md` (good vs bad pattern) diff --git a/.kilocode/rules/project_context.md b/.kilocode/rules/project_context.md index 51fe515..420c6c3 100644 --- a/.kilocode/rules/project_context.md +++ b/.kilocode/rules/project_context.md @@ -1,176 +1,45 @@ -# Project Context β€” NT8 SDK (Sprint 2: SIM Validation) -**Last Updated:** 2026-03-27 +# Project Context - NT8 SDK +**Last Updated:** 2026-04-05 -You are working on the **NT8 SDK** β€” an institutional-grade algorithmic futures trading system for NinjaTrader 8. -This is **production trading software**. Bugs cause real financial losses. Never take shortcuts. +Mission: ship safe, compile-stable NT8 trading software with strict scope control and durable governance documentation. ---- +## Session Start (Mandatory) +- [ ] Read these files first, in order: + 1. `docs/00-governance/executive_summary.md` + 2. `docs/00-governance/current_status.md` + 3. `docs/00-governance/active_work.md` + 4. `docs/00-governance/architecture.md` + 5. `docs/00-governance/roadmap.md` +- [ ] Treat `docs/00-governance/*` as canonical for current direction. -## Onboarding / First Read (Canonical Order) +## Historical/Contextual Sources (Non-Canonical) +Use only for background unless explicitly requested in task scope: +- `README.md` +- `docs/README.md` +- `PROJECT_HANDOVER.md` +- `DESIGNED_VS_IMPLEMENTED_GAP_ANALYSIS.md` +- `docs/INDEX.md` -For every new Kilo session, start with `docs/00-governance/` as the primary source of truth: -1. `docs/00-governance/executive_summary.md` -2. `docs/00-governance/current_status.md` -3. `docs/00-governance/active_work.md` -4. `docs/00-governance/architecture.md` -5. `docs/00-governance/roadmap.md` +## File Touch Scope (Hard Rules) +- [ ] Modify only files explicitly listed in the task spec. +- [ ] Do not edit adjacent files for cleanup or style-only changes. +- [ ] If a required fix is outside scope, stop and record a scope blocker. +- [ ] Respect `.kilocode/rules/file_boundaries.md` at all times. -`PROJECT_HANDOVER.md` and `DESIGNED_VS_IMPLEMENTED_GAP_ANALYSIS.md` are historical/contextual references only. Use them for background, not for authoritative current direction. +## Conversation Separation (Hard Rules) +- [ ] Strategy conversations: entry/exit logic and behavior. +- [ ] Architecture conversations: cross-component design and interfaces. +- [ ] Coding conversations: implementation details and diffs. +- [ ] Do not mix decisions across tracks; record architecture decisions in `docs/00-governance/decisions.md`. ---- +## Documentation Sync Triggers +Update governance docs as part of normal task completion: +- [ ] Update `docs/00-governance/active_work.md` when current priorities, status, blockers, or ownership change. +- [ ] Update `docs/00-governance/roadmap.md` when milestone sequence, scope, or timing changes. +- [ ] Update `docs/00-governance/decisions.md` when a durable tradeoff or architecture decision is made. +- [ ] Update `CLEANUP_LOG.md` when cleanup debt is created, resolved, or deferred. -## Critical Rules for Kilocode - -1. **Only modify files listed in the task spec.** Never touch adjacent code. -2. **C# 5.0 only.** No `$""`, no `?.`, no `=>` bodies, no `nameof()`, no async/await. -3. **Never remove XML documentation or comments.** -4. **Never change interface signatures** β€” IStrategy, IRiskManager, IPositionSizer, INT8ExecutionBridge are frozen. -5. **Always build before deploying:** `dotnet build NT8-SDK.sln --configuration Release` -6. **Always deploy to BOTH paths** after every code change: - - Repo: `C:\dev\nt8-sdk\src\NT8.Adapters\Strategies\` - - NT8: `C:\Users\billy\Documents\NinjaTrader 8\bin\Custom\Strategies\` -7. **Never guess NT8 API signatures.** Verify at `https://developer.ninjatrader.com/docs/desktop`. - ---- - -## Current State (2026-03-27) - -**What works end-to-end:** -- SimpleORBStrategy with 10-factor confluence scoring -- NT8StrategyBase with session management, kill switch, connection recovery -- Dual-leg scaler + runner architecture (EntriesPerDirection=2 restored) -- PortfolioRiskManager singleton (kill switch, daily loss, contract cap) -- File logging (session log + settings export) -- Historical replay guard (_realtimeBarSeen) -- Execution confirmed in SIM on 2026-03-27 - -**Pending validation:** -- Runner leg dual-fill (Qty=2) β€” run backtest to confirm -- Breakeven + trail in live multi-bar scenario - ---- - -## Architecture - -``` -SimpleORBNT8.cs NT8 entry point - ↓ -NT8StrategyBase.cs Abstract base: bar routing, kill switch, breakeven, runner trail - ↓ -SimpleORBStrategy.cs Signal: ORB detection, 10-factor confluence, _tradeTaken lock - ↓ -NT8OrderAdapter.cs INT8ExecutionBridge: EnterLong/EnterShort/SetStopLoss - ↓ -PortfolioRiskManager.cs Singleton: cross-strategy risk - ↓ -NinjaTrader 8 -``` - -## Key Files - -| File | Path | -|---|---| -| NT8StrategyBase.cs | `src\NT8.Adapters\Strategies\` | -| SimpleORBNT8.cs | `src\NT8.Adapters\Strategies\` | -| SimpleORBStrategy.cs | `src\NT8.Strategies\Examples\` | -| NT8OrderAdapter.cs | `src\NT8.Adapters\NinjaTrader\` | -| PortfolioRiskManager.cs | `src\NT8.Core\Risk\` | -| deploy-to-nt8.bat | `deployment\` | - -## Active Sprint Tasks - -See `SPRINT_BOARD.md` (at `docs\architecture\phase1_sprint_plan.md`) for full task list. - -Immediate next action: Run Strategy Analyzer backtest (NQ JUN26, Jan 1 2026 β†’ Mar 27 2026) and confirm `PNL_UPDATE Position=Short Qty=2` in session log to validate runner leg. - ---- - -## What Is Already Built (Do Not Touch) - -All core trading logic is complete and has 240+ passing tests: - -| Layer | Status | Key Files | -|---|---|---| -| Risk (Tier 1-3) | βœ… Complete | `src/NT8.Core/Risk/` | -| Position Sizing | βœ… Complete | `src/NT8.Core/Sizing/` | -| OMS / Order Lifecycle | βœ… Complete | `src/NT8.Core/OMS/` | -| Intelligence | βœ… Complete | `src/NT8.Core/Intelligence/` | -| Analytics | βœ… Complete | `src/NT8.Core/Analytics/` | -| Execution Utilities | βœ… Complete | `src/NT8.Core/Execution/` | -| Market Data | βœ… Complete | `src/NT8.Core/MarketData/` | - -**NT8 Order Execution is ALREADY WIRED.** -`NT8StrategyBase.SubmitOrderToNT8()` calls `EnterLong`, `EnterShort`, `SetStopLoss`, and -`SetProfitTarget` directly. The execution path works end-to-end. Do not re-implement it. - ---- - -## What You Are Fixing (The Active Task List) - -### CRITICAL β€” `NT8StrategyBase.cs` - -**Gap 1 β€” No kill switch** -`NT8StrategyBase` has no `EnableKillSwitch` NinjaScript parameter and no early-exit in `OnBarUpdate()`. -A runaway strategy cannot be stopped without killing NinjaTrader. -**Fix:** Add `EnableKillSwitch` (bool NinjaScript property) and `EnableVerboseLogging` property. -Add kill switch check as the FIRST thing in `OnBarUpdate()`. -β†’ See `TASK-01-kill-switch.md` - -**Gap 2 β€” `ExecutionCircuitBreaker` not wired** -`src/NT8.Core/Execution/ExecutionCircuitBreaker.cs` is complete and tested. -It is never instantiated. Orders submit regardless of latency or rejection conditions. -**Fix:** Instantiate in `InitializeSdkComponents()`, gate orders in `SubmitOrderToNT8()`, wire rejections in `OnOrderUpdate()`. -β†’ See `TASK-02-circuit-breaker.md` - -### HIGH β€” `TrailingStopManager.cs` - -**Gap 3 β€” Placeholder stop math returns zero** -`CalculateNewStopPrice()` FixedTrailing branch: `marketPrice - (x - x)` = always zero movement. -ATRTrailing and Chandelier also have meaningless placeholder formulas. -**Fix:** Replace with real calculations using `TrailingStopConfig.TrailingAmountTicks` and `AtrMultiplier`. -β†’ See `TASK-03-trailing-stop.md` - -### HIGH β€” `BasicLogger.cs` - -**Gap 4 β€” No log-level filter** -Every log statement writes to console unconditionally. Cannot suppress debug noise in production. -**Fix:** Add `MinimumLevel` property (defaults to `Information`). Suppress messages below threshold. -β†’ See `TASK-04-log-level.md` - -### MEDIUM β€” `SessionManager.cs` - -**Gap 5 β€” No holiday awareness** -`IsRegularTradingHours()` checks session times only. Will attempt to trade on Christmas, Thanksgiving, etc. -**Fix:** Add static CME holiday set for 2025/2026. Return `false` on those dates. -β†’ See `TASK-05-session-holidays.md` - ---- - -## Architecture (Read Before Touching Anything) - -``` -SimpleORBStrategy.OnBar() - ↓ returns StrategyIntent -NT8StrategyBase.OnBarUpdate() - ↓ [TASK-01: kill switch check here, first] - ↓ calls ProcessStrategyIntent() - ↓ calls _riskManager.ValidateOrder() - ↓ calls _positionSizer.CalculateSize() - ↓ calls SubmitOrderToNT8() - ↓ [TASK-02: circuit breaker gate here] - ↓ calls EnterLong/EnterShort/SetStopLoss/SetProfitTarget (already works) -NT8 callbacks β†’ OnOrderUpdate / OnExecutionUpdate - ↓ [TASK-02: record rejections in circuit breaker here] -``` - ---- - -## Technology Constraints - -- **C# 5.0 only** β€” no `$""`, no `?.`, no `=>` on methods/properties, no `nameof()`, no `out var` -- **.NET Framework 4.8** β€” not .NET Core/5+/6+ -- **NinjaScript managed orders** β€” `EnterLong`, `EnterShort`, `SetStopLoss`, `SetProfitTarget` -- `string.Format()` everywhere, never string interpolation -- All `Dictionary`, `HashSet` access inside `lock (_lock)` blocks -- XML doc comments on all public members -- `try/catch` on all public methods with `LogError` in the catch +## Compatibility and Safety Baselines +- [ ] C# 5.0 only (`.kilocode/rules/csharp_50_syntax.md`). +- [ ] NT8 compile safety (`.kilocode/rules/ninjascript_guardrails.md`, `.kilocode/rules/nt8compilespec.md`). +- [ ] Verification gates (`.kilocode/rules/verification_requirements.md`). diff --git a/docs/00-governance/common_failures.md b/docs/00-governance/common_failures.md index e69de29..0faca06 100644 --- a/docs/00-governance/common_failures.md +++ b/docs/00-governance/common_failures.md @@ -0,0 +1,33 @@ +# Common Compile Failures +**Last Updated:** 2026-04-05 + +Record concise error fingerprints and verified fixes. + +## Entry Template +- **Date:** YYYY-MM-DD +- **Error:** `CSXXXX` +- **Fingerprint:** file + line + short symptom +- **Root cause:** one sentence +- **Fix:** one to three concrete steps +- **Prevention link:** guardrail/pattern doc entry added + +## Starter Examples +1. **`CS0115` no suitable method found to override** + - Root cause: incorrect NT8 override signature. + - Fix: replace with exact official signature; recompile. + +2. **`CS0507` cannot change access modifiers when overriding** + - Root cause: used `public override`/`private override` instead of `protected override`. + - Fix: change to `protected override`; recompile. + +3. **`CS0246` type or namespace not found** + - Root cause: missing using/namespace or undefined domain type. + - Fix: add correct namespace reference or confirmed type definition. + +4. **`CS1503` argument type mismatch** + - Root cause: wrong overload or argument ordering. + - Fix: align call with exact method signature and parameter types. + +5. **C# 6+ syntax in C# 5 project** + - Root cause: use of `$""`, `?.`, `nameof`, expression-bodied members, etc. + - Fix: rewrite using C# 5 compatible constructs. diff --git a/docs/00-governance/compile_guardrails.md b/docs/00-governance/compile_guardrails.md index e69de29..1b69614 100644 --- a/docs/00-governance/compile_guardrails.md +++ b/docs/00-governance/compile_guardrails.md @@ -0,0 +1,20 @@ +# Compile Guardrails +**Last Updated:** 2026-04-05 + +Preventive rules to reduce repeat compile failures. + +## Core Prevention Rules +- [ ] Verify NT8 signatures in official docs before adding/changing any `protected override`. +- [ ] Keep NinjaScript edits within task scope and allowed file boundaries. +- [ ] Enforce C# 5.0 syntax only; reject C# 6+ constructs. +- [ ] Keep managed order sequence correct (stop/target before entry on same bar). +- [ ] Guard `OnBarUpdate` by `BarsInProgress` and bar readiness. +- [ ] Do not use unsupported attributes/types/enums without confirmation. + +## Verification Gates +- [ ] Run `.\verify-build.bat` after changes. +- [ ] Run focused tests for changed area. +- [ ] If NinjaScript touched, compile in NT8 NinjaScript Editor. + +## Update Rule +- [ ] Add a new guardrail entry whenever a compile issue reveals a missing prevention rule. diff --git a/docs/00-governance/patterns_and_antipatterns.md b/docs/00-governance/patterns_and_antipatterns.md index e69de29..8f126f6 100644 --- a/docs/00-governance/patterns_and_antipatterns.md +++ b/docs/00-governance/patterns_and_antipatterns.md @@ -0,0 +1,36 @@ +# Patterns and Anti-Patterns +**Last Updated:** 2026-04-05 + +Capture recurring implementation patterns that impact compile stability. + +## Pattern Entry Template +- **Context:** where this applies +- **Good pattern:** concise example/description +- **Anti-pattern:** concise example/description +- **Why it matters:** one sentence + +## Starter Patterns +1. **NT8 override signatures** + - Good pattern: copy exact signature from official NT8 docs before coding. + - Anti-pattern: infer or copy from outdated examples. + - Why it matters: prevents `CS0115` and runtime integration drift. + +2. **Access modifier on overrides** + - Good pattern: use `protected override` for NT8 lifecycle/event methods. + - Anti-pattern: `public override` or `private override`. + - Why it matters: prevents `CS0507`. + +3. **C# 5 compatibility discipline** + - Good pattern: `string.Format`, explicit null checks, block-bodied members. + - Anti-pattern: string interpolation, null-conditional, expression-bodied members. + - Why it matters: prevents avoidable language-version compile failures. + +4. **Managed order sequencing** + - Good pattern: set stop/target before entry on the same bar. + - Anti-pattern: entry first, then stop/target. + - Why it matters: avoids silent behavior defects and rejected assumptions. + +5. **Scope-first fixes** + - Good pattern: smallest safe change in scoped files only. + - Anti-pattern: broad cleanup or adjacent-file edits during bugfix. + - Why it matters: reduces regression risk and review churn.