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	finished	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.

Legacy Policy

Canonical State Hub-local workplans use STATE-WP-*. Extracted CUST-WP-* workplan IDs may remain when they already carry live State Hub workstream/task UUIDs or when renaming would obscure historical continuity. Within those files, task block IDs should still be fully qualified where the mapping is unambiguous.

T01 - Inventory ID And Prefix Drift

id: STATE-WP-0046-T01
status: done
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.

Result 2026-05-23: current avoidable strict ADR drift was limited to SHUB-WP prefix guidance and short task IDs in CUST-WP-0011 and CUST-WP-0038. Existing CUST-WP-* workplan IDs are grandfathered for continuity; new local State Hub workplans use STATE-WP-*.

T02 - Decide Canonical Prefix Policy

id: STATE-WP-0046-T02
status: done
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-*.

Result 2026-05-23: STATE-WP-* is the canonical State Hub-local prefix. Updated SCOPE.md, README.md, and docs/workplan-convention.md to remove the older SHUB-WP-* guidance.

T03 - Normalize Safe Workplan IDs And Filenames

id: STATE-WP-0046-T03
status: done
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.

Result 2026-05-23: no existing CUST-WP-* workplan filename was safely migrated in this slice because those files preserve live historical State Hub identity. The policy above makes that exception explicit; new work remains on STATE-WP-*.

T04 - Normalize Safe Task IDs

id: STATE-WP-0046-T04
status: done
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.

Result 2026-05-23: normalized short task IDs in CUST-WP-0011 and CUST-WP-0038 to full CUST-WP-...-TNN IDs while preserving each state_hub_task_id.

T05 - Encode Legacy Exceptions

id: STATE-WP-0046-T05
status: done
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.

Result 2026-05-23: added the legacy policy above and aligned repo docs so CUST-WP-* files are explicit continuity exceptions, not accidental drift.

T06 - Verify Consistency And ADR Compliance

id: STATE-WP-0046-T06
status: done
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.

Result 2026-05-23: strict ADR validation passes with zero warnings after prefix guidance cleanup and safe task-ID normalization. Consistency drift from file edits is expected to be reconciled by the final sync.

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.