Workplan consistency improvement workplans

workplans/STATE-WP-0046-workplan-id-normalization.md

@@ -0,0 +1,140 @@
+---
+id: STATE-WP-0046
+type: workplan
+title: "Workplan ID Normalization and Legacy Cleanup"
+domain: custodian
+repo: state-hub
+status: proposed
+owner: codex
+topic_slug: custodian
+planning_priority: high
+planning_order: 46
+created: "2026-05-23"
+updated: "2026-05-23"
+state_hub_workstream_id: "2370b7cb-affd-4bf2-a193-84e73ec53cd3"
+---
+
+# STATE-WP-0046 - Workplan ID Normalization and Legacy Cleanup
+
+## Goal
+
+Reduce broken-window drift in State Hub workplan management by normalizing
+workplan prefixes, task IDs, filenames, and references where migration is safe,
+while preserving State Hub DB continuity and leaving explicit legacy exceptions
+where renaming would create more confusion than it removes.
+
+## Context
+
+State Hub is now a standalone repository, but it still carries extracted
+`CUST-WP-*` files and short task IDs such as `T01`. The runtime consistency
+checker passes, but strict ADR validation still reports task-ID format warnings
+for migrated workplans. Documentation also disagrees on the new local prefix:
+`AGENTS.md` uses `STATE-WP-*`, while older State Hub docs mention `SHUB-WP-*`.
+
+The cleanup should prefer deterministic renames and mechanical reference
+updates, but it must not break existing `state_hub_workstream_id` or
+`state_hub_task_id` links.
+
+## T01 - Inventory ID And Prefix Drift
+
+```task
+id: STATE-WP-0046-T01
+status: todo
+priority: high
+state_hub_task_id: "e966289f-bb27-4da0-b00c-2bba2751fad7"
+```
+
+Build an inventory of all local State Hub workplan files, frontmatter IDs,
+filenames, task IDs, State Hub workstream IDs, task IDs, and references from
+docs/tests/scripts.
+
+Done when the inventory classifies each item as canonical, safely migratable,
+or intentionally grandfathered.
+
+## T02 - Decide Canonical Prefix Policy
+
+```task
+id: STATE-WP-0046-T02
+status: todo
+priority: high
+state_hub_task_id: "ee965266-4578-4ad1-b5b7-481e243a67dc"
+```
+
+Record the canonical State Hub-local prefix decision and update conflicting
+guidance so new workplans consistently use `STATE-WP-*`.
+
+Done when `AGENTS.md`, `SCOPE.md`, `README.md`, templates, and docs no longer
+disagree on `STATE-WP-*` versus `SHUB-WP-*`.
+
+## T03 - Normalize Safe Workplan IDs And Filenames
+
+```task
+id: STATE-WP-0046-T03
+status: todo
+priority: high
+state_hub_task_id: "fd753850-93ba-4daa-9664-466f07097af5"
+```
+
+Rename safely migratable local files and frontmatter IDs to canonical
+`STATE-WP-*` names, preserving existing State Hub UUID links and updating
+references in docs, tests, scripts, dashboard docs, and workplan dependency
+text.
+
+Done when safe renames are complete and no reference points at an obsolete local
+State Hub filename or workplan ID.
+
+## T04 - Normalize Safe Task IDs
+
+```task
+id: STATE-WP-0046-T04
+status: todo
+priority: high
+state_hub_task_id: "6d60cd2c-0b0c-41e8-a957-b04a5fe0b31e"
+```
+
+Replace short extracted task IDs such as `T01` with full canonical IDs such as
+`STATE-WP-NNNN-T01` where the mapping is unambiguous, preserving
+`state_hub_task_id` links.
+
+Done when strict ADR validation has no task-ID-format warnings for workplans
+that were safe to normalize.
+
+## T05 - Encode Legacy Exceptions
+
+```task
+id: STATE-WP-0046-T05
+status: todo
+priority: medium
+state_hub_task_id: "a5a77bbe-4aa5-4e9a-9387-400a0093ed39"
+```
+
+For items that should remain legacy, add explicit machine-readable or
+documented exceptions so future agents understand that the drift is intentional
+and not fresh neglect.
+
+Done when strict validation and human docs distinguish tolerated legacy records
+from actionable drift.
+
+## T06 - Verify Consistency And ADR Compliance
+
+```task
+id: STATE-WP-0046-T06
+status: todo
+priority: high
+state_hub_task_id: "69a3255c-1cc9-47d0-9947-350a443173d8"
+```
+
+Run State Hub consistency sync/checks and strict ADR validation after the
+migration. Confirm the DB still points at the intended workstreams and tasks.
+
+Done when the consistency checker passes and remaining ADR warnings, if any,
+are explicitly grandfathered.
+
+## Acceptance Criteria
+
+- New State Hub-local workplans consistently use `STATE-WP-*`.
+- Safe legacy IDs and short task IDs are normalized without losing State Hub
+  UUID links.
+- Remaining legacy exceptions are explicit and auditable.
+- `make fix-consistency REPO=state-hub` and strict ADR validation no longer
+  produce avoidable ID-format noise.