From c9b7cab9c315b5df9cea8bf558112c58eb8c3e0c Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 17 Aug 2026 10:19:03 +0200 Subject: [PATCH] docs(workplans): RMGR-WP-0005 registrar consolidation + deterministic IDs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- WORK-RECORDS.md | 8 + ...P-0004-repository-standards-conformance.md | 49 +++++ ...gistrar-consolidation-deterministic-ids.md | 167 ++++++++++++++++++ 3 files changed, 224 insertions(+) create mode 100644 workplans/RMGR-WP-0005-registrar-consolidation-deterministic-ids.md diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index f130ae7..5a4b673 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -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 | diff --git a/workplans/RMGR-WP-0004-repository-standards-conformance.md b/workplans/RMGR-WP-0004-repository-standards-conformance.md index 1f34c23..58f1967 100644 --- a/workplans/RMGR-WP-0004-repository-standards-conformance.md +++ b/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 diff --git a/workplans/RMGR-WP-0005-registrar-consolidation-deterministic-ids.md b/workplans/RMGR-WP-0005-registrar-consolidation-deterministic-ids.md new file mode 100644 index 0000000..21b45d3 --- /dev/null +++ b/workplans/RMGR-WP-0005-registrar-consolidation-deterministic-ids.md @@ -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.