state-hub/docs/workplan-convention.md

# State Hub Workplan Convention

New workplans in this repository use:

```text
STATE-WP-0001-short-title.md
```

Workplan frontmatter should include:

```yaml
id: STATE-WP-0001
type: workplan
title: "Short Title"
domain: custodian
repo: state-hub
status: proposed
owner: custodian
topic_slug: custodian
```

During extraction, legacy `CUST-WP-*` plans may be bridged or migrated with
their existing `state_hub_workstream_id` values. Write files first, then run
State Hub consistency sync after this repo is registered.

When a workplan is `blocked`, record the unblock condition in frontmatter:

```yaml
status: blocked
blocked_on: message-from:llm-connect
```

`blocked_on` uses the `message-from:<agent>` form so fix-consistency can
cross-check unread inbox messages from that counterpart and warn when the
blocker may have cleared.

Canonical workplan/workstream statuses are:

```text
proposed, ready, active, blocked, backlog, finished, archived
```

Use `proposed` for a new plan that still needs review, `ready` after it has
been checked against the current repo state, and `finished` when implementation
is complete. `stalled` and `needs_review` are derived health labels, not stored
frontmatter statuses.

### Residuals when finishing

If work remains after a plan is complete, **do not** leave it only as prose or
in `SCOPE.md`. Before `status: finished`, hand off each actionable residual as
a live work record:

- parkable Green/Blue → **intake** with `origin: residual`, `origin_ref: <WP-id>`
- multi-step → **new workplan** (optional promote from residual intake)
- founder gate/time → **decision** / **engagement**

Canon: `the-custodian/canon/standards/work-record-types_v0.1.md` § Residuals.
Hub index/list: State Hub (not domain-local residual files).