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

id	type	title	domain	repo	status	flavor	owner	topic_slug	created	updated	reviewed_at	reviewed_by	reviewed_against_commit	reviewed_note	quality_dor	quality_dor_at	quality_dor_by	quality_dor_note	state_hub_workstream_id
FLEX-WP-0020	workplan	Repository identity migration from flex-auth to access-engine	infotech	flex-auth	active	planning	codex	netkingdom	2026-08-29	2026-09-15	2026-08-29	codex	7d7b4531d1	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.	DoR-Ok	2026-08-29	codex	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.	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

id: FLEX-WP-0020-T01
status: done
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.

2026-09-15: captured in docs/evidence/2026-09-15-repository-rename-baseline.md. Signing is no longer a blocker. safe_to_apply=true, zero blockers, warning active_work_present disposed by FLEX-DEC-2026-014. A later commit still needs a T05 preflight before forge-renamed.

2. Prepare repository metadata and work-record frontmatter

id: FLEX-WP-0020-T02
status: done
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.

2026-09-15: README states the planned access-engine clone URL and that frontmatter stays repo: flex-auth until rebind. No UUID fields rewritten.

3. Decide product and runtime naming separately

id: FLEX-WP-0020-T03
status: done
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.

2026-09-15: accepted as FLEX-DEC-2026-013 / hub 9f2dd7a4-6437-4e59-8403-ae56d9cc1d09.

4. Inventory consumers and create owned handoffs

id: FLEX-WP-0020-T04
status: progress
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.

2026-09-15: inventory in docs/evidence/2026-09-15-repository-rename-handoffs.md. Owner work-record IDs are requested, not invented. T06 stays blocked on those IDs plus the human confirm string.

2026-09-20: first owner work-record returned. reuse-surface created REUSE-WP-0023 (65c03b24-4349-5a60-b7d6-79cf54931d06, active) with T01 d97094d4-4cad-5b35-aa88-eb952215937a and T02 77b1eb56-bbf6-5454-892f-bf60e32b864a, both deliberately in wait. Recorded in the evidence file; not marked done from here. Verified independently: the hub record exists and is active, access-engine raw returns 404 while flex-auth returns 303, so the rename has not landed and their refusal to pre-rewrite the source URL is correct. It adds an ordering constraint this plan now owns — the federation source rewrite follows T06 rather than preceding it, and flex-auth owes them a ping on message thread 82bfe60f-1258-4d5d-9b81-9596b5fedd9e once access-engine serves /raw/main/registry/indexes/capabilities.yaml. Nine owners remain pending.

2026-09-21: two more owner records acknowledged. tenant-engine returned TEN-IN-0004 (hub intake 01a0c14b-b2f7-78f1-8f6c-e36c952fe004) with the retained runtime contract verified; secrets-engine returned SECRETS-IN-0002 with one repository path held until the rename lands. Both are open by design and close on their side after T06; flex-auth owes each a "rename landed" notice. Recorded in the evidence file. Seven owners remain pending.

2026-09-27: net-kingdom confirmed NK-WP-0039-T02 done (package coordinate unchanged, pins stay, no other coordinate reference found) and runtime.yaml now declares current tenant-engine/user-engine digests. NK-WP-0039-T03 waits only on flex-auth's announcement that access-engine resolves, i.e. it is gated on T06 like the others. Separately, net-kingdom found sso-mfa/k8s/tenant-engine/runtime.yaml live-ahead-of-file beyond digests (missing --caller-auth-mode enforce and caller bindings) and proposed replacing the flex-auth part of it with a pointer to values/<consumer>.yaml per their ADR-0015; flex-auth replied with no objection, since that matches the pattern flex-auth already uses for other consumers and points at a file that actually tracks caller-auth state. Six owners now confirmed acknowledged or resolved on their side; the remainder is still tracked in the evidence file. This does not change T04's own gate — the external ownership ledger still requires every discovered change to land its own owning-repository handoff before T05/T06.

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

id: FLEX-WP-0020-T05
status: wait
priority: high
state_hub_task_id: "86fecbb6-b008-5354-8d70-0f4ba5077a58"

Owner: flex-auth.

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.

2026-09-15: signing is provisioned; a private preflight of 6fd3a0c was zero-blocker. Re-run after this source commit. Human confirmation of rename:fda8ad85-a7d7-4055-8f21-902a533e59df:flex-auth:access-engine is still required before T06. Do not start the journal from this session.

6. Execute the Forgejo repository rename

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:

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

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.

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

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

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.

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

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.

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

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.