docs(workplans): RMGR-WP-0005 registrar consolidation + deterministic IDs
Implements ADR-007 decision 2: interim single-writer, target UUIDv5 derived from the globally unique PREFIX-WP-NNNN so writeback is idempotent across instances. T04 migrates the 758 files carrying hub identifiers. T06 covers lifecycle protection including the C-15 task-status override. RMGR-WP-0004 gains T08 enforcing ADR-007 identifier uniqueness, which gates RMGR-WP-0005-T03 — deriving from a non-unique identifier would manufacture UUID collisions. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
parent
211b81cd94
commit
c9b7cab9c3
3 changed files with 224 additions and 0 deletions
|
|
@ -11,6 +11,7 @@
|
|||
| workplan | RMGR-WP-0001 | finished | — | workplans/RMGR-WP-0001-foundation.md |
|
||||
| workplan | RMGR-WP-0002 | finished | — | workplans/RMGR-WP-0002-retirement-dual-run-strangler.md |
|
||||
| workplan | RMGR-WP-0003 | finished | — | workplans/RMGR-WP-0003-production-pilot-dual-run.md |
|
||||
| workplan | RMGR-WP-0004 | proposed | — | workplans/RMGR-WP-0004-repository-standards-conformance.md |
|
||||
| task | RMGR-WP-0001-T01 | done | — | workplans/RMGR-WP-0001-foundation.md |
|
||||
| task | RMGR-WP-0001-T02 | done | — | workplans/RMGR-WP-0001-foundation.md |
|
||||
| task | RMGR-WP-0001-T03 | done | — | workplans/RMGR-WP-0001-foundation.md |
|
||||
|
|
@ -26,3 +27,10 @@
|
|||
| task | RMGR-WP-0003-T02 | done | — | workplans/RMGR-WP-0003-production-pilot-dual-run.md |
|
||||
| task | RMGR-WP-0003-T03 | done | — | workplans/RMGR-WP-0003-production-pilot-dual-run.md |
|
||||
| task | RMGR-WP-0003-T04 | done | — | workplans/RMGR-WP-0003-production-pilot-dual-run.md |
|
||||
| task | RMGR-WP-0004-T01 | todo | — | workplans/RMGR-WP-0004-repository-standards-conformance.md |
|
||||
| task | RMGR-WP-0004-T02 | wait | — | workplans/RMGR-WP-0004-repository-standards-conformance.md |
|
||||
| task | RMGR-WP-0004-T03 | wait | — | workplans/RMGR-WP-0004-repository-standards-conformance.md |
|
||||
| task | RMGR-WP-0004-T04 | wait | — | workplans/RMGR-WP-0004-repository-standards-conformance.md |
|
||||
| task | RMGR-WP-0004-T05 | wait | — | workplans/RMGR-WP-0004-repository-standards-conformance.md |
|
||||
| task | RMGR-WP-0004-T06 | wait | — | workplans/RMGR-WP-0004-repository-standards-conformance.md |
|
||||
| task | RMGR-WP-0004-T07 | wait | — | workplans/RMGR-WP-0004-repository-standards-conformance.md |
|
||||
|
|
|
|||
|
|
@ -16,6 +16,7 @@ related:
|
|||
- STATE-WP-0079
|
||||
- RMGR-WP-0001
|
||||
- CFED-WP-0001
|
||||
state_hub_workstream_id: "b8b3f1e0-b8df-4405-849e-11ec51f80ae5"
|
||||
---
|
||||
|
||||
# Repository standards conformance and governed scaffolding
|
||||
|
|
@ -55,6 +56,7 @@ claims "repository registration, identity, classification, and lifecycle" and
|
|||
id: RMGR-WP-0004-T01
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "dd2db30f-c48f-404d-a1b4-bd75b41d42f4"
|
||||
```
|
||||
|
||||
Give Repo Manager a first-class representation of the standards a repository is
|
||||
|
|
@ -81,6 +83,7 @@ into a second definition.
|
|||
id: RMGR-WP-0004-T02
|
||||
status: wait
|
||||
priority: high
|
||||
state_hub_task_id: "2c9b0cb1-f0f0-40f7-83ef-1828298338d3"
|
||||
```
|
||||
|
||||
Check a repository against its flavor's standard and report violations with
|
||||
|
|
@ -104,6 +107,7 @@ Known first findings, both live today:
|
|||
id: RMGR-WP-0004-T03
|
||||
status: wait
|
||||
priority: high
|
||||
state_hub_task_id: "8e6fa8d7-f169-44f5-bdc9-29376bb2ef64"
|
||||
```
|
||||
|
||||
Take ownership of creating conformant repository files, replacing the templating
|
||||
|
|
@ -134,6 +138,7 @@ ordinary repos receive.
|
|||
id: RMGR-WP-0004-T04
|
||||
status: wait
|
||||
priority: medium
|
||||
state_hub_task_id: "8cd3ba11-b16b-4910-8bf6-651a24d47b8c"
|
||||
```
|
||||
|
||||
`make update-agent-instructions` regenerates `AGENTS.md`, `CLAUDE.md`,
|
||||
|
|
@ -152,6 +157,7 @@ flavor-blind template silently re-breaks conformant repos.
|
|||
id: RMGR-WP-0004-T05
|
||||
status: wait
|
||||
priority: medium
|
||||
state_hub_task_id: "8402b8b6-2a1e-4236-b27d-d50b6161a176"
|
||||
```
|
||||
|
||||
Coordinate the transfer with `STATE-WP-0080`, which is retargeted to a thin
|
||||
|
|
@ -173,6 +179,7 @@ Follow the dual-run strangler pattern already proven in `RMGR-WP-0002` and
|
|||
id: RMGR-WP-0004-T06
|
||||
status: wait
|
||||
priority: medium
|
||||
state_hub_task_id: "faaeb016-3ba8-493a-bbdf-9227de24f720"
|
||||
```
|
||||
|
||||
Per `SCOPE.md` § Initial extraction source, extraction must preserve behaviour
|
||||
|
|
@ -185,12 +192,54 @@ with compatibility tests. Cover:
|
|||
- flavor signals that disagree warn rather than silently resolving;
|
||||
- re-running scaffolding on a conformant repo is idempotent.
|
||||
|
||||
## Enforce workplan identifier uniqueness
|
||||
|
||||
```task
|
||||
id: RMGR-WP-0004-T08
|
||||
status: wait
|
||||
priority: high
|
||||
```
|
||||
|
||||
Implement `ADR-007` decision 1 as a repository standard: `PREFIX-WP-NNNN` names
|
||||
exactly one workplan fleet-wide, for all time.
|
||||
|
||||
- **Prefix ownership registry** — one prefix, one repository. New machinery: no
|
||||
such registry exists today. `C-26` checks prefix conformance *within* a repo
|
||||
against a canonical prefix, but nothing checks across repos.
|
||||
- **Forward-only numbering** — a running number is never reused within a prefix,
|
||||
including after cancel, archive, or delete.
|
||||
- **Prefixes derive from project or repository identity**, never from a flavor
|
||||
marker or category. This is what makes `PRJ-WP-` invalid by construction and
|
||||
connects back to T03.
|
||||
|
||||
Live violations to detect (fleet scan, 2026-08-16 — 955 hub workplans, 525
|
||||
parseable identifiers):
|
||||
|
||||
```text
|
||||
prefixes shared across repos:
|
||||
CUST-WP- state-hub, the-custodian
|
||||
RAIL-BS-WP- railiance-bootstrap, railiance-cluster
|
||||
RAILIANCE-WP- railiance-apps, railiance-forge, railiance-platform, railiance-telemetry
|
||||
|
||||
identifiers reused:
|
||||
CUST-WP-0000 / 0010 / 0045 the-custodian ×2 each
|
||||
RAILIANCE-WP-0015 railiance-platform, railiance-apps
|
||||
RAILIANCE-WP-0016 railiance-platform ×2, railiance-apps
|
||||
```
|
||||
|
||||
Detection only. Remediating the existing collisions is an open ruling in
|
||||
`ADR-007` § Migration and is not authorized by this task.
|
||||
|
||||
**This task gates `RMGR-WP-0005`.** Deterministic identifier derivation from a
|
||||
non-unique identifier would manufacture UUID collisions rather than remove them.
|
||||
|
||||
## Confirm the canon boundary
|
||||
|
||||
```task
|
||||
id: RMGR-WP-0004-T07
|
||||
status: wait
|
||||
priority: low
|
||||
state_hub_task_id: "7fdd54fe-fba7-4713-9814-d4534ff19706"
|
||||
```
|
||||
|
||||
Repo Manager implements repository standards; it does not author them. Confirm
|
||||
|
|
|
|||
|
|
@ -0,0 +1,167 @@
|
|||
---
|
||||
id: RMGR-WP-0005
|
||||
type: workplan
|
||||
title: "Registrar consolidation and deterministic hub identifiers"
|
||||
domain: infotech
|
||||
repo: repo-manager
|
||||
status: proposed
|
||||
owner: codex
|
||||
topic_slug: infotech
|
||||
created: "2026-08-17"
|
||||
updated: "2026-08-17"
|
||||
parent_project: prj-state-hub-retirement
|
||||
parent_workplan: SHR-WP-0001
|
||||
related:
|
||||
- RMGR-WP-0004
|
||||
- STATE-WP-0080
|
||||
- STATE-WP-0068
|
||||
- CFED-WP-0001
|
||||
---
|
||||
|
||||
# Registrar consolidation and deterministic hub identifiers
|
||||
|
||||
## Goal
|
||||
|
||||
Make hub identifiers stored in repository files **derivable rather than
|
||||
database-local**, so that any number of hub instances can reconcile the same
|
||||
repository without overwriting each other.
|
||||
|
||||
Implements `ADR-007` decision 2: interim single-writer (A), target deterministic
|
||||
derivation (C2).
|
||||
|
||||
## The defect
|
||||
|
||||
`state_hub_workstream_id` and `state_hub_task_id` are database-local primary
|
||||
keys stored in a shared git artifact. Two hub instances over two databases each
|
||||
mint their own value for the same workplan, and every sync overwrites the other.
|
||||
|
||||
Observed 2026-08-16 on `STATE-WP-0080`: workplan UUID `03f38314` from the
|
||||
workstation hub, `bbfce36a` from a second instance (404 against the workstation
|
||||
database), plus two disjoint sets of task UUIDs. Sync commits appear under both
|
||||
`+0000` and `+0200` timezones, confirming two machines write to one repository.
|
||||
|
||||
It also inverts `ADR-001`. Files are meant to originate work with the hub as read
|
||||
model; a file carrying a hub's private key is the file holding hub state.
|
||||
|
||||
**Scope: 758 workplan files** across the fleet currently carry these fields.
|
||||
|
||||
## Apply the interim single-writer rule
|
||||
|
||||
```task
|
||||
id: RMGR-WP-0005-T01
|
||||
status: todo
|
||||
priority: high
|
||||
```
|
||||
|
||||
Until derivation ships, exactly one instance may write hub identifiers into
|
||||
repository files. The interim registrar is the automated production instance;
|
||||
workstation hubs are development read replicas.
|
||||
|
||||
- Make the writeback path refuse to mint identifiers when the instance is not
|
||||
the registrar, rather than relying on operator discipline.
|
||||
- Provide the configuration that designates the registrar, and make a
|
||||
non-registrar instance's read/project behaviour unchanged.
|
||||
- Document the accepted cost: registration requires connectivity to the
|
||||
registrar, so disconnected work cannot register until T03 lands.
|
||||
|
||||
Interim, and deliberately so — it trades availability for correctness, and T03
|
||||
removes the need for the trade.
|
||||
|
||||
## Re-register identifiers minted outside the registrar
|
||||
|
||||
```task
|
||||
id: RMGR-WP-0005-T02
|
||||
status: wait
|
||||
priority: medium
|
||||
```
|
||||
|
||||
Records minted by non-registrar instances before T01 need reconciliation. Known
|
||||
cases, all created 2026-08-16/17 from the workstation hub:
|
||||
|
||||
- `RMGR-WP-0004` (`b8b3f1e0`) and its seven tasks;
|
||||
- `CFED-WP-0001` (`7a96da54`) and its thirteen tasks, plus the
|
||||
`prj-canon-federation` repo record (`3809b0ff`);
|
||||
- `STATE-WP-0080` — already reconciled by hand to the second instance's IDs
|
||||
(`bbfce36a`), retained here as the worked example.
|
||||
|
||||
Prefer waiting for T03 where possible: once identifiers are derived, these
|
||||
converge without manual intervention. Re-register by hand only what blocks work
|
||||
before then.
|
||||
|
||||
## Derive identifiers deterministically
|
||||
|
||||
```task
|
||||
id: RMGR-WP-0005-T03
|
||||
status: wait
|
||||
priority: high
|
||||
```
|
||||
|
||||
Replace minted UUIDs with UUIDv5 derived from the globally unique
|
||||
`PREFIX-WP-NNNN` identifier (and `PREFIX-WP-NNNN-TNN` for tasks).
|
||||
|
||||
- Fix the namespace UUID and derivation input as a published contract — the
|
||||
value must be reproducible by any implementation, not just this one.
|
||||
- Field shape is unchanged, so consumers reading `state_hub_workstream_id`
|
||||
keep working; only the provenance of the value changes.
|
||||
- Writeback becomes idempotent: two instances write identical bytes, so the
|
||||
flip-flop cannot recur regardless of how many hubs run.
|
||||
|
||||
**Blocked on `RMGR-WP-0004-T08`.** Deriving from a non-unique identifier
|
||||
manufactures collisions: two repositories sharing `PRJ-WP-` would compute the
|
||||
same UUID for different workplans. Uniqueness must be enforced first.
|
||||
|
||||
## Migrate the fleet
|
||||
|
||||
```task
|
||||
id: RMGR-WP-0005-T04
|
||||
status: wait
|
||||
priority: high
|
||||
```
|
||||
|
||||
One-time pass over the 758 files carrying hub identifiers: compute the derived
|
||||
value, update the database to match, and write the file.
|
||||
|
||||
- Must be all-or-nothing per repository — a half-migrated repo has some derived
|
||||
and some minted identifiers and reconciles unpredictably.
|
||||
- Records whose current identifier is already referenced externally (dashboards,
|
||||
saved queries, progress events) need a mapping table from old to derived, kept
|
||||
as provenance rather than discarded.
|
||||
- Repositories with unresolved identifier collisions cannot migrate until
|
||||
`ADR-007` § Migration is ruled on; skip and report them rather than guessing.
|
||||
|
||||
## Retire the interim rule
|
||||
|
||||
```task
|
||||
id: RMGR-WP-0005-T05
|
||||
status: wait
|
||||
priority: low
|
||||
```
|
||||
|
||||
Once derivation is live fleet-wide, remove the single-writer restriction from
|
||||
T01. Multiple hub instances become an availability choice rather than a
|
||||
correctness constraint, and disconnected registration works again.
|
||||
|
||||
Confirm before removal: two instances reconciling the same repository produce
|
||||
byte-identical writeback, and neither creates a duplicate record.
|
||||
|
||||
## Protect lifecycle status from automation
|
||||
|
||||
```task
|
||||
id: RMGR-WP-0005-T06
|
||||
status: wait
|
||||
priority: medium
|
||||
```
|
||||
|
||||
Implement `ADR-007` decision 3: an automated normalization pass may report
|
||||
lifecycle drift but may not promote a workplan from `proposed` to `active`.
|
||||
`proposed` means awaiting human review; automated promotion destroys the gate.
|
||||
|
||||
Observed: commit `ff909e1` ("renormalize lifecycle state [auto]") promoted
|
||||
`STATE-WP-0080` to `active` hours after it was drafted for review.
|
||||
|
||||
Extend the same protection to task status, where the symptom is currently
|
||||
sharper: `C-15` forces `CFED-WP-0001-T02` back to `wait` on every sync
|
||||
regardless of file content — reproduced three times, via file edit and via
|
||||
`update_task_status`, with the task never holding `todo`. Establish which
|
||||
direction wins for task status and make it consistent with `ADR-001`, where the
|
||||
file originates work.
|
||||
Loading…
Add table
Add a link
Reference in a new issue