tegwick
ad621d6c0d
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a023c0-a0a3-7c03-b395-5a0d2757214d
55 lines
2.3 KiB
Markdown
55 lines
2.3 KiB
Markdown
---
|
|
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.
|