cocottetech/@platform/codebase/@features/ai-copilot/docs/policy-card.screen.md

# policy-card.screen

Per-surface automation policy — the screen that turns "press 'I'm Available' on Tryst every 2–3 hours" (cadence is tier-dependent per [surface-tryst.brief.md §canonical-facts](./surface-tryst.brief.md)) into a single decision. Implements [brief H §H1](./H-recurring-chores.brief.md). Quinn's #1 stated time-suck; this screen is the antidote.

The policy card lives in two places: (a) the chat-home inline strip (compact, status-only) and (b) the per-surface settings sheet (full, editable). This document is the full sheet; the inline strip is covered in [chat-home.screen.md](./chat-home.screen.md).

## Layout (full-screen sheet)

```
┌─────────────────────────────────────────────────┐
│ ◄ Settings                              Done    │ 56pt — top bar
├─────────────────────────────────────────────────┤
│                                                 │
│  ⌖ Tryst bumps                                  │   surface + action heading
│                                                 │
│  ●  Bumping every 3h · next at 3:02             │   live status strip (cadence per tier)
│     [ Pause 1h ] [ Pause today ] [ Stop ]       │   quick-snooze buttons
│                                                 │
│  ─── Cadence ───                                │
│  Every: [ 3h ▼ ]   (Tryst max for this tier)    │
│                    Basic/Std = 3h; Premium+ = 2h│
│                    See surface-tryst §canonical │
│                                                 │
│  ─── Active window ───                          │
│  From: [ 10:00 ▼ ]   To: [ 02:00 ▼ ]            │
│  Days: [M T W T F S S]  ← tap-toggle           │
│                                                 │
│  ─── Vacation mode ───                          │
│  ○ Off                                          │
│  ○ Until I say so                              │
│  ○ Through: [ Sun May 26 ▼ ]                    │
│                                                 │
│  ─── Last 10 bumps ───                          │
│  ✓ 14:02 · accepted  →                          │
│  ✓ 10:02 · accepted  →                          │
│  ⚠ 06:02 · failed · retried · ok →             │
│  ✓ 02:02 · accepted  →                          │
│  …                                              │
│  [ See all in audit → ]                         │
│                                                 │
│  ─── Voice & failure ───                        │
│  When a bump fails: [ Page me · 2 fails ▼ ]    │
│  Receipts: [ Show in chat ▾ ]                  │
│                                                 │
└─────────────────────────────────────────────────┘
```

## Components

| Component | Notes |
|---|---|
| Top bar | Back to settings list; "Done" right-aligned commits + closes. |
| Heading | Surface chip + action verb. Per [F §F5](./00-system-visual-system.md) iconography. |
| Live status | Plain-register one-liner status + countdown to next action. Updates every 60s. |
| Quick-snooze buttons | Three buttons sized for thumb: "Pause 1h" / "Pause today" / "Stop." "Stop" = vacation-mode-on. |
| Cadence picker | Discrete options (2/3/4/6/8h). Sets `policy.cadence`. |
| Active window | Time-range pickers + day toggles. Sets `policy.active_hours` + `policy.active_days`. |
| Vacation mode | 3-option radio. Routes to vacation-mode setup if "Through:" or "Until I say so". |
| Last 10 | Compact rolling list; tap a row → audit-row-detail.screen.md. |
| Failure threshold | When to escalate failed bumps. Default: 2 fails in a row → high-stakes interrupt per brief M §M3a. |
| Receipts toggle | Whether successful bumps show as ambient receipts in chat (per chat-home.screen.md state 1 receipt bubble) or stay silent in audit. |

## States

1. **Active (currently bumping)** — live status green dot, countdown ticking.
2. **Paused short (1h)** — yellow dot, "Paused 47min. Resumes 14:49." Snooze buttons become "Resume now."
3. **Paused today** — yellow dot, "Paused until tomorrow 10:00 UTC."
4. **Vacation through {date}** — orange dot, "Bumping resumes Sun May 26." Editable.
5. **Vacation until-i-say-so** — orange dot, "Bumping paused. Tap Resume to start again."
6. **Stopped (master off)** — grey dot, "Tryst bumping is off. Enable cadence above to start."
7. **Failure-state (after threshold)** — red dot, banner: "Tryst rejected the last 2 bumps. Re-auth or pause?" with linked re-auth flow per brief M §M2a.
8. **Newly added surface** (per L §L4 specialist onboarding) — banner: "First time bumping Tryst. I'll watch the first 24h carefully and surface anything weird."
9. **Editing cadence/window/days** — picker open; "Done" disabled until valid (e.g. From < To with wrap-handling).
10. **Conflict (vacation overlaps a declared tour)** — per brief H §H3 + brief K §K4 → top inline pill: "⚠ This vacation overlaps your Berlin tour (Oct 3–7). Resolve?" with link to tour calendar.

## Interactions / gestures

- **Tap "Pause 1h" / "Pause today"** → snooze fires immediately, status updates, audit row recorded. No confirmation needed for snooze (low-stakes per [brief F §F1](./00-system-visual-system.md)).
- **Tap "Stop"** → vacation-mode-on with confirmation (medium stakes — full pause is a bigger commitment).
- **Tap a Last-10 row** → audit-row-detail.screen.md.
- **Long-press the heading chip** → quick menu: "Move this policy to another specialist" / "Disable this surface entirely" / "Show all policies."
- **Swipe-down to dismiss** → standard iOS sheet dismiss; commits any pending edits.
- **VoiceOver** — reading order: heading → status → cadence → window → vacation → last 10 → failure config. Status line always first so screen readers communicate "what's happening right now" immediately.

## Edge cases

- **Active window crosses midnight** (e.g. 10:00–02:00) — picker handles wrap; status display shows "active until 02:00 tomorrow."
- **All days off** — surface becomes effectively stopped; status: "No active days. Bumping won't run." Subtle warning, not an error.
- **Cadence shorter than service rate-limit allows** (e.g. user picks 2h but Tryst's auto-cap is 4h) — status banner: "Tryst's rate limit suggests 4h minimum. I'll cap at 4h until you raise the cadence." Audit row records the cap.
- **Vacation-mode "Through: {date}"** date in past → input rejects + suggests today's date.
- **Multiple devices editing concurrently** — per brief M §M7: last-write-wins for atomic policy fields; if conflict detected at save, surface 3-way diff.
- **Reduced motion / Dynamic Type XXL** — buttons stack vertically when row would clip; status strip wraps.
- **Tryst auth expired** — top inline banner: "Re-auth required before next bump." Buttons + cadence remain editable (so Quinn can change config without auth).

## Related
- [Brief H §H1](./H-recurring-chores.brief.md) — the parent design pattern.
- [Brief M §M2a, §M3a](./M-error-degraded-modes.brief.md) — failure threshold, soft-degraded state.
- [Brief K §K4](./K-safety-blocklist.brief.md) — jurisdiction rules can auto-pause this policy on a tour stop.
- [Brief I](./I-audit-trust-replay.brief.md) — every cadence/window/vacation edit is an `agent_actions` row.
- [Brief L §L3 `bookings-tryst`](./specialist-bookings-tryst.contract.md) — the specialist that consumes this policy.
- [Brief F §F1](./00-system-visual-system.md) — stakes color dot semantics.
- [chat-home.screen.md](./chat-home.screen.md) — inline-strip variant of this policy.
- [audit-row-detail.screen.md](./audit-row-detail.screen.md) — what each Last-10 row opens to.

## Out of scope
- Per-prospect routing rules (different policy class; belongs in triage specialist drawer).
- Multi-account bumping on the same directory (deferred — see brief H §out-of-scope).
- Cross-policy correlation (e.g. "pause all bumps when I declare vacation everywhere") — handled at the vacation-mode-everywhere setting, not per-surface.