Document rapp-openbao compatibility handoff

SCOPE.md

@@ -22,9 +22,9 @@ cnpg-system namespace) as the canonical database operator. Valkey cluster is
 also in scope for S3 extraction from S2.
 
 OpenBao is a platform capability in this repo, but not every OpenBao-related
-file necessarily belongs in the long-term S3 ownership home. Deployment package
+file belongs in the long-term S3 ownership home. The deployable package surface
-assets are being separated from custody, policy, and lane governance as part of
+now has a wave-1 repo home in `rapp-openbao`, while this repo retains custody,
-the future `rapp-openbao` extraction.
+policy, and lane governance.
 
 ---
 
@@ -47,7 +47,7 @@ the future `rapp-openbao` extraction.
 - Kubernetes runtime → railiance-cluster (S2)
 - Developer tooling, CI/CD → railiance-enablement (S4)
 - Application deployments → railiance-apps (S5)
-- Standalone workload-package ownership for OpenBao deployment assets -> future `rapp-openbao`, while S3 retains secrets custody and policy
+- Standalone workload-package ownership for OpenBao deployment assets -> `rapp-openbao`, while S3 retains secrets custody and policy
 - No re-configuration of S1/S2 concerns from this repo
 
 ---
@@ -71,11 +71,13 @@ the future `rapp-openbao` extraction.
 
 ## Current State
 
-- Status: active / emerging
+- Status: maintained / emerging
 - Implementation: CloudNative PG operator (cnpg) deployed; `databases` namespace active; OpenBao is live as the S3 secrets service; Valkey + legacy postgresql-ha extraction from S2 remain in progress
 - Stability: emerging — cnpg deployed but database cluster definitions not yet migrated from S2
 - Usage: shared database, cache, and secrets layer; cnpg-system, databases, and openbao namespaces are live
-- Open work: `RAILIANCE-WP-0012` rapp-openbao extraction boundary (active); `RAILIANCE-WP-0013` Forgejo admin PAT OpenBao consumer cutover (active)
+- Open work: Valkey and legacy postgresql-ha extraction remain active; the
+  OpenBao package boundary and PAT consumer cutover are now documented and
+  closed
 
 ---
 
@@ -90,7 +92,7 @@ the future `rapp-openbao` extraction.
 ## Terminology
 
 - Preferred terms: OAS Stack Level S3, platform services, boundary rule, migration (extracting from S2 subcharts)
-- Potentially confusing terms: "migration" here means moving Helm releases between layers, not database schema migration; `rapp-openbao` would package OpenBao, but it would not own platform custody or policy
+- Potentially confusing terms: "migration" here means moving Helm releases between layers, not database schema migration; `rapp-openbao` packages OpenBao, but it does not own platform custody or policy
 
 ---
 

WORK-RECORDS.md

@@ -13,7 +13,7 @@
 | workplan | RAILIANCE-WP-0009 | finished | — | workplans/RAILIANCE-WP-0009-issue-core-runtime-ingestion-key-lane.md |
 | workplan | RAILIANCE-WP-0010 | finished | — | workplans/RAILIANCE-WP-0010-llm-connect-openrouter-provider-key-lane.md |
 | workplan | RAILIANCE-WP-0011 | finished | — | workplans/RAILIANCE-WP-0011-reuse-surface-runtime-secrets-openbao-lane.md |
-| workplan | RAILIANCE-WP-0012 | active | — | workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md |
+| workplan | RAILIANCE-WP-0012 | finished | — | workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md |
 | workplan | RAILIANCE-WP-0013 | finished | — | workplans/RAILIANCE-WP-0013-forgejo-admin-pat-openbao-cutover.md |
 | task | RAILIANCE-WP-0005-T01 | done | — | workplans/RAILIANCE-WP-0005-credential-request-and-lease-broker.md |
 | task | RAILIANCE-WP-0005-T02 | done | — | workplans/RAILIANCE-WP-0005-credential-request-and-lease-broker.md |
@@ -51,7 +51,7 @@
 | task | RAILIANCE-WP-0012-T01 | done | — | workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md |
 | task | RAILIANCE-WP-0012-T02 | done | — | workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md |
 | task | RAILIANCE-WP-0012-T03 | done | — | workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md |
-| task | RAILIANCE-WP-0012-T04 | wait | — | workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md |
+| task | RAILIANCE-WP-0012-T04 | done | — | workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md |
 | task | RAILIANCE-WP-0013-T01 | done | — | workplans/RAILIANCE-WP-0013-forgejo-admin-pat-openbao-cutover.md |
 | task | RAILIANCE-WP-0013-T02 | done | — | workplans/RAILIANCE-WP-0013-forgejo-admin-pat-openbao-cutover.md |
 | task | RAILIANCE-WP-0013-T03 | done | — | workplans/RAILIANCE-WP-0013-forgejo-admin-pat-openbao-cutover.md |

docs/openbao.md

@@ -10,10 +10,12 @@
 
 ---
 
-Ownership note: the deployable OpenBao package surface documented here is the
+Ownership note: the deployable OpenBao package surface now has a wave-1 home in
-candidate for a future `rapp-openbao` repo. Platform custody, policy,
+`rapp-openbao`. Platform custody, policy, credential lanes, delegated
-credential lanes, delegated automation, and root-of-trust handling remain
+automation, and root-of-trust handling remain `railiance-platform`
-`railiance-platform` responsibilities even after that package extraction.
+responsibilities. Use `docs/rapp-openbao-compatibility-handoff.md` for the
+migration-window split between package-owned deploy/smoke surfaces and retained
+S3 bootstrap/governance work.
 
 ---
 

docs/rapp-openbao-boundary.md

@@ -1,6 +1,6 @@
 # rapp-openbao Boundary
 
-This document records the first-wave boundary for extracting a future
+This document records the first-wave boundary for extracting the wave-1
 `rapp-openbao` repo out of `railiance-platform`.
 
 The rule is simple:
@@ -9,7 +9,7 @@ The rule is simple:
 - `railiance-platform` keeps secret custody, policy, lane governance, and
   platform-wide operator controls
 
-## Package Assets For Future `rapp-openbao`
+## Package Assets For `rapp-openbao`
 
 These files describe or implement the OpenBao workload package itself and are
 valid candidates for a dedicated wrapper repo.
@@ -58,7 +58,7 @@ These files and concerns stay in S3 even after a wrapper repo exists.
 
 ## First Move Set
 
-The first repo-creation handoff for `rapp-openbao` should start with the least
+The initial repo-creation handoff for `rapp-openbao` started with the least
 coupled package assets:
 
 - `helm/openbao-values.yaml`
@@ -75,6 +75,9 @@ coupled package assets:
 This first move set is enough to establish a package repo that can render,
 deploy, and verify OpenBao without inheriting platform lane governance.
 
+The migration-window compatibility path between `railiance-platform` and
+`rapp-openbao` now lives in `docs/rapp-openbao-compatibility-handoff.md`.
+
 ## Resulting Rule
 
 `rapp-openbao` may own how OpenBao is packaged, deployed, verified, and skinned

docs/rapp-openbao-compatibility-handoff.md

@@ -0,0 +1,97 @@
+# `rapp-openbao` Compatibility Handoff
+
+## Purpose
+
+Define the migration-window handoff between `railiance-platform` and
+`rapp-openbao` for the deployable OpenBao package surface.
+
+Wave 1 makes `rapp-openbao` the durable owner of the OpenBao package contract.
+`railiance-platform` remains the S3 owner of custody, policy, credential-lane
+governance, and root-of-trust handling. During the migration window,
+`railiance-platform` keeps a thin compatibility surface so current operators do
+not need a flag day.
+
+## Canonical Package Owner
+
+Use `rapp-openbao` as the canonical home for these package-owned assets and
+behaviors:
+
+- `helm/openbao-values.yaml`
+- `helm/openbao-middleware.yaml`
+- `helm/openbao-ui-overlay-k8s.yaml`
+- `helm/openbao-ui-overlay/`
+- `scripts/openbao-ui-overlay-apply.sh`
+- `scripts/openbao-verify.sh`
+- `scripts/openbao-verify-login-overlay.sh`
+- `scripts/openbao-validate-emergency-drill-evidence.sh`
+- `scripts/openbao-validate-restore-evidence.sh`
+- the drill-evidence example JSON files
+- the package-owned `Makefile` targets:
+  `openbao-repo`, `openbao-dry-run`, `openbao-overlay-apply`,
+  `openbao-deploy`, `openbao-status`, `openbao-verify`,
+  `openbao-verify-post-unseal`, `openbao-verify-login-overlay`,
+  `openbao-validate-restore-evidence`, and
+  `openbao-validate-emergency-evidence`
+
+New behavior, docs, and fixes for that deploy/overlay/smoke surface should land
+in `rapp-openbao` first.
+
+## Platform-Side Compatibility Surface
+
+During the migration window, `railiance-platform` may still expose the same
+package-owned `Makefile` targets and keep compatibility copies of the
+package-owned files listed above.
+
+Those copies are for operator continuity only. They are not the long-term
+source of truth.
+
+If package-owned behavior changes:
+
+1. update `rapp-openbao` first;
+2. refresh the compatibility copy in `railiance-platform` only when current
+   operators or automation still depend on it; and
+3. avoid evolving the platform copy independently.
+
+## What Stays In `railiance-platform`
+
+The handoff does not expand the package boundary.
+
+Still retained in `railiance-platform` as S3 ownership:
+
+- `docs/openbao.md` sections covering init, unseal, custody, auth bootstrap,
+  audit posture, and platform-owned policy
+- `scripts/openbao-apply-initial-config.sh`
+- `scripts/openbao-verify-authenticated.sh`
+- `scripts/openbao-apply-ssh-engine.sh`
+- `scripts/openbao-verify-ssh-engine.sh`
+- `scripts/openbao-apply-workload-kv-lanes.sh`
+- `scripts/openbao-apply-credential-change-appliers.py`
+- `scripts/openbao-apply-token-grants.py`
+- the matching `Makefile` targets:
+  `openbao-configure-initial`, `openbao-configure-ssh`,
+  `openbao-verify-ssh`, `openbao-verify-authenticated`,
+  `openbao-configure-workload-kv-lanes`,
+  `openbao-configure-credential-change-appliers`,
+  `openbao-configure-token-grants`, and related verification targets
+- platform policy, credential-grant, and delegated-metadata source under
+  `openbao/policies/`, `credential-change-requests/`, and `credential-grants/`
+
+## Operator Migration Path
+
+Operators can move without a flag day:
+
+1. Use `rapp-openbao` for package deploy, overlay, smoke, and package-owned
+   drill-evidence work.
+2. Continue using `railiance-platform` for attended bootstrap, authenticated
+   verification, and policy/governance flows.
+3. If existing automation still calls the package-owned OpenBao targets from
+   `railiance-platform`, it may keep doing so during the migration window, but
+   canonical fixes still land in `rapp-openbao` first.
+4. Split mixed docs and scripts before removing the platform compatibility
+   copies.
+
+## Exit Condition
+
+The migration window can end once current operators and automation no longer
+depend on `railiance-platform` copies of package-owned OpenBao files or
+targets, and the remaining mixed material has been split cleanly.

workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md

@@ -4,11 +4,11 @@ type: workplan
 title: "rapp-openbao extraction boundary"
 domain: financials
 repo: railiance-platform
-status: active
+status: finished
 owner: codex
 topic_slug: railiance
 created: "2026-07-25"
-updated: "2026-07-25"
+updated: "2026-07-26"
 state_hub_workstream_id: "6ec5f317-e6c6-48e8-a7d4-850c13541641"
 ---
 
@@ -104,7 +104,7 @@ lane governance, delegated automation, credential grants, and SSH signing.
 
 ```task
 id: RAILIANCE-WP-0012-T04
-status: wait
+status: done
 priority: medium
 state_hub_task_id: "25bf2d11-4a85-4259-9027-79768a23a06c"
 ```
@@ -116,6 +116,14 @@ current operators or losing source-of-truth clarity inside `railiance-platform`.
 
 Done when the future package extraction can start from a stable boundary.
 
+2026-07-26: Added `docs/rapp-openbao-compatibility-handoff.md` to define the
+current migration-window split: `rapp-openbao` is now the canonical home for
+package-owned deploy/overlay/smoke assets, while `railiance-platform` retains
+bootstrap, policy, credential-lane governance, and authenticated verification.
+`docs/rapp-openbao-boundary.md`, `docs/openbao.md`, and `SCOPE.md` now point to
+that split explicitly, so current operators can keep using temporary platform
+copies without losing source-of-truth clarity.
+
 ## Notes
 
 This workplan is repo-local. The framework-level sequencing stays in