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 **declares** itself Taxonomy of Railiance workload
operations in `INTENT.md` frontmatter and `layer.yaml` (`layer: Taxonomy`,
NetKingdom security-layer-model v0.7). It is not a row in the NetKingdom
§4 catalog. It is not PEP-shaped. Assent to statute §20 is
`docs/adr/ADR-0009-netkingdom-security-layer-interaction.md`.

The current implementation includes:

- nine accepted framework ADRs covering repository families, rail composition,
  production admission, the rapp declaration contract, exposure posture, and
  the NetKingdom security-layer interaction boundary;
- 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 tracked unanswered in
  `docs/netkingdom-axis-layer-open-questions.md`
- 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 the earlier eight
ADRs as `metadata-pending`; ADR-0009 is an additional source record awaiting
the same publication addressing.

---

## 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 and `layer.yaml` declare
  `layer: Taxonomy` against security-layer-model v0.7; no Tooling contacts;
  State Hub listed as a non-Tooling client; not PEP-shaped
- Security consumption: ADR-0009 and
  `docs/netkingdom-security-consumption-contract.md` encode the §20.2 rules
  (one PDP, approvals as claims, credentials after a decision, evidence
  bound, PEP-shape of implementation runtimes)
- Admission (ADR-0006), exposure (ADR-0008), and authorization
  (`access-engine` via ADR-0009) are demarcated in-repo
- Axis-to-layer mapping: five statute §20.3 questions are tracked unanswered
  in `docs/netkingdom-axis-layer-open-questions.md`; next review 2026-11-29
- 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, now including ADR-0009

---

## 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 interaction: `layer.yaml`,
  `docs/netkingdom-security-consumption-contract.md`,
  `docs/netkingdom-axis-layer-open-questions.md`,
  `docs/adr/ADR-0009-netkingdom-security-layer-interaction.md`
- NetKingdom alignment review:
  `history/260829-demand-netkingdom-security-layer-alignment.md`
- Machine-readable contracts: `schemas/`, `layer.yaml`,
  `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
(including ADR-0009), cleanly archive completed work without breaking State
Hub conventions, and retain a repeatable canon-consumer review packet as the
architecture evolves. The NetKingdom security-layer declaration, §20 assent,
consumption contract, and admission/exposure/authorization split are now
evidenced. The five axis-to-layer questions remain tracked unanswered until
their named reviewers assent; they are not a silent deficit of this
repository. Do not invent the mapping, host a PDP, or take PEP shape here.