docs: align master with canon and policy publication
This commit is contained in:
codex
parent
6e230be13a
commit
7d32673812
12 changed files with 403 additions and 70 deletions
198
SCOPE.md
198
SCOPE.md
|
|
@ -1,112 +1,166 @@
|
|||
# SCOPE
|
||||
|
||||
> This file helps you quickly understand what this repository is about,
|
||||
> when it is relevant, and when it is not.
|
||||
> It is intentionally lightweight and may be incomplete.
|
||||
> This file describes the repository's current, evidenced responsibility. It is
|
||||
> deliberately distinct from the direction in `INTENT.md` and from unreviewed
|
||||
> consumer demand.
|
||||
|
||||
---
|
||||
|
||||
## One-liner
|
||||
|
||||
Architecture-definition home for Railiance: repository taxonomy, framework ADRs,
|
||||
cross-repo boundary rules, and cross-repo workplans for architecture changes.
|
||||
Current source of truth for Railiance repository taxonomy, family contracts,
|
||||
framework ADRs, declaration schemas, and cross-repo architecture workplans.
|
||||
|
||||
---
|
||||
|
||||
## Core Idea
|
||||
## Current Responsibility
|
||||
|
||||
`railiance-master` is the framework-level architecture repo for Railiance.
|
||||
It exists so shared concepts such as `railiance-*`, `rail-*`, `rapp-*`, and
|
||||
`reef-*` are defined once, with explicit boundaries, before they spread across
|
||||
implementation repos.
|
||||
`railiance-master` currently owns the Railiance-specific meaning of the four
|
||||
repository axes: ownership repos (`railiance-*`), execution contracts
|
||||
(`rail-*`), managed workload packages (`rapp-*`), and substrate boundaries
|
||||
(`reef-*`).
|
||||
|
||||
It also serves as the natural workplan home for changes that span multiple
|
||||
Railiance repos and cannot be owned cleanly by only one of them.
|
||||
The current implementation includes:
|
||||
|
||||
- eight accepted framework ADRs covering repository families, rail composition,
|
||||
production admission, the rapp declaration contract, and exposure posture;
|
||||
- framework contracts and migration guidance under `docs/`;
|
||||
- JSON Schemas for rail, rapp, and reef declarations plus a family-declaration
|
||||
validator and fixtures;
|
||||
- cross-repo workplans and State Hub bindings for architecture changes that do
|
||||
not belong wholly to one implementation repository.
|
||||
|
||||
This repo owns the architectural source documents and their lifecycle. It does
|
||||
not own every implementation implied by them.
|
||||
|
||||
---
|
||||
|
||||
## In Scope
|
||||
|
||||
- Framework-level architecture documents for Railiance
|
||||
- Repository taxonomy and naming conventions
|
||||
- Architectural boundaries between ownership repos, rails, `rapp`s, and reefs
|
||||
- Architecture decision records affecting multiple Railiance repos
|
||||
- Cross-repo Railiance workplans whose implementation spans multiple sibling repos
|
||||
- Railiance framework architecture and Railiance-specific vocabulary
|
||||
- Repository taxonomy, naming, composition, lifecycle, and boundary rules
|
||||
- Architecture decisions affecting multiple Railiance repositories
|
||||
- Rail/rapp/reef declaration contracts and framework-level validation rules
|
||||
- Cross-repo workplans whose outcome cannot be owned cleanly by one concrete
|
||||
ownership or family repository
|
||||
- Source metadata and lifecycle decisions for this repo's publishable ADRs
|
||||
- Routing accepted architecture into repo-local implementation work
|
||||
|
||||
---
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- OS provisioning and host hardening work owned by `railiance-infra`
|
||||
- Kubernetes runtime implementation owned by `railiance-cluster`
|
||||
- Platform-service implementation owned by `railiance-platform`
|
||||
- Application release implementation owned by `railiance-apps`
|
||||
- Forge runtime implementation owned by `railiance-forge`
|
||||
- Fabric graph implementation owned by `railiance-fabric`
|
||||
- General semantic canon or repository standards owned by `info-tech-canon`
|
||||
- Permanent policy addressing, rendering, hosting, and currency checks owned by
|
||||
`policy-nexus`
|
||||
- Regulatory interpretation or disclosure timing owned by `risk-nexus`
|
||||
- OS provisioning and host hardening owned by `railiance-infra`
|
||||
- Kubernetes substrate implementation owned by `railiance-cluster`
|
||||
- Rail implementation owned by the relevant `rail-*` repository
|
||||
- Managed workload implementation owned by the relevant `rapp-*` repository
|
||||
- Reef-local substrate declarations and operations owned by the relevant
|
||||
`reef-*` repository
|
||||
- Platform services, application releases, forge runtime, and Fabric graph
|
||||
implementation owned by their concrete repositories
|
||||
|
||||
---
|
||||
|
||||
## Authority and Publication Boundaries
|
||||
|
||||
| Concern | Authority | Relationship to `railiance-master` |
|
||||
| --- | --- | --- |
|
||||
| General semantic models and repository-layout standard | `info-tech-canon` | Imported and applied; not redefined here |
|
||||
| Railiance framework architecture and ADR lifecycle | `railiance-master` | Authored, reviewed, accepted, superseded, or withdrawn here |
|
||||
| Permanent publication of accepted ADRs | `policy-nexus` | Downstream read-only publication; never a second source of truth |
|
||||
| Work indexing and coordination | State Hub | Cache/index rebuilt from repo-local workplan files |
|
||||
| Runtime implementation | Concrete ownership, rail, rapp, or reef repo | Routed outward after the framework boundary is settled |
|
||||
|
||||
The policy publication corpus from this repo is `docs/adr/*.md`. Workplans,
|
||||
evidence, runbooks, schemas, and general documentation are not policy merely
|
||||
because they are useful. `policy-nexus` currently discovers all eight ADRs, but
|
||||
they remain `metadata-pending` until source lifecycle metadata and explicit
|
||||
publication addressing are completed.
|
||||
|
||||
---
|
||||
|
||||
## Relevant When
|
||||
|
||||
- Defining a new Railiance repo family or framework term
|
||||
- Clarifying boundaries between existing Railiance repos
|
||||
- Planning migrations that touch multiple Railiance repos
|
||||
- Recording a framework-level architecture decision
|
||||
|
||||
---
|
||||
- Defining or changing a Railiance repository family or framework term
|
||||
- Clarifying a boundary shared by multiple implementation repositories
|
||||
- Deciding how rails, rapps, reefs, and ownership repositories compose
|
||||
- Establishing framework-wide admission, exposure, declaration, or lifecycle
|
||||
rules
|
||||
- Planning a migration that spans multiple Railiance repositories
|
||||
- Recording or reviewing a Railiance framework ADR
|
||||
|
||||
## Not Relevant When
|
||||
|
||||
- The work belongs entirely inside one implementation repo
|
||||
- The work is operational rather than architectural
|
||||
- The work is workload-specific rather than framework-wide
|
||||
- Work belongs entirely inside one implementation repository
|
||||
- Work is operational execution of an already-settled boundary
|
||||
- A workload-specific decision has no framework-wide consequence
|
||||
- The request is raw demand that has not yet been reviewed for purpose and scope
|
||||
fit
|
||||
|
||||
---
|
||||
|
||||
## Current State
|
||||
|
||||
- Status: maintained / evolving
|
||||
- Implementation: architecture baseline documents are present and the first concrete repo-family materialization wave has been completed from this repo
|
||||
- Stability: evolving
|
||||
- Usage: internal Railiance framework architecture home and handoff point for cross-repo planning
|
||||
- Status: maintained and evolving
|
||||
- Architecture baseline: four repository axes are materialized and governed by
|
||||
accepted ADRs and contracts
|
||||
- Validation: rail/rapp/reef schemas and declaration checks are implemented
|
||||
- Active cross-repo work: OpenBao migration closeout remains partially blocked;
|
||||
public-listener retraction is in progress while destructive source cleanup
|
||||
retains separate approval and disaster-recovery gates
|
||||
- Publication: ADR discovery exists in `policy-nexus`; publication metadata and
|
||||
stable addressing remain an open alignment gap
|
||||
|
||||
The repo now holds the canonical framework decisions and boundary documents for
|
||||
separating `rail-*`, `rapp-*`, and `reef-*` concerns out of the existing
|
||||
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.
|
||||
---
|
||||
|
||||
## InfoTechCanon Repository-Layout Alignment
|
||||
|
||||
Declared conformance: **`minimal`** under ITC-REPO-LAYOUT 0.1.0-RC1.
|
||||
|
||||
- `INTENT.md` contains stable aspiration and boundaries.
|
||||
- `SCOPE.md` contains current evidenced responsibility and explicit gaps.
|
||||
- `docs/` contains stakeholder-facing framework contracts and ADRs.
|
||||
- `workplans/` contains committed work and remains authoritative for State Hub.
|
||||
- `history/` contains dated, inactive architecture explorations.
|
||||
|
||||
Intentional deviations and omissions:
|
||||
|
||||
- Finished workplan archival follows the Custodian ADR-001 convention at
|
||||
`workplans/archived/YYMMDD-...`, not the generic ITC `history/` placement, so
|
||||
State Hub discovery remains deterministic.
|
||||
- `demand/`, `research/`, `spec/`, `wiki/`, and `issues/` are not currently
|
||||
claimed. They should be added only when their distinct semantics are needed,
|
||||
not as empty structural decoration.
|
||||
- Consumer purposes and inbound requests are not folded into INTENT or SCOPE;
|
||||
a future demand intake may provide that third plane explicitly.
|
||||
|
||||
---
|
||||
|
||||
## How It Fits
|
||||
|
||||
- Upstream dependencies: `the-custodian` canon and State Hub conventions
|
||||
- Downstream consumers: all `railiance-*`, future `rail-*`, future `rapp-*`, and future `reef-*` repos
|
||||
- Often used with: `railiance-fabric`, `railiance-platform`, `railiance-cluster`, `state-hub`
|
||||
|
||||
---
|
||||
|
||||
## Terminology
|
||||
|
||||
- Preferred terms: architecture home, repository axis, rail, `rapp`, reef, ownership repo
|
||||
- Also known as: framework architecture repo
|
||||
- Potentially confusing terms: this repo defines framework structure; it does not implement the lower-layer systems it describes
|
||||
|
||||
---
|
||||
|
||||
## Related / Overlapping Repositories
|
||||
|
||||
- `railiance-fabric` — models the ecosystem graph; `railiance-master` defines framework taxonomy and boundaries
|
||||
- `state-hub` — indexes and coordinates work; `railiance-master` provides the framework architecture to be coordinated
|
||||
- `repo-scoping` — explains what repos are useful for; `railiance-master` defines how Railiance repo families fit together
|
||||
- Upstream standards: `info-tech-canon`, `the-custodian` canon, Custodian
|
||||
workplan conventions
|
||||
- Downstream policy publisher: `policy-nexus` (ADRs only, read-only)
|
||||
- Downstream architecture consumers: all `railiance-*`, `rail-*`, `rapp-*`, and
|
||||
`reef-*` repositories
|
||||
- Coordination/index: State Hub
|
||||
- Common collaborators: `railiance-fabric`, `railiance-platform`,
|
||||
`railiance-cluster`, `railiance-infra`, `railiance-enablement`
|
||||
|
||||
---
|
||||
|
||||
## Getting Oriented
|
||||
|
||||
- Start with: `README.md`, `INTENT.md`
|
||||
- Key files / directories: `docs/`, `history/`, `workplans/`
|
||||
- Entry points: `docs/repository-axes.md`, `docs/reef-substrate-model.md`, `docs/adr/`
|
||||
- Start with: `README.md`, `INTENT.md`, `SCOPE.md`
|
||||
- Architecture entry points: `docs/repository-axes.md`,
|
||||
`docs/reef-substrate-model.md`, `docs/adr/`
|
||||
- Machine-readable contracts: `schemas/`,
|
||||
`tools/validate-family-declarations.py`
|
||||
- Active and historical coordination: `workplans/`, `WORK-RECORDS.md`
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -122,13 +176,21 @@ keywords: [railiance, architecture, taxonomy, rail, rapp, reef]
|
|||
```capability
|
||||
type: governance
|
||||
title: Railiance framework architecture decisions
|
||||
description: Records framework-level architecture decisions and boundary guidance for changes spanning multiple Railiance repos.
|
||||
keywords: [architecture, adr, governance, boundaries, framework]
|
||||
description: Owns framework ADR content and lifecycle while permanent publication is delegated read-only to policy-nexus.
|
||||
keywords: [architecture, adr, governance, boundaries, policy-source]
|
||||
```
|
||||
|
||||
```capability
|
||||
type: validation
|
||||
title: Railiance family declaration contracts
|
||||
description: Provides schemas and validation rules for rail, rapp, and reef declarations and their cross-family constraints.
|
||||
keywords: [schema, validation, declaration, rail, rapp, reef]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
## Gap to Intent
|
||||
|
||||
Use this repo for architecture that must stay shared. Push concrete
|
||||
implementation outward into the ownership repos once the framework boundary is clear.
|
||||
The next obvious alignment work is to make accepted ADRs publication-ready,
|
||||
formalize how raw architecture demand is reviewed before it becomes a workplan,
|
||||
and cleanly archive completed work without breaking State Hub conventions.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue