Module workflow 

Workflow state persistence helpers.

State is per-phase: each active phase persists to .devflow/state-{phase:02}.json (mirroring the per-phase lock naming), so devflow parallel sibling phases never clobber one another (13-DEFERRED-CR-03). A legacy single-slot .devflow/state.json from an older binary is migrated to its per-phase name on first read.

Enums

WorkflowError

Errors produced while reading or writing workflow state.

Functions

clear_state

Remove a phase’s persisted state if present.

devflow_dir

Return the .devflow directory for a project.

ensure_devflow_dir

Create dir (and any missing parents), then self-protect any .devflow directory found in its path by writing <that-dir>/.gitignore containing * — so a downstream user’s routine git add . && git commit never sweeps DevFlow’s runtime artifacts (agent stdout, gate context, state) into their repository, independent of whether their own root .gitignore mentions .devflow at all (closes 19a-WR-01, 19-CONTEXT.md D-14).

list_states

Enumerate every active phase state, sorted by phase number.

load_state

Load workflow state for a phase from .devflow/state-{NN}.json.

remove_corrupt_legacy_state

Delete a legacy state.json that cannot be parsed — and therefore can never be migrated by [migrate_legacy_state] or matched by clear_state’s phase check (14-CR-04). Ordinary reads deliberately leave such a file in place; only the operator-driven reset (recover --clean) is sanctioned to call this. Returns whether a file was removed.

save_state

Save workflow state to .devflow/state-{NN}.json, keyed by state.phase.

state_path

Return the persisted state path for a phase of a project.