# Phase 5 — Execution Plan (Updated, repository-based)

> Read-only roadmap. No implementation. The repository is the source of truth.
> **Architecture is final and unchanged:** Runtime → proposal only →
> `POST /api/v1/ai/agent-runs/{run}/decision` → existing Numu decision / policy /
> approval / execution pipeline. No new repository, service, module, package, or
> execution path may be introduced.

**As-of:** 2026-07-05 · **Branch:** `feat/agent-knowledge-cache` (HEAD `47621d4`; runtime `29f916a`).

---

## 1. Status snapshot (what the repository proves today)

| Capability | State | Evidence |
|---|---|---|
| Knowledge Cache (immutable, per-env, rollback, audit) | ✅ Done | `4b4854f`, `33d8e49`, `a9fa600` + tests |
| Registry-driven Loader (7-file package, validation, checksum) | ✅ Done | `a9fa600`; `AgentKnowledgeCacheTest` (27) |
| Read API (metadata/runtime split) | ✅ Done | `AgentKnowledgeController` |
| Handoff store/latest/list/show | ✅ Done | `HandoffController` |
| Handoff P1 hardening (semantic validation, supersede guard, investor unique, QueryException map) | ✅ Done | `a9fa600`; `HandoffHardeningTest` (13) |
| Agent Runtime endpoint (propose-only) | ✅ Done | `29f916a`; `AgentRuntimeRunTest` (14) |
| **Live Claude validation** (`claude-sonnet-5`, real cache, propose-only) | ✅ Done | `LIVE_RUNTIME_SMOKE_TEST_REPORT.md` |
| Repository↔document reconciliation | ✅ Documented | `REPOSITORY_QUESTION_ANSWERS.md` |
| Make orchestration (trigger → runtime → decision) | ❌ Not started | no event/trigger in repo |
| Handoff idempotency / duplicate prevention | ❌ Not implemented | `HANDOFF_GAP_ANALYSIS.md` §1/§7/§8 |
| Environment reconciliation (`production` vs `prod`) | ❌ Not done (fail-safe today) | `ENVIRONMENT_RECONCILIATION_ANALYSIS.md` |
| AUTO-025 evaluation fixture through runtime | ❌ Not run | — |

**Full Agents test suite:** 68 passing (234 assertions).

---

## 2. Production-readiness gates

A gate must be GREEN before broad production activation.

| Gate | Status | Blocking? |
|---|---|---|
| G1 — Runtime works against a real model, propose-only, single write | ✅ GREEN | — |
| G2 — Knowledge loaded from cache only (never SharePoint) | ✅ GREEN | — |
| G3 — Structured validation + fail-closed + repair | ✅ GREEN (repair unit-tested) | — |
| G4 — Proposal enters existing decision pipeline unchanged | ✅ GREEN | — |
| G5 — Handoff idempotency/duplicate protection (multi-caller) | 🔴 RED | Yes for unsupervised automation |
| G6 — Automated production trigger (Make orchestration) | 🔴 RED | Yes for automation (manual path OK) |
| G7 — Environment namespace reconciled | 🟡 AMBER (fail-safe) | No (clarity only) |
| G8 — `intake_triage` policy data cleaned (duplicate/conflicting `move_to_review`) | 🟡 AMBER | No (operational hygiene) |
| G9 — AUTO-025 evaluation fixture parity through runtime | 🟡 AMBER | No (quality assurance) |
| G10 — Graph/SharePoint production source consent (if `AGENT_KNOWLEDGE_SOURCE=graph`) | 🟡 AMBER | No (local source works) |

---

## 3. Critical path

```
[DONE] Runtime + Live Claude validation (G1–G4)
   │
   ├─► M1  Handoff idempotency (logical-tuple unique + idempotent create)   ── closes G5
   │        (additive migration + create() guard; reuse mapQueryException 409)
   │
   ├─► M2  Make orchestration: completed-run → call runtime → submit to
   │        POST /agent-runs/{run}/decision  (+ pre-GET-latest dup check)     ── closes G6
   │        (orchestration only; NO new execution path)
   │
   └─► M3  Controlled end-to-end dev run through Make (audit-verified)        ── production go/no-go
            │
            └─► Broad intake_triage activation (single agent), then AUTO-027+ later
```

M1 and M2 are largely independent and can proceed in parallel; **M3 depends on both**.

## 4. Dependencies

- **M1 (idempotency)** → depends on nothing new; additive to `handoffs` + `HandoffService`.
- **M2 (Make orchestration)** → depends on the **already-shipped** runtime + decision endpoints; needs the runtime-env↔decision-env mapping documented (done in the env analysis). Should not create handoffs until M1 lands (or must run the pre-check).
- **M3 (controlled E2E)** → depends on M1 + M2; uses a marked safe test startup + the `test` decision environment (as the smoke test did) before any `prod` policy path.
- **AUTO-025 eval (G9)** → depends on runtime (done) + a loaded eval fixture; independent of M1/M2.
- **Env reconciliation (G7)** → independent; recommended **after** Make integration (fail-safe today).

## 5. Blockers (must-fix before the stated milestone)

| Blocker | Gate | Needed for |
|---|---|---|
| No backend handoff idempotency/duplicate protection | G5 | Unsupervised production handoff creation |
| No automated production trigger | G6 | Full automation (not manual/poll) |
| Seeded `intake_triage` has duplicate/conflicting `prod` `move_to_review` policies (`always_allow` + `needs_approval`) | G8 | Any live `prod` decision submission for `move_to_review` — **must be cleaned first** so policy resolution is deterministic |

> **G8 is the sharpest near-term item:** the smoke test deliberately used `test` env to avoid it. Before submitting a real `move_to_review` proposal in `prod`, the duplicate/conflicting policy rows must be reconciled (operational data cleanup), or resolution is ambiguous and could hit `always_allow` → live execution.

## 6. Optional improvements (non-blocking)

- Handoff `retention_class` + `schema_version` allow-lists (`HANDOFF_GAP_ANALYSIS.md` §4/§5).
- Environment unification `production → prod` data migration (`ENVIRONMENT_RECONCILIATION_ANALYSIS.md`).
- Read/validation-failure audit rows for handoffs.
- Runtime context expansion: full handoff history (currently latest-only) + notes/documents (deferred per request §8.8).
- A live **repaired-output** run (repair path is unit-tested but not yet live-verified).
- Graph production source enablement once Azure `Files.Read.All`/`Sites.Read.All` consent is granted.

## 7. Estimated implementation order

1. **G8 policy data cleanup** (operational; unblocks any real `prod` decision) — smallest, highest-urgency.
2. **M1 — Handoff idempotency** (additive migration + `create()` guard + tests) — closes G5/§1/§7/§8.
3. **M2 — Make orchestration** (trigger → runtime → decision; pre-GET-latest dup check) — closes G6; reuses existing endpoints only.
4. **M3 — Controlled E2E dev run** through Make on a marked safe record (audit-verified) — production go/no-go.
5. **G9 — AUTO-025 evaluation fixture** through the runtime (record in `05 Testing`) — quality gate.
6. **Optional hardening** — env reconciliation (G7), allow-lists, audit expansion, context expansion.
7. **Broad rollout** — `intake_triage` first, then later agents (AUTO-027+) only after M3 is green.

## 8. Guardrails (unchanged, must hold in every milestone)

- Runtime stays **propose-only**; the only AgentRun write is the traceability stamp.
- Submission is exclusively via `POST /agent-runs/{run}/decision`; **no** parallel execution path.
- Make remains orchestration-only; it never calls the model, owns prompts/validation, or writes final state (may create handoffs only as the approved temporary fallback, with a duplicate pre-check).
- Knowledge is read only from the Knowledge Cache; SharePoint stays the long-term source, never the runtime source.
- No new repository / service / module / package / execution path.
- All work continues on `feat/agent-knowledge-cache`; no push / PR until directed.