HartOMat/docs/workflows/WORKFLOW_DELIVERY_CHECKLIST.md

Workflow Delivery Checklist

Parallel execution ownership and stage gates are defined in docs/workflows/WORKERS.md.

Phase Checklist

Phase 1

• Canonical workflow schema finalized
• Frontend and backend workflow types aligned
• Preset workflow migration helpers added
• Tests added for legacy preset conversion
• Legacy dispatch remains default

Phase 2

• Node registry implemented
• Node definitions API available
• All required nodes have settings schemas
• Editor consumes node definitions from backend

Phase 3

• Missing legacy steps extracted into reusable executors
• Extracted node behavior matches legacy services
• Node-level tests cover success and failure paths
• Progress: Phase 3 parity nodes are extracted, covered by targeted runtime tests, and exercised through the workflow executor with legacy-safe bridge dispatch.

Phase 4

• Workflow context introduced
• Node outputs are persisted and reusable
• Graph runtime supports legacy fallback
• legacy, graph, and shadow modes exist
• Progress: Workflow configs now normalize to an explicit execution mode, the editor exposes and persists legacy/graph/shadow, production order-line dispatch can opt into graph mode with hard fallback to legacy on graph failure, workflow runs persist their execution mode, notify handoff is armed only for authoritative graph renders, and output_save is now graph-authoritative for still renders, turntable/video renders, and .blend exports while shadow runs remain observer-only.

Phase 5

• Editor saves nodes and edges
• Editor roundtrip preserves workflow configs
• All node settings are editable
• Validate, dry-run, and dispatch are available
• Runs are visible with node-level status and logs
• Editor authoring follows family-safe module contracts instead of ad hoc node metadata
• Progress: The workflow canvas header has been compressed into a single canvas-adjacent control strip, preserving right-click node insertion, auto-align, edge deletion, preflight, dispatch, and save actions while reducing top-of-page bloat.
• Progress: The canonical still-path bridge nodes now expose editor-visible, runtime-backed settings for template overrides, material resolution, auto-population behavior, GLB source preference, output-save artifact expectations, and notify arming. The remaining Phase 5 work is authoring hierarchy and end-to-end editor verification, not hidden backend-only params.

Phase 7

• Output-type create defaults match current backend constraints
• Output types model workflow invocation profiles
• Output types validate against workflow family and artifact contract
• Admin create/edit flow is workflow-first instead of renderer-first
• Progress: The admin output-type form now opens with a dedicated workflow-contract section, keeps invocation-profile inputs ahead of renderer compatibility knobs, and moves catalog/business fields into a separate closing section so legacy Blender details no longer dominate the primary authoring flow.
• Progress: Output-type contract helpers now expose family-safe format lists, blend is treated as a first-class blend_asset contract in both frontend and backend, and the admin form no longer steers users into obviously invalid cad_file/video or order_line/model-export combinations.
• Progress: API responses now serialize the invocation profile through the typed schema, and create/edit validation rejects mixed-family workflows plus workflow/artifact mismatches before dispatch time.

Phase 6

• Shadow mode parity execution dispatches real graph observer runs alongside authoritative legacy dispatch
• Progress: Workflow runs now expose a comparison endpoint that resolves authoritative legacy outputs and matching shadow artifacts, including file hashes, image dimensions, and mean pixel delta for parity inspection.
• Progress: scripts/test_render_pipeline.py --workflow-still-smoke --execution-mode shadow now provisions the canonical still smoke contract, runs preflight, dispatches via the real order/output-type workflow linkage, resolves the resulting workflow run, and prints the shadow comparison verdict.
• Golden cases pass against legacy outputs
• Progress: On April 8, 2026, the live --workflow-golden-suite passed end to end for still_legacy, still_graph, still_shadow, turntable_graph, and blend_graph. The blend export contract now completes the order line, persists the primary .blend result, and links the resulting blend_production media asset back to the workflow run.
• Rollout can be enabled per workflow or output type
• Rollback to legacy is immediate

Quality Gates

QG-1: Model Gate

• New workflow saves only use canonical schema.
• Backend rejects malformed configs with clear errors.
• Existing preset workflows can be migrated without data loss.

QG-2: Node Gate

• Every editor-visible node has:
  • backend node definition
  • validated settings schema
  • default params
  • family and module contract metadata
  • executor coverage or explicit disabled status

QG-3: Legacy Safety Gate

• Legacy render dispatch remains callable and unchanged in behavior.
• Existing output types still render without workflow migration.
• Graph failures do not block legacy renders.

QG-4: Parity Gate

• Golden cases match on:
  • render status
  • generated output file
  • media asset creation
  • notifications
  • core render log fields
• For graph still renders with downstream output_save, no duplicate self-published MediaAsset is created before the authoritative graph save step completes.
• For graph turntable/video renders with downstream output_save, no duplicate self-published MediaAsset is created before the authoritative graph save step completes.
• For graph .blend exports with downstream output_save, no duplicate self-published MediaAsset is created before the authoritative graph save step completes.

QG-5: Editor Gate

• Workflow configs survive save/load roundtrip without loss.
• Invalid graphs are blocked before dispatch.
• All node settings needed for parity are present in the editor.
• Family-specific authoring prevents invalid cad_file/order_line graph composition.
• Progress: Backend-owned still bridge modules now declare the settings required for parity; the next gate is browser-level confirmation that the inspector presents them cleanly enough for real authoring.

QG-7: Invocation Gate

• Output type creation and editing use valid backend defaults.
• Output types bind to workflows through an explicit invocation contract.
• Legacy output types remain renderable during migration.
• Progress: This gate is functionally green at the API layer. Remaining rollout work is operational adoption, not missing contract primitives.

QG-6: Rollout Gate

• Shadow mode has been exercised on representative workflows.
• Graph runtime error rate is at or below legacy error rate.
• Rollout and rollback are possible per workflow or output type.
• Canonical still rollout smoke commands:
  • python scripts/test_render_pipeline.py --workflow-still-smoke --execution-mode legacy
  • python scripts/test_render_pipeline.py --workflow-still-smoke --execution-mode graph
  • python scripts/test_render_pipeline.py --workflow-still-smoke --execution-mode shadow
• Sequential low-RAM gate wrapper:
  • ./scripts/workflow_sequential_gates.sh
  • ./scripts/workflow_sequential_gates.sh --with-cad-parity
  • ./scripts/workflow_sequential_gates.sh --with-live-shadow
  • ./scripts/workflow_sequential_gates.sh --with-cad-parity --with-live-shadow --with-golden
• CAD/Viewer parity smoke for repeated-instance products:
  • python3 scripts/compare_live_cad_parity.py --cad-id 7c214057-9982-4d6e-aa87-43bfabfdb709
• Progress: The repeated-instance CAD regression now has a dedicated live gate. The current reference case passes with 146 manifest parts, 146 mesh nodes, 146 unique partKeys, and no missing or duplicate assignments.
• Rollout approval rule for the canonical still workflow:
  • shadow must finish with a successful order line and a comparison verdict of pass
  • warn or fail means legacy remains authoritative
  • graph may only be enabled on real output types after the shadow command passes cleanly
• Progress: the canonical still smoke flow now passes live in legacy, graph, and shadow. Shadow observer output may arrive slightly later than the authoritative legacy file, but the rollout gate now treats proven de-minimis Blender drift as pass instead of a rollout-blocking warn.
• Progress: the live smoke and golden harnesses now provision explicit workflow_rollout_mode values when linking non-legacy output types, so graph and shadow exercises no longer depend on whatever rollout state happened to be left behind in the database.
• Progress: the broader golden suite is green in live graph execution, and the remaining rollout work is operational enablement per workflow/output type rather than still-shadow image drift.

Definition of Done

• /workflows is production-capable for authoring and running workflows.
• Legacy functionality is available in graph form with parity coverage.
• Legacy execution still exists as a supported fallback.
• Output types are modeled as workflow invocation profiles, not as loose legacy render presets.