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

approval-card.screen

Single-screen breakdown for the approval card — the centerpiece of the supervised-autonomy contract. Appears inline in chat (brief A), in pending-approvals inbox (brief A §10 overflow), as a full-screen sheet on long-press, and as the multi-surface variant (brief H §H4). Voice register: working (brief voice §V2b).

Layout (inline + full-screen-sheet variants)

┌─────────────────────────────────────────────────┐
│ ┃ ▢ New about-me for Tryst              ⋯ menu │ ┃ = stakes color band (4pt left edge)
│ ┃                                              │   (F §F1: low neutral, medium amber, high rose)
│ ┃ [Tryst] [profile-copy] · medium · 0.78      │   surface chip + kind chip + stakes + confidence
│ ┃                                              │
│ ┃ ─── Current ───                              │
│ ┃ "Professional, discreet companion based      │   diff: current (muted)
│ ┃  in the Bay Area…"                           │
│ ┃                                              │
│ ┃ ─── Proposed ───                             │
│ ┃ "Independent escort based in the Bay Area.   │   diff: proposed (emphasized)
│ ┃  Trans, femme, real, no rush."               │
│ ┃                                              │
│ ┃ Why: "corporate" line removed at your        │   one-line rationale ("why" affordance)
│ ┃ request 3 weeks ago. Voice register holds.   │
│ ┃                                              │
│ ┃ [ Edit ] [ Set aside ] [ Approve ]          │   3 actions, right-aligned, primary = Approve
└─────────────────────────────────────────────────┘

Full-screen sheet variant uses the same skeleton but expanded: scrollable body, persistent header, fixed action bar at the bottom safe-area.

Components

Component	Notes
Stakes color band	4pt left edge, color per F §F1 (low/medium/high). Persistent visual cue.
Header row	Title + overflow menu (⋯). Menu: "see full reasoning", "talk to {specialist}", "report this draft", "show me what was blocked" (if K phrase-blocklist fired and content was re-drafted).
Chip row	Surface chip (per F §F5 iconography), action-kind chip, stakes label, confidence value (0.00–1.00).
Body	Polymorphic per kind: text diff for profile-copy, list for tour multi-surface, image-grid for content-post, reservation/booking detail card for booking. See variants below.
"Why" line	One-sentence rationale + tappable to expand into CoT brief (the 6-step ported from v2 per brief J).
Action bar	Edit / Set aside / Approve. Approve is primary (filled). Set aside moves to pending-approvals drawer. Edit opens compose sheet with proposed text.

States

1. Pending (default) — fresh card, all three actions live, no animation.
2. Editing — Edit tapped; compose sheet over card with proposed text editable. Approve becomes "Approve edit." Cancel restores card.
3. Approving (transient) — Approve tapped; card animates off (right-slide), success haptic, replaced by receipt bubble per chat-home.screen.md.
4. Approved (sticky for 30s, undo window) — receipt bubble with "↶ undo" — tapping reverts the action and restores the card.
5. Set aside — card slides into pending-approvals drawer; minimal toast.
6. Declined — long-press → "Decline with reason" sheet. Adds row to brief I audit with state=declined.
7. Edited-then-approved — same as Approved state but receipt explicitly notes "edited" with one-line edit summary.
8. Failed to commit — per brief M §M2 / §M7: card reappears with a red badge + "failed: {short reason}", retry / view-reason affordances. Recovers the 3-action bar.
9. Stakes-elevated — when K phrase-blocklist or coop intel (brief N) flags the subject, the stakes color band auto-elevates one tier with a chip explaining why.
10. Multi-surface variant (brief H §H4) — per-surface row list inside the body; each row has its own surface chip + per-surface preview + checkbox. Approve fans out; in-flight shows per-row spinners; post shows per-row ✓/✗.
11. Disputed / contested — when M §M7 conflict resolution applies, the body collapses into a 3-way diff (current / yours / theirs); action bar replaced by "pick a version" buttons.
12. Specialist-degraded — per L §L4 + M §M2a: header shows degraded badge ("content-x is offline"); Approve disabled, Set aside live.

Variant body layouts

• profile-copy — two-pane diff (Current vs Proposed), mobile-narrow stacks vertically.
• tour (multi-surface H §H4) — header city/dates; per-surface checklist; per-surface preview is a 2-line excerpt.
• content-post — image-grid preview (max 4 thumbnails) + caption text below; tap image expands.
• reservation / booking — line items list with prices/times; flagged-if-conflict against calendar.
• grocery (carry-over from the HTML canvas; if grocery use-case is ever wired, this is the form) — cart list with qty steppers + total.
• engagement-reply — thread context excerpt + proposed reply + tone hint.

Interactions / gestures

• Right-swipe → Approve (with haptic threshold per F §F4).
• Left-swipe → Set aside.
• Long-press → full-screen sheet variant; the same card with more breathing room + the CoT brief expanded by default.
• Two-finger swipe down → minimize-to-inbox (moves to pending-approvals without committing decline).
• Tap "Why" line → expand the CoT brief in place.
• Tap "approved" undo → revert + restore card. 30s window per F §F4 motion spec.
• Pinch-out on diff → opens full-screen 3-way diff view.

Edge cases

• Card arrives as part of a multi-message turn coalesce (A §state 2b) → the card is one of N from a single debounced turn; renders in a tight stack with siblings; header gains a "from your last 3 messages" footnote referencing the coalesced turn. The N cards share a single turn_id for audit linkage (brief I §I3 row-detail will surface the turn).
• Card stale (>24h since draft) → header gets "drafted Tue 3pm" timestamp + a gentle warning ("Cocotte's data is stale — re-draft before approving?") with a single tap to re-draft.
• Confidence below threshold (e.g. 0.45 for high-stakes) → Approve button disabled; Edit-then-approve or "ask Cocotte to try again" prominent.
• Auto-action receipt vs approval card — these look related but are visually distinct: receipts have NO action bar and NO stakes band; they're past tense. Don't conflate.
• Approval card that targets a blocked subject (brief K) → card never shows; the relevant specialist filters at draft time. If somehow surfaced, replace with a K-violation explainer.
• VoiceOver reading order — header → stakes/confidence → "Why" line first → body → actions last. Most-important-context-first.
• Reduced motion — replace swipe-off animation with crossfade.
• Dynamic Type XXL — action bar wraps to 2 rows (Approve full-width on top, Edit/Set-aside side-by-side below).

Related

• Brief A §approval — surface integration.
• Brief H §H4 — multi-surface variant.
• Brief I §3 — what an approved/declined card becomes in the audit.
• Brief F §F1, §F4 — stakes color band, swipe haptics.
• Brief J §6-step CoT — the "Why" expansion text source.
• 00-system/voice.md §V2b — copy register for action bar + body text.

Out of scope

• Animation timing curves (in F §F4).
• The compose sheet that opens on Edit (its own screen.md if it grows beyond a textarea).
• Approval cards on iPad / Mac / web (brief E + G secondary surfaces; pattern reuses, layout adapts).