repo-manager/docs/work-record-uuid-derivation_v1.md

id	type	title	version	status	created	updated	workplan_task
RMGR-CONTRACT-UUID-0001	contract	Deterministic work-record UUID derivation	1	active	2026-08-21	2026-08-21	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:

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.

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.