mo/nt8-sdk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Harden AI agent rules and compile learning workflow

Browse Source
This commit is contained in:
Mo Hussain
2026-04-05 17:59:34 -04:00
parent 4453ff552a
commit de6e150655
9 changed files with 301 additions and 963 deletions
Download Patch File Download Diff File Expand all files Collapse all files

239
.kilocode/rules/Compile error guidance.md
View File

@@ -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. # Compile Error Guidance - Reusable Protocol
**Last Updated:** 2026-04-05
This third file confirms a recurrence of CS0246 compiler errors in VWAP_Pro.cs, specifically related to undefined types like ModeType and AnchorModeType.
Apply this protocol for all compile issues.
🔍 CS0246 - "The type or namespace name 'X' could not be found"
Line Column Missing Type ## 1) Verify First
371 28 ModeType - [ ] Verify exact NinjaScript/API signature against official NT8 docs before editing: `https://developer.ninjatrader.com/docs/desktop`.
371 43 AnchorModeType - [ ] Confirm file is in scope before making any change.
391 39 ModeType
391 54 AnchorModeType ## 2) Classify the Error
376 51 ModeType - [ ] Missing type/namespace (e.g., `CS0246`).
✅ How to Fix It - [ ] Invalid override/signature/access modifier (e.g., `CS0115`, `CS0507`).
🔧 1. Define Missing Enums (Recommended Fix) - [ ] Argument mismatch or wrong overload (e.g., `CS1503`).
- [ ] C# language version incompatibility (C# 6+ syntax in C# 5 project).
It seems that ModeType and AnchorModeType are custom enums that were expected to exist in the code but were never declared.
## 3) Apply Smallest Safe Fix
Create a separate file or include this in the same VWAP_Pro.cs file near the top: - [ ] Prefer minimal edits in scoped files only.
- [ ] Fix root cause, not symptom chaining.
public enum ModeType - [ ] Preserve existing architecture/contracts unless task explicitly requires change.
{
Standard, ## 4) Re-Run Verification
Aggressive, - [ ] Run `.\verify-build.bat`.
Conservative - [ ] Run required tests for changed area.
} - [ ] If NinjaScript touched, run NT8 compile check in NinjaScript Editor.
public enum AnchorModeType ## 5) Capture Durable Learning
{ For non-trivial compile failures, add concise entries to:
SessionStart, - [ ] `docs/00-governance/common_failures.md` (error fingerprint + fix).
FixedTime, - [ ] `docs/00-governance/compile_guardrails.md` (prevention rule).
Custom - [ ] `docs/00-governance/patterns_and_antipatterns.md` (good vs bad pattern).
}
## Do Not
- [ ] Do not guess signatures, overloads, enums, or attributes.
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. - [ ] 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`.
🔧 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.

273
.kilocode/rules/coding_patterns.md
View File

@@ -1,252 +1,33 @@
# Coding Patterns — NT8 SDK Required Patterns # Coding Patterns - NT8 SDK Required Patterns
**Last Updated:** 2026-03-27 **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 ## Core Implementation Patterns
// ❌ PROHIBITED — compiler will fail silently or error - [ ] Validate inputs at method entry.
$"Hello {name}" // no string interpolation - [ ] Wrap public method logic in `try/catch` with meaningful logging.
obj?.Method() // no null-conditional - [ ] Protect shared mutable collections/state with `lock (_lock)`.
public int Prop => _value; // no expression body - [ ] Do not raise events while holding locks.
nameof(SomeClass) // no nameof - [ ] Keep public members documented with XML comments where required by project standards.
await SomeAsync() // no async/await
// ✅ REQUIRED ## NinjaScript Coding Patterns (When Applicable)
string.Format("Hello {0}", name) - [ ] Keep `OnStateChange` responsibilities separated by state.
obj != null ? obj.Method() : null - [ ] Guard `OnBarUpdate` by `BarsInProgress` and bar readiness.
public int Prop { get { return _value; } } - [ ] In managed order flow, set stop/target before entry on the same bar.
"SomeClass" // string literal
// synchronous only
```
--- ## Authoritative Rule References (Do Not Duplicate)
- Syntax constraints: `.kilocode/rules/csharp_50_syntax.md`
## 0b. NT8-Specific Critical Rules - NT8 compile and API constraints: `.kilocode/rules/nt8compilespec.md`
- Verification commands and gates: `.kilocode/rules/verification_requirements.md`
```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<MyClass> 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<string, OrderStatus>();
_logger.LogInformation("MyClass initialized");
}
```
---
## 6. XML Documentation — Required on All Public Members
```csharp
/// <summary>
/// Brief one-line description of what this does.
/// </summary>
/// <param name="intent">The trading intent to validate.</param>
/// <param name="context">Current strategy context with account state.</param>
/// <returns>Risk decision indicating allow or reject.</returns>
/// <exception cref="ArgumentNullException">Thrown when intent or context is null.</exception>
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 `/// <summary>` on every public method, property, class
- [ ] No C# 6+ syntax
- [ ] Events raised outside lock blocks
- [ ] `verify-build.bat` passes

390
.kilocode/rules/development_workflow.md
View File

@@ -1,344 +1,46 @@
# NT8-SDK — Kilocode Development Workflow # NT8-SDK Development Workflow
**Last Updated:** 2026-03-27 **Last Updated:** 2026-04-05
This is the authoritative workflow for all development work on NT8-SDK using Kilocode. Operational workflow for Kilo/Codex-assisted development.
--- ## Per-Task Workflow (Required)
1. **Confirm scope**
## Division of Labor - [ ] Confirm exact files allowed by task spec.
- [ ] Cross-check `.kilocode/rules/file_boundaries.md`.
| Role | Responsibility | 2. **Set task state**
|---|---| - [ ] Move task status from `todo` -> `doing` before edits.
| **Claude** | Architecture, diagnosis, Kilocode prompt authoring, sequencing | 3. **Implement**
| **Kilocode** | ALL code implementation — zero exceptions | - [ ] Make minimum-diff changes only in scoped files.
| **Mo** | Strategy direction, backtest execution, log collection, go/no-go | 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)
## Per-Task Workflow - [ ] Validate signatures against official NT8 docs.
- [ ] Run repo build/deploy sequence required for NT8.
1. **Claude writes Kilocode prompt** — exact Find/Replace, both file paths, build command, validation checklist - [ ] Compile in NinjaScript Editor (authoritative NT8 check).
2. **Mo runs Kilocode** — pastes prompt, Kilocode executes 6. **Documentation updates**
3. **Kilocode reports** — build output + files changed - [ ] Update `docs/00-governance/active_work.md` when task status or blockers changed.
4. **Mo brings results to Claude** — Kilocode report + session log + CSV - [ ] Update `docs/00-governance/roadmap.md` when sequencing/scope changed.
5. **Claude diagnoses** — confirms or issues follow-up prompt - [ ] Update `docs/00-governance/decisions.md` when durable architecture decisions were made.
6. **Mo commits:** `git add` → `git commit` → `git push` - [ ] Update `CLEANUP_LOG.md` when cleanup debt status changed.
7. **Update SPRINT_BOARD** — task to Done or Blocked 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`.
## Kilocode Prompt Template 8. **Set task state and report**
- [ ] Move task status from `doing` -> `review`.
``` - [ ] Report changed files and verification evidence.
TASK: [one-line description]
## Definition of Done (Required)
CONTEXT: - [ ] Only scoped files changed.
[1-3 sentences explaining why] - [ ] Verification gates passed.
- [ ] NT8 compile checks completed when relevant.
FILES TO MODIFY: - [ ] Relevant governance docs updated.
1. C:\dev\nt8-sdk\src\... [repo path] - [ ] Compile learnings captured when applicable.
2. C:\Users\billy\...\Strategies\... [NT8 path — same change] - [ ] Task moved to `review` with evidence.
CHANGE 1 — [description]: ## Out-of-Scope Safety
File: [path] - [ ] Do not modify files outside task scope.
Find: - [ ] Do not apply opportunistic refactors.
[exact existing code] - [ ] Do not modify historical/contextual docs unless explicitly requested.
Replace with: - [ ] If a real fix needs out-of-scope changes, stop and report a scope blocker.
[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.

31
.kilocode/rules/docs_maintenance.md Normal file
View File

@@ -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.

35
.kilocode/rules/ninjascript_guardrails.md Normal file
View File

@@ -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)

197
.kilocode/rules/project_context.md
View File

@@ -1,176 +1,45 @@
# Project Context — NT8 SDK (Sprint 2: SIM Validation) # Project Context - NT8 SDK
**Last Updated:** 2026-03-27 **Last Updated:** 2026-04-05
You are working on the **NT8 SDK** — an institutional-grade algorithmic futures trading system for NinjaTrader 8. Mission: ship safe, compile-stable NT8 trading software with strict scope control and durable governance documentation.
This is **production trading software**. Bugs cause real financial losses. Never take shortcuts.
--- ## Session Start (Mandatory)
- [ ] Read these files first, in order:
## Onboarding / First Read (Canonical Order)
For every new Kilo session, start with `docs/00-governance/` as the primary source of truth:
1. `docs/00-governance/executive_summary.md` 1. `docs/00-governance/executive_summary.md`
2. `docs/00-governance/current_status.md` 2. `docs/00-governance/current_status.md`
3. `docs/00-governance/active_work.md` 3. `docs/00-governance/active_work.md`
4. `docs/00-governance/architecture.md` 4. `docs/00-governance/architecture.md`
5. `docs/00-governance/roadmap.md` 5. `docs/00-governance/roadmap.md`
- [ ] Treat `docs/00-governance/*` as canonical for current direction.
`PROJECT_HANDOVER.md` and `DESIGNED_VS_IMPLEMENTED_GAP_ANALYSIS.md` are historical/contextual references only. Use them for background, not for authoritative current direction. ## 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`
--- ## 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.
## Critical Rules for Kilocode ## 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`.
1. **Only modify files listed in the task spec.** Never touch adjacent code. ## Documentation Sync Triggers
2. **C# 5.0 only.** No `$""`, no `?.`, no `=>` bodies, no `nameof()`, no async/await. Update governance docs as part of normal task completion:
3. **Never remove XML documentation or comments.** - [ ] Update `docs/00-governance/active_work.md` when current priorities, status, blockers, or ownership change.
4. **Never change interface signatures** — IStrategy, IRiskManager, IPositionSizer, INT8ExecutionBridge are frozen. - [ ] Update `docs/00-governance/roadmap.md` when milestone sequence, scope, or timing changes.
5. **Always build before deploying:** `dotnet build NT8-SDK.sln --configuration Release` - [ ] Update `docs/00-governance/decisions.md` when a durable tradeoff or architecture decision is made.
6. **Always deploy to BOTH paths** after every code change: - [ ] Update `CLEANUP_LOG.md` when cleanup debt is created, resolved, or deferred.
- 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`.
--- ## Compatibility and Safety Baselines
- [ ] C# 5.0 only (`.kilocode/rules/csharp_50_syntax.md`).
## Current State (2026-03-27) - [ ] NT8 compile safety (`.kilocode/rules/ninjascript_guardrails.md`, `.kilocode/rules/nt8compilespec.md`).
- [ ] Verification gates (`.kilocode/rules/verification_requirements.md`).
**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

33
docs/00-governance/common_failures.md
View File

@@ -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.

20
docs/00-governance/compile_guardrails.md
View File

@@ -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.

36
docs/00-governance/patterns_and_antipatterns.md
View File

@@ -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.