# Phase Plan Index

Per-phase implementation briefs for the Seedbox Command Center. Each brief is self-contained and authoritative for its phase. `PROJECT.md` remains the master architectural spec; `DECISIONS.md` accumulates the design choices made phase by phase.

**Read order for a new contributor:** `PROJECT.md` first, then `PROGRESS.md` to learn current state, then the brief for the phase about to be implemented, then the prior phase's brief for context on what to build on.

| Phase | Brief | Mission | Estimated hours (PROJECT.md §9) |
|---|---|---|---|
| 0 | [CLAUDE.md](CLAUDE.MD) | Foundation: module, systemd, SQLite + DuckDB, logging, secrets, config, health endpoint, embedded frontend skeleton | 4–6 |
| 1 | [CLAUDE-phase1.md](CLAUDE-phase1.md) | First tracker scrape, first ratio view, scrape hygiene primitive, integration adapter pattern | 6–8 |
| 2 | [CLAUDE-phase2.md](CLAUDE-phase2.md) | WebAuthn passkeys, sessions, recovery codes, login UI | 4–5 |
| 3 | [CLAUDE-phase3.md](CLAUDE-phase3.md) | qui/qBittorrent integration, torrent list + detail, WebSocket eventbus | 4–6 |
| 4 | [CLAUDE-phase4.md](CLAUDE-phase4.md) | Internal event bus promoted, HMAC webhook ingress, SSE, reconciliation loop | 6–8 |
| 5 | [CLAUDE-phase5.md](CLAUDE-phase5.md) | autobrr REST + filter-to-upload performance correlation with provenance for cross-seed credit | 6–8 |
| 6 | [CLAUDE-phase6.md](CLAUDE-phase6.md) | VAPID push, rules engine with every Appendix C trigger type, multi-channel delivery | 5–6 |
| 7 | [CLAUDE-phase7.md](CLAUDE-phase7.md) | Intelligence: ratio velocity, HR risk, dead swarms, disk Monte Carlo forecast, recommendations with provenance | 8–10 |
| 8 | [CLAUDE-phase8.md](CLAUDE-phase8.md) | Simulation engine: sandboxed what-if against historical snapshots; promote to production | 8–10 |
| 9 | [CLAUDE-phase9.md](CLAUDE-phase9.md) | tqm and cross-seed integration: config management, run recording, activity dashboard | 6–8 |
| 10 | [CLAUDE-phase10.md](CLAUDE-phase10.md) | Health budget framework: SLO-style burn rate tracking with period rollover | 4–6 |
| 11 | [CLAUDE-phase11.md](CLAUDE-phase11.md) | Tracker rule corpus per Appendix E, warning system on destructive actions | 6–8 |
| 12 | [CLAUDE-phase12.md](CLAUDE-phase12.md) | Local LLM (Ollama) conversational layer with structured tool calls + iOS Shortcuts | 10–12 |
| 13 | [CLAUDE-phase13.md](CLAUDE-phase13.md) | Multi-armed bandit filter variant tuning (Thompson sampling, ε-greedy, UCB1) | 6–8 |
| 14 | [CLAUDE-phase14.md](CLAUDE-phase14.md) | Prometheus / Loki / OpenTelemetry self-observability + heartbeat + Grafana dashboard | 4–6 |
| 15 | [CLAUDE-phase15.md](CLAUDE-phase15.md) | Polish, onboarding, settings UI, data export, backup automation, emergency mode | 8–10 |

**Total estimated:** ~95–135 hours. Each phase ships a deliverable that stands alone; operators may stop at any phase boundary and still have a working system.

## How these briefs relate to each other

Phases form a dependency DAG, not a strict linear order, though the numbering reflects a sensible default sequence:

- **Phase 0 is foundation for everything.** Every other phase consumes its primitives.
- **Phase 1 is foundation for Phases 3, 5, 7, 9, 11** — anything that scrapes or correlates per-tracker state.
- **Phase 2 is foundation for Phases 6, 12, 15** — anything user-facing that requires identity.
- **Phase 3 is foundation for Phases 5, 7, 8, 9** — anything that reasons about torrents.
- **Phase 4 is foundation for Phases 5, 6, 7, 9, 11** — the event bus is consumed by every reactive subsystem.
- **Phase 5 is foundation for Phase 13** — bandit tuning is filter performance scoring with a variant dimension.
- **Phase 6 is foundation for Phases 7, 10, 11** — rules + notifications are how Phase 7's recommendations, Phase 10's budget burns, and Phase 11's warnings reach the operator.
- **Phase 7 is foundation for Phase 8** — simulation replays Phase 7's intelligence modules against historical data.
- **Phase 10 is foundation for Phase 11's warnings AND Phase 7's recommendations** — budget pressure is an input to recommendations.

Phases 14 and 15 sit on top of everything and don't have downstream dependencies within the planned scope.

## Re-planning policy

Each brief is committed at the moment its predecessor completes. The 15 briefs in this repository are forward-looking projections — they describe the intent, the deliverables, the boundary against neighboring phases, and the rough shape. **The architecture and dependencies may shift as earlier phases reveal new constraints.** Treat each brief as binding for its phase, and update the briefs of later phases when an earlier phase produces a decision that invalidates them. Document every such update in `DECISIONS.md` so the divergence between brief and reality is auditable.

## Stop rules

- **At the end of each phase**, the implementer writes a `PROGRESS.md` entry summarizing what was built and stops. They do **not** begin the next phase. The operator (or the next session) re-reads the next phase's brief, possibly amends it, then begins implementation.
- **If a brief is wrong** — the architecture shifted, a dependency went a different way, an estimate proved optimistic — the implementer updates the brief and `DECISIONS.md` rather than silently deviating. The brief is the contract; updating the contract is fine; ignoring it is not.