---
id: STATE-WP-0046
type: workplan
title: "Workplan ID Normalization and Legacy Cleanup"
domain: custodian
repo: state-hub
status: finished
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.

## 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

```task
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

```task
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

```task
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

```task
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

```task
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

```task
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.