--- 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. state_hub_workstream_id: "99a661a8-b36c-5c1c-b78b-1e8930bcd0a9" --- # 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 state_hub_task_id: "bb989019-50a7-5273-ba09-b2df2e2602a4" ``` 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 state_hub_task_id: "102e9dc7-4724-5e80-84c4-092e6ecfbb2b" ``` 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 state_hub_task_id: "5095ddbc-b69c-5a52-b97f-08fca9b610c3" ``` 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 state_hub_task_id: "9bb138e1-5edb-5714-8d89-3b1b7039a7ce" ``` 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 state_hub_task_id: "86fecbb6-b008-5354-8d70-0f4ba5077a58" ``` 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 state_hub_task_id: "aa7ccd59-ddd3-5af0-a866-30e88552fc09" ``` 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 state_hub_task_id: "155041ed-8cba-5e5e-ac59-fc03ef6dd0ce" ``` 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 state_hub_task_id: "c8afe078-41cf-5d8c-84d1-a49e4b618d34" ``` 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 state_hub_task_id: "fdb50a96-f7fa-5d4a-9efa-231750dcb2f1" ``` 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 state_hub_task_id: "3dc49eb4-1f39-5250-87c9-716a9a97790d" ``` 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 state_hub_task_id: "46d8318b-d1fb-52e3-b632-52230ed1438f" ``` 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.