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

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, state_hub_workstream_id, created, updated

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

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

Derived health labels:

needs_review, stalled

Normal progression:

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

Tasks

T01 - Capture State Model Proposal

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

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

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

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

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

Support optional ready-review metadata:

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

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

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

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.