From 22b4618abdce6f7a19f3b7ac290c366a7e40d7b2 Mon Sep 17 00:00:00 2001 From: tegwick Date: Thu, 26 Feb 2026 18:03:05 +0100 Subject: [PATCH] dashboard: add progress log documentation and ? button on page heading MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - src/docs/progress-log.md: covers append-only constitution §5 guarantee, event structure (all fields), standard + convention event types, session protocol, MCP and curl usage, filters, and the 30-day volume chart - progress.md: withDocHelp applied to #observablehq-main h1 → ? button appears on hover over the 'Progress Log' page heading - observablehq.config.js: Progress Log added to Reference nav section Co-Authored-By: Claude Sonnet 4.6 --- state-hub/dashboard/observablehq.config.js | 1 + state-hub/dashboard/src/docs/progress-log.md | 113 +++++++++++++++++++ state-hub/dashboard/src/progress.md | 3 + 3 files changed, 117 insertions(+) create mode 100644 state-hub/dashboard/src/docs/progress-log.md diff --git a/state-hub/dashboard/observablehq.config.js b/state-hub/dashboard/observablehq.config.js index cf1183c..3d994ff 100644 --- a/state-hub/dashboard/observablehq.config.js +++ b/state-hub/dashboard/observablehq.config.js @@ -11,6 +11,7 @@ export default { pages: [ { name: "Live Data", path: "/docs/live-data" }, { name: "Decision Health", path: "/docs/decisions-kpi" }, + { name: "Progress Log", path: "/docs/progress-log" }, ], }, ], diff --git a/state-hub/dashboard/src/docs/progress-log.md b/state-hub/dashboard/src/docs/progress-log.md new file mode 100644 index 0000000..0f42aef --- /dev/null +++ b/state-hub/dashboard/src/docs/progress-log.md @@ -0,0 +1,113 @@ +--- +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 Bernd. 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 = "", // link to relevant workstream (optional) + topic_id = "", // 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": "Bernd"}' +``` + +--- + +## Filters + +| Filter | Effect | +|---|---| +| **Author** | Restrict to events by a specific author (`custodian`, `Bernd`, 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.* diff --git a/state-hub/dashboard/src/progress.md b/state-hub/dashboard/src/progress.md index c2bf0d3..9587976 100644 --- a/state-hub/dashboard/src/progress.md +++ b/state-hub/dashboard/src/progress.md @@ -44,6 +44,9 @@ const _liveEl = html`
`; withDocHelp(_liveEl, "/docs/live-data"); injectTocTop("live-indicator", _liveEl); + +const _h1 = document.querySelector("#observablehq-main h1"); +if (_h1) { _h1.style.position = "relative"; withDocHelp(_h1, "/docs/progress-log"); } ``` ## Event Volume (Last 30 Days)