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