Carlos Florêncio
115 lines
4.9 KiB
Markdown
115 lines
4.9 KiB
Markdown
---
|
|
created: 2026-08-31
|
|
status: done
|
|
requirements:
|
|
- REQ-UI-COMMAND-PANEL-TASK-ACTIVITY-001
|
|
system_design:
|
|
- ../../specs/ui/system-design/command-panel-task-activity-icons.md
|
|
legacy_specs: []
|
|
---
|
|
|
|
# Implementation Plan: Keep Command Panel Workflow Steps Fresh
|
|
|
|
## Overview
|
|
|
|
Keep the workflow-step badge in an open command-panel task result aligned with
|
|
the same accepted live task projection that already drives the sidebar-parity
|
|
activity icon. A search response may contain an older `workflow_step_id` after
|
|
a task move, while the Kanban snapshot has the current placement. The result
|
|
row must use the current placement without requiring a new search.
|
|
|
|
The existing activity resolver already applies the timestamp guard that
|
|
rejects stale live projections. The implementation will expose its effective
|
|
workflow-step ID to the result row and remove the duplicate, HTTP-only badge
|
|
lookup.
|
|
|
|
## Scope
|
|
|
|
### In scope
|
|
|
|
- Reuse the accepted live placement for the command-panel workflow-step badge.
|
|
- Preserve the existing step name, color, layout, selection, and navigation
|
|
presentation.
|
|
- Keep the existing HTTP fallback when live data is absent or stale.
|
|
- Add component regression coverage for newer and stale live placements.
|
|
- Extend the existing desktop command-panel badge scenario and retain the
|
|
existing phone row coverage for mobile parity.
|
|
|
|
### Out of scope
|
|
|
|
- Backend, HTTP, or WebSocket contract changes.
|
|
- Changes to task search ranking, result limits, or navigation.
|
|
- Changes to badge presence, styling, responsive geometry, or touch targets.
|
|
- A second live-data freshness policy or a subscription to session-detail
|
|
streams.
|
|
|
|
## Technical approach
|
|
|
|
### Effective placement
|
|
|
|
- `apps/web/lib/commands/task-result-activity.ts`
|
|
(`TaskResultActivity`, `resolveTaskResultActivity`): return the effective
|
|
workflow-step ID selected from the accepted live projection, falling back to
|
|
`task.workflow_step_id` when the live projection is absent or rejected by
|
|
`currentLiveTask`.
|
|
- Keep the existing status-summary revision and task timestamp rules as the
|
|
only freshness decisions. Do not infer placement from activity or session
|
|
state.
|
|
|
|
### Result-row rendering
|
|
|
|
- `apps/web/components/command-panel-results.tsx` (`TaskResultItem`): resolve
|
|
activity before reading the step map, then use the effective step ID for the
|
|
existing badge name and color lookup.
|
|
- Keep `stepMap` ownership and the current behavior when a step definition is
|
|
not loaded. No API or store shape changes are needed.
|
|
|
|
### Regression coverage
|
|
|
|
- `apps/web/components/command-panel-task-activity.test.tsx`: add a failing
|
|
first test with an older HTTP step and a newer live step, then assert the
|
|
live step badge is shown. Add the inverse stale-live case to pin the
|
|
timestamp guard.
|
|
- `apps/web/e2e/tests/command-panel.spec.ts`: extend the existing inline task
|
|
search badge scenario to move the task through the API after the initial
|
|
result is available and assert the open result updates to the new step.
|
|
- `apps/web/e2e/tests/search/mobile-command-palette-scopes.spec.ts`: keep the
|
|
existing active-task row icon and title-width assertions as the mobile
|
|
composition/parity check; no new mobile layout is introduced.
|
|
|
|
## Tests
|
|
|
|
| Acceptance criteria | Evidence |
|
|
| --- | --- |
|
|
| `AC-UI-COMMAND-PANEL-TASK-ACTIVITY-001.4` | Component coverage proves an accepted live placement update is reflected without a new search. |
|
|
| `AC-UI-COMMAND-PANEL-TASK-ACTIVITY-001.5` | Component and desktop E2E coverage preserve the existing badge presentation and row behavior while changing only stale placement data. |
|
|
| `AC-UI-COMMAND-PANEL-TASK-ACTIVITY-001.6` | Existing phone E2E coverage continues to assert icon state, title width, and no horizontal overflow. |
|
|
| `AC-UI-COMMAND-PANEL-TASK-ACTIVITY-001.8` | Component coverage asserts newer live placement wins and stale live placement does not. Desktop E2E covers the live move flow. |
|
|
|
|
## E2E tests
|
|
|
|
Use the managed web runner for the existing desktop command-panel spec and
|
|
the existing mobile command-palette scope spec. The desktop test can use
|
|
`apiClient.listWorkflowSteps` to select a non-start step and
|
|
`apiClient.moveTask` to generate the live placement update.
|
|
|
|
## Work orders
|
|
|
|
- [x] [Task 01: Refresh workflow-step badges](task-01-refresh-workflow-step-badges.md)
|
|
|
|
## Verification results
|
|
|
|
Focused Vitest (28 tests), web typecheck, targeted ESLint, i18n validation,
|
|
desktop Chromium E2E (1 test), mobile Chrome E2E (1 test), specification lint,
|
|
and diff checks passed.
|
|
|
|
## Risks
|
|
|
|
- A live task projection without `updatedAt` follows the existing legacy
|
|
acceptance rule; changing that rule would regress live activity clears.
|
|
- The result row can only show a live step label when its step definition is
|
|
already present in the existing `stepMap`; broadening step loading is a
|
|
separate concern.
|
|
- The E2E move must wait for the command-panel result to receive the Kanban
|
|
update, not just for the move request to return.
|