[Cogitations] Implement structured error handling with custom exceptions

[zircote]

Quality Gate Reference

• Checklist Item(s): COD-006 (Error Handling Strategy, score 0.5 — critical severity)
• Current Score: Coding domain 60/100
• Impact: Medium — addresses critical-severity item, improves testability
• Effort: Medium

Description

Python scripts use untyped error dicts ({"error": "message"}) with no custom exception types or error wrapping. The agent reaping issue (now fixed in skill files) exposed that error handling lacks resilience patterns.

Implementation Plan

1. Create scripts/exceptions.py with hierarchy:
   • RefactorError (base)
   • SubprocessError — wraps failed subprocess.run with command, exit code, stderr
   • UnsupportedLanguageError — raised when language detection fails
   • CoverageParseError — raised when coverage output can't be parsed
   • ProjectDetectionError — raised when project root/language can't be determined
2. Replace bare dict-based error returns with proper exceptions in run_tests.py, coverage_report.py, detect_project.py
3. Add context wrapping: catch low-level errors, re-raise with domain context
4. Keep dict-based returns at the API boundary (__init__.py exports) for backward compatibility — catch exceptions internally and convert

Cross-Domain Impact

• Makes error paths testable (pytest.raises assertions) — improves TDD scores
• Clean exception hierarchy improves code review quality

Acceptance Criteria

• COD-006 score → ≥0.8
• All error paths have specific exception types
• Tests verify error paths with pytest.raises
• No regression in other domain scores

---

Generated by Cogitations /cog-discover