Plan: rebuild workflow state and operator UX from backend truth

[shiny-code-bot]

Finish Line

One backend workflow-state contract drives worklist, Folder Studio, actions, and series/season scope UX.

Why This Exists

The current UX keeps breaking because the backend, worklist, Folder Studio, folder actions, and series navigation all infer workflow state from different partial signals: raw item statuses, review badges, encode jobs, staged artifacts, candidate counts, and local frontend branch order.

The fix is not another visual reset. The fix is to rebuild the foundation from backend truth upward, then redesign the operator UI around that contract.

Current Status

State: Active, final polish remaining.
Next action: Start #129 (Polish the workflow UI after backend truth lands) for a browser-validated final operator UX pass across the workflow matrix.
Blocked by: None.
Waiting for: None.
Last verified: 2026-06-06 after PR #131 and PR #132 merged; post-merge CI and CodeQL passed on main.

Completed sub-issues: #121, #122, #123, #124, #125, #126, #127, and #128 are closed as completed.

Evidence:

• PR Clarify output workflow scope and work lanes #131 landed the canonical backend workflow state, manifest filtering, series/season aggregation, payload exposure, Folder Studio/worklist scope migration, and browser route validation.
• PR Align validate action with workflow lane #132 aligned the validate action with the validate lane so validated staged outputs stay reserved for promotion.
• Acceptance gate passed locally before both merges, and GitHub CI/CodeQL passed after both merges.

Roadmap

1. Define canonical backend workflow state and lane derivation.
2. Move manifest candidate selection and folder actions onto that state.
3. Normalize season/series aggregation.
4. Expose the canonical state in dashboard and folder payloads.
5. Add regression fixtures so Terminator-style contradictions cannot return.
6. Rebuild worklist and Folder Studio UX around one next action, clear scope, and consistent copy.
7. Perform the visual/interaction polish pass once the state model is true.

Principles

• Backend truth first, frontend presentation second.
• No UI surface may independently invent workflow state for operator actions.
• Season and series scope must be explicit in every action label.
• "Queue", "validate", and "promote" are different operator actions and must never collapse into one vague readiness state.
• Browser validation is required for UI phases.

Recovery Notes

Agent review converged on the same diagnosis: the root failure is duplicated state derivation, not just bad copy. The narrower short-term fix would add encoded-output counts, but the durable plan is to make workflow state a typed backend contract and migrate all operator surfaces to it.