From 56606e1d166405d289ddd558f1380b2c1419ca60 Mon Sep 17 00:00:00 2001 From: Dotta Date: Fri, 7 Aug 2026 16:13:03 +0000 Subject: [PATCH] docs(runner): reconcile resume-line order and add happy-path screenshot UX review PAP-16714 findings applied: - Resume line now normatively precedes the response control (UX doc 2.3), matching OPX-4/OPX-F3 DOM-order gates and the doc's own acceptance criterion 4; the PAP-16712 mockup footer placement is noted as non-normative. - 18.12.13 screenshot matrix gains the accepted happy path (completion_contract_satisfied -> Done, four layers in agreement). Co-Authored-By: Paperclip --- .../spec/paperclip-native-runner-spike-spec.md | 9 ++++++--- .../spec/paperclip-runner-status-attention-ux.md | 4 ++-- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/packages/paperclip-runner/spec/paperclip-native-runner-spike-spec.md b/packages/paperclip-runner/spec/paperclip-native-runner-spike-spec.md index 638b78b353f..2701a1f6353 100644 --- a/packages/paperclip-runner/spec/paperclip-native-runner-spike-spec.md +++ b/packages/paperclip-runner/spec/paperclip-native-runner-spike-spec.md @@ -4855,9 +4855,12 @@ copy law of `[OPX-2]`. A new reason code, component field, or gate that breaks any of those relationships fails the check before it can reach a UI surface. Screenshot matrix (adds to section 23.10, all at 1440×900 desktop; mobile is -deferred by the source ticket): flows A–E of the UX document, the board row with -each chip, the properties panel rows, the legacy-run ledger, the expired and -exhausted attention states, and the superseded-decision chain. The artifact +deferred by the source ticket): the accepted happy path +(`completion_contract_satisfied` applied, issue moved to Done, all four layers +in agreement — the state where a claim chip sits next to a green badge and the +layers must still read separately), flows A–E of the UX document, the board row +with each chip, the properties panel rows, the legacy-run ledger, the expired +and exhausted attention states, and the superseded-decision chain. The artifact index names the fixture, the flow, the reason code, the route, and the gate it satisfies. diff --git a/packages/paperclip-runner/spec/paperclip-runner-status-attention-ux.md b/packages/paperclip-runner/spec/paperclip-runner-status-attention-ux.md index 13372ac1859..5127d3ad50e 100644 --- a/packages/paperclip-runner/spec/paperclip-runner-status-attention-ux.md +++ b/packages/paperclip-runner/spec/paperclip-runner-status-attention-ux.md @@ -78,8 +78,8 @@ Anatomy top-to-bottom: - **Scope** — "blocks this turn only" / "blocks one track" / "blocks the whole task". When narrowed, strike the claim: `~~task-wide~~ → this turn` with the alternate live track linked. - **Attempts** — "attempt 2 of 6" from `AttentionResolutionBudget` (spec §18.3.3); expandable route history (context ✓ → retry ✗ → agent…) so a human landing here sees escalation was earned, not first-resort. - **Expiry** — relative countdown "expires in 3h 40m"; switches to amber text under 25% remaining; the expired state renders the card inert with "expired unanswered · one fallback wake sent". -3. **Response affordance** — only for `route: board` + state `pending/routed`: the existing typed interaction control (`AttentionInteractionResolver`) — answer / choose / approve / decline. All other routes render read-only. -4. **Resume line (footer, always present):** the exact consequence of responding, generated from the response binding (spec §18.3.6): "*Answering wakes UXDesigner and resumes this turn*" / "*Answer recorded; UXDesigner wakes on its next scheduled turn*" / "*Recorded for audit only — this request was superseded*". Fitts/forgiveness: the operator knows what the button fires before pressing it. +3. **Resume line (always present, directly above the response control):** the exact consequence of responding, generated from the response binding (spec §18.3.6): "*Answering wakes UXDesigner and resumes this turn*" / "*Answer recorded; UXDesigner wakes on its next scheduled turn*" / "*Recorded for audit only — this request was superseded*". Fitts/forgiveness: the operator knows what the button fires before pressing it — which is why it precedes the control in DOM order (spec §18.12 `[OPX-4]`/OPX-F3; sequential reading order for screen-reader users, who must hear the consequence before reaching the button). The PAP-16712 mockups draw this line as a card footer; this list's order is normative, not the mockup. +4. **Response affordance** — only for `route: board` + state `pending/routed`: the existing typed interaction control (`AttentionInteractionResolver`) — answer / choose / approve / decline. All other routes render read-only. ### 2.4 Extensions to existing components