headquarter/openspec/changes/notification-center/tasks.md

# SDD Tasks: Notification Center

## Review Workload Forecast

| Field | Value |
|-------|-------|
| Estimated changed lines | ~1,800 total (PR-1 ~600; PR-2 ~250; PR-3 ~700; PR-4 ~250) |
| 400-line budget risk | High |
| Chained PRs recommended | Yes |
| Suggested split | PR 1 (Backend Core) → PR 2 (Backend Integration) → PR 3 (Frontend Core) → PR 4 (Toast Coordination) |
| Delivery strategy | auto-chain |
| Chain strategy | stacked-to-main |

```
Decision needed before apply: No
Chained PRs recommended: Yes
Chain strategy: stacked-to-main
400-line budget risk: High
```

> **Note:** PR-1 (~600 lines) and PR-3 (~700 lines) exceed the 400-line review budget. PR-3 in particular carries High risk. Tasks within each PR are grouped into autonomous work units. If review fanout is available, PR-3 can be split into (a) Provider + Hook + Styles and (b) NotificationCenter + NotificationItem + AppShell integration. PR-1 can be split into (a) Migration + Model + Service and (b) Router + Registration + Tests.

---

## PR-1: Backend Core

**Goal:** Establish the persistent notification backend: database schema, SQLAlchemy model, NotificationService singleton, FastAPI router with Pydantic schemas, and comprehensive unit + integration tests.

**Estimated Lines:** ~600
**Review Risk:** Medium

---

### NC-PR1-001: Create Alembic migration for notifications table

**Description:**
Write an Alembic revision that creates the `notifications` table with all columns, constraints, indexes, and the foreign key to `users.id` as specified in the design.

**Files to modify:**
- `apps/api/alembic/versions/2026_05_29_add_notifications_table.py` *(new)*

**Acceptance criteria:**
- [ ] Migration creates `notifications` table with columns: `id`, `user_id`, `category`, `severity`, `title`, `message`, `source_type`, `source_id`, `metadata`, `read_at`, `dismissed_at`, `created_at`.
- [ ] Foreign key `user_id` references `users.id` with `ON DELETE CASCADE`.
- [ ] Index `idx_notifications_user_created_at` on `(user_id, created_at DESC)`.
- [ ] Partial index `idx_notifications_user_unread` on `(user_id, read_at)` where `read_at IS NULL`.
- [ ] `upgrade()` and `downgrade()` are both implemented and pass `alembic upgrade head` / `alembic downgrade -1`.
- [ ] Migration depends on current `head` revision.

**Estimated effort:** Small (2–3 hours)
**Dependencies:** None

---

### NC-PR1-002: Create SQLAlchemy Notification model and export

**Description:**
Add the `Notification` SQLAlchemy model following the existing `UUIDPrimaryKeyMixin` + `Base` pattern. Export it from `models/__init__.py` for Alembic autogenerate discovery.

**Files to modify:**
- `apps/api/src/models/notification.py` *(new)*
- `apps/api/src/models/__init__.py`

**Acceptance criteria:**
- [ ] `Notification` model matches the design schema exactly with correct types (`UUID`, `String(32)`, `String(16)`, `String(255)`, `Text`, `JSONB`, `DateTime(timezone=True)`).
- [ ] `user_id` has `ForeignKey("users.id", ondelete="CASCADE")`, `nullable=False`, `index=True`.
- [ ] `read_at` and `created_at` are indexed.
- [ ] `metadata` column defaults to `{}`.
- [ ] Model is exported in `models/__init__.py`.
- [ ] `alembic revision --autogenerate` produces no drift against the hand-written migration.

**Estimated effort:** Small (2–3 hours)
**Dependencies:** NC-PR1-001

---

### NC-PR1-003: [RED] Write NotificationService unit tests — basic CRUD

**Description:**
Write failing pytest unit tests for `NotificationService` covering create, list, count, mark_read, mark_all_read, and dismiss happy paths.

**Files to modify:**
- `apps/api/tests/unit/test_notification_service.py` *(new)*

**Acceptance criteria:**
- [ ] `test_create_notification`: assert row inserted with correct values, `read_at` NULL, `dismissed_at` NULL.
- [ ] `test_list_notifications_orders_by_created_at_desc`: 3 rows inserted, newest first.
- [ ] `test_list_notifications_excludes_dismissed`: dismissed row not returned.
- [ ] `test_list_notifications_unread_only`: `unread_only=True` returns only unread.
- [ ] `test_get_unread_count`: 5 rows, 2 unread → count is 2.
- [ ] `test_mark_read_sets_read_at`: `read_at` is not NULL after call.
- [ ] `test_mark_all_read_affects_all_unread`: all unread rows updated.
- [ ] `test_dismiss_sets_dismissed_at`: `dismissed_at` is not NULL after call.
- [ ] Tests use `db_session` fixture and create test `User` rows in session.

**Estimated effort:** Small (3–4 hours)
**Dependencies:** NC-PR1-002

---

### NC-PR1-004: [GREEN] Implement NotificationService

**Description:**
Implement the `NotificationService` singleton with all methods. The service accepts `AsyncSession` explicitly and filters all queries by `user_id`.

**Files to modify:**
- `apps/api/src/services/notification_service.py` *(new)*

**Acceptance criteria:**
- [ ] `create_notification(session, user_id, *, category, severity, title, ...)` inserts row and returns `Notification`.
- [ ] `list_notifications(session, user_id, *, limit=20, offset=0, unread_only=False, mute_categories=None)` returns `(items, total)` tuple, excludes `dismissed_at IS NOT NULL`, orders by `created_at DESC`.
- [ ] `get_unread_count(session, user_id)` counts rows where `read_at IS NULL` and `dismissed_at IS NULL`.
- [ ] `mark_read(session, notification_id, user_id)` sets `read_at = now()`, returns updated row; raises 404-equivalent if not found or not owned.
- [ ] `mark_all_read(session, user_id)` sets `read_at = now()` on all unread rows for user; returns count updated.
- [ ] `dismiss(session, notification_id, user_id)` sets `dismissed_at = now()`; raises 404-equivalent if not found or not owned.
- [ ] All methods filter by `user_id`.
- [ ] `NC-PR1-003` tests pass.

**Estimated effort:** Medium (4–5 hours)
**Dependencies:** NC-PR1-003

---

### NC-PR1-005: [TRIANGULATE] NotificationService edge-case and isolation tests

**Description:**
Add unit tests for cross-user isolation, wrong-owner failures, mute category filtering, and partial index usage.

**Files to modify:**
- `apps/api/tests/unit/test_notification_service.py`

**Acceptance criteria:**
- [ ] `test_mark_read_wrong_owner_raises`: User A creates notification; User B calls `mark_read` → exception raised.
- [ ] `test_dismiss_wrong_owner_raises`: User A creates notification; User B calls `dismiss` → exception raised.
- [ ] `test_list_notifications_mute_categories`: pass `mute_categories=["instance"]`; instance rows excluded, system rows returned.
- [ ] `test_get_unread_count_excludes_dismissed`: unread but dismissed row → count is 0.
- [ ] `test_get_unread_count_query_uses_partial_index`: query plan uses `idx_notifications_user_unread` (verified via `EXPLAIN` or SQLite equivalent).

**Estimated effort:** Small (2–3 hours)
**Dependencies:** NC-PR1-004

---

### NC-PR1-006: [RED] Write API integration tests — basic endpoints

**Description:**
Write failing integration tests for the notifications API router covering list, unread count, mark read, mark all read, and dismiss.

**Files to modify:**
- `apps/api/tests/integration/test_notifications_api.py` *(new)*

**Acceptance criteria:**
- [ ] `test_list_requires_auth`: `GET /notifications` without auth → `401`.
- [ ] `test_list_returns_only_own_notifications`: create for user A; user B lists → not in response.
- [ ] `test_unread_count_endpoint`: create 3 unread; `GET /notifications/unread` → `{count: 3}`.
- [ ] `test_mark_read_endpoint`: create unread; `PATCH /notifications/{id}/read` → `200`, `read_at` set.
- [ ] `test_mark_all_read_endpoint`: create 4 unread; `POST /notifications/mark-all-read` → `{marked_count: 4}`.
- [ ] `test_dismiss_endpoint`: create notification; `DELETE /notifications/{id}` → `204`; subsequent list excludes it.
- [ ] Uses `authenticated_client` and `db_session` fixtures.

**Estimated effort:** Small (3–4 hours)
**Dependencies:** NC-PR1-004

---

### NC-PR1-007: [GREEN] Implement FastAPI notifications router and Pydantic schemas

**Description:**
Create the FastAPI `APIRouter` for `/notifications` with all endpoints and Pydantic response models. Read `mute_categories` from `UserConfig` and pass to `list_notifications`.

**Files to modify:**
- `apps/api/src/api/notifications.py` *(new)*
- `apps/api/src/api/__init__.py`

**Acceptance criteria:**
- [ ] `GET /notifications` with `limit`, `offset`, `unread_only` query params; returns `NotificationListResponse`.
- [ ] `GET /notifications/unread` returns `UnreadCountResponse`.
- [ ] `PATCH /notifications/{id}/read` returns `NotificationItem`; `404` if not owned.
- [ ] `POST /notifications/mark-all-read` returns `MarkAllReadResponse`.
- [ ] `DELETE /notifications/{id}` returns `204 No Content`; `404` if not owned.
- [ ] Router reads `notification_mute_categories` from user's `UserConfig.config` and passes to `list_notifications`.
- [ ] `limit` capped at 100.
- [ ] All endpoints use `get_current_user_id` / `get_db_session` dependencies.
- [ ] Router exported from `api/__init__.py`.
- [ ] `NC-PR1-006` tests pass.

**Estimated effort:** Medium (4–5 hours)
**Dependencies:** NC-PR1-006

---

### NC-PR1-008: [TRIANGULATE] API edge-case and ownership tests

**Description:**
Add integration tests for pagination, ownership enforcement, and mute categories filtering at the API layer.

**Files to modify:**
- `apps/api/tests/integration/test_notifications_api.py`

**Acceptance criteria:**
- [ ] `test_list_pagination`: create 25 notifications; `limit=10&offset=10` → items length 10, total 25.
- [ ] `test_mark_read_404_for_other_user`: create for user A; user B PATCH → `404`.
- [ ] `test_dismiss_404_for_other_user`: user B DELETE user A's notification → `404`.
- [ ] `test_mute_categories_filter_in_list`: set user config `mute_categories=["instance"]`, create instance + system notifications; `GET /notifications` returns only system.
- [ ] `test_mark_all_read_affects_only_caller`: user A has 3 unread, user B has 2; A calls mark-all-read → A=0, B=2.

**Estimated effort:** Small (2–3 hours)
**Dependencies:** NC-PR1-007

---

### NC-PR1-009: Register router in main.py and import model for Alembic

**Description:**
Import and include the notifications router in the FastAPI app. Import the `Notification` model in `main.py` for Alembic autogenerate discovery.

**Files to modify:**
- `apps/api/src/main.py`

**Acceptance criteria:**
- [ ] `notifications_router` imported and included with `app.include_router(...)`.
- [ ] `Notification` model imported in `main.py` (F401 noqa comment if unused).
- [ ] App boots without import cycles.
- [ ] `GET /health` still returns `200`.
- [ ] `GET /notifications` returns `401` when unauthenticated (smoke test).

**Estimated effort:** Small (1 hour)
**Dependencies:** NC-PR1-007

---

### NC-PR1-010: [REFACTOR] Backend code quality and type safety pass

**Description:**
Run `ruff check .`, `mypy .`, and `pytest` on the new code. Fix any lint errors, type annotations, or docstring gaps. Ensure no `print` statements or debug logs remain.

**Files to modify:**
- Any of the above files with lint/type issues.

**Acceptance criteria:**
- [ ] `ruff check .` passes with zero errors on new files.
- [ ] `mypy .` passes with zero type errors on new files.
- [ ] `pytest tests/unit/test_notification_service.py tests/integration/test_notifications_api.py` passes.
- [ ] All public methods have docstrings.
- [ ] No `print()` or leftover `logger.debug` from development.

**Estimated effort:** Small (1–2 hours)
**Dependencies:** NC-PR1-008, NC-PR1-009

---

## PR-2: Backend Integration

**Goal:** Wire lifecycle hooks and health monitor to create notifications, extend UserConfig for preferences, and validate the end-to-end event producer flow.

**Estimated Lines:** ~250
**Review Risk:** Low

---

### NC-PR2-001: Wire lifecycle_hooks.py to call NotificationService

**Description:**
After `publish_lifecycle_event()` publishes the raw event to `InstanceEventBus`, call `NotificationService.create_notification()` with `user_id=tool_instance.owner_id`. Wrap in `try/except` so event pipeline is never blocked.

**Files to modify:**
- `apps/api/src/services/lifecycle_hooks.py`

**Acceptance criteria:**
- [ ] `publish_lifecycle_event` calls `notification_service.create_notification(...)` after bus publish.
- [ ] `user_id` is set to `instance.owner_id`.
- [ ] `category="instance"`.
- [ ] `severity` mapped: `info` for created/started/stopped/restarted/deleted; `error` for error.
- [ ] `title` derived from event type (e.g., "Container started").
- [ ] `source_type="tool_instances"`, `source_id=instance.id`.
- [ ] Service call wrapped in `try/except`; on failure, error is logged with `correlation_id` and execution continues.
- [ ] Original event bus publish and audit row insert are unaffected by notification failure.

**Estimated effort:** Small (2–3 hours)
**Dependencies:** NC-PR1-010

---

### NC-PR2-002: Wire health_monitor.py to call NotificationService

**Description:**
After `HealthMonitor` detects a state change and publishes the event, call `NotificationService.create_notification()` with `user_id=instance.owner_id`. Wrap in `try/except`.

**Files to modify:**
- `apps/api/src/services/health_monitor.py`

**Acceptance criteria:**
- [ ] `_handle_state_change` calls `notification_service.create_notification(...)` after bus publish.
- [ ] `user_id` is set to `instance.owner_id`.
- [ ] `category="health"` for health changes; `"instance"` for errors.
- [ ] `severity` mapped: `error` for crash, `warning` for unhealthy, `info` for recovery.
- [ ] `source_type="tool_instances"`, `source_id=instance.id`.
- [ ] Service call wrapped in `try/except`; on failure, error is logged with `correlation_id` and loop continues.
- [ ] Original event bus publish and health check insert are unaffected.

**Estimated effort:** Small (2–3 hours)
**Dependencies:** NC-PR1-010

---

### NC-PR2-003: Extend UserConfig schema for notification preferences

**Description:**
Add `notification_mute_categories` and `notification_toast_level` to the `UserConfigResponse` and `UserConfigUpdate` Pydantic models. Apply `mute_categories` filtering in `list_notifications`.

**Files to modify:**
- `apps/api/src/api/user_config.py`
- `apps/api/src/services/notification_service.py`

**Acceptance criteria:**
- [ ] `UserConfigResponse` includes `notification_mute_categories: list[str] | None = None` and `notification_toast_level: str | None = None`.
- [ ] `UserConfigUpdate` includes the same optional fields.
- [ ] `list_notifications` in `NotificationService` accepts `mute_categories` and filters with `Notification.category.not_in(mute_categories)`.
- [ ] `GET /users/me/config` returns new keys when present in JSON blob.
- [ ] `PATCH /users/me/config` persists new keys into the JSON blob.
- [ ] Existing config keys are unaffected.

**Estimated effort:** Small (2–3 hours)
**Dependencies:** NC-PR1-010

---

### NC-PR2-004: [RED] Write event producer integration tests

**Description:**
Write integration tests that exercise real lifecycle and health monitor endpoints and assert notification rows are created for the instance owner.

**Files to modify:**
- `apps/api/tests/integration/test_notification_producers.py` *(new)*

**Acceptance criteria:**
- [ ] `test_lifecycle_event_creates_notification`: trigger `instance.started` via lifecycle hook; assert notification row exists with `category="instance"`, `severity="info"`, `user_id=owner_id`.
- [ ] `test_health_monitor_error_creates_notification`: simulate health monitor detecting crash; assert notification row with `severity="error"`.
- [ ] `test_notification_failure_does_not_block_event_pipeline`: mock `create_notification` to raise; assert event is still published and no exception escapes.
- [ ] `test_notification_ownership_matches_instance_owner`: create instance for user A; trigger event; assert notification `user_id` is A's ID, not the calling user's.
- [ ] Uses `authenticated_client`, `db_session`, and `test_project_and_repo` fixtures.

**Estimated effort:** Medium (3–4 hours)
**Dependencies:** NC-PR2-001, NC-PR2-002, NC-PR2-003

---

### NC-PR2-005: [GREEN / REFACTOR] Verify producer tests pass and clean up

**Description:**
Run the producer integration tests, fix any failures, and do a final lint/type check on all modified files.

**Files to modify:**
- Any files with issues found during test runs.

**Acceptance criteria:**
- [ ] `pytest tests/integration/test_notification_producers.py` passes.
- [ ] `ruff check .` passes on modified files.
- [ ] `mypy .` passes on modified files.
- [ ] No regressions in existing `pytest` suite.

**Estimated effort:** Small (1–2 hours)
**Dependencies:** NC-PR2-004

---

## PR-3: Frontend Core

**Goal:** Build the frontend notification surface: icon registry, React context with polling, hook, notification list components, styles, and AppShell integration.

**Estimated Lines:** ~700
**Review Risk:** High

---

### NC-PR3-001: Add bell icon to icon registry

**Description:**
Register the Phosphor `Bell` icon in the frontend icon registry under the name `"bell"`.

**Files to modify:**
- `apps/web/src/utils/icons.ts`

**Acceptance criteria:**
- [ ] `"bell"` added to `IconName` union type.
- [ ] `bell: Bell` added to `iconRegistry` map.
- [ ] `Bell` imported from `@phosphor-icons/react`.
- [ ] `<Icon name="bell" />` renders without error in a quick manual check.

**Estimated effort:** Small (30 minutes)
**Dependencies:** None (can be prepared before PR-2 merges)

---

### NC-PR3-002: [RED] Write useNotifications hook tests

**Description:**
Write failing tests for the `useNotifications` hook covering state exposure, optimistic updates, and revert behavior.

**Files to modify:**
- `apps/web/src/hooks/use-notifications.test.ts` *(new)*

**Acceptance criteria:**
- [ ] `test_returns_notifications_and_unreadCount_from_context`: mock provider value; assert hook returns same array and count.
- [ ] `test_optimistically_updates_on_markRead`: call `markRead`; assert local `read_at` set and `unreadCount` decremented before API resolves.
- [ ] `test_reverts_optimistic_update_on_markRead_failure`: mock API rejection; assert state reverted.
- [ ] `test_optimistically_updates_on_dismiss`: call `dismiss`; assert item removed and count decremented.
- [ ] `test_reverts_optimistic_update_on_dismiss_failure`: mock API rejection; assert item restored.
- [ ] `test_calls_refreshList_when_invoked`: assert `GET /notifications` called.

**Estimated effort:** Small (2–3 hours)
**Dependencies:** NC-PR3-001

---

### NC-PR3-003: [GREEN] Implement NotificationProvider context with polling

**Description:**
Create the `NotificationProvider` React context that polls the backend endpoints, manages notification list and unread count, and handles tab visibility pause/resume.

**Files to modify:**
- `apps/web/src/state/notifications.tsx` *(new)*

**Acceptance criteria:**
- [ ] Context maintains `notifications: NotificationItem[]` and `unreadCount: number`.
- [ ] Polls `GET /notifications/unread` every 15 seconds.
- [ ] Polls `GET /notifications` every 30 seconds when dropdown is closed.
- [ ] Pauses all polling when `document.hidden` is true; resumes on visible.
- [ ] On dropdown open: immediately fetches list, pauses 30s list poll.
- [ ] On dropdown close: restarts 30s list poll.
- [ ] On logout: stops polling and clears state.
- [ ] Polling errors are silently logged; next cycle proceeds.
- [ ] On `401` response: stops all polling.

**Estimated effort:** Medium (4–5 hours)
**Dependencies:** NC-PR3-002

---

### NC-PR3-004: [GREEN] Implement useNotifications hook

**Description:**
Create the `useNotifications()` consumer hook that exposes state and mutation callbacks with optimistic updates.

**Files to modify:**
- `apps/web/src/hooks/use-notifications.ts` *(new)*

**Acceptance criteria:**
- [ ] Hook returns `notifications`, `unreadCount`, `isLoading`, `error`, `markRead`, `markAllRead`, `dismiss`, `refreshList`.
- [ ] `markRead(id)`: optimistically sets `read_at` and decrements `unreadCount`; calls `PATCH /notifications/{id}/read`; reverts on failure.
- [ ] `markAllRead()`: optimistically sets `read_at` on all items and `unreadCount=0`; calls `POST /notifications/mark-all-read`; reverts on failure.
- [ ] `dismiss(id)`: optimistically removes item and decrements `unreadCount` if unread; calls `DELETE /notifications/{id}`; reverts on failure.
- [ ] `refreshList()`: calls `GET /notifications` and updates state.
- [ ] Errors are surfaced as `error` state but not thrown.
- [ ] `NC-PR3-002` tests pass.

**Estimated effort:** Medium (3–4 hours)
**Dependencies:** NC-PR3-003

---

### NC-PR3-005: [TRIANGULATE] Hook edge-case and error handling tests

**Description:**
Add tests for 401 handling, polling pause, and multiple rapid mutations.

**Files to modify:**
- `apps/web/src/hooks/use-notifications.test.ts`

**Acceptance criteria:**
- [ ] `test_stops_polling_on_401`: simulate 401; assert polling intervals cleared.
- [ ] `test_pauses_polling_when_document_hidden`: simulate `visibilitychange` to hidden; assert `clearInterval` called.
- [ ] `test_resumes_polling_when_document_visible`: simulate hidden then visible; assert intervals restarted and immediate fetches fired.
- [ ] `test_multiple_markRead_calls_decrement_correctly`: mark 3 items read rapidly; assert `unreadCount` decrements by 3.

**Estimated effort:** Small (2–3 hours)
**Dependencies:** NC-PR3-004

---

### NC-PR3-006: [RED] Write NotificationItem component tests

**Description:**
Write failing render tests for the `NotificationItem` presentational component.

**Files to modify:**
- `apps/web/src/components/notification-item.test.tsx` *(new)*

**Acceptance criteria:**
- [ ] `test_displays_title_and_relative_time`: render with sample data; assert title and relative time visible.
- [ ] `test_applies_unread_styling_when_read_at_is_null`: assert unread CSS class present.
- [ ] `test_applies_read_styling_when_read_at_is_set`: assert read CSS class present.
- [ ] `test_calls_onMarkRead_when_mark_read_clicked`: simulate click; assert callback with correct id.
- [ ] `test_calls_onDismiss_when_dismiss_clicked`: simulate click; assert callback with correct id.
- [ ] `test_displays_severity_icon`: assert severity icon element present.

**Estimated effort:** Small (2–3 hours)
**Dependencies:** NC-PR3-001

---

### NC-PR3-007: [GREEN] Implement NotificationItem component

**Description:**
Build the presentational row component for a single notification.

**Files to modify:**
- `apps/web/src/components/notification-item.tsx` *(new)*

**Acceptance criteria:**
- [ ] Accepts `notification: NotificationItem`, `onMarkRead: (id: string) => void`, `onDismiss: (id: string) => void`.
- [ ] Displays severity icon mapped from `severity` to Phosphor icon (`Info`, `Warning`, `XCircle`, `CheckCircle`).
- [ ] Displays `title` and relative timestamp (e.g., "2m ago").
- [ ] Unread rows have `.notification-item--unread` class (bolder text, accent border, background tint).
- [ ] Read rows have `.notification-item--read` class (reduced opacity).
- [ ] Renders "Mark read" and "Dismiss" action buttons.
- [ ] `NC-PR3-006` tests pass.

**Estimated effort:** Small (3–4 hours)
**Dependencies:** NC-PR3-006

---

### NC-PR3-008: [RED] Write NotificationCenter component tests

**Description:**
Write failing render and interaction tests for the `NotificationCenter` component.

**Files to modify:**
- `apps/web/src/components/notification-center.test.tsx` *(new)*

**Acceptance criteria:**
- [ ] `test_renders_bell_icon`: assert bell icon visible.
- [ ] `test_shows_badge_when_unread_count_gt_0`: provider state `unreadCount=3`; assert badge text is "3".
- [ ] `test_hides_badge_when_unread_count_is_0`: assert badge not in document.
- [ ] `test_opens_dropdown_on_bell_click`: simulate click; assert dropdown panel visible.
- [ ] `test_closes_dropdown_on_outside_click`: open dropdown; click outside; assert panel not visible.
- [ ] `test_closes_dropdown_on_escape`: open dropdown; fire `Escape` key; assert panel not visible.
- [ ] `test_renders_empty_state_when_no_notifications`: assert empty state text visible.
- [ ] `test_renders_notification_items`: list has 2 items; assert 2 `NotificationItem` components rendered.
- [ ] `test_calls_markAllRead_on_footer_button_click`: simulate click; assert mock called.
- [ ] `test_refreshes_list_immediately_on_open`: open dropdown; assert `refreshList` mock called.

**Estimated effort:** Small (3–4 hours)
**Dependencies:** NC-PR3-007

---

### NC-PR3-009: [GREEN] Implement NotificationCenter component

**Description:**
Build the `NotificationCenter` component: bell icon with badge, dropdown panel with list, empty state, footer actions, outside-click/Escape close, and mobile terminal hiding.

**Files to modify:**
- `apps/web/src/components/notification-center.tsx` *(new)*

**Acceptance criteria:**
- [ ] Renders bell icon (`<Icon name="bell" />`).
- [ ] Shows unread count badge when `unreadCount > 0`; caps display at "99+".
- [ ] Badge uses existing `nav-badge` CSS class.
- [ ] Dropdown opens on bell click, closes on outside click or `Escape`.
- [ ] Dropdown is a positioned panel below the bell, right-aligned.
- [ ] Contains scrollable list of `NotificationItem` components.
- [ ] Shows empty state message when list is empty (e.g., "No notifications").
- [ ] Footer has "Mark all as read" button calling `markAllRead()`.
- [ ] Calls `refreshList()` immediately when opening.
- [ ] Hidden when `isMobileTerminal` is true.
- [ ] Uses `useNotifications()` hook.
- [ ] `NC-PR3-008` tests pass.

**Estimated effort:** Medium (4–5 hours)
**Dependencies:** NC-PR3-008

---

### NC-PR3-010: Add notification CSS styles

**Description:**
Add utility classes for the notification dropdown, items, badge, and empty state to `styles.css`.

**Files to modify:**
- `apps/web/src/styles.css`

**Acceptance criteria:**
- [ ] `.notification-dropdown` has absolute positioning, `z-index` above header, `max-height`, scroll, shadow, and matches light/dark theme variables.
- [ ] `.notification-item` has padding, border-bottom, hover state.
- [ ] `.notification-item--unread` has distinct styling (accent left border, slightly different background).
- [ ] `.notification-item--read` has reduced opacity.
- [ ] `.notification-badge` reuses or extends existing `nav-badge` styles.
- [ ] `.notification-empty` has centered text and muted color.
- [ ] Styles work in both light and dark themes.

**Estimated effort:** Small (2–3 hours)
**Dependencies:** NC-PR3-009

---

### NC-PR3-011: Integrate NotificationCenter into AppShell

**Description:**
Mount `<NotificationCenter />` inside the `AppShell` `header-actions` area. Wrap with `NotificationProvider` at the appropriate level.

**Files to modify:**
- `apps/web/src/components/app-shell.tsx`

**Acceptance criteria:**
- [ ] `<NotificationProvider>` wraps the authenticated app layout (inside or alongside `EventProvider`).
- [ ] `<NotificationCenter />` rendered inside `header-actions` div, before the user chip.
- [ ] Component is hidden when `isMobileTerminal` is true.
- [ ] No visual regressions in existing header layout.
- [ ] Existing tests for `AppShell` still pass (or are updated if needed).

**Estimated effort:** Small (1–2 hours)
**Dependencies:** NC-PR3-009, NC-PR3-010

---

### NC-PR3-012: [REFACTOR] Frontend code quality and type check pass

**Description:**
Run `npm run typecheck`, `npm run lint`, and frontend tests. Fix any errors. Verify accessibility (keyboard navigation, ARIA labels).

**Files to modify:**
- Any files with type/lint issues.

**Acceptance criteria:**
- [ ] `npm run typecheck` passes with zero errors.
- [ ] `npm run lint` passes with zero errors.
- [ ] `npm test` (or `vitest run`) passes for all new test files.
- [ ] Bell icon has `aria-label="Notifications"`.
- [ ] Dropdown panel has `role="menu"` or `role="dialog"` and appropriate `aria-*` attributes.
- [ ] Mark read / dismiss buttons have accessible labels.
- [ ] No `console.log` left from development.

**Estimated effort:** Small (1–2 hours)
**Dependencies:** NC-PR3-011

---

## PR-4: Toast Coordination

**Goal:** Update the toast bridge to respect notification preferences, extend settings UI for preference controls, and verify coordination end-to-end.

**Estimated Lines:** ~250
**Review Risk:** Low

---

### NC-PR4-001: Extend toast-rules.ts with category/severity mapping

**Description:**
Add `mapEventToCategory` and `mapEventToSeverity` functions to `toast-rules.ts` so the bridge can evaluate events against user preferences.

**Files to modify:**
- `apps/web/src/components/toast-rules.ts`

**Acceptance criteria:**
- [ ] `mapEventToCategory(event)` returns `"instance"` for `instance.*` events, `"health"` for `health.*`, `"system"` otherwise.
- [ ] `mapEventToSeverity(event)` returns `"error"` for `instance.error` / `health.error`; `"warning"` for unhealthy health changes; `"info"` for created/started/stopped/restarted/deleted; `"success"` for recovery to running.
- [ ] Functions are pure and exported.
- [ ] Existing toast mapping behavior is preserved (no regressions in current tests).
- [ ] New functions have unit tests.

**Estimated effort:** Small (2–3 hours)
**Dependencies:** PR-3 merged (frontend types available)

---

### NC-PR4-002: [RED] Write EventToastBridge preference check tests

**Description:**
Write failing tests for the updated `EventToastBridge` that verify preference-based toast suppression.

**Files to modify:**
- `apps/web/src/components/event-toast-bridge.test.tsx` *(new)*

**Acceptance criteria:**
- [ ] `test_shows_toast_when_level_is_all_and_category_not_muted`: assert toast shown.
- [ ] `test_suppresses_toast_when_level_is_none`: assert no toast.
- [ ] `test_suppresses_info_toast_when_level_is_errors`: event severity `info`; assert no toast.
- [ ] `test_shows_error_toast_when_level_is_errors`: event severity `error`; assert toast shown.
- [ ] `test_suppresses_toast_when_category_is_muted`: config mute contains event category; assert no toast.
- [ ] Tests mock `useEventContext`, user config context, and `toast-rules.ts` as needed.

**Estimated effort:** Small (2–3 hours)
**Dependencies:** NC-PR4-001

---

### NC-PR4-003: [GREEN] Update EventToastBridge with preference checks

**Description:**
Modify `EventToastBridge` to read `notification_toast_level` and `notification_mute_categories` from user config and skip toasts based on the preference hierarchy.

**Files to modify:**
- `apps/web/src/components/event-toast-bridge.tsx`

**Acceptance criteria:**
- [ ] Bridge reads user config (from existing settings API / context).
- [ ] Evaluation order: mute categories first, then toast level.
- [ ] If `notification_toast_level === "none"`: no toasts shown.
- [ ] If `notification_toast_level === "errors"`: only toasts for `severity === "error"`.
- [ ] If `notification_toast_level === "all"`: toasts shown as before.
- [ ] If event category is in `notification_mute_categories`: toast suppressed.
- [ ] Backend notification creation is unaffected; bridge only controls toast surfacing.
- [ ] `NC-PR4-002` tests pass.

**Estimated effort:** Small (2–3 hours)
**Dependencies:** NC-PR4-002

---

### NC-PR4-004: [TRIANGULATE] Bridge edge-case and integration tests

**Description:**
Add tests for preference changes taking effect immediately, mixed mute + level constraints, and no regressions in existing deduplication.

**Files to modify:**
- `apps/web/src/components/event-toast-bridge.test.tsx`

**Acceptance criteria:**
- [ ] `test_preference_change_is_immediate`: config changes from `"all"` to `"none"`; next event suppressed.
- [ ] `test_muted_category_overrides_all_level`: level `"all"` but category muted; toast suppressed.
- [ ] `test_deduplication_still_works_with_preferences`: two identical allowed events within 1s → one toast.
- [ ] `test_unmapped_event_defaults_to_info`: unknown event type → category `"system"`, severity `"info"`.

**Estimated effort:** Small (1–2 hours)
**Dependencies:** NC-PR4-003

---

### NC-PR4-005: Extend settings UI with notification preferences

**Description:**
Add notification preference controls to the existing General settings tab: a multi-select/checkbox group for mute categories and a select for toast level.

**Files to modify:**
- `apps/web/src/pages/settings.tsx`
- `apps/web/src/api/settings.ts`

**Acceptance criteria:**
- [ ] `UserConfig` interface in `api/settings.ts` includes `notification_mute_categories?: string[]` and `notification_toast_level?: "all" | "errors" | "none"`.
- [ ] `UserConfigUpdate` interface includes the same optional fields.
- [ ] General settings tab has a "Notifications" section.
- [ ] Toast level select with options: "All", "Errors only", "None".
- [ ] Mute categories checkboxes for known categories: `instance`, `system`, `health`, `security`.
- [ ] Preferences save via existing `updateUserConfig` API.
- [ ] Saved preferences persist after page reload.
- [ ] Default values: `notification_toast_level="all"`, `notification_mute_categories=[]`.

**Estimated effort:** Small (3–4 hours)
**Dependencies:** NC-PR4-003

---

### NC-PR4-006: [REFACTOR] Final quality pass and verification

**Description:**
Run full frontend type check, lint, and test suite. Do a manual smoke test of the notification center + toast coordination.

**Files to modify:**
- Any files with issues found.

**Acceptance criteria:**
- [ ] `npm run typecheck` passes.
- [ ] `npm run lint` passes.
- [ ] `npm test` passes for all new and modified test files.
- [ ] Manual smoke test: trigger an `instance.error` event → notification appears in dropdown → toast appears (if level="all") → mark read → badge clears.
- [ ] Manual smoke test: set toast level to "none" → trigger event → no toast appears, but notification still created.
- [ ] No regressions in existing settings page functionality.

**Estimated effort:** Small (1–2 hours)
**Dependencies:** NC-PR4-004, NC-PR4-005

---

## Dependency Graph (PR Level)

```
PR-1: Backend Core
│
├─► NC-PR1-001 ──► NC-PR1-002
│
├─► NC-PR1-003 ──► NC-PR1-004 ──► NC-PR1-005
│
├─► NC-PR1-006 ──► NC-PR1-007 ──► NC-PR1-008
│
├─► NC-PR1-009
│
└─► NC-PR1-010

PR-2: Backend Integration (depends on PR-1 merged)
│
├─► NC-PR2-001
│
├─► NC-PR2-002
│
├─► NC-PR2-003
│
├─► NC-PR2-004
│
└─► NC-PR2-005

PR-3: Frontend Core (depends on PR-1/PR-2 merged)
│
├─► NC-PR3-001
│
├─► NC-PR3-002 ──► NC-PR3-003 ──► NC-PR3-004 ──► NC-PR3-005
│
├─► NC-PR3-006 ──► NC-PR3-007
│
├─► NC-PR3-008 ──► NC-PR3-009 ──► NC-PR3-010 ──► NC-PR3-011
│
└─► NC-PR3-012

PR-4: Toast Coordination (depends on PR-3 merged)
│
├─► NC-PR4-001
│
├─► NC-PR4-002 ──► NC-PR4-003 ──► NC-PR4-004
│
├─► NC-PR4-005
│
└─► NC-PR4-006
```

---

## Task Summary

| PR | Task ID | Description | TDD Phase | Effort |
|----|---------|-------------|-----------|--------|
| 1 | NC-PR1-001 | Alembic migration for notifications table | — | S |
| 1 | NC-PR1-002 | SQLAlchemy Notification model and export | — | S |
| 1 | NC-PR1-003 | Service unit tests — basic CRUD | RED | S |
| 1 | NC-PR1-004 | Implement NotificationService | GREEN | M |
| 1 | NC-PR1-005 | Service edge-case and isolation tests | TRIANGULATE | S |
| 1 | NC-PR1-006 | API integration tests — basic endpoints | RED | S |
| 1 | NC-PR1-007 | Implement FastAPI router and Pydantic schemas | GREEN | M |
| 1 | NC-PR1-008 | API edge-case and ownership tests | TRIANGULATE | S |
| 1 | NC-PR1-009 | Register router in main.py | — | S |
| 1 | NC-PR1-010 | Backend code quality and type safety pass | REFACTOR | S |
| 2 | NC-PR2-001 | Wire lifecycle_hooks.py to NotificationService | — | S |
| 2 | NC-PR2-002 | Wire health_monitor.py to NotificationService | — | S |
| 2 | NC-PR2-003 | Extend UserConfig schema for preferences | — | S |
| 2 | NC-PR2-004 | Event producer integration tests | RED | M |
| 2 | NC-PR2-005 | Verify producer tests and clean up | GREEN / REFACTOR | S |
| 3 | NC-PR3-001 | Add bell icon to icon registry | — | S |
| 3 | NC-PR3-002 | useNotifications hook tests | RED | S |
| 3 | NC-PR3-003 | Implement NotificationProvider context | GREEN | M |
| 3 | NC-PR3-004 | Implement useNotifications hook | GREEN | M |
| 3 | NC-PR3-005 | Hook edge-case and error handling tests | TRIANGULATE | S |
| 3 | NC-PR3-006 | NotificationItem component tests | RED | S |
| 3 | NC-PR3-007 | Implement NotificationItem component | GREEN | S |
| 3 | NC-PR3-008 | NotificationCenter component tests | RED | S |
| 3 | NC-PR3-009 | Implement NotificationCenter component | GREEN | M |
| 3 | NC-PR3-010 | Add notification CSS styles | — | S |
| 3 | NC-PR3-011 | Integrate NotificationCenter into AppShell | — | S |
| 3 | NC-PR3-012 | Frontend code quality and type check pass | REFACTOR | S |
| 4 | NC-PR4-001 | Extend toast-rules.ts with mapping | — | S |
| 4 | NC-PR4-002 | EventToastBridge preference check tests | RED | S |
| 4 | NC-PR4-003 | Update EventToastBridge with preference checks | GREEN | S |
| 4 | NC-PR4-004 | Bridge edge-case and integration tests | TRIANGULATE | S |
| 4 | NC-PR4-005 | Extend settings UI with notification preferences | — | S |
| 4 | NC-PR4-006 | Final quality pass and verification | REFACTOR | S |

**Total tasks:** 31  
**Total estimated effort:** ~100 hours (backend ~40h, frontend ~45h, integration ~15h)