checkpoint: 22:00 auto-commit

wizards/allegro/docs/ADR-001-harness-engineering-pivot.md

@@ -0,0 +1,114 @@
+# ADR-001: Harness Engineering Pivot
+
+**Status:** APPROVED  
+**Date:** 2026-04-01  
+**Deciders:** Alexander Whitestone (Father), Allegro (Executor), Ezra (Scribe)  
+**Owner:** Allegro  
+
+---
+
+## Context
+
+We have been operating on Hermes Agent as our default harness. While functional, this creates lock-in to a single runtime. The exposure of Claude Code's architecture and the rapid emergence of Claw Code (98K+ stars, fastest to 50K in GitHub history) presents an opportunity.
+
+Claw Code represents a clean-room Python/Rust rewrite of Claude Code's patterns with:
+- Provider trait abstraction (swappable LLMs)
+- Native MCP (Model Context Protocol) support
+- Plugin hook system (PreToolUse/PostToolUse)
+- Session compaction for context management
+
+---
+
+## Decision
+
+We pivot to **harness engineering**: building a multi-runtime, swappable architecture that adopts best patterns from Claw Code while preserving our values layer.
+
+### What This Means
+
+| From | To |
+|------|-----|
+| Hermes default | Best runtime default |
+| Code loyalty | Results loyalty |
+| Single harness | Multi-runtime, swappable |
+| NIH syndrome | SOTA tracking |
+
+### What We Keep
+
+- **Checkpoint system** (Ezra's ownership model)
+- **Profile-based architecture** (wizard separation)
+- **SOUL.md / Conscience layer** (values enforcement)
+- **Heartbeat pattern** (execution cadence)
+- **Gitea integration** (issue tracking)
+
+---
+
+## Consequences
+
+### Positive
+- No LLM lock-in (Kimi ↔ Ollama ↔ Claude ↔ OpenAI)
+- Tools become portable MCP servers
+- Plugin system enables SOUL.md enforcement via hooks
+- Session compaction solves token limits
+- Faster iteration on harness improvements
+
+### Negative
+- Migration work required (8-week timeline)
+- Learning curve for Rust if we adopt core runtime
+- Potential instability during transition
+- Need to maintain backward compatibility for 90 days
+
+### Risks
+| Risk | Mitigation |
+|------|------------|
+| Claw Code API churn | Mirror repo with hourly sync, pin to stable commits |
+| Rust competency gap | Hybrid approach: core in Rust, tools in Python |
+| Migration disruption | Parallel operation period, feature flags |
+| SOUL enforcement gaps | Implement as PreToolUse hook, test exhaustively |
+
+---
+
+## Implementation
+
+### Phase 1: Assessment (Week 1) - IN PROGRESS
+- [x] Document Claw Code architecture analysis
+- [x] Identify migration touchpoints
+- [ ] Create claw-code-mirror repo (BLOCKED: Tailscale)
+- [ ] Set up automated upstream sync
+
+### Phase 2: Runtime Abstraction (Weeks 2-3)
+- [ ] Define Provider trait
+- [ ] Implement Kimi-coding provider
+- [ ] Provider factory/config
+
+### Phase 3: Tool System (Weeks 3-4)
+- [ ] Extract tools to registry pattern
+- [ ] MCP client implementation
+- [ ] Convert skills to MCP servers
+
+### Phase 4: Plugin Architecture (Weeks 4-5)
+- [ ] Hook system (PreToolUse, PostToolUse)
+- [ ] Plugin manifest format
+- [ ] SOUL.md enforcement via hooks
+
+### Phase 5: CLI & UX (Weeks 5-6)
+- [ ] Single entrypoint
+- [ ] Profile-based configuration
+- [ ] Session persistence
+
+### Phase 6: Validation (Weeks 6-8)
+- [ ] Full test suite (200+ tests)
+- [ ] Migration guide
+- [ ] Deprecation plan for Hermes
+
+---
+
+## References
+
+- Claw Code upstream: https://github.com/instructkr/claw-code
+- MCP Spec: https://modelcontextprotocol.io/
+- North Star doc: `/root/wizards/allegro/home/claw_code_north_star.md`
+- Architecture analysis: `/root/wizards/allegro/home/claw_code_followup.md`
+
+---
+
+*"Code loyalty → Results loyalty"*