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

# Work Records — Reference

A **work record** is any identified, lifecycle-bearing **coordination artefact**
indexed by State Hub. The term is intentionally **generic**: the same
framework covers individual units of work or discovery, **collections and
plans**, and related artefacts (decisions, engagements, register entries). It
is a mode of organising coordination — not a single product page and not a
synonym for “task.”

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.

---

## Units and structure

Kinds share one spine and registry, but they play different **roles**:

| Role | What it is | Kinds today | Everyday gloss |
|------|------------|-------------|----------------|
| **Unit** | A single coordination atom | `task`, `intake`, `decision`, `engagement`, many `register-entry` rows | work-item (task); find / spark (intake) |
| **Structure** | A collection or plan with relations | `workplan` | delivery plan over tasks (and dependencies between plans) |

A **workplan is a work record** in the mechanical sense (id, status, hub index).
It is **not** a large task: it is **structure** over unit records. Calling both
“work records” means they use the same identity and reconciliation machinery,
not that they feel the same in day-to-day language.

Generated views (for example a per-repo work-record index, or a future
“discovery map” over intakes) organise records **without** needing a new kind
until a real aggregate must be owned as its own artefact.

---

## Kind registry (closed list)

| Kind | Role | Id scheme (typical) | Meaning in State Hub today |
|------|------|---------------------|----------------------------|
| **workplan** | structure | `{PREFIX}-WP-NNNN` | Dependency-bearing plan; file under `workplans/` (ADR-001) |
| **task** | unit | `{WP-ID}-TNN` · `ADHOC-YYYY-MM-DD-TNN` | Smallest executable delivery unit; lives in a workplan file |
| **intake** | unit | `{PREFIX}-IN-NNNN` | Discovery spark: idea, finding, directive, or request |
| **decision** | unit | `{PREFIX}-DEC-YYYY-NNN` (file) · hub decision entity | Approval package / recorded choice |
| **engagement** | unit | `{PREFIX}-ENG-YYYY-NNN` | Scheduled external interaction (file-backed; hub entity not yet first-class) |
| **register-entry** | unit (mostly) | `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).

---

## Lifecycle vs quality (Definition-of-X)

Two independent axes:

| Axis | Answers | Examples |
|------|---------|----------|
| **Lifecycle** (`status`) | Where is this in process? | workplan `active` / `finished`; intake `routed`; task `progress` |
| **Definition assessment** | Did it pass a named quality policy when assessed? | DoC / DoR / DoD (and DoI / DoM for repos/services) |

Assessments do **not** invent extra lifecycle states. Outcomes are:

- **unassessed** — no Definition-of-X assessment recorded yet  
- **`DoX-Ok`** (tiered policies may use `DoM-Ok-1`, …) — last assessment passed  
- **`DoX-Failed`** — assessment ran and failed  

A workplan may be `status=finished` without **DoD-Ok**, or `status=ready`
without **DoR-Ok**. That is allowed: process can advance while quality debt
stays visible. Policies live under `policies/` (same pattern as Repository DoI
and Service DoM):

| Policy | Dashboard | Rates |
|--------|-----------|-------|
| **DoC** | [Intake DoC](/policy/intake-doc) | Discovery quality (`intake`) |
| **DoR** | [Work-item DoR](/policy/work-item-dor) | Implementation-readiness (`task`, `workplan`) |
| **DoD** | [Workplan DoD](/policy/workstream-dod) | Completion quality (workplan) |

Full matrix, badge spelling, and **recording fields**
(`quality_doc` / `quality_dor` / `quality_dod`): repo doc
`docs/work-record-quality-gates.md`. Soft list: `statehub quality-debt`.

Discovery quality (intake) is **not** the same as implementation-readiness
(task/workplan). Outside or sparse-context signals should be comprehended
(DoC) before they are promoted into structured delivery work.

---

## 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.*
