feat(web): warn about workflow replay cycles (#1720)
This commit is contained in:
@@ -0,0 +1,277 @@
|
||||
---
|
||||
spec: docs/specs/workflow-cycle-guardrails/spec.md
|
||||
created: 2026-07-15
|
||||
status: complete
|
||||
---
|
||||
|
||||
# Implementation Plan: Workflow Cycle Guardrails
|
||||
|
||||
## Overview
|
||||
|
||||
Add a deterministic frontend graph analyzer first, then place a shared mutation
|
||||
guard in the workflow card so both draft creation and existing immediate step
|
||||
mutations use the same proposed-shape decision. Build the trace UI on that
|
||||
contract and finish with desktop and mobile Playwright coverage. The existing
|
||||
workflow HTTP contracts and runtime engine remain unchanged.
|
||||
|
||||
---
|
||||
|
||||
## Backend
|
||||
|
||||
No backend changes are planned. The feature is an authoring-time guard over the
|
||||
complete client-visible `WorkflowStep[]`; it intentionally does not make replay
|
||||
cycles a persistence invariant or alter `POST /api/v1/workflow/steps`,
|
||||
`PUT /api/v1/workflow/steps/:id`, step deletion/reorder, or workflow import.
|
||||
|
||||
Relevant contracts verified during planning:
|
||||
|
||||
- `apps/backend/internal/workflow/models/models.go` defines `on_enter`,
|
||||
`on_turn_start`, and `on_turn_complete` action semantics.
|
||||
- `apps/backend/internal/workflow/engine/types.go` resolves the same three move
|
||||
action kinds and applies first-eligible-transition behavior.
|
||||
- `apps/backend/internal/orchestrator/event_handlers_workflow.go` confirms that
|
||||
`on_turn_start` is user-message driven and an entered `auto_start_agent` step
|
||||
starts the workflow prompt.
|
||||
- `apps/backend/internal/orchestrator/task_operations.go` defines the three
|
||||
prompt-source cases that the diagnostic describes.
|
||||
|
||||
---
|
||||
|
||||
## Frontend
|
||||
|
||||
### Replay-cycle analyzer
|
||||
|
||||
Files:
|
||||
|
||||
- `apps/web/lib/workflows/replay-cycle-analysis.ts` (new)
|
||||
- `apps/web/lib/workflows/replay-cycle-analysis.test.ts` (new)
|
||||
|
||||
Changes:
|
||||
|
||||
- Add `analyzeWorkflowReplayCycles(steps: WorkflowStep[])` and exported
|
||||
diagnostic/trace types matching the spec's Analysis Contract.
|
||||
- Normalize order by `position`, resolve `move_to_next`,
|
||||
`move_to_previous`, and valid `move_to_step` targets for both kanban
|
||||
triggers, and find paths that return to each `on_enter.auto_start_agent`
|
||||
step through an `on_turn_complete` replay edge. Treat `on_turn_start` entry
|
||||
into an auto-start step as safe because the runtime skips destination
|
||||
`on_enter` while dispatching the user's message.
|
||||
- Classify a hop as automatic when its source auto-starts on entry and the
|
||||
transition does not require approval. This includes `on_turn_start`
|
||||
transitions fired by an auto-started prompt. A cycle is blocking only when
|
||||
all of its hops are automatic.
|
||||
- Produce stable diagnostic identities, affected step IDs, a deterministic
|
||||
highest-severity/shortest trace per auto-start step, and the prompt-source
|
||||
category.
|
||||
- Ignore unresolved targets and cycles without an auto-start re-entry.
|
||||
|
||||
### Proposed-shape mutation guard
|
||||
|
||||
Files:
|
||||
|
||||
- `apps/web/components/settings/workflow-card-actions.ts`
|
||||
- `apps/web/components/settings/workflow-card-actions.test.ts`
|
||||
- `apps/web/components/settings/workflow-card.tsx`
|
||||
|
||||
Changes:
|
||||
|
||||
- Introduce a workflow-card guard state that compares analyzer diagnostics for
|
||||
the current server-backed shape and a proposed shape.
|
||||
- Route existing step update, add, remove, and reorder handlers through a
|
||||
single guard before their current API call. Build proposed arrays with the
|
||||
same step update/start-step demotion, add, delete/reindex, and reorder
|
||||
semantics already used by the handlers.
|
||||
- For a new draft, run the guard in `handleSaveWorkflow` before
|
||||
`createWorkflowAction` so cancellation sends neither the workflow create nor
|
||||
any follow-up step mutations.
|
||||
- Hold one pending user-mediated operation until confirmation; execute it once
|
||||
on **Apply anyway** or **Create anyway**, and discard it on cancel.
|
||||
- Reject fully automatic proposals without exposing an override. Compare a
|
||||
bounded identity inventory so alternate cycles are not hidden by the
|
||||
preferred display trace, and fall back conservatively when that inventory is
|
||||
exhausted. Always allow changes that remove diagnostics.
|
||||
- Preserve current request errors, temp-step remapping, optimistic reorder
|
||||
feedback, and workflow creation sequencing. Reconcile successful remote
|
||||
mutations from their authoritative responses and roll failed reorders back.
|
||||
|
||||
### Diagnostic presentation
|
||||
|
||||
Files:
|
||||
|
||||
- `apps/web/components/settings/workflow-cycle-diagnostic.tsx` (new)
|
||||
- `apps/web/components/settings/workflow-pipeline-editor.tsx`
|
||||
- `apps/web/components/settings/workflow-card.tsx`
|
||||
|
||||
Changes:
|
||||
|
||||
- Add a reusable diagnostic view for the inline alert and the confirmation or
|
||||
blocking dialog. Render severity, ordered trace, user-mediated hops, and the
|
||||
prompt-source explanation without rendering prompt contents.
|
||||
- Place the inline alert above the pipeline's horizontal scroll area and pass
|
||||
affected step IDs into pipeline nodes for icon/text plus border treatment,
|
||||
so affected steps are not communicated by color alone.
|
||||
- Use an `AlertDialog` for a pending proposal. Blocking diagnostics provide
|
||||
only a return action; warning diagnostics provide Cancel plus the context
|
||||
appropriate **Apply anyway** or **Create anyway** action.
|
||||
- Keep dialog actions and the full trace keyboard accessible. At narrow widths,
|
||||
stack trace hops and actions, wrap long names, maintain touch-sized controls,
|
||||
and prevent horizontal page overflow while leaving the pipeline's contained
|
||||
horizontal scrolling intact.
|
||||
|
||||
No API-client or Zustand state changes are required; workflow cards already own
|
||||
their loaded step arrays and mutation callbacks.
|
||||
|
||||
---
|
||||
|
||||
## Tests
|
||||
|
||||
- **What:** transition resolution for next, previous, and explicit targets on
|
||||
both triggers, including reordered positions and dangling targets.
|
||||
**File:** `apps/web/lib/workflows/replay-cycle-analysis.test.ts`
|
||||
**How:** table-driven pure unit tests.
|
||||
|
||||
- **What:** fully automatic cycles are blocking only when every source step
|
||||
auto-starts and every hop is unapproved `on_turn_complete`.
|
||||
**File:** `apps/web/lib/workflows/replay-cycle-analysis.test.ts`
|
||||
**How:** graph fixtures that vary auto-start, trigger, and approval config.
|
||||
|
||||
- **What:** user-mediated cycles, generic cycles without auto-start, stable
|
||||
diagnostic identities, deterministic trace selection, and all three prompt
|
||||
sources.
|
||||
**File:** `apps/web/lib/workflows/replay-cycle-analysis.test.ts`
|
||||
**How:** focused unit fixtures.
|
||||
|
||||
- **What:** the built-in Review `on_turn_start` feedback edge into In Progress
|
||||
does not warn or replay auto-start behavior.
|
||||
**File:** `apps/web/lib/workflows/replay-cycle-analysis.test.ts`
|
||||
**How:** regression fixture matching the built-in Kanban transition shape.
|
||||
|
||||
- **What:** an existing step edit that introduces a blocking cycle does not call
|
||||
`updateWorkflowStepAction`; a warning holds the call until confirmation and
|
||||
calls it exactly once; cancel does not call it.
|
||||
**File:** `apps/web/components/settings/workflow-card-actions.test.ts`
|
||||
**How:** mocked action tests around the guard/controller helper extracted from
|
||||
`useWorkflowStepActions`.
|
||||
|
||||
- **What:** add, remove, and reorder use proposed full shapes and existing
|
||||
diagnostics are not repeatedly confirmed.
|
||||
**File:** `apps/web/components/settings/workflow-card-actions.test.ts`
|
||||
**How:** mocked action tests with baseline/proposed diagnostic identities.
|
||||
|
||||
- **What:** draft creation is blocked before `createWorkflowAction`, warning
|
||||
cancellation sends no requests, and confirmation runs the existing creation
|
||||
sequence once.
|
||||
**File:** `apps/web/components/settings/workflow-card-actions.test.ts`
|
||||
**How:** extend the current new-workflow save tests.
|
||||
|
||||
- **What:** the inline and dialog variants render the exact trace, prompt source,
|
||||
affected-step accessibility text, and correct action labels.
|
||||
**File:** `apps/web/components/settings/workflow-cycle-diagnostic.test.tsx`
|
||||
**How:** Vitest/Testing Library component tests.
|
||||
|
||||
---
|
||||
|
||||
## E2E Tests
|
||||
|
||||
- **Scenario:** a persisted existing-workflow edit introduces a user-mediated
|
||||
return path to an auto-start step; no PUT is observable until **Apply
|
||||
anyway**, and the inline alert remains after persistence.
|
||||
**File:** `apps/web/e2e/tests/workflow/workflow-cycle-guardrails.spec.ts`
|
||||
**What to verify:** exact step/trigger trace, task-description prompt source,
|
||||
cancellation behavior, confirmation, and persisted events through the API
|
||||
helper.
|
||||
|
||||
- **Scenario:** a draft workflow contains a fully automatic cycle; saving is
|
||||
blocked and no workflow is created.
|
||||
**File:** `apps/web/e2e/tests/workflow/workflow-cycle-guardrails.spec.ts`
|
||||
**What to verify:** blocking severity, no override action, and workflow absent
|
||||
after reload/API list.
|
||||
|
||||
- **Scenario:** a cycle without auto-start remains allowed.
|
||||
**File:** `apps/web/e2e/tests/workflow/workflow-cycle-guardrails.spec.ts`
|
||||
**What to verify:** no diagnostic and normal persistence.
|
||||
|
||||
- **Scenario:** at a mobile viewport, a user-mediated draft warning exposes the
|
||||
complete trace and prompt source and can be cancelled/confirmed by touch
|
||||
without horizontal page overflow.
|
||||
**File:** `apps/web/e2e/tests/workflow/mobile-workflow-cycle-guardrails.spec.ts`
|
||||
**What to verify:** touch-reachable dialog actions, wrapped/visible trace,
|
||||
successful confirmation, and document width not exceeding viewport width.
|
||||
|
||||
---
|
||||
|
||||
## Implementation Waves
|
||||
|
||||
Wave 1:
|
||||
|
||||
- [x] [task-01-cycle-analyzer](task-01-cycle-analyzer.md) (done)
|
||||
|
||||
Wave 2:
|
||||
|
||||
- [x] [task-02-mutation-guard](task-02-mutation-guard.md) (done)
|
||||
|
||||
Wave 3:
|
||||
|
||||
- [x] [task-03-diagnostic-ui](task-03-diagnostic-ui.md) (done)
|
||||
|
||||
Wave 4:
|
||||
|
||||
- [x] [task-04-e2e-verification](task-04-e2e-verification.md) (done)
|
||||
|
||||
---
|
||||
|
||||
## Verification Commands
|
||||
|
||||
Format first:
|
||||
|
||||
```bash
|
||||
make fmt
|
||||
```
|
||||
|
||||
Focused frontend unit tests:
|
||||
|
||||
```bash
|
||||
(cd apps && pnpm --filter @kandev/web test -- lib/workflows/replay-cycle-analysis.test.ts components/settings/workflow-card-actions.test.ts components/settings/workflow-cycle-diagnostic.test.tsx)
|
||||
```
|
||||
|
||||
Frontend typecheck and lint:
|
||||
|
||||
```bash
|
||||
(cd apps/web && pnpm run typecheck)
|
||||
(cd apps && pnpm --filter @kandev/web lint)
|
||||
```
|
||||
|
||||
Focused desktop and mobile E2E (rebuilds the production web/backend artifacts
|
||||
through the repo E2E harness):
|
||||
|
||||
```bash
|
||||
(cd apps/web && pnpm e2e:run --host tests/workflow/workflow-cycle-guardrails.spec.ts)
|
||||
(cd apps/web && pnpm e2e:run --host --no-build --project mobile-chrome tests/workflow/mobile-workflow-cycle-guardrails.spec.ts)
|
||||
```
|
||||
|
||||
Full repository verification:
|
||||
|
||||
```bash
|
||||
make typecheck test lint
|
||||
```
|
||||
|
||||
## Risks
|
||||
|
||||
- `move_to_next` and `move_to_previous` change targets when steps are reordered;
|
||||
every topology-changing handler must analyze its proposed array, not only
|
||||
event updates.
|
||||
- Existing step controls issue remote mutations immediately and some maintain
|
||||
local debounced input. The pending-operation guard must avoid optimistic UI
|
||||
that disagrees with the server after cancel or failure.
|
||||
- The backend engine supports additional generic triggers and configurations.
|
||||
The diagnostic must state its two-trigger scope and tests must prevent the UI
|
||||
from implying that every possible workflow event has been analyzed.
|
||||
- New workflow persistence is a multi-request sequence. Preflighting before the
|
||||
first request is required so a cancelled warning cannot leave a partial
|
||||
workflow.
|
||||
|
||||
## Open Questions
|
||||
|
||||
None for this implementation. The first iteration deliberately guards the
|
||||
kanban-era `on_turn_start` and `on_turn_complete` paths agreed in the feature
|
||||
spec and leaves direct API/import enforcement for separate work.
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
id: "01-cycle-analyzer"
|
||||
title: "Workflow replay cycle analyzer"
|
||||
status: done
|
||||
wave: 1
|
||||
depends_on: []
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/workflow-cycle-guardrails/spec.md"
|
||||
---
|
||||
|
||||
# Task 01: Workflow replay cycle analyzer
|
||||
|
||||
## Acceptance
|
||||
|
||||
- A pure deterministic analyzer returns the diagnostic contract from the spec
|
||||
for cycles over `on_turn_start` and `on_turn_complete` move actions.
|
||||
- Fully automatic versus user-mediated classification accounts for source-step
|
||||
auto-start and approval, including automatic `on_turn_start` transitions,
|
||||
and ignores cycles without auto-start
|
||||
re-entry through `on_turn_complete`. An `on_turn_start` edge into an
|
||||
auto-start step is covered as a safe non-replay regression.
|
||||
- Trace choice, bounded identity inventory with conservative truncation,
|
||||
affected steps, dangling targets, reorder behavior, and all three
|
||||
prompt-source categories have focused unit coverage.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
(cd apps && pnpm --filter @kandev/web test -- lib/workflows/replay-cycle-analysis.test.ts)
|
||||
(cd apps/web && pnpm run typecheck)
|
||||
```
|
||||
|
||||
## Files Likely Touched
|
||||
|
||||
- `apps/web/lib/workflows/replay-cycle-analysis.ts`
|
||||
- `apps/web/lib/workflows/replay-cycle-analysis.test.ts`
|
||||
|
||||
## Dependencies
|
||||
|
||||
None.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Spec sections `What`, `Analysis Contract`, and `Scenarios`.
|
||||
- `apps/web/lib/types/workflow-actions.ts` for action shapes.
|
||||
- `apps/backend/internal/workflow/engine/types.go` for transition resolution
|
||||
and trigger semantics.
|
||||
- `apps/backend/internal/orchestrator/event_handlers_workflow.go` for the
|
||||
auto-start/user-turn distinction.
|
||||
|
||||
## Output Contract
|
||||
|
||||
When finished, change this task's `status` to `done`, check it in `plan.md`, and
|
||||
report the analyzer API, files changed, tests run, blockers, and residual risks.
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
id: "02-mutation-guard"
|
||||
title: "Workflow mutation guard"
|
||||
status: done
|
||||
wave: 2
|
||||
depends_on: ["01-cycle-analyzer"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/workflow-cycle-guardrails/spec.md"
|
||||
---
|
||||
|
||||
# Task 02: Workflow mutation guard
|
||||
|
||||
## Acceptance
|
||||
|
||||
- Existing update/add/delete/reorder handlers analyze their complete proposed
|
||||
shape before sending the current API mutation.
|
||||
- Blocking proposals send no request; warning proposals execute exactly once
|
||||
only after confirmation; existing diagnostic identities and cycle-removing
|
||||
edits are not gated unless identity comparison is conservatively truncated.
|
||||
- Successful remote mutations reconcile from their authoritative responses;
|
||||
reorder remains optimistic while pending and rolls back on request failure.
|
||||
- Draft workflow save preflights before `createWorkflowAction`, with cancel
|
||||
leaving the draft and sending no create or step requests.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
(cd apps && pnpm --filter @kandev/web test -- components/settings/workflow-card-actions.test.ts lib/workflows/replay-cycle-analysis.test.ts)
|
||||
(cd apps/web && pnpm run typecheck)
|
||||
```
|
||||
|
||||
## Files Likely Touched
|
||||
|
||||
- `apps/web/components/settings/workflow-card-actions.ts`
|
||||
- `apps/web/components/settings/workflow-card-actions.test.ts`
|
||||
- `apps/web/components/settings/workflow-card.tsx`
|
||||
|
||||
## Dependencies
|
||||
|
||||
Task 01.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Spec scenarios for existing mutations, baseline/proposed comparison, and
|
||||
draft creation.
|
||||
- Analyzer and diagnostic identity contract from Task 01.
|
||||
- Existing `useWorkflowStepActions` and `useWorkflowSaveActions` behavior,
|
||||
including temp-step remapping and request-error feedback.
|
||||
|
||||
## Output Contract
|
||||
|
||||
When finished, change this task's `status` to `done`, check it in `plan.md`, and
|
||||
report guarded operations, request behavior tests, files changed, blockers, and
|
||||
residual risks.
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
id: "03-diagnostic-ui"
|
||||
title: "Workflow cycle diagnostic UI"
|
||||
status: done
|
||||
wave: 3
|
||||
depends_on: ["02-mutation-guard"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/workflow-cycle-guardrails/spec.md"
|
||||
---
|
||||
|
||||
# Task 03: Workflow cycle diagnostic UI
|
||||
|
||||
## Acceptance
|
||||
|
||||
- Existing and proposed diagnostics render severity, exact ordered trigger
|
||||
trace, user-required hops, and prompt source through one reusable component.
|
||||
- Blocking dialogs expose no override; warning dialogs use **Apply anyway** or
|
||||
**Create anyway**, and affected pipeline steps are identified without color
|
||||
alone.
|
||||
- Desktop and narrow layouts keep text/actions usable, keyboard/touch
|
||||
accessible, and page overflow contained.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
make fmt
|
||||
(cd apps && pnpm --filter @kandev/web test -- components/settings/workflow-cycle-diagnostic.test.tsx components/settings/workflow-card-actions.test.ts)
|
||||
(cd apps/web && pnpm run typecheck)
|
||||
(cd apps && pnpm --filter @kandev/web lint)
|
||||
```
|
||||
|
||||
## Files Likely Touched
|
||||
|
||||
- `apps/web/components/settings/workflow-cycle-diagnostic.tsx`
|
||||
- `apps/web/components/settings/workflow-cycle-diagnostic.test.tsx`
|
||||
- `apps/web/components/settings/workflow-pipeline-editor.tsx`
|
||||
- `apps/web/components/settings/workflow-card.tsx`
|
||||
- `apps/web/components/settings/workflow-card-dialogs.tsx`
|
||||
|
||||
## Dependencies
|
||||
|
||||
Task 02.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Spec prompt-source language, trace requirements, and mobile behavior.
|
||||
- Pending-operation state from Task 02.
|
||||
- Existing `AlertDialog`, workflow pipeline scroll area, and workflow-card
|
||||
dialog patterns.
|
||||
|
||||
## Output Contract
|
||||
|
||||
When finished, change this task's `status` to `done`, check it in `plan.md`, and
|
||||
report responsive behavior, accessibility treatment, files changed, tests run,
|
||||
blockers, and residual risks.
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
id: "04-e2e-verification"
|
||||
title: "Workflow cycle guardrail E2E verification"
|
||||
status: done
|
||||
wave: 4
|
||||
depends_on: ["03-diagnostic-ui"]
|
||||
plan: "plan.md"
|
||||
spec: "../../specs/workflow-cycle-guardrails/spec.md"
|
||||
---
|
||||
|
||||
# Task 04: Workflow cycle guardrail E2E verification
|
||||
|
||||
## Acceptance
|
||||
|
||||
- Desktop Playwright covers warning cancel/confirm, blocking draft creation,
|
||||
exact trace/prompt source, persisted diagnostics, and an allowed generic
|
||||
cycle without auto-start.
|
||||
- A `mobile-*.spec.ts` test completes the warning confirmation flow by touch
|
||||
and asserts the trace/actions fit without horizontal page overflow.
|
||||
- Focused and repository verification commands run after formatting, with any
|
||||
environment-only blocker reported exactly.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
make fmt
|
||||
(cd apps/web && pnpm e2e:run --host tests/workflow/workflow-cycle-guardrails.spec.ts)
|
||||
(cd apps/web && pnpm e2e:run --host --no-build --project mobile-chrome tests/workflow/mobile-workflow-cycle-guardrails.spec.ts)
|
||||
(cd apps/web && pnpm run typecheck)
|
||||
(cd apps && pnpm --filter @kandev/web lint)
|
||||
make typecheck test lint
|
||||
```
|
||||
|
||||
## Files Likely Touched
|
||||
|
||||
- `apps/web/e2e/pages/workflow-settings-page.ts`
|
||||
- `apps/web/e2e/tests/workflow/workflow-cycle-guardrails.spec.ts`
|
||||
- `apps/web/e2e/tests/workflow/mobile-workflow-cycle-guardrails.spec.ts`
|
||||
|
||||
## Dependencies
|
||||
|
||||
Task 03.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Every user-visible spec scenario.
|
||||
- Existing workflow settings page object and API helper patterns.
|
||||
- Mobile parity requirement that mobile tests use the `mobile-` filename
|
||||
convention and real touch-accessible actions.
|
||||
|
||||
## Output Contract
|
||||
|
||||
When finished, change this task's `status` to `done`, check it in `plan.md`, and
|
||||
report desktop/mobile scenarios, files changed, exact commands/results,
|
||||
environment blockers, and residual risks.
|
||||
Reference in New Issue
Block a user