---
path: /review
surface: admin
domain: governance
auth: signed-in (admin) + scope:admin:workspace:review
source: apps/oshun/admin/src/app/review/page.tsx
status: drafted
last_walked: '—'
---

# Governance · Review and approval

## Purpose

The approval-center cockpit: drives review packages through stage graphs,
captures rationale, resolves delegation / escalation, and seals decisions into
the audit trail. `operatorPromise`: "Approvals are deterministic, evidence-rich,
and reversible — nothing lands without a traceable decision path."

## Entry points

- Sidebar item **"Review"** (AdminSidebar — governance group)
- Inbox handoff (`inbox → review` per `OSHUN_ADMIN_WORKSPACE_RELATIONSHIPS`) —
  "Operator opens a review package or approval item from the unified inbox."
- Editorial handoff (`editorial → review`) and Research-integrity handoff
  (`research-integrity → review`) on the same relationships table
- Deep link to a specific package: `/review/<reviewId>` (see `review-id.md`)

## Layout regions

Inside `AdminShell`:

- `<WorkspaceEntryPoint workspaceId="review" ...>` — gating block (access /
  availability) always rendered
- When `detail.accessible`:
  - `<ReviewPackageList snapshot={snapshot}>` — the package list (top)
  - When `triageItems.length > 0`:
    - `<ReviewSavedViewsSurface initialQueue={triageItems}>` — saved filter /
      view chips for the triage queue
    - `<KeyboardTriageReviewPanel items={triageItems}>` — keyboard- driven
      triage list (Approve/Reject/Skip shortcuts)

`triageItems` is built from `snapshot.queue.map(...)` with fields `reviewId`,
`artifactRef`, `priority`, `stageState`, `escalated`, `governanceTagged`,
`assignedReviewerId`, `sourceDomain`, `queuePosition`, `lastUpdatedAt`.

## States

- [ ] Anonymous → middleware redirect to
      `/unauthorized?reason=missing-session&returnTo=/review`
- [ ] Signed-in (admin) without `admin:*`, `admin:studio`, or
      `admin:workspace:review` → `WorkspaceEntryPoint` "Access not granted";
      ReviewPackageList / SavedViews / KeyboardTriage hidden
- [ ] Signed-in (admin) + scope ok + BFF returns review snapshot with
      `queue.length > 0` → all three panels render
- [ ] Signed-in (admin) + scope ok + BFF returns `workspace-unavailable` →
      entry-point "Workspace data unavailable"; panels hidden
- [ ] `snapshot.queue` empty → `ReviewSavedViewsSurface` and
      `KeyboardTriageReviewPanel` not rendered (the `triageItems.length     > 0`
      guard); `ReviewPackageList` may still render whatever the snapshot
      provides
- [ ] Snapshot lacks `extractReviewSnapshot` fields → list / triage mappings
      fall back to defaults (`assignedReviewerId ?? undefined`)

## Interactions

The `/review` index page itself wires three top-level components; the discrete
interactive elements live inside each:

- [ ] **ReviewPackageList** — top of page (snapshot table / cards); per-row
      click should route to `/review/<reviewId>` for detail
- [ ] **ReviewSavedViewsSurface** — saved-view chip / filter controls; persists
      view selection
- [ ] **KeyboardTriageReviewPanel** — keyboard-first triage; expected bindings:
      arrow keys to move, Enter/A to approve, R to reject, S to skip (verify in
      component source)

The page itself exposes no top-level buttons / inputs / links.

## Data & contracts

- **Reads**: `loadWorkspaceDetail('review', session)` →
  `/v1/admin/workspaces/review`; snapshot from
  `extractReviewSnapshot(detail.result.value)` provides `queue`, `reviewers`,
  and per-package fields used downstream
- **Writes**: _None on this index page_ — write actions (decide / delegate /
  approve high-risk) live on the detail route `/review/[reviewId]`
- **Realtime**: _None on this index._
- **Auth/role check**: middleware (any admin session) + page
  (`canEnterAdminWorkspace(scopes, 'review')` → required scopes
  `['admin:*', 'admin:studio', 'admin:workspace:review']`)

## Cross-references

- Shell: `shell/01-app-shell.md`, `shell/04-workspace-pattern.md`
- Workspace definition: `libs/oshun/navigation/src/admin-ia.ts` (`review` —
  `kind: 'approval-center'`, `operatorRelationship: 'decide'`)
- Detail route: `review-id.md`
- Handoff origins (`from → review`): `inbox.md`, `../content/editorial.md`,
  `../content/research-integrity.md`
- Handoff destinations (`review → …`): `../safety/rights.md`,
  `../content/personas.md`, `../content/models.md` (from
  `OSHUN_ADMIN_WORKSPACE_RELATIONSHIPS`)
- Component sources: `apps/oshun/admin/src/components/ReviewPackageList.tsx`,
  `apps/oshun/admin/src/components/ReviewSavedViewsSurface.tsx`,
  `apps/oshun/admin/src/components/KeyboardTriageReviewPanel.tsx`,
  `apps/oshun/admin/src/lib/review-detail.ts`

## Open questions / known gaps

- [ ] Document `ReviewPackageList`'s rendering when `snapshot.queue` is empty vs
      missing (the `triageItems.length > 0` guard only gates the keyboard
      surfaces — the list itself always renders)
- [ ] Document `ReviewSavedViewsSurface`'s persistence target (localStorage /
      URL hash / BFF saved views?)
- [ ] Confirm whether keyboard shortcuts on `KeyboardTriageReviewPanel` conflict
      with `AdminCommandPalette` (`⌘K`) or shell-level bindings