# 00 — Master Execution Plan

**Parent:** [`docs/ROADMAP.md`](../ROADMAP.md)
**Related sub-plans:** [`01_FOUNDATIONS_AND_DECISIONS.md`](./01_FOUNDATIONS_AND_DECISIONS.md) · `03_RICH_ITEMS_ROADMAP.md` _(create when Phase 2 begins)_ · `04_AGENT_API_ROADMAP.md` _(create when Phase 3 begins)_ · `05_INTAKE_ROADMAP.md` _(create when Phase 4 begins)_

---

## Sequencing Overview

```
Phase 0 ✅ Shipped (baseline)
       │
       ▼
Phase 1 🔄 Production Hardening (sequential A→B→C→D→E→F)
       │
       ├──────────────────┐
       ▼                  ▼
Phase 2 UI Primitives    Phase 3 Agent API
       │                  │
       └────────┬─────────┘
                ▼
       Phase 4 Multi-Source Intake
                │
       ┌────────┴─────────┐
       ▼                  ▼
Phase 5 Analytics    Phase 6 Mobile/A11y
```

---

## Critical Path

The critical path to "production-ready, agent-driven, multi-source tracker" is:

1. **Phase 1.A** → unblock container health → 4 h
2. **Phase 1.B** → workspace health → 2 h
3. **Phase 1.C** → Docker hardening → 4 h
4. **Phase 1.D** → UI drift ratchet → 3 h
5. **Phase 1.E** → test hardening → 8 h
6. **Phase 1.F** → observability + security → 5 h
7. **Phase 2.1** → UI primitives migration → 10 h
8. **Phase 2.3–2.6** → rich item details → 20 h
9. **Phase 3.1–3.4** → agent API + webhooks → 25 h
10. **Phase 4.4** → cross-product routing → 8 h

**Critical-path total:** ~90 hours focused work. Parallelisable to ~50 hours real-time with 2 agents.

---

## Workstream Ownership

| Workstream          | Suggested owner      | Phase coverage                                             |
| ------------------- | -------------------- | ---------------------------------------------------------- |
| **Infra + DevOps**  | Platform agent       | 1.A, 1.C, 1.E (Docker bits), 1.F (Prometheus/Grafana/Loki) |
| **Frontend**        | UI agent             | 1.B, 1.D, 2.1, 2.3–2.9, 6.1, 6.3                           |
| **Backend / API**   | Backend agent        | 2.5 (linked items, milestones), 3.1–3.6, 4.3               |
| **Agent ecosystem** | Agent platform agent | 3.5 (SDK), 3.6 (AI triage), 4.2–4.3 (intake)               |
| **PM / Docs**       | Human PM             | 4.4, 4.6, runbooks, PRD updates                            |

---

## Parallelisation Rules

- **Phase 1 is sequential within itself.** Do not parallelise 1.A → 1.F.
- **Phase 2 and Phase 3 can run in parallel** after Phase 1 closes.
- **Phase 4 depends on Phase 3 webhooks shipping** before bidirectional sync (4.3) can start.
- **Phase 5 and Phase 6 can run in parallel** after Phase 4.
- **Docs work** (PRD updates, runbooks, ADRs) can happen alongside any phase.

---

## Cross-Repo Coordination

The tracker-web shares concerns with other ByteLyst products. When work overlaps:

| Concern                                   | Lead repo                                           | Tracker-web role                                                                |
| ----------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------- |
| `@bytelyst/ui` primitives                 | `learning_ai_common_plat/packages/ui`               | Consumer; report bugs/requests via tracker; never patch directly in tracker-web |
| `platform-service` auth + tracker backend | `learning_ai_common_plat/services/platform-service` | Consumer; raise schema-mismatch PRs against platform-service                    |
| `@bytelyst/design-tokens`                 | `learning_ai_common_plat/packages/design-tokens`    | Consumer of `--tk-*` tokens; never inline hex                                   |
| `docker-prep.sh` pattern                  | NoteLett / FlowMonk                                 | Adapter; copy + tracker-specific tweaks                                         |
| MEK rotation pattern                      | NoteLett (`bcad7d3`)                                | Adapt runbook with tracker-specific keys                                        |

---

## Implementation Tracking Protocol

- **Checkpoint updates:** every meaningful slice updates [`../IMPLEMENTATION_TRACKER.md`](../IMPLEMENTATION_TRACKER.md) with commit SHA
- **Roadmap commit-hash backfill:** when a roadmap item closes, paste the commit SHA after the checkbox
- **Open questions:** unresolved items go in [`../PRD.md`](../PRD.md) § Open Questions
- **Deferred items:** non-blocking scope cuts go in the tracker doc and relevant phase roadmap
- **Cross-agent safety:** strategic decisions in [`01_FOUNDATIONS_AND_DECISIONS.md`](./01_FOUNDATIONS_AND_DECISIONS.md) should not be silently changed after downstream work starts

---

## Verification Gates Between Phases

Before declaring a phase complete and moving to the next, the following must hold:

### Phase 1 → Phase 2 gate

- All Phase 1 exit criteria in [`../PRODUCTION_READINESS_HANDOFF_ROADMAP.md`](../PRODUCTION_READINESS_HANDOFF_ROADMAP.md) met
- 24 h of healthy containers (no flapping)
- Zero new bugs filed by `auto_detected` source in past 24 h

### Phase 2 → Phase 3 gate

- UI drift ratchet shows zero hardcoded colors + zero direct `@bytelyst/ui` imports outside adapter
- Acceptance criteria checklist data model live and tested (prereq for Phase 3.2 checklist endpoint)
- PR link data model live and tested (prereq for Phase 3.2 PR endpoint)

### Phase 3 → Phase 4 gate

- Agent API keys functional with at least one real agent (Claude Code or Codex) demonstrably claiming + closing items
- Inbound + outbound webhooks delivering reliably (< 0.1 % delivery failure rate)
- OpenAPI spec published at `/api-docs`

### Phase 4 → Phase 5 gate

- All four intake sources (public / internal / dev / agent) functional and documented
- Cross-product routing demonstrably moves items between products with audit trail intact

### Phase 5 → Phase 6 gate

- Analytics dashboard rendering correctly with live data
- SLA alerts firing in test scenarios
- Data retention policy applied to at least one historical batch
