Workflows 3/5: versioned append-only workflow store + admin UI (draft/publish/rollback, audit, diff, version per chat turn) #83

Part of #80. Slice 3 of 5 (v1): the auditability slice. Depends on slice 1.

Context

Auditability and change management are the top priority for workflow configuration. Built-in workflows (slice 1) are files reviewed through git; this slice adds a versioned, append-only Postgres store and an admin UI, so workflows can be changed at runtime with full audit and without a file-upload path.

Scope

Storage

1. workflow_versions table (Alembic): full YAML text, content hash, author (Keycloak sub), timestamp, required change note, parent version, source (builtin | admin), status (draft | published).
2. Repository with no update/delete methods (structural enforcement, same as AuditLogRepository) plus a public-surface test. Name it so tools/lint_repositories.py covers it, or rely on the explicit surface test if the name doesn't fit.
3. Consider a hash chain (each version stores the previous version's hash) for tamper evidence. Decide in the plan.
4. Active-version pointer per workflow. Publish = move the pointer; rollback = re-publish an older version (itself a new audit event). Pointer move and audit entry happen in one transaction.
5. Change management is configurable per deployment (see Workflows: configurable change management — direct / git-advisory / git-authoritative publish modes, two-person approval, external or in-stack git #87: direct / git_advisory / git_authoritative, plus optional two-person approval). This slice implements only direct, the default. Keep publishing behind a single service entry point, so Workflows: configurable change management — direct / git-advisory / git-authoritative publish modes, two-person approval, external or in-stack git #87's modes replace one step rather than several scattered call sites. Don't build the mode abstraction here, since only one mode exists in v1. Show the effective mode (always direct for now) read-only on the Workflows screen.

Change management
6. Draft → validate → publish. A draft can only be saved if it passes slice 1's validation. Publishing requires a confirmation showing the diff (same pattern as the retention-shortening confirmation).
7. Audit events workflow.draft_saved, workflow.published, workflow.rolled_back, with before/after version IDs; update docs/AUDIT_EVENTS.md.
8. Built-ins are read-only; editing one creates an admin-owned copy. A newer built-in in a later image shows as "update available" and never silently overwrites (full flow in the git-export follow-up).

Traceability
9. Record the workflow version ID on every chat turn, and tag Phoenix spans with workflow name + version. This answers "which prompt produced this answer on the 14th?" after later edits.

Admin UI (frontend/src/components/, three-layer client → service → hook)
10. Workflow list (source, active version), plain-textarea YAML editor with inline server validation errors, version history, diff between any two versions, publish/rollback, and a workflow diagram (LangGraph's get_graph() Mermaid export; Mermaid must be vendored for air-gap, or render the simple graph directly. Decide in the plan).
11. No file upload / bulk import in v1. Note: a text editor is equivalent in power to upload. The security controls are validation, the tool allowlist, the loop ceiling, the change note, audit, and immutable versions, not the absence of upload.

User-visible signal

A new admin "Workflows" screen showing every workflow, its history, and diffs; publishes appear on the Audit Log screen.

RBAC

Admin feature (require_admin) for every endpoint here.

Configuration call-out

No new tunables expected. If any appear (e.g. max YAML size), decide knob vs. constant explicitly in the plan.

Deferred (note in the PR; file if needed)

Two-person approval and git-backed publishing (now scoped as configurable change modes in #87; the draft/publish split leaves room for them), a separate workflow-admin role, a form-based editor, a syntax-highlighting editor (needs vendoring).

Definition of Done

• Append-only store + migration + surface test.
• Draft/publish/rollback endpoints, transactional with audit entries, tested.
• Version ID on chat turns and Phoenix spans.
• Admin UI with diff, history, diagram, publish confirmation.
• e2e spec: admin edits a workflow, publishes, and sees the audit entry.
• docs/AUDIT_EVENTS.md, docs/SECURITY.md, and the workflow guide updated.
• Standard merge gate from AGENTS.md's Definition of Done applies in full.