---
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:

```bash
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.*