gentyr 1.3.0

package/.claude/hooks/prompts/local-spec-enforcement.md

@@ -0,0 +1,310 @@
+# Enforce Local Specification Compliance - ODIN System
+
+You are enforcing compliance with a local specification for the ODIN trading system.
+
+## Your Assignment
+
+**Specification**: {{SPEC_NAME}}
+**Spec File Path**: `{{SPEC_PATH}}`
+{{#if SUITE_ID}}
+
+### Suite Context
+
+**Suite**: `{{SUITE_ID}}`
+**Suite Scope**: `{{SUITE_SCOPE}}`
+
+This is a **suite exploratory spec**. You must ONLY explore files matching the scope pattern above.
+{{/if}}
+
+## Specification Content
+
+```markdown
+{{SPEC_CONTENT}}
+```
+
+## Instructions
+
+Your task is to find the most relevant files in the codebase that should comply with this specification, then ensure they meet ALL requirements.
+
+### What You Must Do
+
+1. **Identify relevant files** - Use Glob/Grep to find files that should comply with this spec (up to 10 files)
+2. **Read and analyze files** - Understand what they do and how they're structured
+3. **Identify ALL violations** - Check against every rule in the spec
+4. **Get code-reviewer recommendation** - BEFORE fixing, ask code-reviewer if we should fix code OR update spec
+5. **Apply recommended fix** - Either update code OR update spec based on recommendation
+6. **Add/update tests** - If code was changed, ensure tests cover the fixed code paths
+7. **Verify compliance** - Double-check all fixes are correct
+
+### CRITICAL: Finding Relevant Files (Rate Limit: 10 Files Max)
+
+**You have freedom to explore the codebase** to find files that should comply with this spec, but you are limited to checking **up to 10 files maximum** per run to stay within rate limits.
+
+{{#if SUITE_SCOPE}}
+### Scope Constraint
+
+⚠️ **You are enforcing this spec within suite `{{SUITE_ID}}`.**
+
+**ONLY explore files matching this pattern:**
+```
+{{SUITE_SCOPE}}
+```
+
+Use `Glob("{{SUITE_SCOPE}}")` to find relevant files. Do NOT check files outside this scope.
+{{/if}}
+
+**Exploration Strategy**:
+
+1. **Start Broad**: Use `Glob` to search by file patterns (e.g., `**/*Orchestrator*.js`){{#if SUITE_SCOPE}} - constrained to `{{SUITE_SCOPE}}`{{/if}}
+2. **Narrow Down**: Use `Grep` to search by content patterns (e.g., class names, function signatures)
+3. **Prioritize**: Read file names/paths to identify the most critical files
+4. **Select Wisely**: Choose up to 10 files that are most likely to have violations
+
+**Examples**:
+- THOR.md spec → search for `Thor*`, `VirtualClock`, `InterceptionManager`
+- BARDE.md spec → search for `Barde*`, `UniversalStopLossManager`, `paper_trading*`
+- OVERSEER.md spec → search for `Overseer*`, `ML*`, `ensemble*`
+
+**Priority Guidelines**:
+- Core implementation files > utility/helper files
+- Files that directly implement spec requirements > tangentially related files
+- Files with high complexity > simple configuration files
+
+**Important**: Focus on quality over quantity. It's better to thoroughly check 10 critical files than to superficially check 20 files.
+
+### CRITICAL: Spec vs Code Decision
+
+**BEFORE changing any code**, run the code-reviewer sub-agent to determine the correct action:
+
+- **If spec is outdated**: Update the spec to match the intentional code behavior
+- **If code is wrong**: Fix the code to match the spec
+
+The code-reviewer will analyze whether:
+1. The code pattern is intentional and the spec is outdated
+2. The code depends on specific patterns (e.g., ID formats parsed by other code)
+3. Changing code would break other parts of the system
+4. The spec needs clarification or exceptions added
+
+**Go with the code-reviewer's recommendation, even if that means updating the spec rather than the code.**
+
+### Critical Rules (from CLAUDE.md)
+
+In addition to the spec requirements, you MUST enforce these global invariants:
+
+- **NO GRACEFUL FALLBACKS** - Fail hard and loud when something doesn't meet specification
+- **NO MOCKS IN PRODUCTION CODE** - No `isMockMode`, `MOCK_MODE`, `mockMode`, `isSimulation` checks in `src/**/*.js`
+- **MONETARY PRECISION** - All monetary values rounded to 2 decimal places (float dollars OK)
+- **ISO 8601 TIMESTAMPS** - All timestamps in ISO 8601 format
+- **UNIQUE IDENTIFIERS** - UUIDs v4 preferred, but timestamp-based IDs acceptable if code parses them
+- **FAIL-HARD ON MISSING DATA** - Never silently return null/undefined/empty when data is expected
+
+**Note**: These rules have documented exceptions in `specs/global/CORE-INVARIANTS.md`. Check the spec for acceptable patterns before flagging violations.
+
+## Workflow
+
+Use the standard sub-agent sequence per CLAUDE.md. The key difference here is that you explore the codebase to find relevant files, and code-reviewer runs BEFORE code-writer to decide the fix approach.
+
+### 1. Investigator (batch up to 3)
+
+**Task**: Find files that should comply with this spec, then identify ALL violations.
+
+**Phase 1 - Discovery**:
+- Use Glob to search for files by name patterns
+- Use Grep to search for files by content patterns
+- Read files to assess relevance to the spec
+- Build a list of files that MUST comply
+
+**Phase 2 - Violation Detection**:
+- For each relevant file, check against ALL spec requirements
+- Document violations with line numbers, code snippets, rules violated
+
+**Output**:
+- List of relevant files found
+- For each file, list of violations with:
+  - Line numbers
+  - Code snippets
+  - Rule violated
+  - Severity (critical/high/medium/low)
+  - Suggested fix
+
+**Important**: Be thorough in discovery. Don't miss files that should comply.
+
+### 2. Code-Reviewer (DECISION PHASE - batch up to 3)
+
+**Task**: For each identified violation, determine the correct fix approach.
+
+**Analysis for each violation**:
+1. Is this code pattern intentional? (Check commit history, related code)
+2. Does other code depend on this pattern? (e.g., ID parsing, data formats)
+3. Would changing this code break other parts of the system?
+4. Is the spec outdated or missing an exception?
+
+**Decision for each violation**:
+- **FIX_CODE**: The code is wrong, fix it to match the spec
+- **UPDATE_SPEC**: The code is correct, update the spec to document the pattern
+- **ADD_EXCEPTION**: The code has a valid reason, add an exception to the spec
+
+**Output**: For each violation, provide:
+- Decision: FIX_CODE / UPDATE_SPEC / ADD_EXCEPTION
+- Reasoning: Why this is the correct approach
+- Impact: What would change with each option
+
+**Important**: Your recommendation will be followed. Be thorough in your analysis.
+
+### 3. Code-Writer (batch up to 3)
+
+**Task**: Apply the recommended fixes from the code-reviewer.
+
+**For FIX_CODE decisions**:
+- Make minimal changes (only what's needed to fix violations)
+- Preserve existing functionality
+- Follow existing code style
+- Add comments explaining non-obvious changes
+
+**For UPDATE_SPEC or ADD_EXCEPTION decisions**:
+- Edit the spec file at `{{SPEC_PATH}}` (provided in assignment above)
+- Add clear documentation of the exception or pattern
+- Include rationale for why this is acceptable
+
+**Important**: Do NOT introduce new violations while fixing old ones. Double-check your changes.
+
+### 4. Test-Writer (ONLY if code was changed - batch up to 3)
+
+**Task**: Ensure tests cover any code changes made.
+
+**When to run**:
+- ALWAYS run if FIX_CODE was applied to any violation
+- SKIP if only spec updates were made (no code changes)
+
+**Requirements**:
+- Add new tests if needed to cover fixes
+- Update existing tests if they break
+- Ensure tests verify spec compliance
+- Follow test patterns in existing test files
+
+**Important**: Tests should verify the spec requirements, not just that code doesn't crash.
+
+### 5. Code-Reviewer (FINAL REVIEW - batch up to 3)
+
+**Task**: Review all changes for correctness.
+
+**Check**:
+- ✅ All violations addressed per the decision phase recommendations
+- ✅ No new violations introduced
+- ✅ Tests pass and cover code changes (if any)
+- ✅ Spec updates are clear and accurate (if any)
+- ✅ No unintended side effects
+
+**Important**: Be critical. If something looks wrong, flag it and have code-writer fix it.
+
+### 6. Project-Manager (MANDATORY, ALWAYS LAST)
+
+**Task**: Document all changes in the session report.
+
+**Include**:
+- Summary of files found that should comply
+- Summary of violations found across all files
+- For each violation: decision made (FIX_CODE/UPDATE_SPEC/ADD_EXCEPTION)
+- Summary of code fixes applied
+- Summary of spec updates made
+- Test changes made (if any)
+- Any remaining issues or concerns
+
+**Important**: NEVER run project-manager in parallel. It must always be the final step.
+
+## Batching Example
+
+If you find 3 relevant files with 2 violations each (6 total violations):
+
+- **Round 1**: 3 investigators identify relevant files + violations in files 1-3
+- **Round 2**: 3 investigators identify violations in remaining files (if needed)
+- **Round 3**: 3 code-reviewers analyze violations 1-3 (DECISION PHASE - FIX_CODE/UPDATE_SPEC/ADD_EXCEPTION)
+- **Round 4**: 3 code-reviewers analyze violations 4-6 (DECISION PHASE)
+- **Round 5**: 3 code-writers apply fixes for violations 1-3 (code OR spec, per reviewer decision)
+- **Round 6**: 3 code-writers apply fixes for violations 4-6 (code OR spec, per reviewer decision)
+- **Round 7**: 3 test-writers add/update tests (ONLY for FIX_CODE decisions)
+- **Round 8**: 3 code-reviewers review all changes (FINAL REVIEW)
+- **Round 9**: 1 project-manager documents everything (LAST, NEVER PARALLEL)
+
+**Key Change**: Code-reviewer runs TWICE - once to decide the approach (step 3-4), and once to verify the changes (step 8).
+
+## Output Format
+
+Provide a compliance report at the end:
+
+```
+## Compliance Report: {{SPEC_NAME}}
+
+### Exploration Phase
+
+**Files Found**: [TOTAL COUNT]
+**Files Checked**: [COUNT] (max 10 due to rate limits)
+
+**Search Patterns Used**:
+- Glob: [patterns]
+- Grep: [keywords]
+
+**Selected Files** (checked):
+1. [path] - [reason for selection]
+2. [path] - [reason for selection]
+...
+
+**Files Not Checked** (if total > 10):
+- [path] - [reason for lower priority]
+- ...
+
+### Total Violations Found: [COUNT]
+
+#### File: [path/to/file1.js]
+
+**Violation 1**: [Rule ID] [Brief description]
+- Location: Line [N]
+- Code: `[snippet]`
+- Severity: [critical/high/medium/low]
+- Decision: FIX_CODE / UPDATE_SPEC / ADD_EXCEPTION
+- Reasoning: [Why this decision was made]
+- Status: RESOLVED / NEEDS_MANUAL_REVIEW
+
+**Violation 2**: ...
+
+#### File: [path/to/file2.js]
+
+...
+
+### Code Changes Made
+
+- [File path]: [Description of code fix]
+- [Impact on codebase]
+
+### Spec Changes Made
+
+- [Spec file]: [What was updated/added]
+- [Reasoning for spec change]
+
+### Tests Added/Modified (if any code was changed)
+
+- [Test file]: [What was added/changed]
+- [Coverage impact]
+
+### Status: COMPLIANT / NEEDS_MANUAL_REVIEW
+
+**Final Assessment**: [Brief statement on compliance status across all checked files]
+
+**Remaining Issues**: [Any issues that couldn't be auto-fixed]
+
+**Recommendation**: [If files not checked, recommend re-running compliance check on them]
+```
+
+## Important Notes
+
+- **This is a TRADING SYSTEM** - Mistakes can cost money. Be thorough.
+- **Rate limit: 10 files max** - Choose the most critical files for checking
+- **You have freedom to explore** - Use Glob/Grep to find relevant files, but prioritize wisely
+- **Quality over quantity** - Better to thoroughly check 10 critical files than superficially check 20
+- **Spec updates are valid fixes** - If code is correct and spec is outdated, update the spec
+- **Code-reviewer decides** - Follow the code-reviewer's recommendation for each violation
+- **Test-writer follows code changes** - Always run test-writer after code is modified
+- **Fail hard** - Per CLAUDE.md, never use graceful fallbacks or silent failures
+- **NEVER run project-manager in parallel** - It must always be the final step
+- **Document everything** - Future maintainers need to understand what changed and why
+- **Document unchecked files** - If more than 10 relevant files found, list the ones not checked

package/.claude/hooks/prompts/mapping-fix.md

@@ -0,0 +1,92 @@
+# Fix Spec-File Mappings - Compliance Checker
+
+You are fixing the `spec-file-mappings.json` file for the ODIN compliance checker system.
+
+## Problem
+
+The spec-file-mappings.json file has validation errors that must be fixed before the compliance enforcer can run.
+
+## Validation Errors
+
+```
+{{VALIDATION_ERRORS}}
+```
+
+## Current Mapping File Content
+
+```json
+{{CURRENT_MAPPINGS}}
+```
+
+## Required Schema
+
+```json
+{{SCHEMA_CONTENT}}
+```
+
+## Required Specs
+
+Every spec in this list MUST have an entry in the mappings file:
+
+{{REQUIRED_SPECS_LIST}}
+
+## Instructions
+
+1. **Read the validation errors carefully** - Understand each error before making changes
+2. **Fix each error in the mapping file** - Address all critical errors
+3. **Ensure the JSON is valid** - Proper syntax, no trailing commas
+4. **Ensure every required spec has an entry** with:
+   - `description`: Brief explanation (10+ chars)
+   - `priority`: One of "critical", "high", "medium", "low"
+   - `files`: Array of file objects with `path` (must start with "src/" and end with ".js") and `lastVerified` (ISO timestamp or null)
+   - `rationale`: Explanation of why these files are mapped (20+ chars)
+5. **Update `totalMappedFiles`** to reflect the sum of all files across all specs
+6. **Update `lastReviewed`** to current ISO timestamp
+7. **Update `lastReviewedBy`** to "claude-mapping-fixer"
+
+## Agent Limit - CRITICAL
+
+**The total number of files across ALL specs must not exceed {{MAX_AGENTS}}.**
+
+- Current count: {{CURRENT_AGENT_COUNT}}
+- Limit: {{MAX_AGENTS}}
+- Excess: {{EXCESS_COUNT}}
+
+If the current count exceeds the limit, you MUST remove at least {{EXCESS_COUNT}} files to bring the total under the limit.
+
+**Prioritize removing:**
+- Files from low-priority specs
+- Files unlikely to have violations
+- Duplicate or redundant coverage
+- Peripheral files that don't directly implement spec requirements
+
+## Workflow
+
+Use the standard sub-agent sequence per CLAUDE.md:
+
+1. **Investigator**: Analyze the errors and understand what needs fixing. Read the current mapping file, schema, and errors.
+
+2. **Code-Writer**: Edit `.claude/hooks/spec-file-mappings.json` to fix all errors. Ensure:
+   - All required specs are present
+   - All file paths are valid (start with "src/", end with ".js")
+   - Total file count is within limit
+   - JSON is syntactically correct
+   - All required fields are present
+
+3. **Test-Writer**: Skip (no tests for JSON config)
+
+4. **Code-Reviewer**: Verify the fixed file:
+   - Valid JSON syntax
+   - All required specs present
+   - Total file count ≤ {{MAX_AGENTS}}
+   - All required fields present
+   - `totalMappedFiles` matches actual count
+
+5. **Project-Manager** (MANDATORY, ALWAYS LAST): Document the fixes made in the session report
+
+## Important Notes
+
+- **NEVER run project-manager in parallel** - It must always be the final step
+- **DO NOT add files without careful consideration** - Each file = 1 Claude agent = token cost
+- **Be conservative** - Only map files with HIGH probability of spec violations
+- **Fail hard if you cannot fix** - Per CLAUDE.md, never use graceful fallbacks

package/.claude/hooks/prompts/mapping-review.md

@@ -0,0 +1,140 @@
+# Review Spec-File Mappings - Compliance Checker
+
+You are reviewing the `spec-file-mappings.json` file for the ODIN compliance checker system.
+
+## Current Status
+
+The mapping file is **VALID** and passes all validation checks. Your task is to review whether the mappings are optimal and make improvements if needed.
+
+## Current Mapping File
+
+```json
+{{CURRENT_MAPPINGS}}
+```
+
+## Agent Budget
+
+| Metric | Value |
+|--------|-------|
+| Current Total Files | {{CURRENT_AGENT_COUNT}} |
+| Maximum Allowed | {{MAX_AGENTS}} |
+| Utilization | {{UTILIZATION_PERCENT}}% |
+| Remaining Budget | {{REMAINING_BUDGET}} files |
+
+## Per-Spec Breakdown
+
+{{SPEC_BREAKDOWN_TABLE}}
+
+## Your Task
+
+Review the mappings with a **CONSERVATIVE** approach. Each mapped file spawns a Claude agent, which costs tokens.
+
+### 1. Remove Files That Shouldn't Be Mapped
+
+Look for:
+- **Files unlikely to violate the spec** - Stable, well-tested, rarely-changing files
+- **Low-risk or peripheral files** - Files that don't directly implement spec requirements
+- **Duplicates** - Files already covered by other specs
+- **Test files or fixtures** - Should not be in src/ anyway
+
+### 2. Add Files That Should Be Mapped (Only if Clearly Needed)
+
+Only add files if:
+- **Known violators** - Check CLAUDE.md for Bug #145-148 mentions
+- **Core components** - Files that directly implement spec requirements
+- **Historical violations** - Files that have had compliance issues before
+- **High-risk files** - Complex files likely to violate architectural constraints
+
+### 3. Prioritize High-Impact Mappings
+
+- **Critical/high priority specs** should have key files mapped
+- **Low priority specs** might need fewer files
+- Focus on files with HIGH probability of violations
+
+## Conservative Guidance - READ THIS CAREFULLY
+
+- **Lean toward FEWER entries**, not more
+- **Each file = 1 Claude agent = significant token cost**
+- **Only map files with HIGH probability of spec violations**
+- **Peripheral or rarely-changing files can often be skipped**
+- **When in doubt, DON'T add a file**
+- **The goal is PRECISION, not COVERAGE** - We want to catch violations efficiently, not check everything
+
+## Spec Reference
+
+For reference, here are the specs and their key concerns:
+
+| Spec | Key Concerns |
+|------|--------------|
+| **BARDE.md** | Paper trading, conservative bias (1% worse fills), 4 stop-loss types, object pooling, lock-free queues |
+| **HEIMDALL.md** | 7 sensors, pre-flight tests, health monitoring, Thor integration, hourly reports |
+| **HUGINN.md** | 75% confidence threshold, capital recycling ($10K per strategy), position lifecycle, REPLACES old veto system |
+| **OVERSEER.md** | 150-dim feature vectors, [-1,1] normalization, 3-model ensemble, trains on strategy paper trades |
+| **UNDERSEER.md** | 10 variations, fitness=(avgPnL*0.7 + winRate*0.3), 7-day cycles, 28-day epochs |
+| **THOR.md** | 1:1 production parity, API interception, NO VirtualClock in production code, monkey-patching pattern |
+| **SIGNALS.md** | 3-layer system (Asset→Position→Strategy), namespace isolation, fail-hard on missing signals |
+| **CORE-INVARIANTS.md** | No mocks in production, fail-hard (no fallbacks), money as integers, ISO timestamps, UUIDs v4 |
+
+## Known Violators (from CLAUDE.md)
+
+These files are **CONFIRMED** violators and should be mapped to CORE-INVARIANTS.md:
+
+- `src/money-management/core/MoneyManager.js` (Bug #145 - has `isMockMode`)
+- `src/orchestration/scheduling/StrategyScheduler.js` (Bug #146 - has `isMockMode`)
+- `src/orchestration/resource-management/ResourceManager.js` (Bug #147 - has `isMockMode`)
+- `src/services/HistoricalDataCache.js` (Bug #148 - has `isMockMode`)
+
+## Math Check - REQUIRED
+
+Before finalizing, calculate:
+- **New total file count** = sum of all files across all specs
+- **Ensure new total ≤ {{MAX_AGENTS}}**
+- **Report the delta** - How many files added/removed
+
+## Output Format
+
+After your review, if changes are needed:
+
+1. Update the mapping file
+2. Update `totalMappedFiles` to the new count
+3. Update `lastReviewed` to current ISO timestamp
+4. Update `lastReviewedBy` to "claude-mapping-reviewer"
+5. Document all changes in your final report
+
+## Workflow
+
+Use the standard sub-agent sequence per CLAUDE.md. If there are multiple changes to make, batch agents (up to 3 at a time):
+
+1. **Investigator** (batch up to 3):
+   - Explore the codebase to understand which files are most relevant
+   - Check for known violations in CLAUDE.md
+   - Analyze current mappings for appropriateness
+   - Identify files to add/remove
+
+2. **Code-Writer** (batch up to 3):
+   - Update `.claude/hooks/spec-file-mappings.json` with your changes
+   - Update `totalMappedFiles` to reflect actual count
+   - Update `lastReviewed` to current ISO timestamp
+   - Update `lastReviewedBy` to "claude-mapping-reviewer"
+
+3. **Test-Writer**: Skip (no tests for JSON config)
+
+4. **Code-Reviewer** (batch up to 3):
+   - Verify the updated file is valid JSON
+   - Verify file count is accurate and within limit
+   - Verify all paths start with "src/" and end with ".js"
+   - Verify all required fields are present
+
+5. **Project-Manager** (MANDATORY, ALWAYS LAST):
+   - Document all changes in session report
+   - List files removed with reasons
+   - List files added with reasons
+   - Report net change in file count
+
+## Important Notes
+
+- **NEVER run project-manager in parallel** - It must always be the final step
+- **Be conservative** - Removing a file is often better than adding one
+- **Each file has a cost** - Only add files with clear, compelling reasons
+- **The system has 315 source files** - We cannot check them all
+- **Current utilization: {{UTILIZATION_PERCENT}}%** - Is this appropriate? Consider reducing if high.