46 — Adaptable Workflow Engine — actor-aware, configurable lifecycle (envisioning)

▶ BACKEND BUILT + iOS SURFACE SHIPPED (2026-06-28). Structure (Stages → Steps), per-type satisfaction, templates + per-project instances + custom steps, per-step assignment — all backend, with a live mongodb-memory-server smoke-test (e2e 4/4). iOS — END-TO-END (2026-06-28): author a template in Configure ▸ Workflow (WorkflowTemplatesView/…EditorView: create-from-default · rename · required toggles · add/delete custom steps · save/delete/duplicate, over /workflow/templates CRUD) → apply it on a project ("Use template" menu on the Project Portal → POST /project/:id/workflow/ instantiate) → the pipeline renders & rolls up that structure (WorkflowPipelineSection off release-readiness), with inline project-step authoring → PATCH /project/:id/readiness. All xcodebuild green. The editor is now a full process-builder (2026-06-29): rename · required toggles · add/delete steps · reorder steps (move up/down · move-to-stage) · stage CRUD (add/rename/move/delete) — the whole structure round-trips through PATCH /workflow/templates/:id. Native drag-reorder + approver-role authoring landed 2026-06-29 (editor rebuilt on List: Edit-mode drag · swipe-delete · per-step approver role Owner/Admin/Editor/Viewer/Anyone, doc-44). Remaining: per-variant appliesToVariants (unblocked — doc-28 variantType exists) · config across other hierarchy dimensions (workflow anchors at Project only today — Roster/Artist/Variant have none; design open) · web parity (parked). See CHANGELOG.md.

Envisioning doc — needs confirmation. Governed by 00-ROADMAP.md. Created 2026-06-28 (owner-raised, off doc-45). The ask: "ensure our software adapts to the end user, their workflow (or many workflows — depending on owner / studio / project), needs, and user-friendly usage." The trigger: a fixed "readiness checklist" of Title·Cover·Version·Lyrics·Master·Metadata is too release-centric and too technical — it ignores the creative/recording lifecycle (re-record, better take, different mic / studio / featured artist, test pressing / test impression, splits, contracts…) where most actors and most of the work actually live, and it's only toggle-configurable, not model-your-own-process configurable.

Three decisions locked at envisioning (2026-06-28, owner):

1. Shape = ordered Stages → Steps (a lifecycle pipeline). Not a flat checklist, not a full state machine — readable phases (Recording → Mix → Master → QC → Rights → Release), each holding steps.
2. Configurability = templates + full custom steps. Ship opinionated workflow templates (per release-type / actor) as starting points and let owners define fully custom stages/steps in their own language. Not "pick from my fixed list."
3. Scope = studio/workspace templates → project instance (+ per-variant). A studio defines its workflow once; each project instantiates + tweaks it; variants (doc-28) can override.

This generalizes the doc-45/32 configurable-readiness profile already shipped (the seed — a flat per-project profile). The release gate becomes the tail stages of a workflow.

The reframe — from "release checklist" to "model your process"

Today's approval (doc-32) + the shipped readiness profile (doc-45) describe the end of the pipeline (is this distributable). The owner's point: the product must model the whole lifecycle, in the studio's own terms, because every studio/owner/project runs a different process and different actors own different phases. The engine's job is to be the adaptable hub for their workflow — calm and user-friendly, template-guided, not a rigid form.

The model

Workspace (studio)                      Project / Release                Variant (doc-28)
──────────────────                      ─────────────────                ────────────────
WorkflowTemplate[]   ──instantiate──▶   Workflow (instance)   ──override──▶  per-variant steps
  Stage[]                                 Stage[] (tweakable)                 (remix skips lyrics,
    Step{...}                               Step{ status, owner, asset }       live needs venue clear…)

• Workflow = an ordered list of Stages; each Stage = a lifecycle phase holding Steps.
• Step = the unit of progress: { key, label, type, ownerRole?, assignee?, checkpoint, assetSlot?, appliesToVariants? }.
  • type (LEGO presets + custom): approval (sign-off, doc-32) · task (done/not-done) · asset (an upload is required — master file, contract, test-pressing) · decision (a recorded choice — mic / studio / take / featured artist) · review (notes round).
  • checkpoint = how it's "satisfied": approved · done · asset-present · decided.
  • ownerRole/assignee = who's responsible (doc-44 role / doc-12 actor) → drives "what's mine."
  • assetSlot = binds to the project asset space (doc-45) when the step produces/needs a file.
• Templates + custom (decision 2): templates are starting points (see §Default templates); owners add / rename / remove / reorder stages & steps in their own words — the LEGO engine (doc-43) stores the definitions (stable keys + i18n labels + custom keys).
• Scope & reuse (decision 3): templates live on the workspace/studio; a project instantiates one into a concrete Workflow it can tweak; variants (doc-28) carry overrides. A solo artist gets a sensible default and never has to think about it.

Actors & assignment (the "ensure it adapts to the user")

Every step carries an owner-role and/or assignee (artist · producer · tracking/mix/master engineer · A&R · manager · label ops · legal — doc-12/17). This is what makes the hub user-friendly per actor: a mix engineer sees their steps, a manager sees what's blocked and on whom. Ties to doc-44 (roles/teams) and the future "manager license" axis (doc-44 §Q6). The workflow is the operational layer under mgmt.ctrl (doc-42) — the Board renders stage progress; Portals (doc-26) render a node's steps.

The lifecycle, grounded (default template content)

Far bigger than Title·Cover·Version. A reasonable default "Studio Release" template (owners edit freely):

Stage	Example steps (type)	Typical owner
Writing / Demo	song selected (decision) · demo approved (approval)	Artist / A&R
Pre-production	arrangement locked (approval) · studio / room / mic chosen (decision) · session booked (task)	Producer
Recording / Tracking	takes captured (asset) · re-record / better take (decision) · comp selected (decision) · featured artist (decision)	Artist / Producer / Engineer
Edit / Mix	edit done (task) · mix approved (approval, per version)	Mix engineer / Artist
Master	master approved (approval) · test pressing / test impression (asset + approval)	Mastering eng. / Artist
QC	loudness / silence check (task) · explicit/clean variants (decision, doc-28)	Engineer / QC
Rights / Business	splits agreed (approval) · contracts signed (asset) · sample / sync clearance (approval) · credits + ISRC/UPC (task)	Manager / Legal
Release	cover still + motion cover (asset + approval, doc-45) · tracklist locked (approval) · distribution metadata (task) · marketing assets (asset)	A&R / Marketing

Note the offending "metadata" splits into real steps people recognize — credits, ISRC/UPC, distribution metadata — and the creative steps (re-record, mic/studio, test pressing) finally have a home. None of this is hardcoded — it's the default template, fully editable.

Relationship to existing docs

Doc	Role under the workflow engine
doc-45 Release pipeline / assets	The release tail of a workflow + the asset space steps bind to (motion covers, documents). The shipped configurable-readiness profile = the v0 seed this generalizes.
doc-32 Approval model	A step of type: approval — the per-dimension sign-off, now one step-type among several.
doc-43 LEGO attributes	The config engine that stores workflow templates / custom step + stage definitions (keys + labels + types). Workflow authoring = a doc-43 catalog editor specialized for steps.
doc-28 Variants	Per-variant step overrides (a remix's workflow ≠ the original's).
doc-12 / doc-17 Actors/UX	The actor model for step ownership/assignment + the per-actor "what's mine" surfaces.
doc-42 mgmt.ctrl	The hub: Board = stage progress across the catalog; the queue = steps awaiting me.
doc-44 RBAC/teams	Who can author templates · who can complete/approve a step (per-resource roles + future license).

Design principle (the motto)

"Start simple, scale to your complexity — only when you need it."

The calm default is the product for 90% of users; the depth is opt-in and reveals itself as a studio's process demands it. Every increment below must hold this line — never make a solo artist pay for a label's complexity.

User-friendliness (the "ensure")

• Template-first onboarding — never a blank slate; pick a template close to your process, then adapt.
• Calm by default — a solo artist sees a short, sensible flow; complexity is opt-in (doc-20/31 professional calm). Stages collapse; show "what's next / what's mine," not the whole graph.
• Their language — custom labels, so a beatmaker's "beat sold" and a label's "A&R sign-off" both fit.
• Progress legible — stages cleared / blocked, owner per step; the release gate is just "all required steps satisfied" (the doc-45 rollup, generalized).

What's built vs net-new

• Built (the seed, doc-45/32): a per-project flat configurable readiness profile + catalog + the generalized computeReleaseReadiness rollup + set-item / set-profile endpoints.
• Net-new: the Stage→Step model · step types (task/asset/decision/review beyond approval) · workflow templates (workspace-level) · instantiate + per-project tweak · per-variant overrides · assignment/ownership per step · the authoring UI (template + step editor) · the hub rendering (stage progress in mgmt.ctrl + Portals).

Per-variant & multi-album workflow (envisioning — owner-decided 2026-06-28)

Decision (owner): workflow is PER-PROJECT — the same recording can sit at a different stage in each album it appears in. Envision before building — it's tangled with doc-28's "a recording appears in multiple albums." The two doc-28 threads in play: variantType (remix / radio-edit / live / instrumental / clean / explicit — a variant is its own Track) and appearsInProjects[] (one recording, many albums).

The model:

1. A variant is a Track (doc-28 variantType). Per-variant workflow = per-track step applicability within a project: a step carries appliesToVariants?: string[] (empty = all), so a project's workflow can skip lyrics for a remix and add venueClearance for a live take — evaluated per track.
2. Multi-album → step SCOPE is the key insight (resolves the tangle):
   • recording-intrinsic steps (takes · arrangement · mix · master) describe the recording → status follows the recording, shared across every album it appears in.
   • release-contextual steps (cover · title · tracklist · distribution details) describe the recording-in-a-release → status is per (recording, project), differing per album. This operationalizes "per-project, can differ per album": the release tail differs per album; the production work is shared.

Status-storage implication (build-time, when multi-album lands): today status lives on the Track (one project) — fine while a track has a single project. Multi-album needs release-scoped step status keyed by (recording, project) (a membership/junction), while recording-scoped steps stay on the recording. The current Track.readiness / releaseStatus + Project.readiness maps are the seam; the junction is the future addition.

Open questions: is a "recording" a first-class entity (doc-28) or just a Track with appearsInProjects[] (decides where the status junction lives)? · default per-variantType rules (template-level) vs purely per-track manual applicability? · does doc-28's sameRecordingAs relation auto-share recording-scoped step status across linked tracks?

Build posture: envisioned, not built. The cheap first slice (when we build it) is per-track appliesToVariants; the multi-album status junction waits for doc-28's multi-album feature.

Open questions / to envision

1. Step status vocabulary — reuse the approval enum (No status / Under review / Approved / Changes) for every step-type, or per-type states (task = todo/done; asset = missing/present)? Recommend a small unified satisfied + per-type detail.
2. Stage gating — are stages strictly ordered (can't start Mix before Recording done) or advisory (parallel allowed)? Recommend advisory by default, optional hard-gates per template (avoids the state-machine complexity we deliberately skipped).
3. Template marketplace? — studio templates shared/forked across workspaces (a future network effect)?
4. Where authoring lives — Workspace Settings (doc-43 editor) vs in-context in mgmt.ctrl / Portal.
5. Migration — fold the shipped readiness profile into a default "Release" stage so nothing breaks.

Sequencing

The seed is shipped (flat profile). The engine is post-MVP, built incrementally, each step shippable: (1) generalize the flat profile into Stages → Steps (default template = today's items as one "Release" stage); (2) add step types (task/asset/decision) beyond approval; (3) workspace templates + instantiate/tweak; (4) per-variant overrides (doc-28); (5) assignment per step; (6) the authoring UI (rides doc-43). mgmt.ctrl Board + Portals surface each increment. Full configurability depends on the doc-43 LEGO engine.

---

Status: envisioning, captured 2026-06-28. Decisions 1–3 locked. Generalizes the shipped doc-45/32 readiness seed into an actor-aware, template-driven, configurable lifecycle workflow — the adaptable hub the owner asked us to ensure. Deepen + build incrementally post-MVP, on the doc-43 LEGO engine.