railiance-master/SCOPE.md

# 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-*`). **Workload**, in that Railiance-specific sense, is a managed
running deployable under rapp coverage (`ADR-0007`); human acts, credentials,
broker actions, and non-deployable infrastructure resources remain outside
that meaning.

This repository now **declares** itself Taxonomy of Railiance workload
operations in `INTENT.md` frontmatter (`layer: Taxonomy`, NetKingdom
security-layer-model v0.7). It is not a row in the NetKingdom §4 catalog.
The machine-readable `layer.yaml` form, a total non-Tooling-client account,
and a framework consumption contract for §20.2 are not yet evidenced here.

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
- Declaring this repository's NetKingdom security layer and the operations
  side of the Railiance/NetKingdom interaction boundary
- Framework-level consumption rules for how rails, rapps, and reefs use
  `access-engine`, `approval-engine`, `secrets-engine`, and `audit-core`
  without hosting those engines here

---

## 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
- glas-harness `rein-*` harness contracts and agentic session semantics; a
  deployed rein is a workload on the four axes, not a fifth Railiance family
- The NetKingdom security-layer constitution owned by `gate-house` and
  published as net-kingdom canon
- Authorization decisions (`access-engine`), approval objects
  (`approval-engine`), credential materialization (`secrets-engine`), and
  evidence custody (`audit-core`)
- PEP stance maps and unreachable-engine behaviour of implementation
  repositories; this repo is not PEP-shaped
- A guessed mapping of rail, rapp, reef, or ownership onto Taxonomy,
  Tooling, Engine, or Staff — statute §20.3 is unsettled
- Automatic containment or production observation; both are estate-wide
  zeros, not this repository's gaps to close

---

## 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 |
| Security-layer constitution (layers, one PDP, Staff/Engine binding, evidence bounds) | `gate-house` / net-kingdom canon, `security-layer-model` v0.7 | Imported as the consumption constitution; not redefined here |
| Workload-operation axes and coverage | `railiance-master` | Owned here; restated, not authored, by NetKingdom §20 |
| 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; a non-catalogued client, not a Tooling contact |
| Runtime implementation | Concrete ownership, rail, rapp, or reef repo | Routed outward after the framework boundary is settled |
| Agentic session and tool-policy seam | `glas-harness` | Adjacent; joint assent required for §20 changes that touch the seam |

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
- Declaring or changing this repository's security layer, or the operations
  side of the NetKingdom interaction boundary

## 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 about glas-harness session, tool, or rein-backend semantics
  rather than how a deployed rein is packaged, executed, or bound as a workload
- The request is to render an authorization decision, store an approval, mint
  a credential, or keep an evidence archive
- The request assumes observation-in-production or automatic containment
  exists
- 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
- Layer declaration: `INTENT.md` frontmatter declares `layer: Taxonomy`
  against security-layer-model v0.7; `layer.yaml` and a conformance check are
  not yet present
- Security consumption: ADR-0001 through ADR-0008 do not yet encode the
  §20.2 rules (one PDP, approvals as claims, credentials after a decision,
  evidence bound, PEP-shape of implementation runtimes)
- Admission (ADR-0006) and exposure (ADR-0008) are live Railiance axes and
  are not yet demarcated in-repo from authorization decisions
- 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: **`core`** under ITC-REPO-LAYOUT 0.1.0-RC1.

- `INTENT.md` contains stable aspiration and boundaries.
- `SCOPE.md` contains current evidenced responsibility and explicit gaps.
- `demand/` holds unreviewed architecture demand and requires a purpose/scope
  disposition before work is committed.
- `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.
- `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;
  `demand/` provides that third plane and resolved reviews move to dated
  `history/` records.

---

## How It Fits

- Upstream standards: `info-tech-canon`, `the-custodian` canon, Custodian
  workplan conventions, NetKingdom `security-layer-model` v0.7 and
  `SECURITY-COMPANION.md` v0.2 (consumption constitution, not authored here)
- 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/`
- NetKingdom alignment review:
  `history/260829-demand-netkingdom-security-layer-alignment.md`
- 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 remaining alignment work is to complete downstream ADR publication, cleanly
archive completed work without breaking State Hub conventions, retain a
repeatable canon-consumer review packet as the architecture evolves, and close
the NetKingdom security-layer gap recorded in
`history/260829-demand-netkingdom-security-layer-alignment.md` and tracked by
`RMASTER-WP-0026`: a machine-readable layer declaration, a §20.2 consumption
contract, a vocabulary split between admission/exposure and authorization, and
assented answers to the five unsettled axis-to-layer questions. Do not invent
the mapping, host a PDP, or take PEP shape in this repository.