refactor: sidecar-evaluate decomposition (learning/decisions/reinforcement modules)

[dean0x]

Overview

sidecar-evaluate has grown to 496 lines with 7 levels of nesting, handling 3 independent features (learning, decisions, reinforcement). Warrants decomposition into independently-sourceable modules. This issue consolidates tech debt from PR #228.

Items

1. sidecar-evaluate monolith (496 lines, 7-level nesting)

   • Handles: learning agent trigger, decisions agent trigger, reinforcement batching, lock cleanup
   • Risk: high cyclomatic complexity, difficult to reason about control flow, tough to modify one feature without affecting others
   • Solution: decompose into sidecar-evaluate-learning.cjs, sidecar-evaluate-decisions.cjs, sidecar-evaluate-reinforcement.cjs (or similar modular structure)

2. EXIT trap handling asymmetry

   • Reinforcement section uses EXIT trap for lock cleanup (line 177, 234-235)
   • Other sections rely on reaching sidecar_lock_release at natural exit
   • Risk: if an early exit path is added, lock cleanup might be skipped in some branches
   • Solution: consistent trap-based lock cleanup across all modules, or unified exit handler

Implementation Plan

• Extract learning trigger logic to standalone module
• Extract decisions trigger logic to standalone module
• Extract reinforcement batching to standalone module
• Consolidate lock cleanup into single trap handler or unified release pattern
• Test all three agents trigger correctly
• Verify lock cleanup on all exit paths (normal, error, signal)

Design Notes

• Each module can be sourced independently for testing
• Maintain atomic file operations (temp+mv for transient state)
• Document shared dependencies (log-paths, json-helper, transient lock directory)

Related

• PR fix(hooks): stop hook field rename + debug tracing system #228: introduced debug-trace + hook field rename
• Related issues: refactor: decompose init.ts action handler into phase functions #139 (decompose init.ts), refactor: decompose learn.ts 673-line action handler into independent functions #207 (decompose learn.ts)