state-hub/dashboard/src/docs/progress-log.md

title

title
Progress Log — Reference

Progress Log — Reference

The progress event log is the episodic memory of the Custodian system. Every significant action, decision, insight, or state change is recorded here as an immutable event. The log is the single source of truth for what happened, when, and why.

---

Append-only by design

Per constitution §5, progress events are never deleted or edited. The API exposes no DELETE endpoint for this resource. Every event is permanent. This guarantees that future sessions — and future humans — can reconstruct the full history of any project without gaps.

---

Event structure

Each event carries:

Field	Type	Description
summary	string	Human-readable one-line description of what happened
event_type	string	Free-form label categorising the event (see below)
author	string	Who created the event — custodian for agent-generated events, or a human name
topic_id	UUID?	Links the event to a topic (optional)
workstream_id	UUID?	Links to a workstream (optional)
task_id	UUID?	Links to a task (optional)
decision_id	UUID?	Links to a decision (optional)
detail	JSON?	Arbitrary structured data — commits, counts, file paths, metrics, etc.
created_at	timestamp	Set by the server on insert; cannot be overridden

---

Standard event types

These types are used by the State Hub's built-in write operations:

Type	When emitted
workstream_created	A new workstream was registered
workstream_status_changed	Workstream moved to active / blocked / completed / archived
task_created	A new task was added to a workstream
task_status_changed	Task moved to todo / in_progress / blocked / done / cancelled
decision_recorded	A decision (pending or made) was recorded
decision_resolved	A pending decision was resolved

Any other string is valid. Common conventions:

Type	Meaning
milestone	A significant completion or threshold was reached
note	General observation or session summary
blocker	An impediment was identified
insight	A discovery that changes how work should proceed
extension_point	An EP-DOMAIN-NNN extension point was identified

---

Session protocol

Every Claude Code session working in this repository should:

1. Start — call get_state_summary() for orientation
2. End — call add_progress_event() to log what was done, decided, or discovered

A session that produces no progress events is invisible to future sessions and to the human. The log is how continuity is maintained across context windows.

---

Adding events

Via the MCP server (in a Claude Code session):

add_progress_event(
  summary    = "What happened, in one clear sentence",
  event_type = "milestone",          // or note, blocker, insight, …
  workstream_id = "<uuid>",          // link to relevant workstream (optional)
  topic_id      = "<uuid>",          // link to relevant topic (optional)
  detail        = { "key": "value" } // any structured data worth preserving
)

Via the REST API directly:

curl -X POST http://127.0.0.1:8000/progress/ \
  -H "Content-Type: application/json" \
  -d '{"summary": "…", "event_type": "note", "author": "human"}'

---

Filters

Filter	Effect
Author	Restrict to events by a specific author (custodian, human, etc.)
Event type	Restrict to one category of event
Since	Show only events after a chosen date

All filters are applied client-side against the last 500 events fetched from the API. The count line above the table reflects the active filter.

---

Event Volume chart

The area chart above the log shows the number of events per day over the last 30 days, using the full unfiltered dataset. It gives a quick sense of activity rhythm — steeper slopes mean more active periods.

---

Append-only per constitution §5 — no deletions, no edits, ever.