---
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. The fleet owner declared the current shared
namespace as **`helixforge`** on 2026-08-21; the versioned declaration is
`config/fleet-namespace.yaml`. This raises the namespace posture from implied
N1 to declared N2. 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 --record-id RMGR-WP-0005
rmgr identifier preflight --root /path/to/fleet
rmgr identifier migration-plan --root /path/to/fleet --output uuid-migration.json
rmgr identifier migration-verify --plan uuid-migration.json
rmgr identifier migration-verify --plan uuid-migration.json --repo repo-manager
rmgr identifier migration-batch-plan \
  --plan uuid-migration.json \
  --repo whynot-design \
  --output batch.json
rmgr identifier migration-batch-verify \
  --plan uuid-migration.json \
  --batch batch.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.

Plans carry a canonical UTC creation time, SHA-256 integrity seal, and per-repo
Git HEAD/source fingerprints. `migration-verify` rejects a modified plan, a
namespace mismatch, an ineligible repository, or authoritative-source drift.
HEAD movement is reported but is not a hard failure when the source fingerprint
is unchanged; otherwise committing the plan itself would invalidate its own
repository. `--repo` verifies one atomic apply unit, so unrelated fleet churn
does not invalidate a stable repository. A new plan is required for each unit
whose authoritative source drifts.

`migration-batch-plan` converts selected atomic units into a bounded approval
package. Each selected repository must still match the planned Git HEAD, have a
clean worktree, exactly match its configured upstream, and use a non-retired
origin. The batch records these facts and its own SHA-256 seal, but always emits
`apply_authorized: false`. An explicit decision must cite that batch hash before
any database or file mutation.

Activation and applying a bulk migration remain separate governed steps.
Publishing or planning this function does not retroactively rewrite existing
identifiers. `--namespace` remains an explicit override for a foreign/forked
fleet; omitting it uses the checked-in `helixforge` declaration.