Define rapp-openbao boundary

SCOPE.md

@@ -14,7 +14,17 @@ S3 Platform Services layer of the Railiance OAS Stack — owns shared cluster se
 
 ## Core Idea
 
-Railiance is structured as five independent repos per OAS Stack layer. This repo is S3 — the platform services that multiple applications share. The active migration is from Bitnami postgresql-ha (repmgr + pgpool, currently a Gitea subchart in S2) to CloudNative PG (cnpg operator, already deployed in the cnpg-system namespace) as the canonical database operator. Valkey cluster is also in scope for S3 extraction from S2.
+Railiance is structured as five independent repos per OAS Stack layer. This repo
+is S3 - the platform services that multiple applications share. The active
+migration is from Bitnami postgresql-ha (repmgr + pgpool, currently a Gitea
+subchart in S2) to CloudNative PG (cnpg operator, already deployed in the
+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
+assets are being separated from custody, policy, and lane governance as part of
+the future `rapp-openbao` extraction.
 
 ---
 
@@ -37,6 +47,7 @@ Railiance is structured as five independent repos per OAS Stack layer. This repo
 - 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
 - No re-configuration of S1/S2 concerns from this repo
 
 ---
@@ -46,6 +57,7 @@ Railiance is structured as five independent repos per OAS Stack layer. This repo
 - Deploying or managing shared services that multiple S5 applications depend on
 - Extracting platform services from application Helm subcharts (boundary enforcement)
 - S2 cluster is operational and platform layer can now be established
+- Defining which OpenBao concerns are workload package assets versus retained platform governance
 
 ---
 
@@ -60,9 +72,10 @@ Railiance is structured as five independent repos per OAS Stack layer. This repo
 ## Current State
 
 - Status: active / emerging
-- Implementation: CloudNative PG operator (cnpg) deployed; `databases` namespace active; Valkey + legacy postgresql-ha extraction from S2 in progress (RAIL-PL-WP-0001)
+- 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: will be the shared database and cache layer; currently cnpg-system + databases namespaces are live
+- 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)
 
 ---
 
@@ -77,7 +90,7 @@ Railiance is structured as five independent repos per OAS Stack layer. This repo
 ## 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
+- 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
 
 ---
 

WORK-RECORDS.md

@@ -48,9 +48,9 @@
 | task | RAILIANCE-WP-0011-T02 | done | — | workplans/RAILIANCE-WP-0011-reuse-surface-runtime-secrets-openbao-lane.md |
 | task | RAILIANCE-WP-0011-T03 | done | — | workplans/RAILIANCE-WP-0011-reuse-surface-runtime-secrets-openbao-lane.md |
 | task | RAILIANCE-WP-0011-T04 | done | — | workplans/RAILIANCE-WP-0011-reuse-surface-runtime-secrets-openbao-lane.md |
-| task | RAILIANCE-WP-0012-T01 | todo | — | workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md |
-| task | RAILIANCE-WP-0012-T02 | todo | — | workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md |
-| task | RAILIANCE-WP-0012-T03 | todo | — | workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md |
+| 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-0013-T01 | todo | — | workplans/RAILIANCE-WP-0013-forgejo-admin-pat-openbao-cutover.md |
 | task | RAILIANCE-WP-0013-T02 | todo | — | workplans/RAILIANCE-WP-0013-forgejo-admin-pat-openbao-cutover.md |

docs/openbao.md

@@ -10,6 +10,13 @@
 
 ---
 
+Ownership note: the deployable OpenBao package surface documented here is the
+candidate for a future `rapp-openbao` repo. Platform custody, policy,
+credential lanes, delegated automation, and root-of-trust handling remain
+`railiance-platform` responsibilities even after that package extraction.
+
+---
+
 ## Architecture
 
 ```

docs/rapp-openbao-boundary.md

@@ -0,0 +1,83 @@
+# rapp-openbao Boundary
+
+This document records the first-wave boundary for extracting a future
+`rapp-openbao` repo out of `railiance-platform`.
+
+The rule is simple:
+
+- `rapp-openbao` owns the deployable OpenBao package surface
+- `railiance-platform` keeps secret custody, policy, lane governance, and
+  platform-wide operator controls
+
+## Package Assets For Future `rapp-openbao`
+
+These files describe or implement the OpenBao workload package itself and are
+valid candidates for a dedicated wrapper repo.
+
+| Path | Why it belongs with the package |
+| --- | --- |
+| `helm/openbao-values.yaml` | Helm values for the OpenBao workload |
+| `helm/openbao-middleware.yaml` | OpenBao-specific ingress/middleware surface |
+| `helm/openbao-ui-overlay-k8s.yaml` | OpenBao UI gateway Deployment/Service/Ingress manifest |
+| `helm/openbao-ui-overlay/` | UI overlay assets and gateway config for the OpenBao service |
+| `scripts/openbao-ui-overlay-apply.sh` | Applies package-owned UI overlay assets |
+| `scripts/openbao-verify.sh` | Non-secret workload deployment verification |
+| `scripts/openbao-verify-login-overlay.sh` | Verifies package-owned public UI overlay behavior |
+| `docs/openbao-emergency-drill-evidence.example.json` | Example workload-specific emergency evidence format |
+| `docs/openbao-restore-drill-evidence.example.json` | Example workload-specific restore evidence format |
+| `scripts/openbao-validate-emergency-drill-evidence.sh` | Validates workload-specific emergency drill evidence |
+| `scripts/openbao-validate-restore-evidence.sh` | Validates workload-specific restore drill evidence |
+
+## Split-Before-Move Assets
+
+These files mix package bring-up with retained S3 governance. They should be
+split before a clean repo move.
+
+| Path | Why it needs splitting |
+| --- | --- |
+| `docs/openbao.md` | Contains both package deployment/runbook material and retained platform custody/bootstrap policy |
+| `scripts/openbao-apply-initial-config.sh` | Combines workload bootstrap with S3-owned `platform-admin` / `platform-readonly` policy loading and Kubernetes auth setup |
+| `Makefile` target `openbao-configure-initial` | Thin wrapper around the mixed script above |
+| `scripts/openbao-verify-authenticated.sh` | Verifies retained policy/auth/audit surfaces, not just package health |
+
+## Retained `railiance-platform` Responsibilities
+
+These files and concerns stay in S3 even after a wrapper repo exists.
+
+| Path or family | Why it stays in S3 |
+| --- | --- |
+| `openbao/policies/platform-admin.hcl`, `openbao/policies/platform-readonly.hcl` | Platform operator and read-only policy surface |
+| `docs/openbao-approved-automation-delegation.md` | Governance for approved metadata mutation under platform control |
+| `openbao/policies/credential-change-*.hcl` and `scripts/openbao-apply-credential-change-appliers.py` | Delegated metadata-apply policy and role management |
+| `docs/credential-change-approval.md`, `docs/credential-lane-lifecycle-runbook.md`, `docs/workload-kv-access-lanes.md`, `credential-change-requests/` | Source of truth for lane approval, lifecycle, and custody decisions |
+| `openbao/policies/workload-kv-read-*.hcl` and `scripts/openbao-apply-workload-kv-lanes.sh` | Cross-workload runtime secret lane governance |
+| `openbao/policies/external-secrets-*.hcl` and `scripts/openbao-apply-external-secrets-issue-core.sh` | Cross-workload External Secrets / ESO integration policy |
+| `openbao/ssh/roles-spec.yaml`, `openbao/policies/warden-sign.hcl`, `scripts/openbao-apply-ssh-engine.sh`, `scripts/openbao-verify-ssh-engine.sh` | Platform SSH signing capability for ops-warden, not an OpenBao package concern |
+| `docs/credential-broker.md`, `credential-grants/`, `scripts/credential.py`, `scripts/openbao-apply-token-grants.py`, `scripts/openbao-verify-token-grants.py`, `openbao/policies/credential-broker-*.hcl` | Platform credential-broker and token-grant governance |
+| `scripts/forgejo-admin-pat-provision.sh` and other workload-lane provisioning helpers | Provision secrets for other workloads through OpenBao; not part of the OpenBao package itself |
+
+## First Move Set
+
+The first repo-creation handoff for `rapp-openbao` should start with the least
+coupled package assets:
+
+- `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`
+- the `Makefile` targets `openbao-repo`, `openbao-dry-run`, `openbao-overlay-apply`,
+  `openbao-deploy`, `openbao-status`, `openbao-verify`, and
+  `openbao-verify-login-overlay`
+
+This first move set is enough to establish a package repo that can render,
+deploy, and verify OpenBao without inheriting platform lane governance.
+
+## Resulting Rule
+
+`rapp-openbao` may own how OpenBao is packaged, deployed, verified, and skinned
+for Railiance. It must not become the home for platform-admin policy, workload
+KV lane policy, delegated metadata authority, credential grants, or human root
+custody procedure.

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

@@ -40,7 +40,7 @@ It must not:
 
 ```task
 id: RAILIANCE-WP-0012-T01
-status: todo
+status: done
 priority: high
 state_hub_task_id: "498a89e1-67e1-4860-8c73-cc38dd92083c"
 ```
@@ -52,11 +52,15 @@ Classify the current OpenBao-related files into:
 
 Done when the distinction is written against real file paths and current usage.
 
+2026-07-25: Added `docs/rapp-openbao-boundary.md` with file-path classification
+for OpenBao package assets, split-before-move assets, and retained S3
+governance material.
+
 ## T02 - Define the first `rapp-openbao` move set
 
 ```task
 id: RAILIANCE-WP-0012-T02
-status: todo
+status: done
 priority: high
 state_hub_task_id: "67526f71-0220-45fb-ab9d-8cef5628257c"
 ```
@@ -70,11 +74,15 @@ Prepare the first move set for the wrapper, including likely candidates such as:
 
 Done when the future wrapper has a concrete first file inventory.
 
+2026-07-25: Recorded the first move set in
+`docs/rapp-openbao-boundary.md`, centered on Helm values, UI overlay assets,
+OpenBao deploy/verify helpers, and the matching `Makefile` targets.
+
 ## T03 - Record the retained S3 platform responsibilities
 
 ```task
 id: RAILIANCE-WP-0012-T03
-status: todo
+status: done
 priority: high
 state_hub_task_id: "30036060-85ec-4a24-a428-9f31dd58f853"
 ```
@@ -88,6 +96,10 @@ Record what must remain in `railiance-platform`, including:
 
 Done when the wrapper cannot be mistaken for the new S3 ownership home.
 
+2026-07-25: Recorded retained S3 responsibilities in
+`docs/rapp-openbao-boundary.md`, including platform-admin policy, workload KV
+lane governance, delegated automation, credential grants, and SSH signing.
+
 ## T04 - Prepare the repo-creation handoff for `rapp-openbao`
 
 ```task