# Human Review & Approval Queue Roadmap

> **Purpose:** Add a generic human-in-the-loop system for agent actions,
> escalations, approvals, and quality review.
>
> **Primary Surface:** `services/platform-service/`
>
> **Status:** Planned
>
> **Estimated Effort:** 2-3 weeks

---

## Why This Is Missing

The platform has MFA push approvals, but that is a narrow auth flow. An agent company
also needs a generic review queue for cases like:

- send this message
- execute this external action
- publish this recommendation
- approve this prompt change
- inspect low-confidence output

---

## Recommended Stack

- `platform-service` review module
- `@bytelyst/queue` for routing and escalation timers
- Slack and Telegram delivery adapters for reviewer notifications
- Optional policy engine later with OpenFGA or Cedar

### Default Decision For This Repo

- Build this inside `platform-service`
- Use agent-run state transitions rather than bespoke approval callbacks per feature
- Reuse existing delivery channels for reviewer notification fan-out

---

## Dependencies

- Agent Runtime & Orchestration
- Org, Workspace & RBAC

---

## V1 Non-Goals

- Full BPM suite
- Arbitrary multi-stage approval designers
- End-user-facing case portals

---

## Phase 1 - Review Objects

- [ ] Create modules:
  - [ ] `reviews`
  - [ ] `approvals`
  - [ ] `escalations`
- [ ] Define review object fields:
  - [ ] subject type
  - [ ] subject ID
  - [ ] review reason
  - [ ] risk level
  - [ ] required decision type
  - [ ] assigned reviewer(s)
  - [ ] SLA and due time
  - [ ] supporting evidence
- [ ] Add states:
  - [ ] pending
  - [ ] claimed
  - [ ] approved
  - [ ] rejected
  - [ ] expired
  - [ ] superseded

---

## Phase 2 - Workflow Integration

- [ ] Allow agent runs to emit `waiting_for_review`
- [ ] Add review decision callbacks to resume or cancel runs
- [ ] Add escalation timers and reassignment
- [ ] Add reviewer comments and audit trail

---

## Phase 3 - Reviewer Experience

- [ ] API and admin UI queue
- [ ] bulk claim and assignment
- [ ] notification fan-out via Slack/Telegram/email
- [ ] filters by risk, workspace, agent, age, reviewer

---

## Tech Stack Options

| Option                                  | Pros                       | Cons                                           | Fit                 |
| --------------------------------------- | -------------------------- | ---------------------------------------------- | ------------------- |
| Platform module + queue + notifications | Simple and aligned to repo | More UI to build                               | Best immediate path |
| Commercial ticketing/workflow tool      | Fast start                 | External dependency and poor control-plane fit | Poor long-term      |
| Dedicated BPM engine                    | Powerful                   | Too heavy for initial need                     | Overkill initially  |

---

## Risks

- If approvals are only implemented ad hoc per module, policy becomes inconsistent
- If decisions are not audit logged, enterprise trust will be weak
- Review queues without SLA and ownership become dead letter inboxes
