coulomb/railiance-master
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
railiance-master/SCOPE.md

7.7 KiB
Raw Blame History

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

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]

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]

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.