flex-auth/workplans/FLEX-WP-0020-repository-identity-migration.md

---
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 <operation-id> \
  --output <private-preflight.json> --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 <operation-id> --preflight-file <private-preflight.json> \
  --actor <actor> --confirm 'rename:fda8ad85-a7d7-4055-8f21-902a533e59df:flex-auth:access-engine' --json
statehub repo rename apply <operation-id> --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 <operation-id> --phase statehub-rebound \
  --confirm 'rename:fda8ad85-a7d7-4055-8f21-902a533e59df:flex-auth:access-engine' --json
statehub repo rename status <operation-id> --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 <operation-id> --json
statehub repo rename apply <operation-id> --phase consumers-verified \
  --checks-file <private-checks.json> --evidence-file <private-evidence.json> \
  --confirm 'rename:fda8ad85-a7d7-4055-8f21-902a533e59df:flex-auth:access-engine' --json
statehub repo rename apply <operation-id> --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 <operation-id> \
  --confirm 'rollback:<operation-id>' --json
# Execute only after reviewing safe_to_rollback and irreversible handoffs:
statehub repo rename rollback <operation-id> \
  --confirm 'rollback:<operation-id>' --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.