Learning: F1.2 Exit Code Spec Validation (2026-04-26)

Agent: spec-validator
Task: Validate F1.2 Exit Codes specification against implementation
Issue: terraphim/agent-tasks#35
Branch: task/860-f1-2-exit-codes

What Worked Well

Clear Specification

F1.2 spec in docs/specifications/terraphim-agent-session-search-spec.md is unambiguous
Exit codes 0-7 with semantic meanings are well-documented
Success criteria for "robot consumers always observe" is precise

Excellent Infrastructure

ExitCode enum complete with all 8 codes (exit_codes.rs)
Termination trait implemented correctly
classify_error() function sophisticated (18+ test cases)
Error pattern matching covers tokio::Elapsed, reqwest, network, auth, timeout, index missing
Unit tests comprehensive and passing (8/8 code values, 3/3 bidirectional conversion)

Code Quality

Robot module well-structured
Error classification heuristics robust
Test suite validates all documented paths

What Failed (Don't Repeat)

Critical Integration Gap

The ExitCode infrastructure exists but is disconnected from main entry point:

fn main() returns Result<()> instead of ExitCode
Robot module marked #[allow(dead_code)]
classify_error() never called in main error path
Result: process always exits 0 (except for 2 hardcoded ErrorUsage paths)

Testing Gap

Unit tests pass ✓
Shell-level integration tests absent ✗
No validation that actual process exit codes match spec

Architecture Issue

main.rs is 4819-line monolithic file
Business logic embedded in main, no separation of concerns
Makes refactoring to return ExitCode harder than it should be

Key Decisions

Why FAIL verdict? Spec contract states "robot consumers always observe correct exit codes 0-7". Current implementation returns 0 or 1 only. Not fulfilled.
Why detailed gap analysis? The issue blocking this task needs clear roadmap. Provided Phase 1-4 breakdown with effort estimates.
Why post to issue #35 not #860? PO Run 22 established agent-tasks as authoritative repo. GitHub issue #860 is phantom (4-line reference task only).

Recommendations for Next Session

If Continuing F1.2 Implementation:

Start with Phase 1 (refactor main() return type) - this unblocks everything
Use the error classification logic already in place
Add integration tests to shell-script suite
Remove #[allow(dead_code)] once wiring complete

For Future Spec Validators:

Check for #[allow(dead_code)] as red flag for disconnected infrastructure
Always require shell-level integration tests, not just unit tests
Map error paths explicitly (use checklist of all error types)
Cross-reference fn main() return type against spec contract

Evidence

Report: /home/alex/terraphim-ai/reports/spec-validation-20260426.md
Gitea Comment: terraphim/agent-tasks#35 (verdict posted)
Files Analyzed:

crates/terraphim_agent/src/robot/exit_codes.rs
crates/terraphim_agent/src/main.rs (4819 lines)
docs/specifications/terraphim-agent-session-search-spec.md

Spec Compliance Scorecard

Dimension	Score
Specification Clarity	10/10
Infrastructure	9/10
Integration	2/10
Unit Testing	9/10
Integration Testing	0/10
Overall Compliance	28%

Exit Criteria for Task #35

Before merge, must satisfy:

fn main() returns ExitCode, not Result<()>
classify_error() wired into main error path
Shell integration tests verify codes 0-7
#[allow(dead_code)] removed from robot module

Next: Implement Phase 1 refactoring (4-6h estimated)