# Implementation Plan

**Status:** Draft for review
**Parent docs:** [Proposal_arch.md](Proposal_arch.md) §10 (phase-level plan), [ui-ux-plan.md](ui-ux-plan.md) (screens), [mcp-servers.md](mcp-servers.md) (tool contracts), [entity-resolution.md](entity-resolution.md) (the Phase 0 spike)
**Purpose:** turn the phase-level checklist in the parent doc into 2-week sprints with explicit dependencies, so it's executable rather than just directional. This doc doesn't repeat §10's content — it sequences it and adds the UI work, which §10 didn't carry.

---

## 1. Team shape (assumed, adjust to reality)

- **1–2 backend/Elixir engineers** — `agent_core`, the five MCP servers, the policy engine, the LLM provider adapters.
- **1 LiveView/frontend engineer** — the Agent Console screens ([ui-ux-plan.md](ui-ux-plan.md)), can start once Phase 1's data model exists.
- **Part-time ops/SME reviewer** — required for every phase's exit criterion that involves human judgment ("≥80% of proposals judged correct"), not a full-time role but a real, scheduled commitment, not an afterthought.
- **No dedicated ML/data science role needed** — per the parent doc §7, there's no model training here; the "learning" is statistics over `agent_outcomes` and prompt/context engineering, both squarely backend-engineering work.

---

## 2. Critical path — resolve these before they become blockers

| Gate | Blocks | Resolve by |
|---|---|---|
| **Data residency decision** (parent doc §12 item 1) | Whether Claude can be used at all in production, vs. Ollama being mandatory from day one | Before Phase 0 ends — this is a legal/compliance answer, not an engineering one, and the longest lead time of anything on this list |
| **Entity-resolution match rate spike** ([entity-resolution.md](entity-resolution.md) §4) | Whether A1/A6 can trust the device→merchant→MID/TID join, or must report it `:unresolved` | Sprint 0.1, half a day of work — do it early, not last, in case the answer changes tool design |
| **MCP server library choice** (parent doc §12 item 8) | D8's tool-layer structure; Phase 1 can start against a plain tool registry and migrate later if this drags | Sprint 0.1–0.2, doesn't block Phase 1's start |
| **jPOS/network metrics export ask** (parent doc §1.7, §12 item 7) | A8's full capability (Phase 3) — but A8 degrades gracefully to BEAM-only, so this is parallel-track, not blocking | Raise with the Java team in parallel with Phase 0–2, so an answer exists by Phase 3 |

---

## 3. Sprint plan — Phase 0 (Foundation, 4–5 weeks ≈ 2–3 sprints)

### Sprint 0.1
- [ ] `apps/agent_core` scaffold; wire into `mix.exs` releases
- [ ] Migrations: all nine `agent_*` tables + `agent_investigations`; `agent_policies` gets its `provider` column (D6) up front, not retrofitted
- [ ] **Entity-resolution spike** — run it this sprint, not later; it's cheap and its answer shapes A1/A6 tool design
- [ ] **MCP library spike** — evaluate against this codebase; doesn't need to conclude before Sprint 0.2 starts
- [ ] Kick off the two-week baseline measurement window (parent doc §11) — starts now so it's done by the time Phase 1 needs a comparison baseline

### Sprint 0.2
- [ ] `AgentCore.LLM.Provider` behaviour + Anthropic adapter (the request shape and constraints are fully specified in D6 — no design work left, just implementation)
- [ ] `AgentCore.ReadTool` behaviour + redaction layer, unit-tested as a pure function against every field flagged across the docs (PAN, CVV, track data, key material, MMS write attempts)
- [ ] `AgentCore.Tool` behaviour + tool registry + `AgentCore.Policy` engine (deterministic, heavily unit-tested — this is the ≥90% branch coverage bar)
- [ ] Sensors: MQTT tap on the existing handler, Oban telemetry tap, periodic sweep

**Phase 0 exit** (parent doc §10, unchanged): policy engine ≥90% branch coverage, rejects every T4 attempt in tests, redaction layer has no PAN-emitting path, entity-resolution spike has a documented match rate.

**No UI work this phase.** Nothing user-facing exists yet.

---

## 4. Sprint plan — Phase 1 (A6 Investigation, 4–6 weeks ≈ 2–3 sprints)

### Sprint 1.1
- [ ] `settlement-mcp`'s `trace_transaction/1` — build this first among all tools in the whole system. It's deterministic, unit-testable against known-good/known-broken transactions, and it's the flagship scenario (parent doc §1.5, investigation doc §3, §5 worked example).
- [ ] `switch-mcp` read tools (`get_switch_transaction`, `get_switch_transaction_reversal`) — `trace_transaction` depends on these existing first, even though it queries them in-process rather than through the MCP boundary (mcp-servers.md's note on why)

### Sprint 1.2
- [ ] Remaining read tools: `tms-mcp` reads, `risk-mcp` reads, `settlement-mcp`'s merchant-resolution tools (via the verified `SettlementCore.Mms.*` path, entity-resolution.md §2.1 — not a new query)
- [ ] Investigation loop: hypothesis/discriminating-test structure, bounded step budget (investigation doc §4)
- [ ] **UI work starts here** — Investigation Console (`/agents/investigations`, ui-ux-plan.md §2.4). This is the *only* screen Phase 1 needs; nothing else has data to show yet.

### Sprint 1.3
- [ ] Investigation Report persistence (`agent_investigations`) + report rendering in the console
- [ ] Self-inspection tools (`get_agent_decisions`, `get_outcome_stats`) — needed by Phase 2, cheap to build now while the read-tool patterns are fresh
- [ ] Evaluation: 20 hand-labelled historical incidents (mixed domains)

**Phase 1 exit** (parent doc §10): ≥70% correct primary cause on the 20-incident eval, **zero confidently-wrong reports**. Add: `trace_transaction/1` correctly locates the first break on 100% of a known-broken fixture set (investigation doc §9) — it's deterministic, so anything less is a bug.

---

## 5. Sprint plan — Phase 2 (A2 Config Compliance, shadow → T1, 4–6 weeks ≈ 2–3 sprints)

### Sprint 2.1
- [ ] `tms-mcp` actuators: `trigger_config_push`, `regenerate_config_artifact`, `start_remote_log_session` (all T1)
- [ ] A2 wired in `:shadow` mode — proposes, never executes
- [ ] Outcome auto-labeller for push convergence (parent doc §6 step [7]) — the first real learning signal in the system

### Sprint 2.2
- [ ] **UI work**: Incident Feed (ui-ux-plan.md §2.1) + Decision Card (§2.2), scoped to A2's incidents only — no other agent produces incidents yet
- [ ] Shadow-vs-`VersionComplianceChecker` comparison view — this *is* the exit-criterion evidence, build it as a first-class screen, not a one-off query

### Sprint 2.3
- [ ] Accumulate ≥200 shadow decisions; ops review pass (the part-time SME role earns its keep here)
- [ ] Promote A2 to `:auto_low_risk` once the bar is met

**Phase 2 exit** (parent doc §10): ≥200 shadow decisions, A2 matches-or-beats `VersionComplianceChecker` on convergence rate, ≥80% of proposals judged correct.

---

## 6. Phases 3–5 — summary (full detail in parent doc §10; not re-sprinted here since they depend on Phase 1–2's actual outcomes, not a plan made today)

| Phase | Backend | UI (ui-ux-plan.md) |
|---|---|---|
| **3** — Fleet + orchestration + infra sensing | A1, A3 (`:shadow`→`:suggest`); A7 orchestrator; A8 (BEAM export + AlertManager webhook, in-repo; jPOS export parallel-track) | Approval Queue (§2.3), Policies & kill switch (§2.6) — approval gating only matters once T2/T3 actions exist |
| **4** — Settlement, risk, learning | A4, A5; nightly learning job; confidence calibration | Playbook Editor (§2.5) — once the learning job is actually producing review candidates |
| **5** — Ongoing | Confidence calibration, playbook curation, selective T2 autonomy per fingerprint | Audit Export (§2.7) — not gated on anything else, build whenever compliance asks |

---

## 7. Risk register

| Risk | Where it's discussed | Mitigation |
|---|---|---|
| Data residency blocks Claude in production | §12 item 1 | Ollama adapter (D6) is designed in from day one, not an afterthought — routing is a policy change, not a rebuild |
| Device↔merchant identity join doesn't hold in production data | entity-resolution.md §4 | Half-day spike in Sprint 0.1; tools report `:unresolved` rather than guessing if it fails |
| Agent is confidently wrong about a fleet-wide push | Proposal_arch.md §8 | Blast-radius cap + T2 gating + canary-first ordering in A3 — tested hardest, per the parent doc's own callout |
| A6 produces a confident, wrong investigation report | investigation doc §9 | Explicit acceptance bar: zero confidently-wrong reports beats 70% raw accuracy; `HIGH` confidence is earned, not defaulted |
| jPOS never exports metrics | §1.7, §12 item 7 | A8 ships BEAM-only and stays useful; jPOS coverage is additive, never blocking |
| MCP library choice drags | §12 item 8 | Phase 1 doesn't wait on it — build against a plain tool registry first, migrate to MCP once chosen |
| Kill switch or policy screen misconfigured | ui-ux-plan.md §2.6 | Narrower permission (`agents.policy.manage`) than general console access; type-to-confirm on the global kill switch |

---

## 8. What "done" looks like at each phase, in one line

- **Phase 0:** the guardrails exist and are proven in tests, before any agent runs.
- **Phase 1:** an operator can ask "why is this transaction missing" and get a trustworthy, cited answer in seconds — with nothing that can act on their behalf yet.
- **Phase 2:** one agent has beaten the rule-based system it replaces, on real decisions, reviewed by a human, before being trusted to act alone.
- **Phase 3:** alert storms become single incidents, and the system watches its own health, not just the fleet's.
- **Phase 4:** the system predicts problems before they breach an SLA, and gets measurably better at its job over time.