docs: Remove temporary analysis documents

docs/CODEX_LOGICAL_REVIEW.md

@@ -1,519 +0,0 @@
-# Codex PRs: Logical Correctness Analysis
-
-**Date**: 2024-11-27  
-**Reviewer**: AI Agent  
-**Scope**: PRs #4, #5, #7 - Logical correctness validation (performance not evaluated)
-
----
-
-## Executive Summary
-
-All three remaining PRs are **logically sound** and safe to merge. No logical errors, broken invariants, or dangerous assumptions detected. Minor observations noted for future consideration.
-
-**VERDICT**: ✅ **APPROVE ALL THREE** - Merge without concerns about correctness
-
----
-
-## PR #5: Shared Reward Helper for Metrics
-
-**Branch**: `codex/introduce-shared-reward-helper-for-metrics`  
-**Verdict**: ✅ **LOGICALLY CORRECT**
-
-### What it does
-
-Creates `EpisodeRewardHelper` class to centralize reward computation logic previously duplicated between agent and training environment.
-
-### Correctness Analysis
-
-#### 1. State Tracking ✅
-```python
-_disposed_cases: int = 0
-_hearing_counts: Dict[str, int] = field(default_factory=lambda: defaultdict(int))
-_urgent_latencies: list[float] = field(default_factory=list)
-```
-
-**Logic**: Sound. Tracks episode-level metrics incrementally as decisions are made.
-
-**Issue**: None. Proper initialization and accumulation.
-
-#### 2. Base Reward Computation ✅
-```python
-def _base_outcome_reward(self, case: Case, was_scheduled: bool, hearing_outcome: str) -> float:
-    reward = 0.0
-    if not was_scheduled:
-        return reward
-    
-    reward += 0.5  # Base scheduling reward
-    
-    lower_outcome = hearing_outcome.lower()
-    if "disposal" in lower_outcome or "judgment" in lower_outcome or "settlement" in lower_outcome:
-        reward += 10.0  # Major positive for disposal
-    elif "progress" in lower_outcome and "adjourn" not in lower_outcome:
-        reward += 3.0  # Progress without disposal
-    elif "adjourn" in lower_outcome:
-        reward -= 3.0  # Negative for adjournment
-```
-
-**Logic**: Sound. Hierarchical string matching with proper elif chain prevents double-counting.
-
-**Issue**: None. "progress" excludes "adjourn" correctly.
-
-#### 3. Episode-Level Components ✅
-```python
-disposal_rate = (self._disposed_cases / self.total_cases) if self.total_cases else 0.0
-reward += self.disposal_weight * disposal_rate
-```
-
-**Logic**: Sound. Safe division with zero check. Rewards scale with system-level disposal rate.
-
-**Issue**: None. Properly guards against division by zero.
-
-#### 4. Gap Scoring ✅
-```python
-if previous_gap_days is not None:
-    gap_score = max(0.0, 1.0 - (previous_gap_days / self.target_gap_days))
-    reward += self.gap_weight * gap_score
-```
-
-**Logic**: Sound. Normalized to [0, 1] range, rewards shorter gaps.
-
-**Issue**: None. Proper bounds checking with `max(0.0, ...)`.
-
-#### 5. Fairness Score ✅
-```python
-def _fairness_score(self) -> float:
-    counts: Iterable[int] = self._hearing_counts.values()
-    if not counts:
-        return 0.0
-    
-    counts_array = np.array(list(counts), dtype=float)
-    mean = np.mean(counts_array)
-    if mean == 0:
-        return 0.0
-    
-    dispersion = np.std(counts_array) / (mean + 1e-6)
-    fairness = max(0.0, 1.0 - dispersion)
-    return fairness
-```
-
-**Logic**: Sound. Coefficient of variation (std/mean) as dispersion metric. Lower dispersion = better fairness.
-
-**Issue**: None. Proper zero checks and epsilon stabilization.
-
-#### 6. Training Integration ✅
-```python
-# OLD (buggy):
-def _compute_reward(self, case: Case, outcome: str) -> float:
-    agent = TabularQAgent()  # Creates fresh agent instance!
-    return agent.compute_reward(case, was_scheduled=True, hearing_outcome=outcome)
-
-# NEW (correct):
-self.reward_helper = EpisodeRewardHelper(total_cases=len(self.cases))  # Reused per episode
-
-rewards[case.case_id] = self.reward_helper.compute_case_reward(
-    case,
-    was_scheduled=True,
-    hearing_outcome=outcome,
-    current_date=self.current_date,
-    previous_gap_days=previous_gap,
-)
-```
-
-**Logic**: Sound. Fixes P1 bug - episode helper reused throughout episode instead of fresh agent per case.
-
-**Issue**: None. Proper lifecycle management.
-
-### Correctness Verdict: ✅ PASS
-
-**No logical errors detected.**
-
----
-
-## PR #4: RL Training Alignment with SchedulingAlgorithm
-
-**Branch**: `codex/modify-training-for-schedulingalgorithm-integration`  
-**Verdict**: ✅ **LOGICALLY CORRECT**
-
-### What it does
-
-Integrates production `SchedulingAlgorithm` into RL training environment to close training-production gap.
-
-### Correctness Analysis
-
-#### 1. Production Components Initialization ✅
-```python
-self.courtrooms = [
-    Courtroom(
-        courtroom_id=i + 1,
-        judge_id=f"J{i+1:03d}",
-        daily_capacity=self.rl_config.daily_capacity_per_courtroom,
-    )
-    for i in range(self.rl_config.courtrooms)
-]
-self.allocator = CourtroomAllocator(
-    num_courtrooms=self.rl_config.courtrooms,
-    per_courtroom_capacity=self.rl_config.daily_capacity_per_courtroom,
-    strategy=AllocationStrategy.LOAD_BALANCED,
-)
-self.algorithm = SchedulingAlgorithm(
-    policy=self.policy,
-    allocator=self.allocator,
-    min_gap_days=self.policy_config.min_gap_days if self.rl_config.enforce_min_gap else 0,
-)
-```
-
-**Logic**: Sound. Mirrors production initialization with configurable parameters.
-
-**Issue**: None. Proper conditional logic for `min_gap_days`.
-
-#### 2. Agent Decisions → Priority Overrides ✅
-```python
-overrides: List[Override] = []
-priority_boost = 1.0
-for case in self.cases:
-    if agent_decisions.get(case.case_id) == 1:
-        overrides.append(
-            Override(
-                override_id=f"rl-{case.case_id}-{self.current_date.isoformat()}",
-                override_type=OverrideType.PRIORITY,
-                case_id=case.case_id,
-                judge_id="RL-JUDGE",
-                timestamp=self.current_date,
-                new_priority=case.get_priority_score() + priority_boost,
-            )
-        )
-        priority_boost += 0.1  # keep relative ordering stable
-```
-
-**Logic**: Sound. Converts agent binary decisions (0/1) into priority overrides.
-
-**Observation**: Incremental priority boost preserves agent's relative ordering if multiple cases selected.
-
-**Issue**: None. Proper override construction.
-
-#### 3. Scheduling Algorithm Invocation ✅
-```python
-result = self.algorithm.schedule_day(
-    cases=self.cases,
-    courtrooms=self.courtrooms,
-    current_date=self.current_date,
-    overrides=overrides or None,
-    preferences=self.preferences,
-)
-
-scheduled_cases = [c for cases in result.scheduled_cases.values() for c in cases]
-```
-
-**Logic**: Sound. Uses production algorithm with agent's overrides. Flattens scheduled cases across courtrooms.
-
-**Issue**: None. Proper dict traversal.
-
-#### 4. Capacity Enforcement ✅
-```python
-daily_cap = config.max_daily_allocations or total_capacity
-if not config.cap_daily_allocations:
-    daily_cap = len(eligible_cases)
-remaining_slots = min(daily_cap, total_capacity) if config.cap_daily_allocations else daily_cap
-
-for case in eligible_cases[:daily_cap]:
-    # ... get state and action
-    
-    if config.cap_daily_allocations and action == 1 and remaining_slots <= 0:
-        action = 0  # Override agent decision if capacity exhausted
-    elif action == 1 and config.cap_daily_allocations:
-        remaining_slots = max(0, remaining_slots - 1)
-```
-
-**Logic**: Sound. Enforces daily capacity limits. Overrides agent decisions if capacity exhausted.
-
-**Issue**: None. Proper decrement and zero check.
-
-#### 5. State Space Expansion ✅
-```python
-# OLD: 6-dimensional state
-def to_tuple(self) -> Tuple[int, int, int, int, int, int]:
-    return (
-        self.stage_encoded,
-        min(9, int(self.age_days * 20)),
-        min(9, int(self.days_since_last * 20)),
-        self.urgency,
-        self.ripe,
-        min(9, int(self.hearing_count * 20))
-    )
-
-# NEW: 9-dimensional state
-def to_tuple(self) -> Tuple[int, int, int, int, int, int, int, int, int]:
-    return (
-        self.stage_encoded,
-        min(9, int(self.age_days * 20)),
-        min(9, int(self.days_since_last * 20)),
-        self.urgency,
-        self.ripe,
-        min(9, int(self.hearing_count * 20)),
-        min(9, int(self.capacity_ratio * 10)),    # NEW: remaining capacity
-        min(30, self.min_gap_days),                # NEW: gap enforcement
-        min(9, int(self.preference_score * 10))    # NEW: judge preference alignment
-    )
-```
-
-**Logic**: Sound. Adds environment context to state representation. Proper discretization and bounds.
-
-**Observation**: State space grows from ~10^6 to ~10^9 states (3 orders of magnitude). Q-table may become sparse.
-
-**Issue**: None logically. Performance implications exist but correctness is sound.
-
-#### 6. Capacity Ratio Helper ✅
-```python
-def capacity_ratio(self, remaining_slots: int) -> float:
-    total_capacity = self.rl_config.courtrooms * self.rl_config.daily_capacity_per_courtroom
-    return max(0.0, min(1.0, remaining_slots / total_capacity)) if total_capacity else 0.0
-```
-
-**Logic**: Sound. Safe division with zero check. Normalized to [0, 1].
-
-**Issue**: None.
-
-#### 7. Preference Score Helper ✅
-```python
-def preference_score(self, case: Case) -> float:
-    if not self.preferences:
-        return 0.0
-    
-    day_name = self.current_date.strftime("%A")
-    preferred_types = self.preferences.case_type_preferences.get(day_name, [])
-    return 1.0 if case.case_type in preferred_types else 0.0
-```
-
-**Logic**: Sound. Binary preference signal (1.0 if aligned, 0.0 otherwise).
-
-**Issue**: None.
-
-### Correctness Verdict: ✅ PASS
-
-**No logical errors detected.** State space expansion is intentional and correctly implemented.
-
----
-
-## PR #7: Output Manager Metadata Tracking
-
-**Branch**: `codex/extend-output-manager-for-eda-recording`  
-**Verdict**: ✅ **LOGICALLY CORRECT**
-
-### What it does
-
-Adds metadata recording to `OutputManager` for EDA versioning, training KPIs, evaluation stats, and simulation metrics.
-
-### Correctness Analysis
-
-#### 1. Run Record Initialization ✅
-```python
-def create_structure(self):
-    # ... create directories
-    
-    if not self.run_record_file.exists():
-        self._update_run_record("run", {
-            "run_id": self.run_id,
-            "created_at": self.created_at,
-            "base_dir": str(self.run_dir),
-        })
-```
-
-**Logic**: Sound. Initializes run record on first directory creation.
-
-**Issue**: None. Idempotent check with `exists()`.
-
-#### 2. Run Record Update Helper ✅
-```python
-def _update_run_record(self, section: str, payload: Dict[str, Any]):
-    record = self._load_run_record()
-    record.setdefault("sections", {})
-    record["sections"][section] = payload
-    record["updated_at"] = datetime.now().isoformat()
-    
-    with open(self.run_record_file, "w", encoding="utf-8") as f:
-        json.dump(record, f, indent=2, default=str)
-```
-
-**Logic**: Sound. Atomic section updates with timestamp tracking. UTF-8 encoding for Windows compatibility.
-
-**Issue**: None. Proper dictionary mutation pattern.
-
-#### 3. EDA Metadata Recording ✅
-```python
-def record_eda_metadata(self, version: str, used_cached: bool, params_path: Path, figures_path: Path):
-    payload = {
-        "version": version,
-        "timestamp": datetime.now().isoformat(),
-        "used_cached": used_cached,
-        "params_path": str(params_path),
-        "figures_path": str(figures_path),
-    }
-    
-    self._update_run_record("eda", payload)
-```
-
-**Logic**: Sound. Tracks EDA version and cache usage for reproducibility.
-
-**Issue**: None. Clean separation of concerns.
-
-#### 4. Training Stats Persistence ✅
-```python
-def save_training_stats(self, training_stats: Dict[str, Any]):
-    self.training_dir.mkdir(parents=True, exist_ok=True)
-    with open(self.training_stats_file, "w", encoding="utf-8") as f:
-        json.dump(training_stats, f, indent=2, default=str)
-```
-
-**Logic**: Sound. Saves raw training statistics to dedicated file.
-
-**Issue**: None. Proper directory creation.
-
-#### 5. Evaluation Stats Persistence ✅
-```python
-def save_evaluation_stats(self, evaluation_stats: Dict[str, Any]):
-    eval_path = self.training_dir / "evaluation.json"
-    with open(eval_path, "w", encoding="utf-8") as f:
-        json.dump(evaluation_stats, f, indent=2, default=str)
-    
-    self._update_run_record("evaluation", {
-        "path": str(eval_path),
-        "timestamp": datetime.now().isoformat(),
-    })
-```
-
-**Logic**: Sound. Persists evaluation metrics and updates run record.
-
-**Issue**: None. Consistent pattern.
-
-#### 6. Simulation KPI Recording ✅
-```python
-def record_simulation_kpis(self, policy: str, kpis: Dict[str, Any]):
-    policy_dir = self.get_policy_dir(policy)
-    metrics_path = policy_dir / "metrics.json"
-    with open(metrics_path, "w", encoding="utf-8") as f:
-        json.dump(kpis, f, indent=2, default=str)
-    
-    record = self._load_run_record()
-    simulation_section = record.get("simulation", {})
-    simulation_section[policy] = kpis
-    record["simulation"] = simulation_section
-    record["updated_at"] = datetime.now().isoformat()
-    
-    with open(self.run_record_file, "w", encoding="utf-8") as f:
-        json.dump(record, f, indent=2, default=str)
-```
-
-**Logic**: Sound. Per-policy metrics storage with consolidated run record tracking.
-
-**Issue**: None. Proper nested dictionary updates.
-
-#### 7. Integration in Pipeline ✅
-
-**EDA Recording**:
-```python
-self.output.record_eda_metadata(
-    version=eda_config.VERSION,
-    used_cached=True,
-    params_path=self.output.eda_params,
-    figures_path=self.output.eda_figures,
-)
-```
-
-**Training Recording**:
-```python
-self.output.save_training_stats(training_stats)
-self.output.save_evaluation_stats(evaluation_stats)
-self.output.record_training_summary(training_summary, evaluation_stats)
-```
-
-**Simulation Recording**:
-```python
-kpis = {
-    "policy": policy,
-    "disposals": result.disposals,
-    "disposal_rate": result.disposals / len(policy_cases),
-    # ... other metrics
-}
-self.output.record_simulation_kpis(policy, kpis)
-```
-
-**Logic**: Sound. Proper integration at each pipeline stage. Captures metadata at point of generation.
-
-**Issue**: None. Clean separation of concerns.
-
-#### 8. Error Handling ✅
-```python
-try:
-    evaluation_stats = evaluate_agent(...)
-    self.output.save_evaluation_stats(evaluation_stats)
-except Exception as eval_err:
-    console.print(f"  [yellow]WARNING[/yellow] Evaluation skipped: {eval_err}")
-```
-
-**Logic**: Sound. Graceful degradation if evaluation fails. Warning instead of crash.
-
-**Issue**: None. Proper exception handling.
-
-### Correctness Verdict: ✅ PASS
-
-**No logical errors detected.** All metadata recording is additive and safe.
-
----
-
-## Cross-PR Compatibility Analysis
-
-### PR #4 + PR #5 Interaction ✅
-
-**Scenario**: Both modify `rl/training.py`
-
-**Conflict**: PR #4 adds capacity/preference context to state extraction. PR #5 replaces reward computation with helper.
-
-**Resolution**: Compatible. Different concerns - state representation vs reward computation.
-
-**Merge Strategy**: Either order works. No logical dependency.
-
-### PR #7 Integration ✅
-
-**Scenario**: PR #7 adds metadata tracking to `OutputManager` and `court_scheduler_rl.py`
-
-**Conflict**: None. Purely additive changes.
-
-**Resolution**: Independent of PR #4 and #5. Can merge in any order.
-
----
-
-## Final Recommendation
-
-### All Three PRs: ✅ APPROVE
-
-**Logical Correctness**: All three PRs are logically sound with no errors, broken invariants, or dangerous assumptions.
-
-**Merge Order** (any order works, but suggested sequence):
-
-1. **PR #5** (Shared reward logic) - Low complexity, fixes P1 bug
-2. **PR #4** (RL training alignment) - High complexity, but logically correct
-3. **PR #7** (Output metadata) - Pure additive, no conflicts
-
-**No blockers for merge based on logical correctness alone.**
-
-### Post-Merge Validation
-
-After merging all three, run:
-
-```bash
-uv run python court_scheduler_rl.py quick
-```
-
-Expected: Pipeline completes without exceptions. RL agent trains successfully.
-
----
-
-## Summary Matrix
-
-| PR | Component | Logical Correctness | Merge Safety | Notes |
-|----|-----------|---------------------|--------------|-------|
-| #5 | Reward Helper | ✅ PASS | ✅ SAFE | Fixes P1 bug, clean abstraction |
-| #4 | RL-Scheduler Integration | ✅ PASS | ✅ SAFE | State space expansion intended, correctly implemented |
-| #7 | Output Metadata | ✅ PASS | ✅ SAFE | Purely additive, no side effects |
-
-**OVERALL VERDICT**: ✅ **MERGE ALL THREE** - No logical correctness concerns