From 3ccd3a8bfdfa398377b689545c37027988bbe3fe Mon Sep 17 00:00:00 2001 From: mo Date: Sun, 5 Apr 2026 16:54:22 -0400 Subject: [PATCH 1/4] Create canonical governance documentation files --- docs/00-governance/active_work.md | 0 docs/00-governance/architecture.md | 0 docs/00-governance/common_failures.md | 0 docs/00-governance/compile_guardrails.md | 0 docs/00-governance/current_status.md | 0 docs/00-governance/decisions.md | 0 docs/00-governance/executive_summary.md | 0 docs/00-governance/patterns_and_antipatterns.md | 0 docs/00-governance/roadmap.md | 0 9 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/00-governance/active_work.md create mode 100644 docs/00-governance/architecture.md create mode 100644 docs/00-governance/common_failures.md create mode 100644 docs/00-governance/compile_guardrails.md create mode 100644 docs/00-governance/current_status.md create mode 100644 docs/00-governance/decisions.md create mode 100644 docs/00-governance/executive_summary.md create mode 100644 docs/00-governance/patterns_and_antipatterns.md create mode 100644 docs/00-governance/roadmap.md diff --git a/docs/00-governance/active_work.md b/docs/00-governance/active_work.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/00-governance/architecture.md b/docs/00-governance/architecture.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/00-governance/common_failures.md b/docs/00-governance/common_failures.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/00-governance/compile_guardrails.md b/docs/00-governance/compile_guardrails.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/00-governance/current_status.md b/docs/00-governance/current_status.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/00-governance/decisions.md b/docs/00-governance/decisions.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/00-governance/executive_summary.md b/docs/00-governance/executive_summary.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/00-governance/patterns_and_antipatterns.md b/docs/00-governance/patterns_and_antipatterns.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/00-governance/roadmap.md b/docs/00-governance/roadmap.md new file mode 100644 index 0000000..e69de29 From ce74f68e54b5affd975c29eb6dbdf4cec83a57b9 Mon Sep 17 00:00:00 2001 From: mo Date: Sun, 5 Apr 2026 17:24:48 -0400 Subject: [PATCH 2/4] Establish governance docs as canonical repo context --- .kilocode/rules/project_context.md | 13 ++++++++++++ docs/00-governance/CLEANUP_LOG.md | 13 ++++++++++++ docs/00-governance/active_work.md | 17 +++++++++++++++ docs/00-governance/architecture.md | 28 +++++++++++++++++++++++++ docs/00-governance/current_status.md | 20 ++++++++++++++++++ docs/00-governance/executive_summary.md | 20 ++++++++++++++++++ docs/00-governance/roadmap.md | 21 +++++++++++++++++++ 7 files changed, 132 insertions(+) create mode 100644 docs/00-governance/CLEANUP_LOG.md diff --git a/.kilocode/rules/project_context.md b/.kilocode/rules/project_context.md index d2c1391..51fe515 100644 --- a/.kilocode/rules/project_context.md +++ b/.kilocode/rules/project_context.md @@ -6,6 +6,19 @@ This is **production trading software**. Bugs cause real financial losses. Never --- +## 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` +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` + +`PROJECT_HANDOVER.md` and `DESIGNED_VS_IMPLEMENTED_GAP_ANALYSIS.md` are historical/contextual references only. Use them for background, not for authoritative current direction. + +--- + ## Critical Rules for Kilocode 1. **Only modify files listed in the task spec.** Never touch adjacent code. diff --git a/docs/00-governance/CLEANUP_LOG.md b/docs/00-governance/CLEANUP_LOG.md new file mode 100644 index 0000000..8e80705 --- /dev/null +++ b/docs/00-governance/CLEANUP_LOG.md @@ -0,0 +1,13 @@ +# Governance Cleanup Log + +## 2026-04-05 +- Established `docs/00-governance/` as canonical governance entry point. +- Added concise governance baseline documents: + - `executive_summary.md` + - `architecture.md` + - `current_status.md` + - `roadmap.md` + - `active_work.md` +- Updated onboarding guidance in `.kilocode/rules/project_context.md` to point new sessions to governance docs first. +- Reclassified `PROJECT_HANDOVER.md` and `DESIGNED_VS_IMPLEMENTED_GAP_ANALYSIS.md` as historical/contextual references, not primary truth. +- No code files modified and no file moves performed. diff --git a/docs/00-governance/active_work.md b/docs/00-governance/active_work.md index e69de29..693c01f 100644 --- a/docs/00-governance/active_work.md +++ b/docs/00-governance/active_work.md @@ -0,0 +1,17 @@ +# Active Work + +## Current Execution Focus +- Validate runner-leg dual-fill behavior in Strategy Analyzer/session logs. +- Close remaining Sprint 2 hardening items already identified in task specs. +- Preserve strict compile and deployment verification sequence for every change. + +## In-Scope Hardening Themes +- Strategy safety controls and execution circuit-breaker wiring. +- Trailing stop calculation correctness. +- Logging verbosity controls for production noise reduction. +- Session/holiday awareness to avoid invalid trading windows. + +## Working Rules +- Apply changes only to explicitly scoped files per task. +- Keep NT8 API signatures and managed-order sequencing exact. +- Maintain C# 5.0 compatibility and existing interface boundaries. diff --git a/docs/00-governance/architecture.md b/docs/00-governance/architecture.md index e69de29..7dffddc 100644 --- a/docs/00-governance/architecture.md +++ b/docs/00-governance/architecture.md @@ -0,0 +1,28 @@ +# Architecture Governance + +## Runtime Flow (Authoritative) +``` +SimpleORBNT8.cs + -> NT8StrategyBase.cs + -> SimpleORBStrategy.cs + -> NT8OrderAdapter.cs + -> PortfolioRiskManager.cs + -> NinjaTrader 8 +``` + +## Responsibilities +- `SimpleORBNT8.cs`: NT8 entry point and platform lifecycle bridge. +- `NT8StrategyBase.cs`: orchestration, risk gate sequencing, execution handoff, platform callbacks. +- `SimpleORBStrategy.cs`: signal generation and confluence grading only. +- `NT8OrderAdapter.cs`: execution bridge to NT8 managed order APIs. +- `PortfolioRiskManager.cs`: cross-strategy risk controls and account-level enforcement. + +## Architectural Constraints +- Risk-first flow is mandatory; no strategy-level bypass of risk validation. +- Managed-order sequence remains required (`SetStopLoss` / `SetProfitTarget` before entry). +- C# 5.0 syntax only, .NET Framework 4.8 only. +- NT8 signatures must be verified against official NinjaTrader docs before API-touching edits. + +## Governance Notes +- Core Risk/Sizing/OMS/Intelligence/Analytics layers are treated as complete and stable unless explicitly re-opened by approved work. +- Hardening changes are concentrated in targeted adapter/utility components per active-work scope. diff --git a/docs/00-governance/current_status.md b/docs/00-governance/current_status.md index e69de29..7ca9eec 100644 --- a/docs/00-governance/current_status.md +++ b/docs/00-governance/current_status.md @@ -0,0 +1,20 @@ +# Current Status + +## Snapshot (2026-04-05) +- Program phase: Sprint 2 SIM validation with production-hardening follow-through. +- Core implementation: complete across major layers with 240+ passing tests. +- Live focus: execution safety, validation depth, and operational reliability. + +## Confirmed Working Areas +- End-to-end strategy pipeline from signal -> risk -> sizing -> NT8 managed execution. +- Session handling, portfolio risk controls, and base strategy orchestration. +- Existing analytics/risk/sizing/OMS foundations remain stable. + +## Open Findings Driving Work +- Runner leg behavior requires explicit validation evidence (`Qty=2` path confirmation). +- Risk/config consistency checks need tightening in runtime safeguards. +- Operational controls (CI automation, alerting, and out-of-sample validation) remain pending. + +## Operational Reality +- `dotnet build` success is necessary but not sufficient; NT8 NinjaScript compile remains a separate required validation step. +- Deployment integrity requires keeping repo and NT8 runtime strategy copies synchronized. diff --git a/docs/00-governance/executive_summary.md b/docs/00-governance/executive_summary.md index e69de29..7d0d822 100644 --- a/docs/00-governance/executive_summary.md +++ b/docs/00-governance/executive_summary.md @@ -0,0 +1,20 @@ +# Executive Summary + +## Scope +- This folder (`docs/00-governance/`) is the canonical governance source for project state, priorities, architecture intent, and active execution guidance. +- Governance is aligned to Sprint 2 (SIM validation) with production hardening gaps tracked and prioritized. + +## Current Position (2026-04-05) +- Core engine is implemented with 240+ passing tests across core components. +- NT8 execution path is wired and validated in SIM for baseline operation. +- Remaining work is focused on closing operational hardening gaps and validating runner behavior under production-like conditions. + +## Approved Direction +- Keep execution in managed-order NT8 patterns and C# 5.0 / .NET Framework 4.8 constraints. +- Complete critical and high-priority hardening tasks before expanding strategy scope. +- Treat historical handover artifacts as context only; governance decisions flow from this folder. + +## Immediate Priorities +- Confirm runner-leg dual-fill behavior in analyzer/session logs. +- Close safety and observability items already identified in Sprint 2/3 gap tracking. +- Maintain strict file-boundary and compile-guardrail discipline for all changes. diff --git a/docs/00-governance/roadmap.md b/docs/00-governance/roadmap.md index e69de29..5326f95 100644 --- a/docs/00-governance/roadmap.md +++ b/docs/00-governance/roadmap.md @@ -0,0 +1,21 @@ +# Roadmap + +## Sprint 2 (Active): SIM Validation +- Validate dual-leg execution behavior with log evidence. +- Complete remaining safety/consistency fixes tied to active gap list. +- Exit criteria: stable SIM behavior with no unresolved critical gaps. + +## Sprint 3: Production Hardening +- Implement CI build/test automation and operational alerting. +- Complete lower-priority runtime consistency and observability improvements. +- Add walk-forward and broader validation coverage beyond in-sample checks. + +## Sprint 4: Live Capital Readiness +- Gate on sustained SIM metrics and drawdown controls. +- Introduce go-live runbook and operational controls for controlled capital exposure. + +## Sprint 5: ML Extension (Deferred) +- Add inference integration only after sufficient live/sim data and stable production operations. + +## Sequencing Rule +- No feature expansion ahead of unresolved safety and validation gates. From 2be9c843e5774f206f25d409cbf3eb8201511c2e Mon Sep 17 00:00:00 2001 From: mo Date: Sun, 5 Apr 2026 17:38:35 -0400 Subject: [PATCH 3/4] Archive stale docs and mark historical references --- DESIGNED_VS_IMPLEMENTED_GAP_ANALYSIS.md | 6 ++++++ PROJECT_HANDOVER.md | 6 ++++++ README.md | 2 ++ docs/00-governance/CLEANUP_LOG.md | 9 +++++++++ docs/INDEX.md | 7 +++++++ docs/README.md | 6 ++++++ .../phase-history}/PHASE2_COMPLETION_REPORT.md | 6 ++++++ 7 files changed, 42 insertions(+) rename docs/{ => archive/phase-history}/PHASE2_COMPLETION_REPORT.md (98%) diff --git a/DESIGNED_VS_IMPLEMENTED_GAP_ANALYSIS.md b/DESIGNED_VS_IMPLEMENTED_GAP_ANALYSIS.md index 9ca7f12..b944cf7 100644 --- a/DESIGNED_VS_IMPLEMENTED_GAP_ANALYSIS.md +++ b/DESIGNED_VS_IMPLEMENTED_GAP_ANALYSIS.md @@ -1,3 +1,9 @@ +> ⚠️ HISTORICAL — see docs/00-governance/ for current state + +This file may contain outdated or mixed historical information. +Canonical current-state documentation lives in docs/00-governance/. +This file is retained for history/reference only. + # NT8-SDK — Gap Analysis & Roadmap **Version:** 3.0 | **Date:** 2026-03-27 | Supersedes all previous gap analysis documents. diff --git a/PROJECT_HANDOVER.md b/PROJECT_HANDOVER.md index 399d428..c1493c0 100644 --- a/PROJECT_HANDOVER.md +++ b/PROJECT_HANDOVER.md @@ -1,3 +1,9 @@ +> ⚠️ HISTORICAL — see docs/00-governance/ for current state + +This file may contain outdated or mixed historical information. +Canonical current-state documentation lives in docs/00-governance/. +This file is retained for history/reference only. + # NT8-SDK — Project Context & Current State **Version:** 3.0 | **Date:** 2026-03-27 | **Status:** Sprint 2 Active — SIM Validation diff --git a/README.md b/README.md index 86e9f96..9cc1ca0 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +> 📋 NOTE — This README is under revision. See docs/00-governance/ for current architecture and status. + # NT8-SDK — Institutional Algorithmic Futures Trading System **See `NT8_SDK_Handover_Package.docx` for the complete milestone handover document.** diff --git a/docs/00-governance/CLEANUP_LOG.md b/docs/00-governance/CLEANUP_LOG.md index 8e80705..4b15a40 100644 --- a/docs/00-governance/CLEANUP_LOG.md +++ b/docs/00-governance/CLEANUP_LOG.md @@ -11,3 +11,12 @@ - Updated onboarding guidance in `.kilocode/rules/project_context.md` to point new sessions to governance docs first. - Reclassified `PROJECT_HANDOVER.md` and `DESIGNED_VS_IMPLEMENTED_GAP_ANALYSIS.md` as historical/contextual references, not primary truth. - No code files modified and no file moves performed. +- Moved `docs/PHASE2_COMPLETION_REPORT.md` to `docs/archive/phase-history/PHASE2_COMPLETION_REPORT.md`. +- Added historical header + archival note block to: + - `docs/README.md` + - `PROJECT_HANDOVER.md` + - `DESIGNED_VS_IMPLEMENTED_GAP_ANALYSIS.md` + - `docs/INDEX.md` + - `docs/archive/phase-history/PHASE2_COMPLETION_REPORT.md` +- Added a softer revision note to `README.md` instead of a historical warning. +- Marked `docs/INDEX.md` historical in place because it currently misdirects navigation. diff --git a/docs/INDEX.md b/docs/INDEX.md index 5158688..726c291 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -1,3 +1,10 @@ +> ⚠️ HISTORICAL — see docs/00-governance/ for current state + +This file may contain outdated or mixed historical information. +Canonical current-state documentation lives in docs/00-governance/. +This file is retained for history/reference only. +Navigation links in this file may be stale or broken. + # NT8 SDK - Documentation Index **Complete documentation for the NT8 Institutional Trading SDK** diff --git a/docs/README.md b/docs/README.md index 44a180b..f2d966d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,3 +1,9 @@ +> ⚠️ HISTORICAL — see docs/00-governance/ for current state + +This file may contain outdated or mixed historical information. +Canonical current-state documentation lives in docs/00-governance/. +This file is retained for history/reference only. + # NT8 Institutional Trading SDK **Version:** 0.2.0 diff --git a/docs/PHASE2_COMPLETION_REPORT.md b/docs/archive/phase-history/PHASE2_COMPLETION_REPORT.md similarity index 98% rename from docs/PHASE2_COMPLETION_REPORT.md rename to docs/archive/phase-history/PHASE2_COMPLETION_REPORT.md index 844e899..1b81e96 100644 --- a/docs/PHASE2_COMPLETION_REPORT.md +++ b/docs/archive/phase-history/PHASE2_COMPLETION_REPORT.md @@ -1,3 +1,9 @@ +> ⚠️ HISTORICAL — see docs/00-governance/ for current state + +This file may contain outdated or mixed historical information. +Canonical current-state documentation lives in docs/00-governance/. +This file is retained for history/reference only. + # Phase 2 Completion Report **Project:** NT8 Institutional Trading SDK From de6e150655529d0114ad4878e483f9db4bdcffec Mon Sep 17 00:00:00 2001 From: mo Date: Sun, 5 Apr 2026 17:59:34 -0400 Subject: [PATCH 4/4] Harden AI agent rules and compile learning workflow --- .kilocode/rules/Compile error guidance.md | 239 ++--------- .kilocode/rules/coding_patterns.md | 273 ++---------- .kilocode/rules/development_workflow.md | 390 +++--------------- .kilocode/rules/docs_maintenance.md | 31 ++ .kilocode/rules/ninjascript_guardrails.md | 35 ++ .kilocode/rules/project_context.md | 207 ++-------- docs/00-governance/common_failures.md | 33 ++ docs/00-governance/compile_guardrails.md | 20 + .../patterns_and_antipatterns.md | 36 ++ 9 files changed, 301 insertions(+), 963 deletions(-) create mode 100644 .kilocode/rules/docs_maintenance.md create mode 100644 .kilocode/rules/ninjascript_guardrails.md 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.