coulomb/the-custodian
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Cleanup of documentation

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-02 00:46:07 +02:00
parent 37d54cbbd4
commit f4e00f5070
14 changed files with 156 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
AGENTS.md
View File

@@ -100,6 +100,11 @@ Every Codex session in this repository must follow this ritual:
```
Requires postgres running (`make db`) and `custodian_test` database to exist.
Create it once with: `psql -U custodian -c "CREATE DATABASE custodian_test"`
Lifecycle movement is now flow-aware: use `get_flow_state()` to inspect
reachable workstations and `advance_workstation()` to move workstreams,
tasks, contributions, or capability requests when the target workstation's
requisite assertions are satisfied. Direct status updates remain available
for bootstrap, compatibility, and file-backed consistency syncs.
5. If any workplan files were written or modified this session, first ensure the
local copy is up to date, then run the consistency sync:
```bash

5
CLAUDE.md
View File

@@ -100,6 +100,11 @@ Every Claude Code session in this repository must follow this ritual:
```
Requires postgres running (`make db`) and `custodian_test` database to exist.
Create it once with: `psql -U custodian -c "CREATE DATABASE custodian_test"`
Lifecycle movement is now flow-aware: use `get_flow_state()` to inspect
reachable workstations and `advance_workstation()` to move workstreams,
tasks, contributions, or capability requests when the target workstation's
requisite assertions are satisfied. Direct status updates remain available
for bootstrap, compatibility, and file-backed consistency syncs.
5. If any workplan files were written or modified this session, first ensure the
local copy is up to date, then run the consistency sync:
```bash

3
agents/agent-scope-analyst.md
View File

@@ -14,6 +14,9 @@ This agent is now primarily a routing shim:
- inspect the target repository enough to decide whether a new SCOPE.md is
needed or an existing one should be refreshed;
- when tied to a State Hub workstream or task, prefer `get_flow_state()` for
lifecycle orientation and `advance_workstation()` for flow-aware movement
after requisite assertions are satisfied;
- prefer `scope.generate` when no SCOPE.md exists or the file is only a stub;
- prefer `scope.update` when a SCOPE.md exists but State Hub reports missing
sections, invalid capability blocks, or stale boundaries;

26
memory/working/260224-wishlist-custodian.md
View File

@@ -221,5 +221,27 @@ EPs need to be surfaced in `get_state_summary()`.
| W2 | `register_project.sh` script + `make register-project` | 1 hr | 25K / registration | Before next project |
| W5 | `TOOLS.md` reference card | 30 min | 2,500 / session | Next custodian session |
| W4 | Topic IDs in canon charters | 20 min | 200 / registration | Low urgency |
| W7 | SessionStart hook for API health | 30 min | Indirect | After W2 |
| W8 | First-class EP entity in state hub (EP-CUST-001) | 2–4 hr | Indirect | When EP count warrants it |
| W7 | SessionStart hook for API health | 30 min | Indirect | After W2 |
| W8 | First-class EP entity in state hub (EP-CUST-001) | 2–4 hr | Indirect | When EP count warrants it |
---
## 2026-05-02 Update — Task-Flow Engine Lifecycle Model
CUST-WP-0035 replaced the old assumption that State Hub lifecycle movement is
only a fixed set of status enums and hardcoded transition tables.
Current model:
- Information objects expose a stored workstation label, still surfaced as
`status` for API compatibility.
- `get_flow_state(entity_type, entity_id)` reports reachable workstations,
unreachable workstations, and blocking assertions.
- `advance_workstation(entity_type, entity_id, target_workstation)` is the
preferred lifecycle movement tool when a flow definition exists.
- Direct status update tools remain useful for bootstrap, legacy workflows, and
file-backed consistency sync, but they are no longer the conceptual center of
lifecycle management.
Reference spec:
`state-hub/docs/task-flow-engine-spec.md`

23
state-hub/dashboard/src/docs/capabilities.md
View File

@@ -96,7 +96,7 @@ This means the requester never needs to know which domain owns a capability.
---
## Request lifecycle
## Request flow
```
requested → accepted → in_progress → ready_for_review → completed
@@ -105,7 +105,7 @@ requested → accepted → in_progress → ready_for_review → completed
withdrawn
```
| Status | Meaning |
| Workstation | Meaning |
|--------|---------|
| **requested** | Need declared; routed (or broadcast) to provider |
| **accepted** | Provider acknowledged and claimed the request |
@@ -115,14 +115,17 @@ requested → accepted → in_progress → ready_for_review → completed
| **rejected** | Provider cannot or will not fulfil the request |
| **withdrawn** | Requester cancelled the request |
Transitions are enforced by the API — you cannot skip stages. Terminal states
(`completed`, `rejected`, `withdrawn`) allow no further transitions.
Request movement is flow-aware. The API evaluates the target workstation's
entry assertions and rejects unreachable movement with machine-readable
blocking assertions. Terminal workstations (`completed`, `rejected`,
`withdrawn`) have no reachable outgoing path in the current flow definition.
---
## Auto-notifications
Every lifecycle transition creates an **AgentMessage** atomically:
Every request movement handled by the capability request API creates an
**AgentMessage** atomically:
| Transition | Notification to |
|------------|----------------|
@@ -182,17 +185,17 @@ accept_capability_request(
)
```
Then advances through the lifecycle:
Then advances through the flow:
```
update_capability_request_status(request_id, "in_progress")
update_capability_request_status(request_id, "ready_for_review", note="Instance up at 10.0.1.42")
advance_workstation(entity_type="capability_request", entity_id=request_id, target_workstation="in_progress")
advance_workstation(entity_type="capability_request", entity_id=request_id, target_workstation="ready_for_review")
```
The requester reviews and completes:
```
update_capability_request_status(request_id, "completed", note="Verified, looks good")
advance_workstation(entity_type="capability_request", entity_id=request_id, target_workstation="completed")
```
---
@@ -203,7 +206,7 @@ The Capabilities page shows:
- **KPI sidebar** — open count, average fulfillment time, high/critical count
- **Summary cards** — requested, in progress, ready for review, completed
- **Kanban board** — cards grouped by status column
- **Kanban board** — cards grouped by workstation/status column
- **Table** — all requests with filters by type, status, and domain
Each card shows the capability type, priority, requester → provider domains,

17
state-hub/dashboard/src/docs/contributions.md
View File

@@ -22,7 +22,7 @@ registered in the state hub so it is never lost.
---
## Lifecycle
## Flow workstations
```
draft → submitted → acknowledged → accepted → merged
@@ -30,7 +30,7 @@ draft → submitted → acknowledged → accepted → merged
rejected withdrawn
```
| Status | Meaning |
| Workstation | Meaning |
|--------|---------|
| **draft** | Artifact written locally; not yet sent upstream |
| **submitted** | Filed as a GitHub issue, PR, or email — awaiting upstream response |
@@ -40,9 +40,12 @@ draft → submitted → acknowledged → accepted → merged
| **rejected** | Upstream declined; record kept for future reference |
| **withdrawn** | We decided not to pursue it |
Transitions are enforced by the API — you cannot skip stages arbitrarily.
`submitted_at` is stamped automatically when status moves to `submitted`;
`resolved_at` is stamped when status moves to `merged`, `rejected`, or `withdrawn`.
Contribution movement is evaluated by the task-flow engine. The API asks
whether the target workstation is reachable from the current information
object; if not, it returns structured blocking assertions instead of a generic
"transition not allowed" message. `submitted_at` is stamped automatically when
the contribution reaches `submitted`; `resolved_at` is stamped when it reaches
`merged`, `rejected`, or `withdrawn`.
---
@@ -57,7 +60,7 @@ communication taxonomy:
| Ecosystem | State hub task with `[repo:<slug>]` prefix |
| **Third-party** | **Contribution artifact in `contrib/` + state hub registration** |
Contributions in `draft`, `submitted`, or `acknowledged` status appear as
Contributions in `draft`, `submitted`, or `acknowledged` workstations appear as
open Third-party todos on the [Todo](/todo) page.
---
@@ -99,7 +102,7 @@ register_contribution(
**3. Close the loop** when you file it upstream:
```
update_contribution_status(contribution_id="<uuid>", status="submitted")
advance_workstation(entity_type="contribution", entity_id="<uuid>", target_workstation="submitted")
```
**4. Keep updating** as upstream responds — `acknowledged`, `accepted`, `merged`.

5
state-hub/dashboard/src/docs/inter-repo-communication.md
View File

@@ -115,7 +115,7 @@ framework you use but do not own.
```
3. When submitted upstream, close the loop:
```python
update_contribution_status(contribution_id="<uuid>", status="submitted")
advance_workstation(entity_type="contribution", entity_id="<uuid>", target_workstation="submitted")
```
Templates: `~/the-custodian/canon/standards/contrib-templates/`
@@ -129,7 +129,8 @@ The session orientation protocol (every repo's CLAUDE.md) surfaces todos from
two sources:
**Internal todos** (Step 2 of orientation) — workplan files in `workplans/`
with `status: active`, tasks with `status: todo` or `in_progress`.
whose stored workstation/status label is `active`, with tasks in `todo` or
`in_progress`.
**Ecosystem todos targeting this repo** (Step 1 of orientation) —
`get_state_summary()` returns all open tasks across all workstreams. The session

1
state-hub/dashboard/src/docs/progress-log.md
View File

@@ -40,6 +40,7 @@ These types are used by the State Hub's built-in write operations:
|---|---|
| `workstream_created` | A new workstream was registered |
| `workstream_status_changed` | Workstream moved to active / blocked / completed / archived |
| `workstation_advanced` | Flow-aware movement via `advance_workstation()` succeeded |
| `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 |

18
state-hub/dashboard/src/docs/tasks.md
View File

@@ -5,13 +5,17 @@ title: Tasks — Reference
# Tasks — Reference
The Tasks page shows all tasks across every workstream and domain, with live
filtering, a status distribution chart, and a blocked-tasks highlight section.
filtering, a workstation distribution chart, and a blocked-tasks highlight
section.
---
## Task statuses
## Task workstations
| Status | Meaning |
Tasks still expose their current workstation through the `status` field for API
compatibility.
| Workstation | Meaning |
|--------|---------|
| **todo** | Not yet started |
| **in_progress** | Actively being worked on |
@@ -45,10 +49,10 @@ All filters are applied client-side after each poll.
---
## Status Distribution chart
## Workstation Distribution chart
A horizontal bar chart (Observable Plot) showing the count of filtered tasks
per status, colour-coded:
per stored workstation/status label, colour-coded:
| Colour | Status |
|--------|--------|
@@ -62,8 +66,8 @@ per status, colour-coded:
## Blocked Tasks section
Shows cards for every task currently in `blocked` status within the active
filter. Each card displays:
Shows cards for every task currently in the `blocked` workstation within the
active filter. Each card displays:
- Priority badge and status
- Domain and workstream context

5
state-hub/dashboard/src/docs/workstream-health-index.md
View File

@@ -76,7 +76,10 @@ Detects concentration of blocking power. High SPR means one delay propagates wid
PEP = active workstreams with all deps completed / (active + blocked)
```
Estimates how much work can proceed right now. A workstream is eligible if its status is `active` and every workstream it depends on has reached `completed` or `archived`.
Estimates how much work can proceed right now. A workstream is eligible if its
stored workstation label is `active` and the flow/dependency checks report no
unmet dependency assertion; practically, every workstream it depends on has
reached `completed` or `archived`.
| PEP | Warning |
|---|---|

65
state-hub/dashboard/src/docs/workstream-lifecycle.md
View File

@@ -4,40 +4,43 @@ title: Workstream Lifecycle — Reference
# Workstream Lifecycle — Reference
A workstream moves through a defined lifecycle from creation to sign-off. The
dashboard "Workstreams by Domain" chart exposes these states as selectable
filters so attention can be directed to the right workstreams at the right time.
A workstream is an information object that occupies a named workstation. The
stored `status` field keeps the current workstation label, while the
task-flow engine derives which other workstations are reachable and which exit
assertions are blocking movement. The dashboard "Workstreams by Domain" chart
exposes stored and derived states as selectable filters so attention can be
directed to the right workstreams at the right time.
---
## Core lifecycle states
## Core workstations
These are the primary stages a workstream passes through in order:
These are the primary workstations used by State Hub workstreams:
| State | Source | Meaning |
| Workstation | Source | Meaning |
|---|---|---|
| **active** | DB `status = active` | Work is in progress or ready to start |
| **finished** | Derived — no open tasks | All tasks are done, but no explicit review has taken place yet |
| **accepted** | DB `status = completed` | Custodian and human have reviewed the workstream, quality checks passed, and it is formally signed off |
The normal progression is: **active → finished → accepted**.
The normal human-facing path is: **active → finished → accepted**.
`accepted` is the only state that requires an explicit action — it is set after
a deliberate review, not automatically. This makes it a reliable anchor:
anything in `finished` but not yet in `accepted` is work that still needs a
quality pass.
`accepted` is the only state that requires an explicit action. It is reached by
advancing the workstream to the `completed` workstation after deliberate
review, not by task counts alone. This makes it a reliable anchor: anything in
`finished` but not yet in `accepted` is work that still needs a quality pass.
---
## Attention signals
These states are orthogonal to the core lifecycle — a workstream can be
These signals are orthogonal to the core workstation — a workstream can be
`active` and `stalled` at the same time. They serve as health indicators
rather than lifecycle stages.
rather than stored lifecycle stages.
| Signal | Source | Meaning |
|---|---|---|
| **blocked** | Derived — has ≥ 1 blocked task | At least one task is waiting on something external |
| **blocked** | Derived — unmet exit assertion or blocked task | Work cannot currently leave its workstation; inspect `blocked_reasons` |
| **stalled** | Derived — `updated_at` > 7 days ago, has both done and open tasks | Work started but activity has stopped; needs a nudge |
| **oldies** | Derived — `created_at` > 7 days ago, zero done tasks | Workstream is old and nothing has been completed yet; may need re-evaluation |
@@ -50,14 +53,15 @@ When a workstream reaches **finished** (all tasks done), the custodian's role is
1. Review the deliverables against the workstream's stated purpose and scope
2. Check for missing tests, documentation, or follow-up issues
3. Create tasks for any gaps found — this moves the workstream back to **active**
4. Once satisfied, set `status = completed` via MCP or API — this marks it as **accepted**
4. Once satisfied, advance to the `completed` workstation — this marks it as **accepted**
This pattern ensures that "done" and "accepted" are distinct signals.
`finished` is a fact about task counts; `accepted` is a statement of quality.
```
# Accept a workstream via MCP
update_workstream_status(workstream_id="<uuid>", status="completed")
# Inspect and accept a workstream via MCP
get_flow_state(entity_type="workstream", entity_id="<uuid>")
advance_workstation(entity_type="workstream", entity_id="<uuid>", target_workstation="completed")
# Or via REST
curl -X PATCH http://127.0.0.1:8000/workstreams/<uuid>/ \
@@ -86,19 +90,22 @@ workstreams to distinguish notable states at a glance.
---
## DB status vs. dashboard state
## Stored Label Vs. Dashboard State
The DB stores a single `status` field on each workstream. The dashboard maps
this alongside derived task-count data to produce the richer set of filter states:
The DB stores a single `status` field on each workstream. Treat it as the
current workstation label. The dashboard maps this alongside flow-engine
results, dependency assertions, and task-count data to produce the richer set
of filter states:
| Dashboard state | DB `status` | Task-count condition |
| Dashboard state | Stored label / derived source | Condition |
|---|---|---|
| active | `active` | — |
| accepted | `completed` | — |
| finished | any | `todo + in_progress + blocked = 0` |
| blocked | any | `blocked ≥ 1` |
| stalled | any | `done ≥ 1` and `open ≥ 1` and `updated_at > 7d ago` |
| oldies | any | `done = 0` and `open ≥ 1` and `created_at > 7d ago` |
| active | `status = active` | — |
| accepted | `status = completed` | — |
| finished | task counts | `todo + in_progress + blocked = 0` |
| blocked | flow result / task counts | `exit_blocked = true` or `blocked ≥ 1` |
| stalled | task counts + timestamp | `done ≥ 1` and `open ≥ 1` and `updated_at > 7d ago` |
| oldies | task counts + timestamp | `done = 0` and `open ≥ 1` and `created_at > 7d ago` |
*Workstreams are never hard-deleted — use `update_workstream_status(..., "completed")` or
`"archived"` to close them without losing history.*
*Workstreams are never hard-deleted — use `advance_workstation(...,
"completed")` or advance/patch to `"archived"` to close them without losing
history.*

35
state-hub/dashboard/src/docs/workstreams.md
View File

@@ -4,22 +4,30 @@ title: Workstreams — Reference
# Workstreams — Reference
A workstream is a bounded unit of work within a topic. It carries a status, an optional owner and due date, and belongs to exactly one of the six project domains. The Workstreams page gives you a filtered, visual overview of all active work and the dependency graph between workstreams.
A workstream is a bounded unit of work within a topic. It carries a stored
workstation label in the `status` field, an optional owner and due date, and
belongs to exactly one project domain. The Workstreams page gives you a
filtered, visual overview of active work, derived blocked state, and the
dependency graph between workstreams.
---
## Status Distribution chart
## Workstation Distribution chart
A horizontal bar chart showing the count of workstreams in each status for the current filter selection. Updates immediately as filters change.
A horizontal bar chart showing the count of workstreams in each stored
workstation/status label for the current filter selection. Updates immediately
as filters change.
| Status | Meaning |
| Workstation | Meaning |
|---|---|
| **active** | Work in progress or ready to start |
| **blocked** | Waiting on something outside the workstream — see Dependencies |
| **blocked** | Stored blocker label; the State Hub can also derive blocked state from unmet exit assertions |
| **completed** | Formally accepted after custodian review (shown as **accepted** in the overview chart) |
| **archived** | Closed without completion; no longer relevant |
See [Workstream Lifecycle](/docs/workstream-lifecycle) for the full state model including derived states (finished, stalled, oldies).
See [Workstream Lifecycle](/docs/workstream-lifecycle) for the full task-flow
model including derived states (finished, stalled, oldies) and assertion-based
blocking.
---
@@ -28,7 +36,7 @@ See [Workstream Lifecycle](/docs/workstream-lifecycle) for the full state model
| Filter | Effect |
|---|---|
| **Domain** | Multi-select — show only workstreams from selected domains |
| **Status** | Multi-select — show only workstreams with selected statuses |
| **Status** | Multi-select — show only workstreams with selected workstation labels |
| **Owner** | Text substring match on the owner field (case-insensitive) |
Leaving a filter empty means "show all". All three filters combine with AND logic. Filters persist across polls — selections are not lost when the page refreshes live data.
@@ -43,7 +51,7 @@ The six domains are: `custodian`, `railiance`, `markitect`, `coulomb_social`, `p
|---|---|
| Title | Workstream title |
| Domain | Derived from the parent topic |
| Status | Current workstream status |
| Status | Current stored workstation/status label |
| Owner | Assigned person (or `—` if unset) |
| Due | Target completion date (or `—`) |
| Updated | Last modification timestamp |
@@ -99,13 +107,18 @@ curl -X POST http://127.0.0.1:8000/workstreams/ \
---
## Updating workstream status
## Advancing a workstream
```
update_workstream_status(workstream_id="<uuid>", status="completed")
get_flow_state(entity_type="workstream", entity_id="<uuid>")
advance_workstation(entity_type="workstream", entity_id="<uuid>", target_workstation="completed")
```
Valid transitions: `active` → `blocked` / `completed` / `archived`; `blocked` → `active`; `completed` → `archived`.
Movement is flow-aware: the task-flow engine evaluates the target
workstation's entry assertions and returns structured blocking assertions when
the target is not reachable. Direct status patching still exists for bootstrap
and compatibility work, but normal lifecycle movement should prefer
`advance_workstation()`.
---

12
state-hub/policies/repo-doi.md
View File

@@ -16,7 +16,9 @@ These are the minimum requirements for the state-hub to be aware of a repo.
`GET /repos/{slug}`
- [ ] **Domain assigned** — repo is linked to an active domain. The domain must
exist in `domains` and be in `active` status.
exist in `domains` and be in `active` status. Domain status is still a
simple administrative label; workstream/task lifecycle labels are now treated
as task-flow workstations.
- [ ] **Local path resolves** — `_resolve_repo_path()` finds an existing
directory on the current host (either via `host_paths[hostname]` or
@@ -43,6 +45,9 @@ A repo at this tier participates in state-hub tracking and tooling.
- [ ] **Workplan convention followed** — any workplans live under
`workplans/<ID>-<slug>.md` with valid YAML frontmatter
(`id`, `type`, `title`, `domain`, `status`, `state_hub_workstream_id`).
The frontmatter `status` is the file-backed source for the workstream's
stored workstation label. Derived blocked state and blocking reasons come
from the task-flow engine, not from the frontmatter alone.
Verified by: `make check-consistency REPO={slug}` → PASS or WARN only
(no FAIL).
@@ -118,3 +123,8 @@ A fully integrated repo contributes to cross-repo planning and capability routin
- A repo may satisfy **Standard** without **Full** indefinitely — Full
integration is appropriate when the repo is actively contributing to
cross-domain work or exposing capabilities to other repos.
- For lifecycle inspection, prefer `get_flow_state(entity_type, entity_id)` and
`advance_workstation(entity_type, entity_id, target_workstation)` over
reasoning from stored status labels alone. Stored labels remain important for
filtering and compatibility, but DoI health should use structured flow
results when blocking assertions matter.

12
workplans/CUST-WP-0037-task-flow-reference-docs-cleanup.md → workplans/archived/260502-CUST-WP-0037-task-flow-reference-docs-cleanup.md
View File

@@ -4,7 +4,7 @@ type: workplan
title: "Task-Flow Reference Documentation Cleanup"
domain: custodian
repo: the-custodian
status: todo
status: completed
owner: custodian
topic_slug: custodian
created: "2026-05-01"
@@ -28,7 +28,7 @@ stabilize before broad documentation churn.
```task
id: CUST-WP-0037-T01
status: todo
status: done
priority: medium
state_hub_task_id: "919d21cb-1cdc-448e-a722-38f1b6374ffb"
```
@@ -44,7 +44,7 @@ without implying that lifecycle movement is controlled by fixed enum tables.
```task
id: CUST-WP-0037-T02
status: todo
status: done
priority: medium
state_hub_task_id: "d6485f6c-815f-4f50-a35e-3fd42046691f"
```
@@ -60,7 +60,7 @@ task-flow-engine model.
```task
id: CUST-WP-0037-T03
status: todo
status: done
priority: medium
state_hub_task_id: "79251442-12a0-4a00-9e3a-fc484933259d"
```
@@ -75,7 +75,7 @@ flow-aware lifecycle movement is relevant.
```task
id: CUST-WP-0037-T04
status: todo
status: done
priority: medium
state_hub_task_id: "e2a9d096-b66a-43f2-af87-ec802ba9e795"
```
@@ -90,7 +90,7 @@ keeping direct status tools documented for bootstrap or compatibility cases.
```task
id: CUST-WP-0037-T05
status: todo
status: done
priority: low
state_hub_task_id: "2320cd6b-8dc6-4160-9623-4e6425b637e5"
```