ypollak2/llm-router

Diagnostics & Violation Reduction

Patch release: Comprehensive tooling to analyze and reduce routing violations (where Claude uses Bash/Edit/Write instead of routing via llm_* tools). Expected to reduce violations by 30-50% through improved hint visibility and session-level escalation.

Added

• cleanup-hook-health.py — Remove test artifacts from hook_health.json

  • --dry-run preview, --remove force-remove support
  • Cleans up stale test entries that inflate error counts

• analyze-violations.py — Per-session routing violation analysis

  • Parses enforcement.log with per-session grouping
  • Top 10 sessions table with violation counts
  • Per-session tool sequences showing what was used vs expected
  • Markdown report output to ~/.llm-router/retrospectives/

• README § Monitoring & Reducing Violations — 1,200+ word guide

  • What violations are and their cost impact
  • Common patterns and fixes
  • Enforcement modes (smart/hard/soft/off)
  • Hook health cleanup instructions

Changed

• auto-route.py — Improved MANDATORY ROUTE hint format

  • Box-drawing visual format (harder to miss in long context)
  • Cost savings estimate per task
  • Explicit forbidden actions list

• enforce-route.py — Per-session violation escalation

  • After 3+ violations, prints warning to stderr
  • Visible as hook message in Claude Code
  • Reminds model to route first

Metrics

• 3,931 violations identified in enforcement.log (prior sessions)
  • llm_generate bypassed: 1,274 (32%)
  • llm_query bypassed: 848 (22%)
  • llm_analyze bypassed: 750 (19%)
  • llm_code bypassed: 615 (16%)
  • llm_research bypassed: 452 (11%)

Impact

• Box-drawing hint format expected to reduce violations by 30-50%
• Session-level nudges (3+ violations) break investigation loops
• Analysis tooling provides visibility into where violations concentrate

Resources

• Documentation
• Analyze Script
• Cleanup Script
• Scripts Directory