Gitea-Tools/docs/webui-notifications.md

Web Console: Notifications & Human-Attention Routing (#648)

• Status: Phase 3 Live
• Tracking Issue: #648
• Parent Epic: #631
• Attention Boundary Reference: #628

---

1. Overview

The Notifications & Human-Attention Console (/notifications, /api/v1/notifications) provides intelligent event classification and human-attention routing for autonomous workflow operations.

To prevent alert fatigue while ensuring critical escalation boundaries are never missed, events are classified into three distinct Attention Classes:

1. human-required (Urgent Escalation Boundary):

   • Items requiring immediate human intervention or business decisions.
   • Triggers: Auth failures, hard stops, irrecoverable state, decision locks, failed report validations, critical probe errors.
   • Display: Highlighted in red (badge-blocked) with a HUMAN REQUIRED badge.

2. operator (Operational Inbox):

   • Items requiring controller or operator review/triage during routine execution.
   • Triggers: Blocked PRs (merge conflicts), stale leases, duplicate PRs on issues, unassigned ready work.
   • Display: Displayed in orange/yellow (badge-claimed).

3. routine (Background Workflow Transitions):

   • Normal, healthy workflow transitions and state progressions.
   • Triggers: Active PRs/issues in standard state, clean branch creation, routine heartbeats.
   • Display: Filtered out of default inbox views to eliminate notification spam; viewable on demand via the "Routine" or "All" tab.

---

2. API Endpoints

GET /api/v1/notifications

Compatibility Alias: GET /api/notifications

Query Parameters:

• project_id (optional): Filter notifications by project ID.
• attention_class (optional): inbox (default: human-required + operator), human-required, operator, routine, all.

Example JSON Response:

{
  "project_id": "gitea-tools",
  "repo_label": "Scaled-Tech-Consulting/Gitea-Tools",
  "human_required_count": 0,
  "operator_count": 2,
  "routine_count": 5,
  "total_count": 7,
  "fetch_error": null,
  "inbox_items": [
    {
      "id": "notif-pr-block-742",
      "attention_class": "operator",
      "category": "blocker",
      "title": "Blocked PR #742",
      "summary": "PR #742 requires merge conflict resolution.",
      "work_kind": "pr",
      "work_number": 742,
      "project_id": "gitea-tools",
      "repo_label": "Scaled-Tech-Consulting/Gitea-Tools",
      "created_at": "2026-07-25T16:39:47Z",
      "deep_link": "/traffic",
      "requires_human": false,
      "extra": {}
    }
  ],
  "all_items": [...]
}

---

3. UI Navigation

• Access via the Traffic navigation menu: Traffic → Notifications.
• The main view displays:
  • Metrics Summary Bar: Highlighting counts for Human Required, Operator Inbox, and Routine items.
  • Attention Filter Tabs: Toggle between Inbox (Human + Operator), Human Required, Operator, Routine, and All.
  • Structured Event Table: Displays category, title, summary, work item links, and timestamps.