How-to guide For operators

Change the workflow

Edit the phases, steps, gates and RACI the factory builds every data product through, without touching the application's code.

Before you start

A copy of the shipped dpf/workflow.yaml to start from — its header comment states the shape and the rules a file has to follow.
For a genuinely new step rather than a reworded one: the code that will tell the application when it is done — see "A new step needs code too", below.

Steps

Copy dpf/workflow.yaml and edit it: phases (key, title, purpose, outcome, artefact, gate, raci) and steps (key, title, phase, who, summary, plus needs / produces / agent / decides / deterministic_because / manual / owner as the step needs them). The file's own header comment is the authority on the shape.
Validate it:
```
.venv/bin/python -m dpf workflow path/to/your.yaml
```
It prints every phase and step when the file is sound, and the complete list of problems — not only the first — when it is not. 3. Point the deployment at it and restart:
```
export DPF_WORKFLOW=path/to/your.yaml
```
4. If a step is new rather than reworded, wire up what it produces — see below — before anybody relies on it.

Check that it worked

The Workflow page's factbar shows File, Schema and Revision — a sha256 fingerprint of the loaded file's contents, because two installations both claiming version 1 can be running different processes. A product already under way keeps the revision it was started under: if the shipped file has changed since, that product's own page carries a changed since this was started badge linking back to Workflow, rather than silently moving it onto a process nobody agreed to.

What validation refuses

dpf workflow fails with the file named and every problem listed at once, including:

A phase with no key or title, defined twice, or missing a gate, an outcome or an artefact — a phase that produces no document produces nothing anybody outside the team can read.
A gate whose step is not one of that phase's own steps.
A step with no key, title or summary, defined twice, in an unknown phase, or with who outside human / agent / auto.
An agent step with no agent named, or a non-agent step naming one.
An auto step with no deterministic_because — the argument for not making it a model belongs in the file, not a meeting.
Two steps produces-ing the same name, or a step producing nothing — state is derived from what exists, so either breaks that.
A step that needs something undefined, or defined later than itself.
parallel: true with no blocks, blocks set without parallel: true, or blocks naming a step that comes before it.
A RACI slot naming something that is not one of the roles the application actually has.

A new step needs code too

A step's state is derived, never stored: it counts as done when whatever it produces exists. The YAML names that key; something has to put the corresponding artefact into the map the web layer builds and hands to the domain's walk() function — currently assembled in dpf/web/views.py (_flow_states) and read in dpf/domain/flow.py. A step that only renames or reorders existing work needs no code at all; one that produces a genuinely new artefact does.

If it does not work

Symptom	Fix
`dpf workflow FILE` lists several problems	Fix them together — it reports every one it finds, not only the first.
The factory won't start after setting `DPF_WORKFLOW`	The same validation runs at import. Run `dpf workflow FILE` against it directly to read the list without another restart.
A step stays "blocked"	Check what it `needs` — a parallel step still holds the gate it `blocks` until it is settled, even once everything else is done.
A product's page reads "changed since this was started"	Expected once the shipped file differs from the one the product began under — not an error.

Workflow — the phases, gates and steps this deployment is currently running.
0004 · The workflow is a validated file, not code — why.