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.

---

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
engagement	queued → prepared → done (file convention)
register-entry	Per existing register conventions

Detail pages:

• Workplan Lifecycle
• Tasks
• Intakes
• 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.

---

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).
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.