feat: hydrate persisted PR details on task disclosure (#3055)

This commit is contained in:
Carlos Florêncio
2026-08-26 15:54:59 +00:00
committed by GitHub
parent 49dd944bd3
commit a6896bca9a
68 changed files with 1764 additions and 130 deletions
@@ -0,0 +1,180 @@
---
created: 2026-08-26
status: complete
requirements:
- REQ-UI-PR-TASK-STATUS-SUMMARY-001
system_design:
- ../../specs/ui/system-design/pr-task-status-summary.md
legacy_specs: []
---
# Implementation Plan: PR Task Status Hover Hydration
## Overview
Make every GitHub task PR indicator disclose details consistently. First add a
task-scoped hydration path for compact indicators. Then add the author identity
to the shared summary and the existing mobile drawer.
This order makes the data available before the presentation and end-to-end
work depends on it.
## Scope
### In scope
- Open a tooltip for compact GitHub PR indicators on mouse hover and keyboard
focus.
- Load persisted full PR records for only the disclosed task.
- Deduplicate concurrent loads, reuse store data, guard HTTP and WebSocket
races, and permit retry after an error.
- Preserve workspace ownership for live TaskPR updates. The browser must reject
missing or foreign workspace IDs, and typed backend events must route by their
owning workspace without falling back to a global broadcast.
- Show the GitHub author login in the task summary.
- Show the same author login in the existing coarse-pointer PR-status drawer.
- Add focused component, desktop Playwright, and mobile Playwright coverage.
### Out of scope
- Upstream GitHub refreshes from the task-row indicator.
- Workspace-wide PR loading for the sidebar.
- Changes to task-summary persistence or projection fields.
- New task-row touch targets, drawers, navigation, or provider associations.
- Author support for GitLab or registered provider summaries.
## Technical approach
### Task-scoped disclosure hydration
Add a hook under `hooks/domains/github` that uses `listTaskPRs([taskId])` when
`taskPRs.byTaskId[taskId]` is empty for the active workspace context. Scope the
in-flight registry to the Zustand store and key it by workspace, workspace
context generation, and task. Preserve deletion tombstones so a late response
cannot restore an association removed while it was pending.
Update `PRTaskIcon` and `TaskContributionIcons` so compact and full data use one
tooltip trigger. Compact content shows localized loading or unavailable text.
Successful data updates replace the content without unmounting the trigger or
closing the tooltip.
Before response application, compare the active workspace and current store
records. Preserve matching records that arrived from WebSocket events. Add only
missing PR identities from the HTTP result.
### Workspace-scoped live PR updates
Treat `TaskPR.workspace_id` as the authoritative owner of a live update. The
frontend handler applies an update only when that ID is present and matches the
active workspace, preserving the current scoped cache for missing or foreign
payloads. The backend exposes `TaskPR.WorkspaceID` to the notification
broadcaster and routes typed PR updates and detachments through the fail-closed
workspace path when authentication is enforced, so an unattributed event is
dropped instead of broadcast globally.
### Author presentation
Add optional author data to `ChangeRequestTaskStatusSummaryData`. Derive the
value from `TaskPR.author_login` and show localized `task:byAuthor` copy below
the title.
Extend `ChangeRequestPopoverHeader` with an optional author value. Pass the
GitHub author from `PRCIPopover` so desktop status content and the existing
mobile drawer use the same text.
### Localization
Add localized loading and unavailable copy to the GitHub namespace in English,
Portuguese, Simplified Chinese, Hong Kong Chinese, and Taiwan Chinese. Reuse
the existing localized `task:byAuthor` key for author presentation.
## Tests
| Acceptance criteria | Evidence |
| --- | --- |
| `AC-UI-PR-TASK-STATUS-SUMMARY-001.13` to `.16` | A new hydration-hook test covers task scope, one in-flight request, cache reuse, workspace and task-context changes, deletion during an HTTP request, empty/error retry, and HTTP/WS ordering. Render tests cover mouse and keyboard disclosure states, including focus continuity. |
| `AC-UI-PR-TASK-STATUS-SUMMARY-001.17` | Summary derivation and shared render tests cover a present and missing author login. |
| Existing `.1` to `.12` | Existing PR icon and shared summary suites remain green. |
| `AC-UI-PR-TASK-STATUS-SUMMARY-001.18` | Existing status-chip component tests and mobile Playwright coverage prove drawer author visibility and unchanged task-row navigation. |
| `AC-UI-PR-TASK-STATUS-SUMMARY-001.19` | `github.test.ts` proves missing and foreign live updates leave the active scoped cache unchanged; `task_notifications_test.go` proves typed events reach only the owning workspace and unattributed events are dropped when auth is enforced; the singleton panel test preserves taskPR scope metadata during task switching. |
## E2E tests
- `apps/web/e2e/tests/pr/pr-sidebar-hover-hydration.spec.ts` uses the `chromium`
project. It opens an unrelated task, hovers an inactive task PR indicator,
observes the task-scoped request, and checks the author and structured rows.
- `apps/web/e2e/tests/task/mobile-task-status-summary.spec.ts` uses the
`mobile-chrome` project. It taps the row, opens the current PR-status drawer,
checks the author, and checks for horizontal overflow.
## Mobile design contract
- **Desktop outcome:** Hover or keyboard focus opens and hydrates the PR task
summary.
- **Mobile entry:** The task row remains the entry point. The user opens the
task and then uses the existing PR-status chip.
- **Exemplars:** `session-task-switcher-sheet.tsx` owns task navigation.
`pr-status-chip.tsx` owns the coarse-pointer drawer.
- **Hierarchy:** The task row stays primary. The PR author is secondary content
below the title in the existing drawer.
- **Presentation:** Reuse the inset PR-status drawer. Do not add another drawer
or a compact icon hit target.
- **Scroll and geometry:** Keep the drawer's existing internal scroll owner,
safe-area behavior, and viewport containment.
- **Shared state:** Desktop and mobile read the same `TaskPR.author_login`.
- **Proof:** The mobile Playwright scenario checks navigation, drawer content,
and horizontal containment.
## Work orders
- [x] [Task 01: Hydrate PR details on disclosure](task-01-hydrate-pr-details-on-disclosure.md)
- [x] [Task 02: Show PR author identity](task-02-show-pr-author-identity.md)
Task 02 depends on Task 01. The work orders are sequential and do not authorize
subagents.
## Verification results
- Focused web unit suite: 163 tests passed across 10 files after the review
fixup, including the workspace-context generation regression test.
- Web typecheck passed.
- Web i18n check and ratchet passed.
- Full web lint passed.
- Desktop Playwright hydration scenario passed, including task-scoped request
deduplication, structured details, author identity, and cache reuse.
- Mobile Chrome Playwright scenario passed, including task navigation, the
existing PR drawer, author identity, and horizontal containment.
- Web E2E build passed.
- Fresh desktop and mobile captures were generated, inspected, compressed,
and validated through `apps/web/.pr-assets/manifest.json`.
- The repository-wide E2E sleep-policy lint remains baseline-red with 188
unrelated errors. Both changed E2E files pass the same lint directly.
- PR review fixup coverage also verifies task-id and workspace-context races,
deletion tombstones, and keyboard focus continuity during hydration.
- Workspace-routing review fixup on 2026-08-26 added the `workspace_id` frontend
contract, missing/foreign event guards, typed backend workspace extraction, and
fail-closed notification tests. The focused frontend suite passed 95 tests
across 6 files and the backend gateway/GitHub suites passed 2,176 tests. The
full frontend Vitest run was stopped after the requested 15-minute local
window without a failure result or terminal summary; the PR checks remain the
authoritative broad-suite validation.
## Documentation impact
No public documentation change is required. This package updates the durable UI
requirement and adds its system design.
## Risks
- A late HTTP result can replace newer WebSocket data unless current store
identities win during response application.
- One hook instance per row can produce duplicate requests unless the in-flight
registry is scoped above each component.
- A request that starts on pointer entry can finish after pointer leave. The
result must remain cached without reopening the tooltip.
- Radix can keep hidden tooltip portals mounted. E2E locators must target the
active tooltip content.
- Adding author text can increase summary height and can wrap in translated
layouts. Desktop and mobile tests must retain viewport containment.
- A missing or mismatched workspace ID must never be replaced with the active
workspace or reach a global notification broadcast.
@@ -0,0 +1,115 @@
---
id: "01-hydrate-pr-details-on-disclosure"
title: "Hydrate PR details on disclosure"
status: done
wave: 1
depends_on: []
plan: "plan.md"
requirements:
- REQ-UI-PR-TASK-STATUS-SUMMARY-001
acceptance_criteria:
- AC-UI-PR-TASK-STATUS-SUMMARY-001.1
- AC-UI-PR-TASK-STATUS-SUMMARY-001.13
- AC-UI-PR-TASK-STATUS-SUMMARY-001.14
- AC-UI-PR-TASK-STATUS-SUMMARY-001.15
- AC-UI-PR-TASK-STATUS-SUMMARY-001.16
system_design:
- ../../specs/ui/system-design/pr-task-status-summary.md
---
# Task 01: Hydrate PR Details on Disclosure
## Summary
Give compact GitHub PR indicators the same tooltip trigger as full indicators.
Load stored full PR records for only the disclosed task and keep the result in
the existing store.
## In scope
- Add a task-scoped hydration hook with store-scoped request deduplication.
- Guard workspace and workspace-context changes, preserve matching WebSocket
store records, and honor deletion tombstones.
- Treat `TaskPR.workspace_id` as authoritative for live updates. Ignore missing
or foreign browser payloads and route typed backend events through the
fail-closed workspace broadcaster when authentication is enforced.
- Render compact loading and unavailable tooltip content.
- Start the load on mouse pointer entry or visible keyboard focus.
- Add localized loading and unavailable copy in all required locales.
## Out of scope
- Author presentation.
- Upstream GitHub refreshes.
- Workspace-wide PR hydration.
- Backend, persistence, or task-summary changes.
## Acceptance
- A compact indicator opens immediately and becomes a full summary after one
task-scoped request.
- Concurrent disclosure requests share one request, and loaded store data
prevents another request.
- Empty, failed, stale-workspace, and WebSocket-before-HTTP paths preserve safe
state and permit a later retry.
- A missing or mismatched workspace ID in a live TaskPR update leaves the active
scoped cache unchanged, and an unattributed typed backend event cannot fan out
across workspace owners when authentication is enforced.
## Verification
```bash
(cd apps && pnpm install --frozen-lockfile)
(cd apps && pnpm --filter @kandev/web exec vitest run hooks/domains/github/use-task-pr-tooltip-hydration.test.tsx components/github/pr-task-icon.render.test.tsx components/task/task-item.test.tsx)
(cd apps/web && pnpm run typecheck)
(cd apps && pnpm --filter @kandev/web run i18n:check)
(cd apps && pnpm --filter @kandev/web run i18n:ratchet)
```
## Files likely touched
- `apps/web/hooks/domains/github/use-task-pr-tooltip-hydration.ts`
- `apps/web/hooks/domains/github/use-task-pr-tooltip-hydration.test.tsx`
- `apps/web/components/github/pr-task-icon.tsx`
- `apps/web/components/github/pr-task-icon.render.test.tsx`
- `apps/web/components/task/task-contribution-icons.tsx`
- `apps/web/components/task/task-item.test.tsx`
- `apps/web/src/locales/*/github.json`
## Dependencies
None.
## Risks
- HTTP hydration and WebSocket updates can arrive in either order.
- Local component state alone cannot deduplicate several mounted task surfaces.
- Pointer leave must not cancel useful store hydration.
## Parallelism
`sequential`
## Inputs
- Requirement criteria `.1` and `.13` to `.16`.
- The disclosure data flow and failure sections in the system design.
- `RegisteredChangeRequestTaskIcon` as the on-open refresh pattern.
## Results
- Added task-scoped compact PR hydration with store-scoped request
deduplication, settled-cache reuse, workspace race protection, WebSocket
precedence, and retryable empty or failed states.
- Added localized loading and unavailable tooltip states in all required
locales.
- Added pointer and keyboard disclosure coverage plus focused hydration tests.
- Added task-id and workspace-context generation race coverage, plus protection
against resurrecting an association deleted while an HTTP request is pending.
- Focused unit tests, typecheck, i18n checks, ratchet, full web lint, desktop
E2E, mobile E2E, and the E2E build passed.
- The 2026-08-26 review fixup added frontend missing/foreign workspace event
coverage, backend typed-event routing and fail-closed coverage, and preserved
taskPR scope metadata in the singleton task-switch test. The focused frontend
suite passed 95 tests across 6 files and the backend gateway/GitHub suites
passed 2,176 tests.
@@ -0,0 +1,105 @@
---
id: "02-show-pr-author-identity"
title: "Show PR author identity"
status: done
wave: 2
depends_on:
- "01-hydrate-pr-details-on-disclosure"
plan: "plan.md"
requirements:
- REQ-UI-PR-TASK-STATUS-SUMMARY-001
acceptance_criteria:
- AC-UI-PR-TASK-STATUS-SUMMARY-001.2
- AC-UI-PR-TASK-STATUS-SUMMARY-001.7
- AC-UI-PR-TASK-STATUS-SUMMARY-001.8
- AC-UI-PR-TASK-STATUS-SUMMARY-001.17
- AC-UI-PR-TASK-STATUS-SUMMARY-001.18
system_design:
- ../../specs/ui/system-design/pr-task-status-summary.md
---
# Task 02: Show PR Author Identity
## Summary
Show the GitHub author login below the PR title in the task summary. Show the
same identity in the existing coarse-pointer PR-status drawer and prove both
user flows end to end.
## In scope
- Add optional author data to the shared task-summary presentation.
- Derive the author from `TaskPR.author_login` and omit empty values.
- Add optional author content to the shared change-request popover header.
- Pass the GitHub author into `PRCIPopover` for desktop and drawer content.
- Add desktop and mobile Playwright coverage.
## Out of scope
- GitLab and registered-provider author derivation.
- New mobile navigation or touch controls.
- Provider refresh, association, or persistence behavior.
## Acceptance
- The hydrated task tooltip shows the non-empty GitHub author below each PR
title and omits an empty author line.
- The existing mobile PR-status drawer shows the same author without changing
task-row tap behavior.
- Desktop and mobile surfaces remain inside their viewports and preserve the
existing structured status rows.
## Verification
```bash
(cd apps && pnpm --filter @kandev/web exec vitest run components/github/pr-task-status-summary.test.ts components/integrations/change-request-task-status-summary.test.tsx components/github/pr-ci-popover.test.ts components/github/pr-status-chip.test.tsx)
(cd apps/web && pnpm e2e:run tests/pr/pr-sidebar-hover-hydration.spec.ts)
(cd apps/web && pnpm e2e:run --project mobile-chrome tests/task/mobile-task-status-summary.spec.ts)
(cd apps/web && pnpm run typecheck)
```
## Files likely touched
- `apps/web/components/integrations/change-request-task-status-summary.tsx`
- `apps/web/components/integrations/change-request-task-status-summary.test.tsx`
- `apps/web/components/integrations/change-request-ci-anatomy.tsx`
- `apps/web/components/github/pr-task-status-summary.tsx`
- `apps/web/components/github/pr-task-status-summary.test.ts`
- `apps/web/components/github/pr-ci-popover.tsx`
- `apps/web/components/github/pr-ci-popover.test.ts`
- `apps/web/components/github/pr-status-chip.test.tsx`
- `apps/web/e2e/tests/pr/pr-sidebar-hover-hydration.spec.ts`
- `apps/web/e2e/tests/task/mobile-task-status-summary.spec.ts`
## Dependencies
- Task 01 must provide the compact-to-full disclosure path.
## Risks
- Shared optional author markup must not change providers that omit the value.
- Longer author identities can wrap and increase overlay height.
- Hidden Radix portals can make unscoped browser assertions ambiguous.
## Parallelism
`sequential`
## Inputs
- Requirement criteria `.2`, `.7`, `.8`, `.17`, and `.18`.
- Author presentation and mobile behavior in the system design.
- Existing task-summary, CI popover, status-chip drawer, and mobile sidebar
tests.
## Results
- Added optional GitHub author presentation below task-summary and CI-popover
titles, while omitting blank identities.
- Reused the existing mobile PR-status drawer and preserved task-row
navigation.
- Added summary, popover, drawer, desktop E2E, and mobile E2E coverage.
- Kept one mounted tooltip trigger across compact-to-full hydration so keyboard
focus and an open disclosure survive the store update.
- Focused unit tests, typecheck, full web lint, desktop E2E, mobile E2E, and the
E2E build passed.
+1
View File
@@ -160,6 +160,7 @@ contract that other capabilities can reuse.
- [Entity Reference Composer](system-design/entity-reference-composer.md)
- [Mobile Task Chrome](system-design/mobile-task-chrome.md)
- [Persistent status motion](system-design/persistent-status-motion.md)
- [PR Task Status Summary](system-design/pr-task-status-summary.md)
- [Prompt History Panel](system-design/prompt-history-panel.md)
- [Quick Chat and Terminal Tabs](system-design/quick-terminal.md)
- [Task Confirmation Warning Hierarchy](system-design/confirmation-warning-hierarchy.md)
@@ -2,6 +2,7 @@
status: active
system: ui
created: 2026-08-06
updated: 2026-08-26
owners:
- kandev
---
@@ -9,7 +10,9 @@ owners:
## Overview
Task pull-request indicators currently flatten the PR title, review state, CI state, and mergeability into one pipe-delimited sentence. Long titles and several adjacent status values make the hover disclosure slow to scan during a brief pointer interaction.
Task pull-request indicators show a compact structured summary of each linked
pull request. The indicator must also work when a task row initially has only
the bounded task-status projection and not the full pull-request record.
## Requirements
@@ -25,12 +28,19 @@ Task pull-request indicators currently flatten the PR title, review state, CI st
- **AC-UI-PR-TASK-STATUS-SUMMARY-001.4:** Known GitHub states use concise user-facing copy such as **Approved**, **Passed**, **In progress**, **Changes requested**, **Conflicts**, and **Ready to merge**. An unrecognized non-empty provider value remains visible instead of being dropped.
- **AC-UI-PR-TASK-STATUS-SUMMARY-001.5:** Ready-to-merge copy uses the existing strict `isPRReadyToMerge` rule. Draft, terminal, review, check, mergeability, aggregate icon color, and multi-PR attention precedence do not change.
- **AC-UI-PR-TASK-STATUS-SUMMARY-001.6:** A task with several linked PRs shows one consistently structured entry per PR, separated clearly, while retaining the existing aggregate icon color, PR count, and ready-to-merge attributes.
- **AC-UI-PR-TASK-STATUS-SUMMARY-001.7:** The disclosure uses localized copy, readable line height, restrained semantic colors, and a viewport-contained width. It remains informational: opening it does not navigate, mutate PR state, fetch new detail, or change task-row activation.
- **AC-UI-PR-TASK-STATUS-SUMMARY-001.7:** The disclosure uses localized copy, readable line height, restrained semantic colors, and a viewport-contained width. Opening it does not navigate, mutate PR state, refresh the provider, or change task-row activation.
- **AC-UI-PR-TASK-STATUS-SUMMARY-001.8:** The shared task PR indicator uses the same summary in the desktop sidebar, Kanban cards, and rich task-list rows.
- **AC-UI-PR-TASK-STATUS-SUMMARY-001.9:** All status entries in one summary share label, icon, and status-text columns so Review, CI, merge, and terminal values start at the same horizontal position.
- **AC-UI-PR-TASK-STATUS-SUMMARY-001.10:** Secondary detail, including merge-queue position and estimated merge time, starts under the status text instead of under the label or icon.
- **AC-UI-PR-TASK-STATUS-SUMMARY-001.11:** Shared columns adapt to translated labels and wrapped values without a fixed label width that clips content.
- **AC-UI-PR-TASK-STATUS-SUMMARY-001.12:** GitHub, GitLab, and registered change-request providers that use the shared summary component receive the same row alignment without changing provider-specific state derivation or copy.
- **AC-UI-PR-TASK-STATUS-SUMMARY-001.13:** When hover or keyboard focus opens a GitHub PR indicator with only compact task-summary data, the disclosure shall appear. The system shall load the stored PR records for that task.
- **AC-UI-PR-TASK-STATUS-SUMMARY-001.14:** While the task-scoped load is pending, the disclosure shall show a localized loading state. On success, it shall replace that state with the structured summary without another user action.
- **AC-UI-PR-TASK-STATUS-SUMMARY-001.15:** Repeated or concurrent disclosure requests for the same task shall share one in-flight load. Loaded store data shall prevent later disclosure requests from starting another load.
- **AC-UI-PR-TASK-STATUS-SUMMARY-001.16:** When the task-scoped load fails or returns no PR records, the disclosure shall show a localized unavailable state. A later disclosure shall retry the load.
- **AC-UI-PR-TASK-STATUS-SUMMARY-001.17:** Each GitHub PR summary shall show the non-empty PR author login below the PR title. A missing author login shall not create an empty label.
- **AC-UI-PR-TASK-STATUS-SUMMARY-001.18:** On a coarse pointer, the task row shall remain the primary touch target. After task navigation, the existing PR-status drawer shall show the same author login.
- **AC-UI-PR-TASK-STATUS-SUMMARY-001.19:** TaskPR API and WebSocket payloads shall carry the owning workspace ID. The backend shall route typed PR events by that ID, and the frontend shall ignore missing or mismatched updates before changing the active workspace cache.
## Migrated source detail
@@ -68,8 +78,12 @@ do not align, and secondary merge-queue text begins under the icon instead of th
- A task with several linked PRs shows one consistently structured entry per PR, separated clearly,
while retaining the existing aggregate icon color, PR count, and ready-to-merge attributes.
- The disclosure uses localized copy, readable line height, restrained semantic colors, and a
viewport-contained width. It remains informational: opening it does not navigate, mutate PR
state, fetch new detail, or change task-row activation.
viewport-contained width. It remains informational and does not mutate provider state.
- If the browser has only compact task-summary data, hover or keyboard focus loads the stored PR
records for that task. The disclosure shows loading and unavailable states without closing.
- Repeated requests for the same task share one in-flight load. Loaded task-store data prevents
another load.
- Each GitHub PR entry shows its non-empty author login below the title.
- The shared task PR indicator uses the same summary in the desktop sidebar, Kanban cards, and rich
task-list rows.
- GitHub, GitLab, and registered change-request providers that use the shared summary component get
@@ -103,13 +117,22 @@ do not align, and secondary merge-queue text begins under the icon instead of th
**THEN** that detail starts under **Awaiting checks** and wraps within the status column.
- **GIVEN** translated row labels have different lengths, **WHEN** the summary renders, **THEN** the
longest available label defines the shared label column and no label or status is clipped.
- **GIVEN** a task row has only compact PR status, **WHEN** a fine pointer hovers the PR indicator
or keyboard focus reaches it, **THEN** a loading disclosure opens and then shows the full stored
PR summary without another user action.
- **GIVEN** two mounted surfaces request the same task PR details, **WHEN** their requests overlap,
**THEN** they share one in-flight load and preserve newer store data that arrives first.
- **GIVEN** a stored PR has an author login, **WHEN** the task summary or mobile PR-status drawer
opens, **THEN** the author login appears below the PR title.
- **GIVEN** a phone task-switcher drawer, **WHEN** a linked-PR task row renders and the user taps
the row, **THEN** the existing task navigation and PR indicator remain usable without horizontal
overflow or a new hover-dependent interaction.
## Out of scope
- Changing polling, API contracts, persistence, or task-to-change-request associations.
- Changing provider polling, persistence, or task-to-change-request associations.
- Refreshing GitHub when the task-row disclosure opens.
- Loading all workspace PR records to satisfy one task-row disclosure.
- Adding check-run lists, reviewer lists, comments, merge controls, or other full PR-detail content
to the task indicator summary.
- Changing GitHub, GitLab, or registered-provider status derivation, icon precedence, or copy.
@@ -121,3 +144,5 @@ do not align, and secondary merge-queue text begins under the icon instead of th
[PR task status summary plan](../../../plans/pr-task-status-summary/plan.md)
[Sidebar task row presentation refinement](../../../plans/sidebar-task-row-presentation/plan.md)
[PR task status hover hydration](../../../plans/pr-task-status-hover-hydration/plan.md)
@@ -0,0 +1,160 @@
---
status: draft
system: ui
requirements:
- REQ-UI-PR-TASK-STATUS-SUMMARY-001
---
# PR Task Status Summary System Design
## Purpose and boundaries
The UI system owns the shared task-indicator disclosure. The disclosure is used
by the sidebar, Kanban cards, and rich task lists.
The task status projection remains the bounded source for inactive task rows.
The GitHub integration remains the source for stored `TaskPR` records. This
design does not add full PR records to `TaskStatusSummary`.
## Requirement mapping
| Requirement | Design sections |
| --- | --- |
| `REQ-UI-PR-TASK-STATUS-SUMMARY-001` | [Disclosure data flow](#disclosure-data-flow), [Author presentation](#author-presentation), [Mobile behavior](#mobile-behavior), [Failure and recovery](#failure-and-recovery) |
## Current data split
`TaskStatusSummary.pull_request` gives every task row compact PR data. The
frontend maps this data to `prInfo`, which contains the PR number, state, and
aggregate state.
`taskPRs.byTaskId` contains full `TaskPR` records. These records contain the
title, `author_login`, review state, CI state, and merge state. The cache also
records the workspace and workspace-context generation that owns its rows, so
task-detail surfaces cannot reuse records from an earlier context. Some routes
load all workspace records, while task-detail surfaces load records for the
active task.
The current fallback indicator uses `prInfo` without a tooltip. The full-data
indicator uses `PRTaskIcon` with `PRTaskStatusSummary`. This split causes the
inconsistent behavior.
## Components and responsibilities
- `TaskContributionIcons` passes compact `prInfo` to the GitHub task indicator.
- `PRTaskIcon` owns one visual trigger for compact, loading, unavailable, and
full-data states.
- A task-scoped hydration hook reads the current workspace-scoped
`taskPRs.byTaskId` entry and uses `listTaskPRs([taskId])` only when full data
is absent.
- `useChangeRequestTaskTooltipState` opens on a mouse pointer or visible
keyboard focus. Its `onOpen` callback starts hydration.
- `PRTaskStatusSummary` derives GitHub presentation data from each `TaskPR`.
- `ChangeRequestTaskStatusSummary` renders the shared summary structure and an
optional author identity.
- `PRCIPopover` and `PRStatusChipDrawer` provide the existing detailed touch
path after the user opens a task.
## Data and contracts
The design uses the existing `GET /api/v1/github/task-prs?task_ids=<id>`
endpoint. This endpoint returns persisted task associations. It does not start
the workspace-wide stale-record refresh.
The frontend store remains the cache. A successful load adds each returned
`TaskPR` through the existing store action. The client-only cache metadata
tracks workspace context and association deletion tombstones; the
implementation adds no database field, task-summary field, or public API.
Every `TaskPR` API and WebSocket payload includes its owning `workspace_id`.
The backend exposes that identity to the WebSocket broadcaster for typed
in-process events and routes PR updates and detachments through the
fail-closed workspace path when authentication is enforced. The frontend
applies an update only when its workspace ID matches the active workspace;
missing or mismatched updates are ignored before the cache changes.
`ChangeRequestTaskStatusSummaryData` gains an optional `author` value. GitHub
sets this value from `TaskPR.author_login`. Other providers can omit it.
## Disclosure data flow
1. The task row renders the compact PR indicator from `prInfo`.
2. A mouse pointer enters the indicator, or keyboard focus becomes visible.
3. The tooltip opens immediately and shows the PR identity with a loading state.
4. The hydration hook checks the current workspace-scoped
`taskPRs.byTaskId` entry again. It stops if full data is available.
5. The hook acquires one in-flight request for the active store, workspace,
workspace-context generation, and task. Other mounted indicators reuse that
request.
6. The response is ignored after a workspace or task context change. Existing
store records win over matching response records, and deletion tombstones
prevent a late response from resurrecting an association. New response
identities can fill missing multi-PR siblings.
7. The full store data replaces the loading content while the tooltip remains
open.
The in-flight registry is scoped to the Zustand store instance. It removes a
request after settlement. The store is the only settled cache.
## Author presentation
The structured task summary shows `task:byAuthor` below the PR title when
`author_login` is non-empty. The author line uses normal text, so its meaning
does not depend on color or an icon.
The GitHub CI popover header receives the same optional author. This header is
shared by the desktop status popover and the coarse-pointer PR-status drawer.
## Failure and recovery
The tooltip does not show a toast for a passive disclosure error. It shows a
localized unavailable state and keeps the compact PR identity visible.
An error or empty response removes the in-flight entry. A later hover or focus
starts another request. Pointer leave does not cancel a request because the
result remains useful to other task surfaces.
HTTP responses cannot replace a matching store record that arrived through a
newer WebSocket path. A workspace or workspace-context change prevents response
application, and a deletion tombstone prevents a late HTTP row from restoring a
removed association.
## Accessibility
The compact fallback and full indicator use the same focusable semantic
trigger. The trigger remains mounted while compact content changes to the full
summary, so keyboard focus and an open tooltip survive hydration. Keyboard
focus starts the same load as mouse hover. Escape dismisses the tooltip, and
later focus can open it again.
Loading and unavailable content uses localized text. The author identity is
part of the visible summary and the accessible content.
## Mobile behavior
The compact task-row indicator remains passive on coarse pointers. The task row
keeps its existing primary navigation action and touch geometry.
After navigation, the existing `PRStatusChipDrawer` is the author-detail entry
point. The drawer keeps its current safe-area handling and internal scroll
owner. Its PR content shows the author below the title.
The closest shipped mobile surfaces are
`session-task-switcher-sheet.tsx` for task navigation and
`pr-status-chip.tsx` for the coarse-pointer drawer.
## Tests
Unit and component tests cover request deduplication, cache reuse, workspace
and task-context changes, WebSocket-before-HTTP races, deletion tombstones,
retry behavior, keyboard-focus continuity, and author omission.
Desktop Playwright coverage starts on an unrelated task detail route. It opens
an inactive task indicator that initially has only compact summary data.
Mobile Playwright coverage taps the inactive task row, opens the existing
PR-status drawer, and checks the author identity and page containment.
## Related designs
- [Bounded Task Status Delivery](../../platform/system-design/bounded-task-status-delivery.md)