Document legacy source cleanup pass 1

docs/00-governance/CLEANUP_LOG.md

@@ -20,3 +20,146 @@
   - `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.
+- Added follow-up debt: shared metrics vocabulary currently duplicated in `docs/02-runbooks/backtest_review_workflow.md` and `docs/02-runbooks/live_test_review_workflow.md`; later extract to shared governance doc `docs/00-governance/metrics_vocabulary.md`.
+
+
+## Legacy Source Cleanup — Pass 1 (Non-Destructive)
+
+**Date:** 2026-04-05
+**Branch:** cleanup/legacy-source
+**Type:** Non-destructive archive + tombstone cleanup
+
+### Summary
+Performed a conservative source cleanup to reduce ambiguity for AI agents and developers.
+Focused on isolating legacy code paths and removing confirmed placeholder/tombstone artifacts without impacting the active runtime path.
+
+---
+
+### Actions Taken
+
+#### 1. Legacy Orders System Archived
+The `NT8.Core.Orders` namespace was explicitly marked as archived and superseded by `NT8.Core.OMS`.
+
+Moved to:
+- `src/_archive/legacy-orders/`
+  - `IOrderManager.cs`
+  - `OrderManager.cs`
+  - `OrderModels.cs`
+
+Paired test moved with source:
+- `tests/_archive/legacy-orders/OrderManagerTests.cs`
+
+Rationale:
+- Prevents compile/runtime confusion between legacy Orders and active OMS
+- Prevents tests from referencing removed implementation paths
+- Ensures AI agents do not target deprecated order management logic
+
+---
+
+#### 2. Placeholder Source Files Archived
+Moved to:
+- `src/_archive/placeholders/`
+  - `PlaceholderAdapter.cs`
+  - `PlaceholderContract.cs`
+  - `PlaceholderStrategy.cs`
+
+Rationale:
+- These files contain no meaningful implementation
+- They create false signal for AI-assisted development
+
+---
+
+#### 3. Placeholder Test Files Archived
+Moved to:
+- `tests/_archive/placeholders/`
+  - `Integration_PlaceholderTests.cs`
+  - `Performance_PlaceholderTests.cs`
+
+Deleted:
+- `tests/NT8.Integration.Tests/UnitTest1.cs`
+- `tests/NT8.Performance.Tests/UnitTest1.cs`
+
+Rationale:
+- Placeholder tests (`Assert.IsTrue(true)`) provide no coverage
+- They distort test signal and can mislead analysis workflows
+
+---
+
+#### 4. Tombstone / Dead Files Removed
+Deleted (confirmed comment-only or empty artifacts):
+- `src/NT8.Adapters/Class1.cs.bak`
+- `src/NT8.Contracts/Class1.cs`
+- `src/NT8.Strategies/Class1.cs`
+
+Rationale:
+- Files contained no executable logic
+- Safe removal reduces noise and ambiguity
+
+---
+
+### Deferred / Blocked Items
+
+These files were intentionally **not modified** in this pass due to active references or ambiguity:
+
+- `src/NT8.Adapters/Wrappers/BaseNT8StrategyWrapper.cs`
+- `src/NT8.Adapters/Wrappers/SimpleORBNT8Wrapper.cs`
+- `src/NT8.Core/Risk/RiskManager.cs`
+- `src/NT8.Adapters/NinjaTrader/NT8Adapter.cs`
+- `src/NT8.Core/Class1.cs.bak` (contains real code, not a tombstone)
+
+Status:
+- Blocked pending second cleanup pass
+
+Reason:
+- Wrapper layer has test dependencies that must be migrated or rewritten before archiving
+- Some files contain real logic and require classification (active vs legacy) before removal
+
+---
+
+### Verification
+
+- `verify-build.bat`: **PASS**
+- All tests passing:
+  - Core: 393/393
+  - Integration: 78/78
+  - Performance: 10/10
+
+No compile errors or regressions introduced.
+
+---
+
+### Impact
+
+- Eliminated legacy order management ambiguity
+- Reduced AI hallucination risk in source selection
+- Removed non-functional placeholder code and tests
+- Preserved full build and test integrity
+
+---
+
+### Follow-Up Actions
+
+1. Second cleanup pass:
+   - Wrapper layer isolation or migration
+   - RiskManager classification
+   - NT8Adapter classification
+   - Resolve `Class1.cs.bak` ambiguity
+
+2. Metrics vocabulary extraction:
+   - Duplicate metrics definitions exist in:
+     - `backtest_review_workflow.md`
+     - `live_test_review_workflow.md`
+   - Planned extraction target:
+     - `docs/00-governance/metrics_vocabulary.md`
+
+3. Optional:
+   - Introduce `src/_archive/experimental/` if needed for future isolation
+
+---
+
+### Notes
+
+- No protected runtime paths were modified
+- No namespaces or interfaces were changed
+- No `.csproj` files were modified
+- All changes were reversible via archive structure

docs/00-governance/decisions.md

@@ -0,0 +1,15 @@
+# Architecture Decisions
+
+Use this file to record durable project decisions that affect implementation patterns, interfaces, or workflow.
+
+## Decision Template
+- ID: DEC-YYYYMMDD-XX
+- Date:
+- Status: proposed | accepted | superseded
+- Context:
+- Decision:
+- Consequences:
+- Related Files:
+
+## Decision Log
+- No decisions recorded yet.

docs/02-runbooks/backtest_review_workflow.md

@@ -0,0 +1,36 @@
+# Backtest Review Workflow
+
+## Purpose
+Provide a consistent pass/fail review process for strategy backtest output.
+
+## Inputs
+- Backtest report (date range, instrument, timeframe, settings).
+- Strategy version/commit reference.
+- Risk and execution assumptions used for the run.
+
+## Review Steps
+1. Confirm run metadata is complete and reproducible.
+2. Validate data window and session settings match test intent.
+3. Review shared metrics vocabulary:
+   - Net Profit
+   - Profit Factor
+   - Max Drawdown
+   - Win Rate
+   - Average Trade
+   - Expectancy
+   - Trade Count
+4. Check risk behavior consistency (drawdown shape, loss clustering, streak behavior).
+5. Compare against prior baseline and flag material regressions.
+6. Record decision: `pass`, `pass_with_conditions`, or `fail`.
+
+## Required Output
+- Backtest Review Note with:
+  - metadata,
+  - metrics snapshot,
+  - baseline delta,
+  - decision,
+  - required follow-ups.
+
+## Exit Criteria
+- Review note is stored with clear decision and rationale.
+- Any follow-up actions are captured as tasks.

docs/02-runbooks/compile_error_triage_workflow.md

@@ -0,0 +1,30 @@
+# Compile Error Triage Workflow
+
+## Purpose
+Resolve compile errors quickly using smallest-safe changes and durable prevention notes.
+
+## Inputs
+- Failing command output (`./verify-build.bat` or `dotnet test`).
+- File scope constraints for current task.
+
+## Steps
+1. Reproduce with the same command to confirm current error set.
+2. Classify each error:
+   - missing type/namespace,
+   - bad override/signature,
+   - wrong overload/argument,
+   - C# 5.0 compatibility violation.
+3. Verify any NinjaScript/API signatures against NT8 docs before editing.
+4. Apply minimum-diff fix in scoped files only.
+5. Re-run `./verify-build.bat`.
+6. Run focused tests for the impacted area.
+7. If issue is non-trivial, add concise prevention notes to governance docs.
+
+## Required Output
+- Error-to-fix mapping (error code, root cause, fix).
+- Verification evidence (build/test commands and results).
+
+## Exit Criteria
+- Build passes.
+- Relevant tests pass.
+- Non-trivial learnings are captured.

docs/02-runbooks/live_test_review_workflow.md

@@ -0,0 +1,36 @@
+# Live Test Review Workflow
+
+## Purpose
+Review paper/live-forward test behavior using the same decision discipline as backtest review.
+
+## Inputs
+- Live test window and environment details (paper/live, broker feed, session template).
+- Strategy version/commit reference.
+- Execution logs and order/rejection events.
+
+## Review Steps
+1. Confirm environment and deployment metadata.
+2. Validate runtime stability (disconnects, errors, unexpected restarts).
+3. Review shared metrics vocabulary:
+   - Net Profit
+   - Profit Factor
+   - Max Drawdown
+   - Win Rate
+   - Average Trade
+   - Expectancy
+   - Trade Count
+4. Inspect execution quality (slippage, missed fills, rejection frequency, latency anomalies).
+5. Compare live metrics to backtest expectations and tolerance bands.
+6. Record decision: `promote`, `extend_test`, or `hold`.
+
+## Required Output
+- Live Test Review Note with:
+  - environment details,
+  - key metrics,
+  - execution anomalies,
+  - decision,
+  - next actions.
+
+## Exit Criteria
+- Review note is complete and decision is explicit.
+- Any blockers or promotion prerequisites are tracked as tasks.

docs/02-runbooks/repo_cleanup_workflow.md

@@ -0,0 +1,25 @@
+# Repo Cleanup Workflow
+
+## Purpose
+Keep repository documentation and task metadata clean without changing functional behavior.
+
+## Inputs
+- Cleanup trigger (stale docs, duplicate guidance, archival need, naming drift).
+- Current governance priorities from `docs/00-governance/active_work.md`.
+
+## Steps
+1. Confirm cleanup scope and impacted files.
+2. Ensure no production code changes are included.
+3. Remove stale or duplicate sections that are no longer authoritative.
+4. Consolidate references so canonical docs remain in `docs/00-governance/`.
+5. Log cleanup action and any remaining debt in `docs/00-governance/CLEANUP_LOG.md`.
+6. Verify links/paths and runbook references after edits.
+
+## Required Output
+- List of files cleaned and reason for each.
+- Cleanup debt notes for deferred follow-ups.
+
+## Exit Criteria
+- Cleanup scope is complete.
+- `CLEANUP_LOG.md` is updated.
+- No code files were modified.

docs/02-runbooks/session_start_workflow.md

@@ -0,0 +1,26 @@
+# Session Start Workflow
+
+## Purpose
+Start each implementation session with correct scope, context, and task state before editing files.
+
+## Inputs
+- Current priority task from Archon.
+- Governance docs in `docs/00-governance/`.
+
+## Steps
+1. Open and read in order:
+   - `docs/00-governance/executive_summary.md`
+   - `docs/00-governance/current_status.md`
+   - `docs/00-governance/active_work.md`
+   - `docs/00-governance/architecture.md`
+   - `docs/00-governance/roadmap.md`
+2. Pull current task details from Archon and confirm acceptance criteria.
+3. Confirm allowed file scope from task spec and `.kilocode/rules/file_boundaries.md`.
+4. Move task status in Archon from `todo` to `doing`.
+5. Capture a short execution plan (3-6 bullets) tied to acceptance criteria.
+6. Begin implementation with minimum-diff edits only in scoped files.
+
+## Exit Criteria
+- Task is set to `doing`.
+- Scope boundaries are explicitly confirmed.
+- Work plan exists and maps to task acceptance criteria.

docs/02-runbooks/spec_to_build_workflow.md

@@ -0,0 +1,49 @@
+# Spec-to-Build Workflow
+
+## Purpose
+Convert an approved spec into implementation-ready work with explicit tool handoffs and verifiable artifacts.
+
+## Roles
+- Planner: decomposes spec into implementable tasks.
+- Implementer: edits code within scope.
+- Verifier: runs required build and tests.
+
+## Tool Handoffs and Artifact Passing
+1. **Spec Intake (Planner)**
+   - Tool: Archon task/project view.
+   - Input artifact: approved spec text.
+   - Output artifact: `Task Brief` containing objective, scope, constraints, acceptance criteria.
+2. **Task Breakdown (Planner)**
+   - Tool: Archon task board.
+   - Input artifact: `Task Brief`.
+   - Output artifact: ordered subtasks with file scope and done criteria.
+3. **Implementation (Implementer)**
+   - Tool: repository editor + scoped files.
+   - Input artifact: ordered subtasks.
+   - Output artifact: minimal code/doc diffs limited to allowed files.
+4. **Build Verification (Verifier)**
+   - Tool: `./verify-build.bat`.
+   - Input artifact: working tree changes.
+   - Output artifact: pass/fail result with error details if failed.
+5. **Focused Tests (Verifier)**
+   - Tool: `dotnet test` with area filter.
+   - Input artifact: verified build output.
+   - Output artifact: test evidence (command + pass/fail + failing test IDs).
+6. **Task State Update (Planner/Implementer)**
+   - Tool: Archon task board.
+   - Input artifact: verification evidence.
+   - Output artifact: task moved `doing` -> `review` with implementation notes and evidence links.
+
+## Required Artifact Bundle for Review
+- `Task Brief` (objective/scope/constraints/acceptance criteria).
+- Subtask list with scoped files.
+- Diff summary (files changed + why).
+- Verification evidence:
+  - `./verify-build.bat` result.
+  - Relevant `dotnet test` result.
+- Known limitations or follow-up items.
+
+## Exit Criteria
+- Acceptance criteria are satisfied.
+- Evidence bundle is complete.
+- Task status is `review`.

src/NT8.Adapters/Class1.cs.bak

@@ -1 +0,0 @@
-// Removed - replaced with PlaceholderAdapter.cs

src/NT8.Contracts/Class1.cs

@@ -1 +0,0 @@
-// Removed - replaced with PlaceholderContract.cs

src/NT8.Strategies/Class1.cs

@@ -1 +0,0 @@
-// Removed - replaced with PlaceholderStrategy.cs

tests/NT8.Integration.Tests/UnitTest1.cs

@@ -1 +0,0 @@
-// Removed - placeholder for integration tests

tests/NT8.Performance.Tests/UnitTest1.cs

@@ -1 +0,0 @@
-// Removed - placeholder for performance tests