# ADR-001: Middleware Architecture Refactor

**Status:** ACCEPTED
**Date:** 2025-12-06
**Decision Makers:** Development Team

---

## Context

The current `src/middleware/` folder is misleadingly named. It contains `SubIterationMiddleware`, which implements a workflow pattern (team→judge loop), not the interceptor middleware pattern used by Microsoft Agent Framework.

Additionally, we're missing proper middleware implementations for:
- Retry logic on transient errors (429, 500, 502, 503, 504)
- Token usage tracking for cost monitoring

---

## Decision

1. **Rename `src/middleware/` to `src/workflows/`** to accurately reflect what it contains
2. **Create new `src/middleware/` with proper MS-pattern middleware:**
   - `RetryMiddleware(ChatMiddleware)` - exponential backoff retry
   - `TokenTrackingMiddleware(ChatMiddleware)` - token usage logging

---

## Consequences

### Positive
- Clearer codebase organization
- Proper use of MS Agent Framework patterns
- HuggingFace 429 crashes will be handled gracefully
- Token usage will be visible for cost monitoring

### Negative
- Requires updating imports in `src/orchestrators/hierarchical.py`
- One-time migration effort

### Neutral
- Aligns with Microsoft Agent Framework conventions

---

## Implementation

See [SPEC-21: Middleware Architecture Refactor](../specs/SPEC-21-MIDDLEWARE-ARCHITECTURE.md) for detailed implementation steps.

---

## References

- Microsoft Agent Framework `_middleware.py`
- [P2 Hardening Issues](../bugs/p2-hardening-issues.md) Issue 2 & 3