coulomb/railiance-enablement
5
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
railiance-enablement/SCOPE.md
tegwick e3c200e1a1
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 1s
Details
Adopt staged WORK-RECORDS generation and catch the index up. 
The generated index had drifted from the workplan files. The opt-in lets
the pre-commit hook rebuild WORK-RECORDS.md in the same commit as the
workplan it indexes.

Assistant: grok
Assistant-Session: 01a17f9d-fe9d-7d72-9a22-6304f1a2a790
2026-10-28 00:31:14 +01:00

6.8 KiB
Raw Blame History

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.

One-liner

S4 Developer Enablement layer of the Railiance OAS Stack — owns reusable CI/CD templates, developer portal paths, platform templates, SDKs, and buildpacks; uses forge capabilities without owning forge runtime or runner substrate.

Core Idea

Railiance is structured as independent repos per OAS Stack layer. This repo is S4: the reusable tools and paved paths that allow the system to evolve. S4 depends on the platform (S3) being operational before tooling can use platform services. S5 applications consume S4 templates and conventions, while railiance-forge provides source hosting, registries, and runner substrate.

In Scope

  • Reusable CI/CD workflow templates and automation patterns
  • Developer portal (self-service deployment interface)
  • Platform deployment templates for workloads
  • SDKs and libraries for platform consumers
  • Buildpacks and image builders
  • Handoff contracts to railiance-forge for runner labels, artifact evidence, and registry consumption
  • Template references to forge-provided runner labels and credentials documented in /home/worsch/railiance-forge/docs/ci-runner-actions-gitops-ownership.md

Out of Scope

  • OS-level concerns → railiance-infra (S1)
  • Kubernetes runtime → railiance-cluster (S2)
  • Platform services → railiance-platform (S3)
  • Source forge runtime, container/package registries, runner deployment, runner labels, and runner credentials → railiance-forge
  • Application deployments → railiance-apps (S5)
  • App-specific workflows, release charts, and source code → app/source repos
  • No re-configuration of lower layers from this repo

Relevant When

  • Setting up CI/CD for the Railiance stack
  • Creating or modifying developer tools and deployment templates
  • Defining reusable workflow templates that run on forge-provided runners
  • Defining promotion conventions and evidence formats consumed by S5
  • S3 is operational and tooling layer can now be built

Not Relevant When

  • S3 (platform services) is not yet operational (pre-condition not met)
  • Infrastructure, cluster, or platform work needed (wrong layer)
  • The work is Gitea/Forgejo runtime, registry endpoint, package retention, runner deployment, or runner secret access (use railiance-forge)
  • The work is a concrete app release or app-specific runbook (use railiance-apps or the source app repo)

Current State

  • Status: emerging, with reusable Forgejo workflow templates and the railiance01 ArgoCD declared state (RAIL-EN-WP-0002 active).
  • S4 owns the consumer-facing contract for runner labels, registries, credentials, and artifact evidence. railiance-forge continues to operate those capabilities; they are not duplicated here.
  • Implementation: Argo CD Core v3.5.3 (headless) is installed on railiance01 in namespace argocd since 2026-09-21. ArchitectureBlueprint §5.6 (railiance-platform) is settled as adopt properly. Its declared state is deploy/argocd/railiance01/ (RAIL-EN-WP-0002). It has 0 Applications and 0 AppProjects, so no workload is under GitOps yet; the live workloads still deploy by Makefile. Adoption (phase B) and retiring CoulombCore's ArgoCD (phase C) each need a founder go-ahead
  • Stability: the pinned install matches live (read-only server-side diff, 2026-09-21); resource requests/limits are declared but not yet applied, so the pods are BestEffort until RAIL-EN-WP-0002-T02
  • Usage: formal S4 tooling work begins after S3 baseline and should consume runner/registry capabilities from railiance-forge until that migration completes
  • Honest gap: this layer's INTENT.md promises considerably more than the repo contains. Read that as open debt, not description

How It Fits

  • Upstream dependencies: railiance-platform (S3) must be operational
  • Adjacent forge provider: railiance-forge owns source hosting, registries, and runner substrate used by S4 workflows
  • Downstream consumers: railiance-apps (S5) uses CI/CD and templates from this layer
  • Often used with: railiance-platform (S3), railiance-forge, railiance-apps (S5)

Terminology

  • Preferred terms: OAS Stack Level S4, developer enablement, paved path, workflow template, promotion convention, boundary rule
  • Distinguish "workflow template" from "runner substrate": templates live here; runner deployment, labels, credentials, and health live in railiance-forge.

Related / Overlapping

  • railiance-platform (S3) — pre-condition; provides services that S4 tooling depends on
  • railiance-forge — provides source forge runtime, artifact registries, and runner substrate consumed by S4 workflows; its runner label and GitOps boundary contract is /home/worsch/railiance-forge/docs/ci-runner-actions-gitops-ownership.md
  • railiance-apps (S5) — consumer of S4 CI/CD and templates

Provided Capabilities

type: infrastructure
title: CI/CD pipeline automation
description: Automated build, test, and deployment pipelines for Railiance workloads — planned for when railiance-platform (S3) is operational.
keywords: [ci, cd, pipeline, automation, template, build, deploy, gitops]

type: documentation
title: Platform deployment templates and SDKs
description: Standardised deployment templates, Helm chart patterns, SDKs, and promotion conventions enabling consistent application deployments across the Railiance stack while consuming forge-owned runners and registries.
keywords: [template, sdk, helm, deployment, developer, buildpack]

Getting Oriented

  • Start with: CLAUDE.md (session protocol, OAS boundary rules)
  • Key files / directories: workflows/, docs/, workplans/, Makefile
  • Pre-conditions: railiance-platform (S3) must be operational

Generated work-record index

This repository opts into staged-source WORK-RECORDS.md generation through .generated-work-records.json and the isolated .generated-work-records.mk recipe. make generated-work-records reuses the State Hub renderer through the Custodian adapter; make generated-work-records-check verifies byte-exact agreement with staged Markdown. The pre-commit hook uses the isolated recipe, preserves unstaged index edits by refusing them, and retains the generated-only commit guard. It does not contact the hub, alter workplan statuses, or grant deployment authority. This consumes shared tooling; it does not make this repository the provider of the generator capability.

Local orientation brief policy — 2026-10-21

.custodian-brief.md is a local, ignored State Hub orientation snapshot. Refreshing it does not require a Git commit. Authored workplans and the generated WORK-RECORDS index keep their existing source and staged-generation contracts.