Session learning from spec-validator on task #35 (ExitCode wiring)

Learning-20260426-spec-validator-35.-.md

@@ -0,0 +1,98 @@
+# 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
+
+1. **Why FAIL verdict?** Spec contract states "robot consumers always observe correct exit codes 0-7". Current implementation returns 0 or 1 only. Not fulfilled.
+
+2. **Why detailed gap analysis?** The issue blocking this task needs clear roadmap. Provided Phase 1-4 breakdown with effort estimates.
+
+3. **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:
+1. Start with Phase 1 (refactor main() return type) - this unblocks everything
+2. Use the error classification logic already in place
+3. Add integration tests to shell-script suite
+4. 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)