state-hub/dashboard/src/docs/todo.md

---
title: Todo — Reference
---

# Todo — Reference

The Todo page shows the Custodian's own open work items classified by where the
work belongs — inside this repo, routed from another ecosystem repo, or aimed
at an upstream third-party project.

This page is the session-start orientation surface for the `the-custodian` repo.
See [Inter-Repo Communication](/docs/inter-repo-communication) for the full
boundary rule and routing workflows.

---

## The three classes

### Internal

Open tasks (`wait`, `todo`, `progress`) in **custodian domain workstreams**
whose title does not contain a `[repo:]` routing prefix.

These are tasks this agent is directly responsible for and can address within
the current repo.

### Ecosystem (inbound)

Tasks from **any workstream** whose title contains `[repo:the-custodian]`.

These tasks were created by agents in other repos to route work to the custodian.
When a task with this prefix appears, the session protocol picks it up, the
custodian creates a workplan file (ADR-001), and addresses the work here.

### Third-party (outbound)

Contribution artifacts in **open status** (`draft`, `submitted`, `acknowledged`).

These represent work the custodian has identified for upstream repos it does not
own. They remain on the todo list until the upstream loop is closed (`merged`,
`rejected`, or `withdrawn`).

---

## Classification decision table

| Situation | Class | Action |
|-----------|-------|--------|
| Bug found in this repo | Internal | Fix it directly |
| Work needed in another registered repo | Ecosystem | `create_task(..., title="[repo:<slug>] ...")` |
| Bug found in an upstream library | Third-party | Create BR artifact + `register_contribution` |
| Feature needed from upstream | Third-party | Create FR artifact + `register_contribution` |

---

## KPI sidebar card

Shows the count of open items in each class at a glance. The `?` button links
to this reference page.

---

## Data sources

Polls every **15 seconds**:
- `GET /tasks/?limit=500` — all tasks
- `GET /workplans/` — for domain + title context
- `GET /topics/` — for domain slug resolution
- `GET /contributions/` — for third-party todos

*Classification is done client-side — no server-side filter endpoint required.*