# Approval / Attention UI

**Status:** Approved target-state behavior  
**Narrow gates:** I1/I2  
**Generic activation:** I3.

## Page Job

Let users make genuinely required decisions/approvals quickly and safely, with enough context to understand consequences but without digging through implementation detail.

## Global Attention Center

Lists unresolved user-owned/policy-required items across Projects, ordered by blocking impact/urgency:

```text
Project / primitive context
what needs decision/approval
why it is required
recommendation/current position
material consequence
blocking gate / affected work
age/expiry/staleness
```

Filters: Project, type, blocking/non-blocking, owner required/policy approval, age/status.

## Approval Detail

One decision context with:

- exact target and revision;
- policy/reason requiring Approval;
- concise recommendation and alternatives when relevant;
- evidence/affected artifacts links;
- consequences of approve/deny/defer where permitted;
- expiry/revalidation rules;
- one primary action group.

High-risk actions (production/destructive/capability broadening) receive proportionate confirmation identifying exact target/impact.

## Decision vs Approval

If the owner must choose product direction, UI records a `Decision`; if policy authorizes a protected action, it records an `Approval`. One interaction can lead to both, but they remain separately attributable.

## Stale / Changed Context

If underlying Plan/ChangeSet/Deployment/policy changed, old approval becomes stale and cannot be submitted blindly. UI shows what changed and requires refresh/review.

## In-App + External Notifications

External channels deep-link to this canonical item. Failure to notify does not lose attention state. Resolving one projection resolves the canonical item everywhere.

## States

pending, loading, stale/revalidation needed, approved, denied, deferred, expired, cancelled, permission lost, provider/connection issue.

## Responsive / Accessibility

Mobile is viable for concise approvals: context -> consequence -> action. Essential evidence is expandable; no wide diff forced into the approval page—link to Review where appropriate. Focus and confirmations follow accessible dialog patterns.

## URL Truth

Stable Attention/Approval route. Back link restores source primitive. Resolved items remain historical read-only pages.

## Increment Realization

I1 merge/security gates may use focused approval UI. I2 Planning owner/policy decisions. I3 generic Attention center and configurable routing. I5/I6/I8 add CI/deployment/incident contexts.

## High-Fidelity Requirements

Before generic I3: global queue, owner Decision, production/high-risk Approval, stale context, denial/defer and mobile approval state.

## Target State

Attention is the durable cross-product projection of items that genuinely need the user; Approval is protected-action authorization tied to an exact target/revision/policy. The page minimizes interruption while preserving enough evidence and consequence to make an informed action.

## Primary Users / Jobs

- owner: make OwnerRequired product decisions and PolicyRequired approvals;
- authorized operator: approve/deny a protected action within delegated scope;
- project/delivery lead: triage what needs human action without blocking unrelated autonomous work.

## Entry / Exit Points

Entry: global Attention indicator/page, Project attention section, Planning, Review/MergeGate, Deployment, Incident, external notification deep link. Exit: exact source primitive/evidence, Decision Log, or resolved historical Approval. Browser back returns to prior queue/filter/context.

## User Journeys

### J1 — Triage attention

```text
open Attention
 -> order by blocking impact/urgency
 -> filter Project/type if needed
 -> select item
 -> understand exact target + reason + consequence + owner
 -> act or open deeper evidence
```

### J2 — Approve a protected action

```text
Approval detail
 -> confirm target revision + policy
 -> review recommendation/evidence/consequence
 -> Approve
 -> high-risk confirmation when proportional
 -> command revalidates target/policy
 -> durable Approval + protected action progress
```

### J3 — Deny or defer safely

```text
pending item
 -> inspect denial/defer consequence
 -> Deny or Defer where policy allows
 -> Decision/Approval history records actor/reason
 -> dependent work blocks/reschedules explicitly
 -> unrelated work continues
```

### J4 — Handle stale Approval

```text
underlying target/policy changes
 -> approval marked stale
 -> submit disabled
 -> show what changed
 -> refresh/review new exact target
 -> new/revalidated Approval if still required
```

## Data / Source of Truth

Canonical Decision, Approval, Attention and originating Project/Plan/ChangeSet/Deployment/Incident state are authoritative. Notification delivery is a projection only. Evidence links point to their defining domains; the Attention list owns no duplicate approval state.

## Actions / Authorization

Only Principals satisfying the policy/target authorization can decide/approve/deny. An Approval never broadens an authority ceiling by itself; it authorizes a specific protected action within configured capability. Decision and Approval identities remain separate even when one interaction creates both.

## Async / Duplicate-Mutation Safety

Approve/deny/defer uses exact target revision, policy revision and idempotency protection. Immediate feedback prevents duplicate clicks; protected action can continue durably after navigation. A disconnected/stale client can read cached context but cannot queue a high-risk Approval for later silent submission.

## Invariants From Day 1

- Attention is canonical in-product discoverability even if external notification fails;
- one item states exact target, reason, consequence and current owner;
- stale Approval cannot apply to changed target/policy;
- Decision, Approval and Review remain distinct;
- protected actions use live authoritative policy evaluation;
- unrelated autonomous work is not paused merely because another item needs attention.

## Current Implementation State

Target page only. Narrow I1/I2 gates may use focused detail before the global I3 center activates.

## Deferred Realization

I3 adds configurable generic Attention routing; I5/I6/I8 add CI/deployment/incident contexts. Enterprise escalation/channel governance waits for later productization.

## Temporary Dogfood Behavior

I1 can present a direct focused Approval/Attention card from Review/Project without a full global queue, using final Approval/Decision semantics and durable history.

## Related Contracts / Decisions

- [`../domains/approvals-decisions.md`](../domains/approvals-decisions.md)
- [`../workflows/human-in-the-loop.md`](../workflows/human-in-the-loop.md)
- [`decision-log.md`](decision-log.md), [`review.md`](review.md), [`release-deployment.md`](release-deployment.md), [`incident.md`](incident.md)
- notification delivery is defined by the Communications domain and cannot replace Attention.

## Decisions / ADRs

Autonomy/HITL policy, Decision participation classes and capability ceilings constrain this page. A new protected-action class requires the corresponding Policy/Decision update rather than UI-only logic.

## Visual Mockup Authority

No generic I3 Attention/Approval high-fi is approved yet. Any focused I1 protected gate must be covered by U4/U5 interaction approval; global queue, production approval, stale, denial/defer and mobile states require later explicit approval.

## Acceptance

A user can decide/authorize with confidence about what exactly will happen, while unrelated autonomous work continues where dependency policy permits.