feat(web): warn about workflow replay cycles (#1720)

This commit is contained in:
Carlos Florêncio
2026-07-17 18:47:27 +01:00
committed by GitHub
parent 16da501fc4
commit 34a031f9b9
22 changed files with 3667 additions and 342 deletions
@@ -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.