From f9d2dd004686ef4f5d03f4d2d21d4fe4b096fa1c Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 17 May 2026 19:10:34 +0200 Subject: [PATCH] docs: rehome state model workplan --- .../README.md => docs/workplan-convention.md | 2 +- ...ST-WP-0042-workplan-state-model-cleanup.md | 214 ++++++++++++++++++ 2 files changed, 215 insertions(+), 1 deletion(-) rename workplans/README.md => docs/workplan-convention.md (93%) create mode 100644 workplans/CUST-WP-0042-workplan-state-model-cleanup.md diff --git a/workplans/README.md b/docs/workplan-convention.md similarity index 93% rename from workplans/README.md rename to docs/workplan-convention.md index f43a33c..b4f9a47 100644 --- a/workplans/README.md +++ b/docs/workplan-convention.md @@ -1,4 +1,4 @@ -# State Hub Workplans +# State Hub Workplan Convention New workplans in this repository use: diff --git a/workplans/CUST-WP-0042-workplan-state-model-cleanup.md b/workplans/CUST-WP-0042-workplan-state-model-cleanup.md new file mode 100644 index 0000000..ffad8a9 --- /dev/null +++ b/workplans/CUST-WP-0042-workplan-state-model-cleanup.md @@ -0,0 +1,214 @@ +--- +id: CUST-WP-0042 +type: workplan +title: "Workplan State Model Cleanup" +domain: custodian +repo: state-hub +status: active +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: +`state-hub/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 `state-hub/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: todo +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: todo +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: todo +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: todo +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: "" +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: todo +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: todo +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: todo +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.