state-hub/dashboard/src/docs/work-records.md

---
title: Work Records — Reference
---

# Work Records — Reference

A **work record** is any identified, lifecycle-bearing coordination artefact
indexed by State Hub. Workplans and tasks are work records; so are intakes,
decisions, engagements, and register entries. The term is the shared umbrella
for planning, execution, and coordination — not a separate product surface.

Fleet canon (normative):
`the-custodian/canon/standards/work-record-types_v0.1.md` and the machine
registry `work-record-types.yaml`. This page describes what State Hub
implements and exposes today.

---

## Kind registry (closed list)

| Kind | Id scheme (typical) | Meaning in State Hub today |
|------|---------------------|----------------------------|
| **workplan** | `{PREFIX}-WP-NNNN` | Structured, dependency-bearing body of work; file under `workplans/` (ADR-001) |
| **task** | `{WP-ID}-TNN` · `ADHOC-YYYY-MM-DD-TNN` | Smallest executable unit; lives in a workplan file |
| **intake** | `{PREFIX}-IN-NNNN` | Spark: idea, finding, directive, or request before it is a plan/task |
| **decision** | `{PREFIX}-DEC-YYYY-NNN` (file) · hub decision entity | Approval package / recorded choice |
| **engagement** | `{PREFIX}-ENG-YYYY-NNN` | Scheduled external interaction (file-backed; hub entity not yet first-class) |
| **register-entry** | `RISK-…`, `TD-…`, `CAP-…`, `CCR-…`, `ADR-…` | Risks, debt, capability requests, credential change requests, ADRs |

Unregistered id patterns are rejected by CI and `statehub fix-consistency`
(sidetrack detector). New kinds are added only via the canon registry.

**Not a work-record kind today:** **contributions** (outbound third-party BR/FR/EP/UPR
artifacts). They remain a separate hub entity and dashboard surface — see
[Contributions](/docs/contributions).

---

## Conventional spine

Every work record carries the same conceptual fields (kind-specific fields
extend them; they do not replace them):

| Field | Role |
|-------|------|
| `id` | Human/agent canonical name (`STATE-WP-0074`, `CUST-IN-0004`, …) |
| `uuid` | Hub-assigned identity for relations and history (UUIDv7 for new intake and related entities; older tables may still use UUIDv4) |
| `kind` | One of the registered kinds |
| `lane` | Autonomy lane (`green` … `red`) where the entity supports it |
| `status` | Kind-specific lifecycle position |
| `owner` | Agent or human |
| `repo` | Owning repo (ADR-001 / ADR-005 anchor) |
| `tags` | Policy and derived labels — not lifecycle states |
| `created` / `updated` | Dates |

Hub write-back of UUIDs into source files uses the familiar
`state_hub_*_id` fields (for workplans the frontmatter key is still
`state_hub_workstream_id` for compatibility).

---

## Abstract lifecycles

| Kind | Lifecycle (stored `status` / outcome) |
|------|----------------------------------------|
| task | `wait → todo → progress → done \| cancel` |
| workplan | `proposed → ready → active → blocked → backlog → finished → archived` |
| intake | `open → vetted → routed → closed(promoted \| declined \| absorbed)` |
| decision | Canon file lifecycle: `prepared → resolved(…)`; hub decision page still uses its own status vocabulary — see [Decisions](/docs/decisions) |
| engagement | `queued → prepared → done` (file convention) |
| register-entry | Per existing register conventions |

Detail pages:

- [Workplan Lifecycle](/docs/workstream-lifecycle)
- [Tasks](/docs/tasks)
- [Intakes](/docs/intakes)
- [Decisions](/docs/decisions)

---

## Source files, registration, and index

1. **Workplans and tasks** are authored in dedicated `workplans/*.md` files
   (ADR-001). `fix-consistency` (C-06 and related checks) registers them and
   writes hub IDs back into the files.
2. **Intakes, decisions, and engagements** may appear as schema-valid YAML
   blocks in any repo markdown file. `fix-consistency` registers intake and
   decision blocks and writes `state_hub_intake_id` (and decision IDs) back when
   present.
3. **Generated index:** each repo may have a `WORK-RECORDS.md` (or equivalent)
   produced by fix-consistency — a read-only orientation table of indexed
   records and their source paths. Do not hand-edit it.
4. The hub remains a **read model** for formal structure: files are source of
   truth for workplans/tasks; hub-first bootstrap tools exist but are not the
   steady-state path.

Promotion from intake to another kind is a first-class operation
(`statehub promote-intake` / `scripts/promote_intake.py`): it writes the target
artefact, sets `promoted_to` / `origin` links, and closes the intake as
`promoted`. Manual copy-paste between kinds is treated as a process defect.

---

## Residuals (role, not kind)

**Residual** means work deliberately left when finishing a workplan. It is
**not** a kind in the registry. Do not invent a parallel residuals file or park
leftovers only in `SCOPE.md` or finished-workplan prose.

| Shape | Capture as | Links |
|-------|------------|--------|
| Parkable Green/Blue | **intake** | `origin: residual` (or `handoff`), `origin_ref: <parent-WP-id>` |
| Multi-step | **workplan** (next WP) | Name parent WP; promote from residual intake when useful |
| Founder gate / time | **decision** / **engagement** | Same origin fields when from residual intake |
| Persistent gap | **register-entry** | Cross-link parent in notes |

**Before** setting a workplan to `finished`, promote each actionable residual
into a live record. Optional narrative under the closing task is fine for
humans; the backlog is the work record. Fleet listing (intakes + open WPs with
those origin fields) belongs on State Hub — future `statehub residuals` /
`GET …` filters — not in domain repos. Canon:
`the-custodian/canon/standards/work-record-types_v0.1.md` § Residuals.

---

## Tags vs status

| Class | Examples | Rule |
|-------|----------|------|
| **Derived tags** | `stalled`, `stale`, `orphaned`, … | Computed; not written as workplan `status` |
| **Policy tags** | `needs-human`, `automatable`, `compliance-relevant`, `residual`, … | Assigned under policy |

Situational labels are tags (or derived health filters). Lifecycle position is
`status` only. Workplan health filters `needs_review` and `stalled` are
documented under [Workplan Lifecycle](/docs/workstream-lifecycle).

---

## Legacy names still visible in State Hub

| Legacy surface | Current meaning |
|----------------|-----------------|
| **workstream** | Compatibility name for **workplan** (some frontmatter keys, retired or metered API aliases) |
| **suggestion** | Pre–work-record hub entity for gated needs; **mutations retired** (HTTP 410). Use **intake**. Reads may remain for history. See [Suggestions (legacy)](/docs/suggestions). |
| Dashboard **Suggestions** page | Still lists the legacy table via `GET /suggestions/`; open backlog has been migrated to file-backed intakes |

---

## Related APIs (orientation)

| Kind / surface | Primary REST | MCP (preferred) |
|----------------|--------------|-----------------|
| workplan | `GET/POST/PATCH /workplans/` | `list_workplans`, `create_workplan`, `update_workplan` |
| task | `GET/PATCH /tasks/` | `list_tasks`, `create_task`, `update_task_status` |
| intake | `GET/POST /intakes/`, `…/route`, `…/close` | `create_intake`, `list_intakes`, `route_intake`, `close_intake` |
| decision | `/decisions/` | `record_decision`, `resolve_decision` |
| contribution (not a work-record kind) | `/contributions/` | `register_contribution` |
| suggestion (legacy, read-only writes) | `GET /suggestions/` | mutation tools return 410 |

---

*Canon and registry live in `the-custodian`. State Hub implements registration,
read model, flow evaluation for some kinds, and the intake promotion CLI.*