diff --git a/README.md b/README.md index ada35ea..7ec04bf 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ recorded before they are spread across implementation repos. - [docs/rapp-first-wave-candidates.md](docs/rapp-first-wave-candidates.md) - [docs/reef-first-wave-rollout.md](docs/reef-first-wave-rollout.md) - [docs/fabric-state-hub-adaptation.md](docs/fabric-state-hub-adaptation.md) +- [docs/repo-family-bootstrap-contract.md](docs/repo-family-bootstrap-contract.md) - [docs/adr/ADR-0001-repository-prefix-architecture.md](docs/adr/ADR-0001-repository-prefix-architecture.md) - [docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md](docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md) - [docs/adr/ADR-0003-rapp-first-wave-selection.md](docs/adr/ADR-0003-rapp-first-wave-selection.md) diff --git a/SCOPE.md b/SCOPE.md index dd42b3a..b2cf59d 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -65,15 +65,16 @@ Railiance repos and cannot be owned cleanly by only one of them. ## Current State -- Status: maintained / evolving -- Implementation: architecture baseline documents are present and the first cross-repo separation workplan has been completed and handed off to sibling repos +- Status: active / evolving +- Implementation: architecture baseline documents are present and the first concrete repo-family materialization wave is now being coordinated from this repo - Stability: evolving - Usage: internal Railiance framework architecture home and handoff point for cross-repo planning The repo now holds the canonical framework decisions and boundary documents for separating `rail-*`, `rapp-*`, and `reef-*` concerns out of the existing -Railiance repos. Active implementation follow-up continues in the sibling -ownership repos. +Railiance repos. It also now governs the first implementation wave that turns +those repo families into concrete repos while downstream ownership repos retain +their implementation responsibility. --- diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index c62f478..3973ee5 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -9,6 +9,7 @@ | Kind | ID | Status | Lane | Source | | --- | --- | --- | --- | --- | | workplan | RAILIANCE-WP-0017 | finished | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md | +| workplan | RAILIANCE-WP-0018 | active | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md | | task | RAILIANCE-WP-0017-T01 | done | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md | | task | RAILIANCE-WP-0017-T02 | done | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md | | task | RAILIANCE-WP-0017-T03 | done | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md | @@ -16,3 +17,9 @@ | task | RAILIANCE-WP-0017-T05 | done | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md | | task | RAILIANCE-WP-0017-T06 | done | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md | | task | RAILIANCE-WP-0017-T07 | done | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md | +| task | RAILIANCE-WP-0018-T01 | done | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md | +| task | RAILIANCE-WP-0018-T02 | progress | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md | +| task | RAILIANCE-WP-0018-T03 | wait | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md | +| task | RAILIANCE-WP-0018-T04 | wait | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md | +| task | RAILIANCE-WP-0018-T05 | wait | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md | +| task | RAILIANCE-WP-0018-T06 | wait | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md | diff --git a/docs/repo-family-bootstrap-contract.md b/docs/repo-family-bootstrap-contract.md new file mode 100644 index 0000000..1b60692 --- /dev/null +++ b/docs/repo-family-bootstrap-contract.md @@ -0,0 +1,183 @@ +# First-Wave Repo Family Bootstrap Contract + +Date: 2026-07-25 + +## Purpose + +Define the minimum bootstrap contract for the first concrete `rail-*`, +`rapp-*`, and `reef-*` repos. + +This document exists to keep the first repo-materialization wave coherent. +Without a shared bootstrap contract, each new repo would improvise its own file +layout, declaration shape, and metadata vocabulary, which would weaken the +architecture as soon as the new repo families become real. + +## Design Goal + +The first concrete repos should be: + +- small enough to create quickly +- explicit enough to be queryable by Fabric and State Hub +- narrow enough to avoid reintroducing ownership ambiguity + +The goal is not to design a perfect final schema before the first repo exists. +The goal is to establish a minimal, repeatable repo baseline that can evolve +without fragmenting. + +## Required Repo Baseline + +Every first-wave `rail-*`, `rapp-*`, and `reef-*` repo should start with: + +- `.repo-classification.yaml` +- `README.md` +- `INTENT.md` +- `SCOPE.md` +- `AGENTS.md` +- `CLAUDE.md` +- `workplans/` +- `workplans/archived/` +- one repo-family declaration file under `declarations/` + +If a repo needs implementation code, manifests, charts, or automation, those +can be added after the bootstrap baseline is in place. + +## Required Classification Metadata + +The following metadata should be present either directly in +`.repo-classification.yaml` or in the first declaration file and projected from +there into Fabric and State Hub: + +- `repo_family` +- `ownership_repo` +- `primary_rail` when applicable +- `supported_rails` when applicable +- `substrate_kind` when applicable + +The source-of-truth rule is: + +- repo-local declarations define the domain facts +- registry metadata reflects the smallest useful projection of those facts + +Do not let registry-only metadata become the only place where a repo family is +described. + +## Required Declaration Files + +The first wave should standardize one obvious declaration path per repo family. + +### `rail-*` + +Path: + +`declarations/rail.yaml` + +Minimum fields: + +- `rail_id` +- `ownership_repo` +- `execution_architecture` +- `substrate_prerequisites` +- `supported_rollout_modes` +- `compatibility_notes` + +### `rapp-*` + +Path: + +`declarations/rapp.yaml` + +Minimum fields: + +- `rapp_id` +- `workload_identity` +- `ownership_repo` +- `supported_rails` +- `runtime_dependencies` +- `rollout_contract` +- `smoke_contract` +- `rollback_contract` + +### `reef-*` + +Path: + +`declarations/reef.yaml` + +Minimum fields: + +- `reef_id` +- `substrate_kind` +- `ownership_repo` +- `lifecycle_state` +- `criticality` +- `hosted_rails` +- `bound_rapps` +- `primary_rail` + +## Required Boundary Rules + +The first concrete repos must respect the architecture boundaries already +defined in `railiance-master`. + +### `rail-*` + +- A rail repo owns an execution contract, not substrate bootstrap. +- `rail-kubernetes` must not absorb S2 cluster provisioning, admission + controller ownership, or generic substrate hardening from + `railiance-cluster`. +- A rail repo may own generic workload-on-that-rail semantics, compatibility + guidance, and rail-local helper tooling. + +### `rapp-*` + +- A `rapp-*` repo owns managed workload packaging and scaffolding. +- A `rapp-*` repo must not become the long-term ownership home of the platform + or application domain around that workload. +- Shared policy, tenant governance, or platform-wide credential semantics stay + in the owning `railiance-*` repo. + +### `reef-*` + +- A reef repo owns one durable substrate boundary. +- A reef repo must not be created automatically for every machine. +- Grouped reefs remain preferred when the machines are managed as one class, + such as workstation fleets. + +## First-Wave Candidates + +The first materialization wave should target: + +- `rail-kubernetes` +- `rapp-openbao` +- `reef-railiance01` + +The follow-on first-wave candidates after those anchors are stable: + +- `rapp-vergabe-teilnahme` +- `reef-coulombcore` +- `reef-ops-workstations` + +This keeps the first concrete rollout narrow while still covering all three new +repo families. + +## Integration Expectations + +The first-wave repos should be able to participate in: + +- State Hub workplan indexing +- Fabric repository registration +- repo-family metadata projection +- later relation projection such as `supports_rail`, `hosts_rail`, + `binds_rapp`, and `governed_by` + +They do not need a fully mature graph model on day one, but they do need enough +structured metadata to avoid becoming opaque one-off repos. + +## Outcome + +The bootstrap contract for the first repo-family wave is: + +- one repeatable baseline file set +- one obvious declaration path per repo family +- one clear metadata projection path into Fabric and State Hub +- one narrow initial rollout set covering `rail-*`, `rapp-*`, and `reef-*` diff --git a/workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md b/workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md new file mode 100644 index 0000000..6c3f036 --- /dev/null +++ b/workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md @@ -0,0 +1,236 @@ +--- +id: RAILIANCE-WP-0018 +type: workplan +title: "First-Wave Repo Family Materialization" +domain: financials +repo: railiance-master +status: active +owner: codex +topic_slug: railiance +planning_priority: high +planning_order: 18 +created: "2026-07-25" +updated: "2026-07-25" +related_repos: + - railiance-master + - railiance-cluster + - railiance-platform + - railiance-infra + - railiance-fabric +state_hub_workstream_id: "054a494c-e430-4164-b2c3-e32e759cc3e0" +--- + +# RAILIANCE-WP-0018 - First-Wave Repo Family Materialization + +## Goal + +Turn the completed separation architecture into the first concrete +`rail-*`, `rapp-*`, and `reef-*` repo materialization wave. + +This workplan governs the first implementation wave that makes the new repo +families real rather than only defined. It stays in `railiance-master` because +the sequencing still spans multiple ownership repos and Fabric integration. + +## Why This Exists + +`RAILIANCE-WP-0017` completed the architecture baseline and launched the first +repo-local follow-up workplans. + +What is still missing is the shared control plane for: + +- creating the first concrete repo-family baselines +- keeping their boundaries consistent across repos +- aligning repo-local declarations with Fabric and State Hub ingestion +- preventing the first repo creations from drifting into ad hoc local patterns + +## Current Starting Point + +The architecture baseline already exists in `railiance-master`: + +- `docs/repository-axes.md` +- `docs/rail-kubernetes-boundary.md` +- `docs/rapp-first-wave-candidates.md` +- `docs/reef-first-wave-rollout.md` +- `docs/fabric-state-hub-adaptation.md` + +The first implementation follow-up work also already exists: + +- `railiance-cluster/workplans/RAIL-BS-WP-0012-rail-kubernetes-extraction.md` +- `railiance-platform/workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md` +- `railiance-infra/workplans/RAIL-HO-WP-0007-first-reef-rollout-and-s1-canonicalization.md` +- `railiance-fabric/workplans/RAIL-FAB-WP-0025-rail-rapp-reef-fabric-adaptation.md` + +Fabric now has first repo-family-aware repository metadata, but the ecosystem +still lacks: + +- the first actual `rail-*` repo +- the first actual `rapp-*` repo +- the first actual `reef-*` repo +- relation projection for rail/rapp/reef topology + +## Target Outcome + +When this workplan is complete: + +1. Railiance has a repeatable bootstrap contract for first-wave `rail-*`, + `rapp-*`, and `reef-*` repos. +2. The first concrete `rail-kubernetes` repo exists and is registered. +3. The first concrete `rapp-openbao` repo exists and is registered. +4. The first concrete `reef-railiance01` repo exists and is registered. +5. Fabric can project the minimum rail/rapp/reef relation topology needed to + answer placement questions. + +## Boundaries + +This workplan may coordinate repo creation, repo-family bootstrap, and graph +integration across Railiance repos. + +It must not weaken the existing ownership boundaries: + +- `railiance-cluster` remains the S2 ownership home +- `railiance-platform` remains the S3 ownership home for OpenBao +- `railiance-infra` remains the canonical S1 ownership home for first-wave reefs +- `railiance-fabric` remains the implementation home for graph ingestion and + projection + +## Tasks + +## T01 - Publish the first-wave repo bootstrap contract + +```task +id: RAILIANCE-WP-0018-T01 +status: done +priority: high +state_hub_task_id: "d6ba9286-222d-49d2-83e9-fd251c534dde" +``` + +Record the minimum bootstrap contract future `rail-*`, `rapp-*`, and +`reef-*` repos should follow so the first materialization wave does not invent +three incompatible patterns. + +Acceptance: + +- one framework document defines the minimum file baseline +- one framework document defines the first declaration path per repo family +- the metadata projection rule into Fabric and State Hub is named + +2026-07-25: Added `docs/repo-family-bootstrap-contract.md`. + +## T02 - Launch the first `rail-kubernetes` repo materialization + +```task +id: RAILIANCE-WP-0018-T02 +status: progress +priority: high +state_hub_task_id: "726a0c5c-2fa5-4bb9-a730-3200abc40ac8" +``` + +Create the concrete repo bootstrap and extraction path for `rail-kubernetes` +using the boundary already defined in `railiance-master` and the repo-local +follow-up work already opened in `railiance-cluster`. + +Acceptance: + +- the new repo has the required baseline files +- the repo declares the Kubernetes rail contract in source-controlled form +- the compatibility path from `railiance-cluster` is preserved +- the repo is ready for Fabric and State Hub registration + +## T03 - Launch the first `rapp-openbao` repo materialization + +```task +id: RAILIANCE-WP-0018-T03 +status: wait +priority: high +state_hub_task_id: "3e46e1bd-c730-4e41-a00a-6aa7a4645023" +``` + +Create the concrete repo bootstrap and workload-package declaration for +`rapp-openbao` without letting the package repo absorb platform ownership. + +Acceptance: + +- the new repo has the required baseline files +- the repo declares OpenBao as a managed workload package +- the repo declares supported rails and rollout/smoke/rollback contract +- the remaining ownership boundary with `railiance-platform` stays explicit + +## T04 - Launch the first `reef-railiance01` repo materialization + +```task +id: RAILIANCE-WP-0018-T04 +status: wait +priority: medium +state_hub_task_id: "f6f2ea73-0ff3-4cfa-b7a7-7b71db3afb4a" +``` + +Create the concrete repo bootstrap and substrate declaration for +`reef-railiance01` as the first durable reef repo. + +Acceptance: + +- the new repo has the required baseline files +- the repo declares substrate kind, lifecycle, criticality, hosted rails, and + primary rail +- the repo stays compatible with the canonical S1 ownership role of + `railiance-infra` + +## T05 - Add relation projection for rails, `rapp`s, and reefs in Fabric + +```task +id: RAILIANCE-WP-0018-T05 +status: wait +priority: medium +state_hub_task_id: "ef999db5-e75e-467a-a72a-d45fda2b6fa7" +``` + +Extend Fabric beyond repo-family-aware metadata so it can project the minimum +rail/rapp/reef relation topology. + +Acceptance: + +- Fabric can project `supports_rail` +- Fabric can project `hosts_rail` +- Fabric can project `binds_rapp` +- Fabric can project `governed_by` +- the projection path is grounded in repo-local declarations rather than + registry-only guesses + +## T06 - Verify first-wave registration and coordination end to end + +```task +id: RAILIANCE-WP-0018-T06 +status: wait +priority: medium +state_hub_task_id: "5834f122-b9e9-41c1-93e9-d5525cd720bf" +``` + +Verify that the first concrete repos participate cleanly in: + +- State Hub registration and indexing +- Fabric registration and graph projection +- workplan tracking across ownership repo and repo-family repo boundaries + +Acceptance: + +- the first concrete repos are visible to State Hub +- the first concrete repos are visible to Fabric +- cross-repo ownership and runtime relations are queryable +- the wave can continue to second candidates without redefining the bootstrap model + +## Exit Criteria + +- [x] The first-wave bootstrap contract is published +- [ ] `rail-kubernetes` exists as a first-class repo baseline +- [ ] `rapp-openbao` exists as a first-class repo baseline +- [ ] `reef-railiance01` exists as a first-class repo baseline +- [ ] Fabric projects the minimum rail/rapp/reef relation topology +- [ ] State Hub and Fabric can coordinate the first concrete repo-family wave end to end + +## Notes + +This workplan should stay focused on the first concrete repo-family wave. + +Second-wave candidates such as `rapp-vergabe-teilnahme`, `reef-coulombcore`, +or a future `rail-knative` should be launched only after the first wave proves +the bootstrap contract, registration path, and relation model.