docs: add access-engine repository migration plan

Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a049a4-ee9f-78e1-9d66-2cb0f9bea3e3
2026-08-29 17:53:43 +02:00 · 2026-08-29 17:53:43 +02:00 · 8d61ac94ab
commit 8d61ac94ab
parent 7d7b4531d1
1 changed files with 425 additions and 0 deletions
--- a/workplans/FLEX-WP-0020-repository-identity-migration.md
+++ 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 <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
+```
+
+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
+```
+
+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
+```
+
+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 <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
+```
+
+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
+```
+
+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.