diff --git a/workplans/FLEX-WP-0020-repository-identity-migration.md b/workplans/FLEX-WP-0020-repository-identity-migration.md new file mode 100644 index 0000000..384621c --- /dev/null +++ b/workplans/FLEX-WP-0020-repository-identity-migration.md @@ -0,0 +1,425 @@ +--- +id: FLEX-WP-0020 +type: workplan +title: "Repository identity migration from flex-auth to access-engine" +domain: "infotech" +repo: "flex-auth" +status: proposed +owner: "codex" +topic_slug: "netkingdom" +created: "2026-08-29" +updated: "2026-08-29" +reviewed_at: "2026-08-29" +reviewed_by: codex +reviewed_against_commit: "7d7b4531d15a2dde7aaa28b9360a13e77b28b2a9" +reviewed_note: >- + Generated from live State Hub preflight 1243b1c9 and reviewed against the + clean local checkout, matching origin/Forge head, Forge repository ID 42, + FLEX-WP-0017/FLEX-WP-0019, three live NetKingdom deployments, and the + repository-coordinate owners listed below. The plan remains proposed until + State Hub preflight signing is provisioned and a fresh zero-blocker capture + replaces this review baseline. +quality_dor: DoR-Ok +quality_dor_at: "2026-08-29" +quality_dor_by: codex +quality_dor_note: >- + Tasks have explicit owners, gates, rollback boundaries, and verification + evidence. DoR describes plan quality; it does not waive the captured signing + blocker or the later human cutover gate. +--- + +# FLEX-WP-0020 — flex-auth to access-engine + +## Goal and authority boundary + +Adopt the new repository coordinate `access-engine` while preserving State Hub +repository UUID `fda8ad85-a7d7-4055-8f21-902a533e59df`, Forge repository ID `42`, source commit +`7d7b4531d15a2dde7aaa28b9360a13e77b28b2a9`, work-record identities, and telemetry relationships. + +This plan changes repository coordinates only. Product/runtime names are a +separate explicit decision. No task in this file may close work owned by +another repository: it records the external handoff ID and waits for evidence +from that owning repository. + +The initial migration is deliberately **repository-only**. The Go module, +binary, `FLEX_AUTH_*` variables, namespace, Services, Helm release/chart, +container package, policy/API vocabulary, and telemetry labels remain +`flex-auth`. A broader product/runtime rebrand requires a later workplan after +the repository-coordinate migration has soaked. This keeps the three live +NetKingdom policy deployments and their consumers out of the cutover blast +radius. + +Live Forgejo rename, State Hub rebind, rollback, and old-checkout cleanup are +Red-lane actions. They require the exact confirmations below and recorded +human approval; redirects are compatibility evidence, not completion. + +## Captured preflight + +- schema: `state-hub.repository-rename-preflight.v1` +- report checksum: `1243b1c9b0574e8c8175f3be601a2a474b3d8c0e56ec3822672e712dbac5d5ed` +- safe to apply at capture: `false` +- State Hub repository UUID: `fda8ad85-a7d7-4055-8f21-902a533e59df` +- Forge repository ID: `42` +- default branch: `main` +- source commit: `7d7b4531d15a2dde7aaa28b9360a13e77b28b2a9` +- registered local path: `/home/worsch/flex-auth` +- host paths: `{"239.62.205.92.host.secureserver.net": "/home/tegwick/flex-auth", "bnt-lap001": "/home/worsch/flex-auth"}` +- protected/current aliases: `["flex-auth"]` +- existing workplans observed: `19` +- archived workplans observed: `0` + +The preflight token is deliberately not stored in this workplan. Generate a +fresh private mode-0600 preflight file immediately before execution. + +Local `HEAD`, `origin/main`, and the Forge snapshot all matched the captured +source commit. The State Hub Forge identity was verified through the supported +API at `2026-08-29T15:46:39Z`; it was not inferred from Git or a redirect. + +## Preflight risk register + +Every blocker, warning, and external handoff from the captured snapshot is +retained here. T05 must reconcile every row; unknown ownership is a blocker. + +| Severity | Code | Captured detail | +| --- | --- | --- | +| blocker | `preflight_signing_unavailable` | `{"code":"preflight_signing_unavailable","message":"Repository rename preflight signing is not configured"}` | +| external-handoff | `fabric-graph-projections` | `Owning repository must be recorded during inventory` | +| external-handoff | `interface-change-consumers` | `Owning repository must be recorded during inventory` | +| warning | `active_work_present` | `{"code":"active_work_present","message":"Active work must be quiesced or explicitly coordinated during cutover","task_count":8,"workplan_count":7}` | + +The signing blocker is owned jointly by `state-hub` (runtime contract) and +`railiance-platform` (OpenBao-backed secret delivery). No generated or live +preflight can authorize mutation until that owner-controlled path is present. + +## Active-work coordination snapshot + +- workplan `flex-wp-0001` / `4dbefd19-bb7d-405c-9a50-e7dbd11cf4d9` is `done` +- workplan `flex-wp-0002` / `aa60e183-9a87-4e03-99b0-15786bfa11ae` is `completed` +- workplan `flex-wp-0003` / `c0a6c9f6-bb6b-416d-b537-f30504c63d75` is `completed` +- workplan `flex-wp-0004` / `99a82976-d376-42b0-89cc-c44e01c0bec6` is `completed` +- workplan `flex-wp-0005` / `e37d42a9-0018-4a67-a672-ff4e9716b338` is `done` +- workplan `flex-wp-0017` / `d75b7256-8b3d-5797-911c-96c3199b8baa` is `active` +- workplan `flex-wp-0019` / `84b9dc5a-71f2-5c70-ace6-78242b13d0f1` is `ready` +- task `7a980074-8488-5ab1-9202-60878adb261d` / `7a980074-8488-5ab1-9202-60878adb261d` is `todo` +- task `FLEX-WP-0017-T03` / `82d39961-8140-5a7f-9bd8-5164dd1742e5` is `wait` +- task `FLEX-WP-0017-T05` / `8c3fc0a2-0855-5ac9-afa5-d03b8b1f0bf9` is `wait` +- task `9d9c0e7a-56e2-5c71-9110-cea973243c22` / `9d9c0e7a-56e2-5c71-9110-cea973243c22` is `todo` +- task `bc109ee3-14b0-5603-a655-0d7376c2a41c` / `bc109ee3-14b0-5603-a655-0d7376c2a41c` is `todo` +- task `d5917b24-2efb-503e-9a9d-837702cafc1c` / `d5917b24-2efb-503e-9a9d-837702cafc1c` is `todo` +- task `f72b1305-114e-5ba2-b84c-f6cc0b524178` / `f72b1305-114e-5ba2-b84c-f6cc0b524178` is `todo` +- task `f7f501d7-6862-5542-88f7-78b704524706` / `f7f501d7-6862-5542-88f7-78b704524706` is `todo` + +Only `FLEX-WP-0017` is active and `FLEX-WP-0019` is ready. The preflight also +returned five historical workplans whose terminal `done`/`completed` status is +not concurrent work. T05 must take a fresh snapshot and explicitly coordinate +the two live workplans; it must not silently cancel or rewrite them. + +## External ownership ledger + +| Effect | Owning repository | What this plan may claim | +| --- | --- | --- | +| State Hub identity and aliases | `state-hub` | Record operation phase/evidence only; State Hub owns the mutation. | +| Preflight signing delivery | `railiance-platform` + `state-hub` | Require a non-secret provisioning receipt and zero-blocker preflight; never store the signing value here. | +| Forge-derived fabric projection | `railiance-fabric` | Record a handoff ID; only that repository closes its source change. | +| Credential-route catalog | `ops-warden` | Record route-review handoff; never request or store a secret here. | +| SBOM projection | `sbom-nexus` | Record re-ingestion evidence; SBOM Nexus owns its projection. | +| Repository CI and Forge-owned settings | `flex-auth` + Forgejo operator | Verify Actions, hooks, deploy keys, releases, redirects, and clone coordinates; keep package `coulomb/flex-auth`. | +| NetKingdom deployment sources and three live workloads | `net-kingdom` | Verify `sso-mfa/k8s/**` and all live `flex-auth-*` workloads remain healthy and intentionally retain runtime names/images. | +| Federation source URL and local roster | `reuse-surface` | Update `registry/federation/**`, re-ingest, and return owner evidence. | +| Publication source URL | `policy-nexus` | Update `source-inventory.config.json`, re-ingest, and return owner evidence. | +| Repository/path inventory | `repo-manager` | Reconcile the fresh clone to the same State Hub UUID; historical evidence stays unchanged. | +| Absolute source documentation link | `user-engine` | Update `wiki/ArchitectureBlueprint.md`; verify adapter/runtime `flex-auth` names remain intentional. | +| Runtime consumers and policy semantics | `tenant-engine`, `user-engine`, `ops-warden`, `railiance-platform`, `markitect-tool`, `gate-house`, `approval-engine`, `secrets-engine`, `zone-engine` | Verify repository URLs/path references change where present and semantic/runtime `flex-auth` names remain unchanged. | + +## 1. Capture immutable cleanliness and identity baseline + +```task +id: FLEX-WP-0020-T01 +status: todo +priority: high +``` + +Owner: `flex-auth`. + +- Require a clean target checkout and every branch/tag/change secured to Forgejo. +- Record `git status`, branch, remote, source commit, default branch, Forge ID, + visibility/readability, protected branches, releases, packages, hooks, deploy + keys, Actions variables, and redirects. +- Reconcile active work above: quiesce it or record an explicit concurrent-work + decision. A moved source commit requires a new preflight. +- If no registered path is visible, stop and register/verify a checkout; do not + infer private Forge state from local Git. + +Gate: repository UUID, Forge ID, branch, commit, and clean-state evidence are +recorded and match a fresh State Hub preflight. + +## 2. Prepare repository metadata and work-record frontmatter + +```task +id: FLEX-WP-0020-T02 +status: todo +priority: high +``` + +Owner: `flex-auth`. + +- Prepare repository metadata, README/INTENT/SCOPE/AGENTS references, Forge + description/topics, and canonical clone coordinates for `access-engine`. +- Keep the established `FLEX-WP-` workplan/task prefix and all existing + `state_hub_workstream_id` / `state_hub_task_id` values unchanged. +- Do not mass-rewrite historical prose or old-slug provenance. New live + frontmatter may adopt `repo: access-engine` only after State Hub rebind. +- Commit preparatory source changes before the final preflight; record the new + intended source commit. + +Gate: work-record parsing succeeds and no existing UUID field was removed, +replaced, or invented. + +## 3. Decide product and runtime naming separately + +```task +id: FLEX-WP-0020-T03 +status: todo +priority: high +``` + +Owner: `flex-auth`. + +The reviewed initial decision is: + +| Surface | Initial decision | +| --- | --- | +| Forge repository name, canonical clone/web/raw URLs, local checkout, and current repository metadata | Rename to `access-engine` in the phased sequence. | +| Workplan/task prefix and all State Hub UUID fields | Retain `FLEX-WP-` and every existing UUID. | +| Go module/import path `github.com/netkingdom/flex-auth`, binary/CLI, and `FLEX_AUTH_*` variables | Retain. | +| Kubernetes namespace, Deployments, Services/DNS, ServiceAccounts, RBAC, NetworkPolicies, Helm release/chart | Retain. | +| Container package `forgejo.coulomb.social/coulomb/flex-auth`, immutable digests, and current CI `IMAGE_NAME` | Retain and verify publication after the repository rename. | +| Policy/API vocabulary, audiences, dashboards, alerts, and telemetry service labels | Retain. | +| Broader product rename | Defer to a separately reviewed workplan after soak; not authorized here. | + +Any change to a `retain` row expands the blast radius and returns this plan to +`proposed` until the affected owner workplans, compatibility window, and +rollback limits are reviewed. + +Gate: every item has a decision record and independently deployable changes +have their own workplan or residual handoff. + +## 4. Inventory consumers and create owned handoffs + +```task +id: FLEX-WP-0020-T04 +status: todo +priority: high +``` + +Owner: `flex-auth` for inventory and handoff creation only. + +- Inventory CI includes/actions, package and image publishers, deployments, + GitOps/Helm/Kubernetes references, credential routes (using `warden route`), + authorization and NetKingdom policy consumers, fabric sources, SBOM scans, + docs, badges, webhooks, mirrors, caches, dashboards, alerts, and local clones. +- Start from the concrete owners and paths below. For each required source + change, create a live residual/intake/workplan in that owner before T05. +- Record each external work-record ID here and attach a + `state-hub.repository-rename-handoff.v1` payload following + `state-hub/docs/schemas/repository-rename-handoff-v1.schema.json`. It names + the source repository, old/new slug, affected paths or graph IDs, required + re-ingest and verification, owning workplan/task, and non-secret evidence. +- Do not mark that external work done from this repository; completion evidence + must come from its owner. +- Include every row in the preflight risk register, even when it is only a + warning or currently zero-count projection. + +Gate: every discovered external change has one named owning repository and +durable handoff ID; unknown ownership blocks the live rename. + +Reviewed inventory baseline: + +| Owner | Required source/verification surface | +| --- | --- | +| `railiance-fabric` | `registry/local-repos.yaml`, `registry/railiance-repos.yaml`, and live `fabric/**` declarations with `repo: flex-auth`; re-ingest repository/path graph nodes while retaining `flex-auth.*` runtime graph IDs. Historical discovery snapshots are evidence and are not rewritten. | +| `ops-warden` | `registry/routing/catalog.yaml` owner repository field; verify credential routing still resolves without exposing or rotating a credential. | +| `reuse-surface` | `registry/federation/sources.yaml`, `registry/federation/local-repo-roster.yaml`, and generated `registry/indexes/federated.yaml`; update raw URL/path, re-ingest, verify capability continuity. | +| `policy-nexus` | `source-inventory.config.json` remote URL; re-ingest and verify the same publication lineage. | +| `user-engine` | `wiki/ArchitectureBlueprint.md` absolute source path; separately verify its adapter and environment vocabulary remains `flex-auth`. | +| `net-kingdom` | Three ready live Deployments (`flex-auth-ops-warden`, `flex-auth-tenant-engine`, `flex-auth-user-engine`) and `sso-mfa/k8s/**`; no runtime rename, image-coordinate change, or rollout is authorized. | +| `tenant-engine` | Verify documentation and client configuration continue to use the retained product/runtime contract; no repository-coordinate source was found in the reviewed live paths. | +| `sbom-nexus` | Re-ingest the new canonical checkout and prove historical/current snapshots remain related to State Hub UUID `fda8ad85-a7d7-4055-8f21-902a533e59df`. | +| `repo-manager` | Reconcile the new canonical path and preserve file-backed identifiers; do not rewrite archived UUID-migration evidence. | +| `railiance-platform`, `markitect-tool`, `gate-house`, `approval-engine`, `secrets-engine`, `zone-engine` | Named verification owners for semantic consumers found in the estate scan; confirm no live repository URL/path remains and retain product/runtime terminology. | +| `flex-auth` + Forgejo operator | `.forgejo/workflows/image.yaml`, `charts/flex-auth/**`, `deploy/**`, releases, packages, hooks, Actions variables, deploy keys, branch protection, redirects, and clone URLs. Only repository coordinates change. | + +## 5. Renew State Hub preflight and record approval + +```task +id: FLEX-WP-0020-T05 +status: todo +priority: high +``` + +Owner: `flex-auth`. + +```text +statehub repo rename preflight flex-auth access-engine \ + --operation-id \ + --output --json +``` + +Verify zero blockers, immutable IDs/commit, active-work disposition, target +availability, every risk-register row, and no queued edge writes. Record a +human decision approving exact operation ID, source commit, target slug, owner, +window, rollback limits, and confirmation `rename:fda8ad85-a7d7-4055-8f21-902a533e59df:flex-auth:access-engine`. + +Gate: a current private preflight and explicit human approval exist. Never +commit the private preflight file or its token. + +## 6. Execute the Forgejo repository rename + +```task +id: FLEX-WP-0020-T06 +status: wait +priority: high +``` + +Owner: `flex-auth`; human approval required. + +Start/retry the durable journal, then apply exactly the Forge phase: + +```text +statehub repo rename start flex-auth access-engine \ + --operation-id --preflight-file \ + --actor --confirm 'rename:fda8ad85-a7d7-4055-8f21-902a533e59df:flex-auth:access-engine' --json +statehub repo rename apply --phase forge-renamed \ + --confirm 'rename:fda8ad85-a7d7-4055-8f21-902a533e59df:flex-auth:access-engine' --json +``` + +Confirm Forgejo reports the same numeric repository ID and commit under +`access-engine`. Stop on identity drift, unreadability, target conflict, or moved +source; do not create a second State Hub repository. + +Gate: operation journal is `forge-renamed` with immutable identity evidence. + +## 7. Record the State Hub identity rebind + +```task +id: FLEX-WP-0020-T07 +status: wait +priority: high +``` + +Owner: `flex-auth` for coordination; `state-hub` owns the mutation. + +```text +statehub repo rename apply --phase statehub-rebound \ + --confirm 'rename:fda8ad85-a7d7-4055-8f21-902a533e59df:flex-auth:access-engine' --json +statehub repo rename status --json +``` + +Record State Hub's phase evidence. Verify both `flex-auth` and `access-engine` +resolve to repository UUID `fda8ad85-a7d7-4055-8f21-902a533e59df`, `access-engine` is canonical, and the old +slug is a protected alias. Do not manually update the database. + +Gate: State Hub journal is `statehub-rebound`; IDs and historical relationships +are unchanged. + +## 8. Establish and register a fresh canonical clone + +```task +id: FLEX-WP-0020-T08 +status: wait +priority: high +``` + +Owner: `access-engine` after rebind. + +- Preserve the old checkout until verification and rollback decisions finish. +- Clone `access-engine` into a new path; verify origin and Forge numeric ID before + trusting redirects. +- Register the fresh path against the existing State Hub UUID, update canonical + source metadata/frontmatter, commit the source-synchronization revision, and + run `statehub fix-consistency` from the new clone. +- Apply `source-synced` with mode-0600 evidence containing + `fresh_clone: true`, Forge numeric `forge_repository_id`, exact `head_commit`, + clone path, registration result, and consistency result. Remote coordinates + contain no embedded credential. + +Gate: no duplicate repository registration exists and the journal is +`source-synced`. + +## 9. Verify identity, history, routes, builds, and deployments + +```task +id: FLEX-WP-0020-T09 +status: wait +priority: high +``` + +Owner: `access-engine` for aggregation; each external owner supplies its evidence. + +Compare relationship checksums—not only counts—for repository UUID, workplans, +tasks, progress, decisions, token events/totals, SBOM snapshots, services, +capabilities, messages, aliases, bindings, and active dispatch. Verify old/new +routes, Forge ID/commit, clean builds/tests, package/image publication, policy +and credential routes, fabric/SBOM projections, deployments, health, dashboards, +alerts, and telemetry continuity. + +```text +statehub repo rename verify --json +statehub repo rename apply --phase consumers-verified \ + --checks-file --evidence-file \ + --confirm 'rename:fda8ad85-a7d7-4055-8f21-902a533e59df:flex-auth:access-engine' --json +statehub repo rename apply --phase completed \ + --confirm 'rename:fda8ad85-a7d7-4055-8f21-902a533e59df:flex-auth:access-engine' --json +``` + +Gate: every required local check passes and every external handoff is `verified` +with evidence from its owning repository before completion. + +## 10. Exercise rollback decision points + +```task +id: FLEX-WP-0020-T10 +status: wait +priority: high +``` + +Owner: `access-engine` for the decision; State Hub and Forge owners execute their +own reversible phases. + +At every phase decide continue, pause safely, or enter rollback preflight. +Rollback is allowed only if the old Forge slug remains available and named +external effects are reversible. It never deletes aliases or history. + +```text +statehub repo rename rollback \ + --confirm 'rollback:' --json +# Execute only after reviewing safe_to_rollback and irreversible handoffs: +statehub repo rename rollback \ + --confirm 'rollback:' --execute --json +``` + +Gate: the forward completion or rolled-back terminal state is explicit; no +generic error is treated as proof of rollback. + +## 11. Soak, hand off residuals, and clean up the old checkout + +```task +id: FLEX-WP-0020-T11 +status: wait +priority: high +``` + +Owner: `access-engine`; destructive cleanup requires separate human approval. + +- Define and observe a soak window covering deployments, policy decisions, + alerts, telemetry, packages, automation, and old-slug compatibility reads. +- Convert every unresolved item into a live residual (`origin: residual`, + `origin_ref: FLEX-WP-0020`) in its owning repository before finishing; + retain its repository-rename handoff payload and owner work-record ID. +- Retain the protected `flex-auth` alias. Alias retirement is out of scope. +- Only after terminal verification, soak, residual handoff, and explicit cleanup + approval may the old local checkout be removed. Record what was removed and + whether recovery remains possible from Forgejo. + +Gate: no actionable residual exists only in prose, the new clone is canonical, +and old-checkout cleanup evidence is recorded.