# Communications and Notifications Domain

**Status:** Approved target-state baseline — first external dogfood channels clarified by pre-run VISION trace  
**First minimal use:** when attention/notification is needed; adapters deepen later.

## Target State

Communication is a primitive so AWP can notify or interact through replaceable channels without embedding Botmaster/systray/email/CRM mechanics into domain workflows.

```text
Business event / Approval / Incident / attention item
  -> Notification
  -> CommunicationEndpoint selection/policy
  -> CommunicationProvider adapter
  -> external channel
```

Botmaster CLI and systray remain separate Overdeck/personal tools. **When AWP first needs external owner communication during dogfood, they are the preferred first external channel adapters/endpoints**, matching the owner VISION. Their implementation/product identity does not migrate into AWP core; AWP integrates them through CommunicationProvider/Endpoint seams.

In-app `Needs Your Attention` remains canonical regardless of whether either external channel is configured.

## Core Primitives

### CommunicationEndpoint

Stable configured destination/channel identity with provider, account/connection, capability, recipient/resource mapping, scope and health.

### Notification

Durable communication intent/result linked to originating Project/Plan/Approval/Incident/etc., priority, content/template/payload references, delivery policy and delivery attempts.

## Initial External Dogfood Adapters

Priority once external owner notification/interaction is needed:

```text
1. Botmaster CLI endpoint/adapter
2. systray endpoint/adapter
3. additional channels only when a concrete user/product need appears
```

This ordering is about first dogfood integration, not architectural coupling. The adapters may invoke/connect to the separately maintained Overdeck tools; they must not copy Botmaster/systray domain or personal-workstation assumptions into AWP.

The exact source/API/socket/CLI mechanism is determined during the Overdeck capability harvest. If a current shared communication seam supersedes an old implementation, preserve behavior and replace mechanics rather than porting debt.

## Invariants From Day 1

- notification delivery failure never mutates originating domain outcome;
- in-product Attention remains discoverable even with no external channel configured;
- first external dogfood channel work checks Botmaster and systray before building generic replacements;
- Botmaster/systray remain separate products/tools behind adapters, not AWP core identity;
- secrets/channel credentials use Connection/CredentialReference;
- channel/provider IDs are mappings, not Notification identity;
- sensitive content respects data classification and least disclosure;
- duplicate retries are idempotent/deduplicated where provider supports it;
- communication preferences/policy can suppress/reroute without losing durable attention state;
- user attention remains discoverable inside AWP even if external notification fails.

## Delivery States

```text
pending -> sending -> delivered
 -> failed/retryable
 -> permanently-failed
 -> suppressed-by-policy
 -> cancelled
```

## Channel Capabilities

Adapters declare text/rich action/link/thread/reply/attachment/interactive-action capabilities. Domain does not assume email or chat semantics universally.

Botmaster/systray adapters expose only capabilities their current integration actually supports; AWP does not fake interactive reply/action semantics on a channel that cannot provide them safely.

## Increment Realization

| Increment | Communication realization |
|---|---|
| I1/I2 | minimal Needs Attention/in-app notification; if external owner channel becomes necessary, Botmaster then systray are first integration targets. |
| I3 | Approval/HITL routing preferences and richer endpoint policy. |
| I8 | Incident notifications/escalation. |
| I9 | customer/enterprise channels, retention and support integrations. |

## Current Implementation State

Target spec; no requirement to migrate personal Overdeck Botmaster/systray code into the AWP repository. Their exact integration mechanism remains a source-harvest/provider preflight.

## Deferred Realization

Email/CRM/Slack/etc. are adapters selected when needed. AWP does not rebuild general messaging infrastructure merely to have a channel catalog.

## Temporary Dogfood Behavior

In-app attention may be sufficient initially. External notifications can be omitted while no concrete need exists, with explicit product state still visible. Once an external dogfood channel is needed, check/implement Botmaster/systray adapter paths before introducing another channel/provider stack.

## Failure / Recovery

Provider outage retries according to channel policy. Permanently invalid endpoint marks attention/configuration issue without blocking unrelated product lifecycle unless policy explicitly requires delivery. Loss of Botmaster/systray availability never erases the canonical in-product Attention item.

## UI Implications

Settings manages endpoints/preferences. Attention center remains canonical; notifications link directly to affected primitive/action. Botmaster/systray endpoint health/capabilities appear like other provider endpoints without exposing their internal/personal-tool architecture.

## Reuse / Harvest

The Overdeck capability harvest must inspect the actual Botmaster/systray integration surfaces before implementing these adapters. Allowed dispositions include wrap/adapt/port behavior/replace with a verified shared seam; blind reimplementation is not permitted.

## Decisions / ADRs

Communication remains an independent primitive to preserve adapter extensibility. Botmaster and systray are the preferred first external dogfood endpoints while remaining outside AWP core product identity.