---
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
rmgr identifier migration-plan --root /path/to/fleet \
  --namespace <fleet-namespace> --output uuid-migration.json
```

`migration-plan` is non-mutating. Its versioned JSON output preserves every
current-to-derived UUID mapping and marks each repository as one atomic apply
unit. A collision or malformed live identifier makes that whole repository
ineligible while leaving unaffected repositories visible in the plan. Existing
output files are not replaced unless `--force` is explicit.

Activation and applying a bulk migration remain separate governed steps.
Publishing or planning this function does not retroactively rewrite existing
identifiers. The caller must supply the namespace explicitly until the current
fleet namespace is declared by the namespace owner under ADR-011.