state-hub/workplans/CUST-WP-0042-workplan-state-model-cleanup.md

---
id: CUST-WP-0042
type: workplan
title: "Workplan State Model Cleanup"
domain: custodian
repo: state-hub
status: finished
owner: custodian
topic_slug: custodian
planning_priority: high
planning_order: 42
state_hub_workstream_id: "522608cb-81a2-491f-b6b3-eff00fe01269"
created: "2026-05-17"
updated: "2026-05-17"
---

# CUST-WP-0042 - Workplan State Model Cleanup

## Goal

Make the State Hub workplan lifecycle explicit and consistent across
file-backed workplans, the workstream API, consistency scripts, validation,
dashboard filters, and documentation.

This workplan exists because `proposed`, `ready`, and `backlog` represent real
planning states that the current model cannot express cleanly:

- `proposed`: plan exists, but must be reviewed against current repo state
- `ready`: reviewed and executable against current repo state
- `backlog`: intentionally parked so it does not clutter current work views

Supporting design note:
`docs/workplan-state-model-proposal.md`

## Context

State Hub currently has vocabulary drift:

- Workstream API/schema: `todo`, `active`, `blocked`, `completed`, `archived`
- Workplan consistency scripts: `active`, `completed`, `archived`
- Dashboard overview modes: `active`, `accepted`, `finished`, `blocked`,
  `stalled`, `oldies`

The intended cleanup is to separate stored lifecycle states from derived health
labels. `stalled`, `oldies`, and stale-ready detection should not be stored as
primary workplan states.

## Target State Model

Canonical stored workplan states:

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

Derived health labels:

```text
needs_review, stalled
```

Normal progression:

```text
backlog -> proposed -> ready -> active -> finished -> archived
                    \          \
                     \          -> blocked -> active
                      -> backlog
```

## Tasks

### T01 - Capture State Model Proposal

```task
id: CUST-WP-0042-T01
status: done
priority: high
state_hub_task_id: "fbc17b50-7b7e-41ba-bd13-d66a6a546450"
```

Write the design proposal that defines canonical states, derived labels, legacy
aliases, UI cleanup, and migration expectations.

Done when `docs/workplan-state-model-proposal.md` exists and can be
reviewed as the design source for this workplan.

### T02 - Centralize Workplan Status Constants

```task
id: CUST-WP-0042-T02
status: done
priority: high
state_hub_task_id: "9be18f7e-1db1-464b-8c65-bf64ae3462e8"
```

Add a shared source of truth for workplan/workstream statuses and legacy aliases
used by API schemas, consistency scripts, validation scripts, and dashboard
classification code.

Done when supported statuses and aliases are no longer duplicated as local
string sets in multiple files.

### T03 - Update API Schema And Database Migration

```task
id: CUST-WP-0042-T03
status: done
priority: high
state_hub_task_id: "1d9964ce-7b30-49d3-a4e3-6d5b3ef8d684"
```

Update the workstream schema to accept the canonical state set and add a
migration for existing values:

- `completed` -> `finished`
- `accepted` -> `finished`
- `todo` -> `ready` when no work has started, otherwise `active`

Done when API validation accepts the canonical states and existing DB rows are
normalized without data loss.

### T04 - Update Consistency And ADR Validation

```task
id: CUST-WP-0042-T04
status: done
priority: high
state_hub_task_id: "c80df776-5d45-419d-a92c-59e3b77d9798"
```

Update `scripts/consistency_check.py` and `scripts/validate_repo_adr.py` so
file-backed workplans can use `proposed`, `ready`, `active`, `blocked`,
`backlog`, `finished`, or `archived` without false warnings.

Done when consistency checks compare normalized values and write back canonical
values only when they intentionally edit files.

### T05 - Add Ready-Staleness Detection

```task
id: CUST-WP-0042-T05
status: done
priority: medium
state_hub_task_id: "97ebc285-3998-4f17-bf43-c4f803cf1e7b"
```

Support optional ready-review metadata:

```yaml
reviewed_at: "YYYY-MM-DD"
reviewed_by: "human-or-agent"
reviewed_against_commit: "<git-sha>"
context_paths:
  - "path/or/glob"
```

Done when `ready` workplans can be flagged as `needs_review` after relevant repo
changes, with any automatic demotion from `ready` to `proposed` guarded behind
an explicit flag.

### T06 - Clean Up Dashboard Status Filters

```task
id: CUST-WP-0042-T06
status: done
priority: high
state_hub_task_id: "210fcff3-e3e9-4f8a-9687-c5de83ace465"
```

Replace dashboard lifecycle filters with canonical stored states and move
`stalled`/`needs_review` into derived health filters or badges.

Done when the overview no longer uses `accepted`, `oldies`, or derived
`finished` as primary lifecycle filters.

### T07 - Update Docs And Registration Templates

```task
id: CUST-WP-0042-T07
status: done
priority: medium
state_hub_task_id: "8ecceebb-0471-4541-96f9-c9f98df12f84"
```

Update dashboard docs, State Hub docs, project registration templates, and
agent guidance so new repos use the canonical workplan frontmatter states.

Done when new generated repo guidance references the same state model as the
API and consistency engine.

### T08 - Add Regression Tests

```task
id: CUST-WP-0042-T08
status: done
priority: medium
state_hub_task_id: "7dd1f27d-4a4a-4c78-8b91-6103688559a9"
```

Add tests for API status validation, file status normalization, legacy alias
handling, ready-staleness detection, and dashboard classification helpers.

Done when the new state model is covered well enough that vocabulary drift is
hard to reintroduce accidentally.

## Acceptance Criteria

- Workplan files and API workstreams support the same canonical state set.
- `proposed`, `ready`, and `backlog` are first-class lifecycle states.
- `stalled` and `needs_review` are derived health labels, not stored lifecycle
  states.
- Legacy status values are normalized or migrated safely.
- Dashboard filters and docs use the same vocabulary as the file/API model.