feat(api,ui): showcase workspace completion — the forecastlab control story

[w7-mgfcode]

Summary

Umbrella #389 closed having shipped the workspace backbone (table + migration #390, 8-preset exposure #391, workspace-tagged plans #392, restore/replay #393, delete #404, release gate #401), but its own out-of-scope list defers the rest of the control story: advanced seed configuration beyond seed/scenario/reset/skip_seed, phase-level configuration, RAG-event + approval-decision capture on the workspace row, export bundles, and a replayed_from provenance column. Today a replay of a reset=true workspace wipes the database with no confirmation (documented designed behavior, docs/_base/RUNBOOKS.md § Showcase workspace), workspaces cannot be renamed/archived/searched, the workspace row lacks seed overrides / user-selected scope / approval history / RAG events / replay lineage, the seeder HTTP contract accepts only scalar overrides, and no export surface exists. Brainstorm Round 5 (.flow/brainstorm-log.md) scored 12 candidates: 7 ship, 5 defer.

Approach

Additive-only delta on the existing demo + seeder slices: one Alembic migration extends showcase_workspace (lifecycle + provenance columns, JSONB story slots); every new request field is additive Optional on DemoRunRequest / the WS start frame (legacy frames byte-identical); the seeder HTTP contract gains an additive nested-override schema for a curated knob subset; the export bundle is a new endpoint writing under artifacts/showcase/<workspace>/. What will NOT change: no new services or runtime dependencies, no new router outside existing slices, and no mid-run pipeline re-architecture — the linear single-asyncio.Lock stream is preserved (all configuration is start-frame-time). Frontend reuses shadcn primitives and deep-links; it does not duplicate /visualize/planner, /visualize/batch, or /ops.

Decomposition

• E1 — Foundation feat(api,db): showcase-completion E1 — workspace metadata & provenance backbone (migration + jsonb story slots + patch lifecycle endpoint) #407 (blocks E2–E6): workspace metadata & provenance backbone — migration (replayed_from_workspace_id, archived, pinned, notes, tags, config_schema_version) + JSONB story slots (seed_overrides, user_scope, approval_events, rag_events, job_ids, phase_summaries) + PATCH lifecycle endpoint
• E2 — Parallel feat(api,ui): showcase-completion E2 — safe replay & workspace lifecycle (confirm/diff, lineage, rename/archive/pin/tags, search, compare, link health) #408: safe replay & workspace lifecycle — destructive-replay confirmation + replay preview/diff, lineage chain + replay badge, rename/archive/pin/notes/tags, list search/filter/sort, multi-select delete, workspace compare, artifact-link liveness + workspace health summary
• E3 — Parallel feat(api,ui): showcase-completion E3 — advanced seed config mvp + store/product scope selection #409: advanced seed config MVP + scope selection — additive seeder override contract (curated knob subset: store/product counts, window, sparsity, promo/stockout intensity, noise), seed_overrides in start frame, store/product focus-pair selector + preview, persisted + honored on replay
• E4 — Parallel feat(api,ui): showcase-completion E4 — run-config phase controls (model set + backtest params in start frame) #410: run-config phase controls — start-frame model-family picker (+ opt-in lightgbm/xgboost/random_forest toggles), backtest horizon/splits/gap/metric config, train-candidate preview, config echoed into the workspace row
• E5 — Parallel feat(api,ui): showcase-completion E5 — agent/hitl + rag story capture (approval history + reject + rag events) #411: agent/HITL + RAG story capture — approval decisions/action ids/tool-call summaries captured on the workspace, Reject button on the HITL card, approval history on Showcase + /ops, RAG events + replay non-reproduction marker
• E6 — Parallel feat(api,ui): showcase-completion E6 — export bundle mvp (manifest + checksums + export endpoint/button) #412: export bundle MVP — artifacts/showcase/<workspace>/ writer, manifest JSON + SHA-256 checksums, export endpoint + UI button, bundle versioning (export-only)
• E7 — Release gate feat(repo): showcase-completion E7 — release gate (docs/runbook/API sweep + dogfood evidence + regression coverage + umbrella close-out) #420 (closes after Foundation + all Parallel): docs/runbook/API-contract sweep, dogfood evidence matrix, regression coverage, umbrella close-out

Out of scope (explicit)

• Mid-run per-phase re-run / resumable pipeline — reason: re-architects the strictly-linear asyncio.Lock streaming pipeline; same deferral as feat(api,ui): showcase workspace — preserve, restore, and replay showcase runs #389.
• Mid-run decision & batch controls (manual winner override, in-run alias forms, mid-run batch matrix) — reason: no mid-run interactive gate infrastructure exists outside the agent HITL step; post-run deep-links already shipped (PRP-39).
• Embedded scenario-builder UI inside /showcase — reason: duplicates /visualize/planner; orchestrate-and-deep-link + the workspace-tagged plan library already shipped (feat(api,ui): showcase-workspace E3 — workspace-tagged scenario plans (pipeline tags + planner library filter) #392 / PRP-40).
• Standalone ops-observability epic — reason: /ops + the ops_snapshot step already cover most of it; the novel link-liveness/health-summary slice is folded into E2.
• Bundle import/restore — reason: highest-risk surface with an unsettled disk-layout design; export-only ships first.
• Workspace story report page + nightly CI bundle validation — reason: zero codebase grounding; a shareable hosted-report surface tensions with the single-host vision.

Success criteria

• The showcase_workspace migration adds lifecycle + provenance columns and JSONB story slots, and applies + downgrades cleanly on a fresh DB
• A replay records replayed_from_workspace_id and the UI renders the lineage chain; a reset=true replay requires an explicit confirmation step before it runs
• Workspaces can be renamed, archived, pinned, annotated (notes/tags), searched, filtered, sorted, and multi-select-deleted (metadata-only) from the saved-workspaces panel
• A showcase run can start with curated seed overrides + an explicit store/product focus pair; both persist to the workspace row and are honored verbatim on replay
• The start frame accepts model-set + backtest config; the chosen config is echoed into the workspace row and visible on the run
• HITL approval decisions (approve AND the new Reject path) and RAG events are captured on the workspace row and rendered as history on Showcase and /ops
• Export produces artifacts/showcase/<workspace>/ with a manifest + SHA-256 checksums that validate
• Legacy start frames (no new fields) behave byte-identically; all five CI gates green on every epic

Risks

Risk	Mitigation
Seeder override contract grows unbounded (25+ knobs)	MVP allow-listed knob subset as additive Optional nested schema; everything else stays preset-driven
New WS start-frame fields break legacy clients	additive Optional only + contract test for the legacy frame (proven pattern from #389)
Replayed seed overrides drift from the original data (e.g. holiday_rush pinned window)	replay echoes recorded overrides verbatim; replay-diff panel surfaces divergence; runbook caveat
Export bundle path traversal / disk leaks	reuse LocalFSProvider traversal prevention; pathlib.Path.resolve() + allow-listed root
Story-capture writes failing the pipeline	keep the warn-and-continue invariant — capture must never break a green run
JSONB story slots become a junk drawer	config_schema_version column + documented slot schema in docs/_base/DOMAIN_MODEL.md

Tracking

• Source of truth: docs/flow-pack-methodology.md + working state .flow/state.md (brainstorm Round 5, 2026-06-12)
• Milestone: showcase-workspace-completion
• Project board: none — single-maintainer repo, GitHub Issues only
• Prior umbrella: feat(api,ui): showcase workspace — preserve, restore, and replay showcase runs #389 (closed) — this umbrella ships its deferred forward-pointers
• One-pass confidence: 8/10 (all epics grounded in feat(api,ui): showcase workspace — preserve, restore, and replay showcase runs #389 forward-pointers + verified additive surfaces; residual risk = seeder contract shape (E3) and export disk layout (E6))