---
id: RMGR-CONTRACT-UUID-0001
type: contract
title: "Deterministic work-record UUID derivation"
version: "1"
status: active
created: "2026-08-21"
updated: "2026-08-21"
workplan_task: RMGR-WP-0005-T03
---

# Work-record UUID derivation v1

For a live workplan or task, implementations derive the existing
`state_hub_workstream_id` or `state_hub_task_id` field with UUIDv5:

```text
namespace UUID: a4058507-5c4a-5a00-ab06-fffa4fb46009
name bytes:      UTF-8(<fleet-namespace> + "\n" + <canonical-identifier>)
```

The fixed UUID is itself UUIDv5(URL,
`https://helixforge.org/repo-manager/work-record/v1`), but consumers use the
fixed value above rather than recomputing it. Fleet namespace names are
lowercase DNS-label style. Canonical identifiers are
`PREFIX-WP-NNNN` or `PREFIX-WP-NNNN-TNN`.

The repository is not a namespace. Under the current N1 posture, the fleet must
declare one shared namespace name before activation. A future fork uses its own
namespace name and therefore derives different UUIDs for the same unqualified
identifier, as required by ADR-011.

Only proposed, ready, active, blocked, or backlog workplans and their unfinished
tasks enter the live derivation set. Finished and archived history retains its
minted identifiers. Before creating, re-deriving, or unarchiving a record, run
the live-collision preflight. Any duplicate is a hard refusal; it is never
silently disambiguated with a repository slug.

```bash
rmgr identifier derive --namespace <fleet-namespace> --record-id RMGR-WP-0005
rmgr identifier preflight --root /path/to/fleet
```

Activation and bulk migration remain separate governed steps. Publishing this
function does not retroactively rewrite existing identifiers.