Module events 

Append-only workflow event log — .devflow/events.jsonl.

One JSON object per line, schema v1:

{"v":1,"ts":1752600000,"phase":14,"event":"transition","from":"code","to":"validate"}

Every line carries v, ts (unix seconds), phase, and event; the remaining fields are kind-specific. The log exists so any frontend (TUI, Hermes plugin, web) can observe a running loop by tailing one file instead of integrating with DevFlow internals — it is the read side of the gate notify hook’s push side.

Emission is fail-soft: an unwritable log warns and returns — recording an event must never abort the workflow it records. Appends are a single write_all of a complete line on an O_APPEND handle, so concurrent phase monitors’ lines interleave without tearing.

Functions

describe

Render an event as a short human-readable summary (“gate_fired (ship)”).

emit

Append one event line. fields supplies the kind-specific payload and must be a JSON object (anything else is recorded under a "data" key).

events_path

Path of a project’s event log.

last_event_for_phase

Read the last event line recorded for phase, if any.

last_events_by_phase

The most recent event per phase, from ONE read + parse pass over the log (14-CR-10) — devflow status renders N phases without N full-file scans.