196 lines
7.7 KiB
Markdown
196 lines
7.7 KiB
Markdown
# SCOPE
|
|
|
|
> 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
|
|
|
|
Current source of truth for Railiance repository taxonomy, family contracts,
|
|
framework ADRs, declaration schemas, and cross-repo architecture workplans.
|
|
|
|
---
|
|
|
|
## Current Responsibility
|
|
|
|
`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-*`).
|
|
|
|
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
|
|
|
|
- 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
|
|
|
|
- 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 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
|
|
|
|
- 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 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
|
|
|
|
---
|
|
|
|
## 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 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`, `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`
|
|
|
|
---
|
|
|
|
## Provided Capabilities
|
|
|
|
```capability
|
|
type: documentation
|
|
title: Railiance repository taxonomy
|
|
description: Defines the canonical Railiance repo families and how ownership repos, rails, managed workloads, and substrate boundaries compose.
|
|
keywords: [railiance, architecture, taxonomy, rail, rapp, reef]
|
|
```
|
|
|
|
```capability
|
|
type: governance
|
|
title: Railiance framework architecture decisions
|
|
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]
|
|
```
|
|
|
|
---
|
|
|
|
## Gap to Intent
|
|
|
|
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.
|