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

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

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	state_hub_workstream_id
STATE-WP-0046	workplan	Workplan ID Normalization and Legacy Cleanup	custodian	state-hub	proposed	codex	custodian	high	46	2026-05-23	2026-05-23	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

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

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

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

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

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

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.