diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0e23cb2 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,174 @@ +# railiance-forge - Agent Instructions + +## Repo Identity + +**Purpose:** Railiance forge and artifact infrastructure - source forge runtime, +container/package registries, forge-backed runner substrate, artifact lifecycle, +and future Forgejo migration. + +**Domain:** railiance +**Repo slug:** railiance-forge +**Topic ID:** `ca369340-a64e-442e-98f1-a4fa7dc74a38` +**Workplan prefix:** `FORGE-WP-` + +--- + +## State Hub Integration + +The Custodian State Hub tracks work across all domains. Interact via HTTP REST - +there is no MCP server for Codex agents. + +| Context | URL | +|---------|-----| +| Local workstation | `http://127.0.0.1:8000` | +| Remote via tunnel | `http://127.0.0.1:18000` | + +### Orient at session start + +```bash +cat .custodian-brief.md + +curl -s "http://127.0.0.1:8000/workstreams/?topic_id=ca369340-a64e-442e-98f1-a4fa7dc74a38&status=active" \ + | python3 -m json.tool + +curl -s "http://127.0.0.1:8000/messages/?to_agent=railiance-forge&unread_only=true" \ + | python3 -m json.tool +``` + +Mark a message read: + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ + -H "Content-Type: application/json" -d '{}' +``` + +### Log progress at session close + +```bash +curl -s -X POST http://127.0.0.1:8000/progress/ \ + -H "Content-Type: application/json" \ + -d '{ + "summary": "what was done", + "event_type": "note", + "author": "codex", + "workstream_id": "", + "task_id": "" + }' +``` + +Omit `workstream_id` / `task_id` when not applicable. + +### Update task status + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"status": "progress"}' +``` + +Canonical task values: `wait | todo | progress | done | cancel`. + +### Flag a task for human review + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"needs_human": true, "intervention_note": "reason"}' +``` + +--- + +## Session Protocol + +**Start:** + +1. `cat .custodian-brief.md` - domain goal and open workstreams. +2. Check inbox: + `GET /messages/?to_agent=railiance-forge&unread_only=true`; mark read. +3. Scan workplans: `ls workplans/` and note `ready`, `active`, or `blocked` + workplans and open tasks. +4. Check blocked tasks: `GET /tasks/?needs_human=true`. + +**During work:** + +- Update task statuses in workplan files as tasks progress. +- Record significant decisions via `POST /decisions/`. +- Keep forge responsibilities separate from S4 templates and S5 app releases. + +**Close:** + +1. Update workplan file task statuses. +2. Log progress with `POST /progress/`. +3. After workplan file changes, run from `~/state-hub`: + + ```bash + make fix-consistency REPO=railiance-forge + ``` + +--- + +## Workplan Convention + +Work items originate as files in this repo. State Hub indexes those files as +workstreams and task blocks. + +**File location:** `workplans/FORGE-WP-NNNN-.md` + +**Archived location:** `workplans/archived/YYMMDD-FORGE-WP-NNNN-.md` + +**Frontmatter:** + +```yaml +--- +id: FORGE-WP-NNNN +type: workplan +title: "..." +domain: railiance +repo: railiance-forge +status: proposed | ready | active | blocked | backlog | finished | archived +owner: codex +topic_slug: railiance +created: "YYYY-MM-DD" +updated: "YYYY-MM-DD" +state_hub_workstream_id: "" # written by fix-consistency - do not edit +--- +``` + +**Task block format:** + +````text +## Task Title + +```task +id: FORGE-WP-NNNN-T01 +status: todo | progress | done | wait | cancel +priority: high | medium | low +state_hub_task_id: "" # written by fix-consistency - do not edit +``` + +Task description text. +```` + +Status progression: `todo` -> `progress` -> `done`, or `wait` / `cancel`. + +To create a new workplan: + +1. Write the file following the format above. +2. Run from `~/state-hub`: + + ```bash + make fix-consistency REPO=railiance-forge + ``` + +--- + +## Repository Boundaries + +This repo owns forge runtime and artifact infrastructure. It does not own: + +- OS/host provisioning (`railiance-infra`); +- Kubernetes runtime primitives (`railiance-cluster`); +- shared database/storage/secret platforms (`railiance-platform`); +- generic CI/CD templates and developer portal paths (`railiance-enablement`); +- user-facing application releases (`railiance-apps`); +- source application code. diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..4e0a8df --- /dev/null +++ b/INTENT.md @@ -0,0 +1,132 @@ +# INTENT + +> This file captures **why this repository exists**, +> the **direction it is moving toward**, and +> the **kind of system it is meant to become**. +> It is intentionally **aspirational and stable**, not a description of current implementation. + +--- + +## One-liner + +**The forge layer - turning source hosting, registries, and automation runners into dependable Railiance release infrastructure.** + +--- + +## Why This Exists + +Applications need more than a runtime to ship safely. They need a governed +place for source hosting, package and image publication, CI runner substrate, +release artifact retention, and operational evidence. + +Before this repo, forge concerns were spread across S4 enablement and S5 +application deployment work. That made it hard to tell who owned Gitea, +Forgejo, package registries, Actions runners, registry storage, and artifact +promotion evidence. + +This layer exists to make those responsibilities explicit and operable. + +--- + +## The Mission + +> *Where we are going.* + +To become the **canonical home for Railiance forge and artifact infrastructure** +- current Gitea operation, future Forgejo migration, container and package +registries, forge-backed automation runner substrate, artifact lifecycle, and +forge operational evidence. + +This means: + +* Source forge runtime is operated through a clear repo-owned contract +* Package and image registries have retention, restore, and capacity posture +* CI runners are owned separately from reusable CI/CD templates +* S5 applications can consume artifacts without owning forge internals +* Future Forgejo cutover can happen without confusing it with app deployment + +--- + +## Core Principles + +### 1. Forge Runtime, Not Application Releases + +Own the forge and artifact infrastructure. Do not own user-facing application +release charts or application source code. + +### 2. Artifacts With Evidence + +Images, packages, and release assets should carry enough provenance and +inspection evidence for downstream releases to trust them. + +### 3. Runner Substrate, Not Every Workflow + +Own the runner infrastructure and credentials. Reusable workflow templates +belong in S4 enablement, and app-specific workflows belong near the app or its +release repo. + +### 4. Stable Handoffs + +Consumers should depend on stable forge capabilities: source hosting, Git SSH, +container registry, package registry, workflow execution, and artifact +promotion evidence. + +### 5. Restore Before Trust + +Forge data is operationally critical. Source repos, packages, registry blobs, +and runner state need explicit backup and restore posture. + +### 6. Current Gitea, Future Forgejo + +Gitea is the current workload; Forgejo is the intended production direction. +The repo should support both the current operating state and clean future +cutover planning. + +--- + +## What This Is (Conceptually) + +This layer is: + +* a **source forge operations** layer +* an **artifact registry** layer +* an **automation runner substrate** layer +* a **release evidence** provider +* a bridge between S4 delivery paths and S5 application releases + +--- + +## What This Is Not + +This layer is not: + +* the infrastructure substrate beneath Railiance +* the Kubernetes runtime +* the shared platform-services layer +* the generic CI/CD template and developer portal layer +* the application release and runbook layer +* the source-code home for business applications +* a runtime secret custody authority + +It is the forge and artifact infrastructure that lets the rest of Railiance +build, publish, automate, and consume releases. + +--- + +## Direction of Evolution + +This layer is expected to evolve toward: + +* Clean extraction of current Gitea operation from `railiance-apps` +* Explicit Forgejo migration and production cutover planning +* Versioned artifact lifecycle and retention policy +* Runner placement, label, credential, and secret-access policy +* Backup and restore evidence for source, package, and registry data +* Fabric declarations for forge capabilities and dependencies +* Self-evidencing forge health and readiness checks + +--- + +## Guiding Question + +> **How can Railiance make source hosting, artifact publication, and automation execution dependable enough that application releases can consume them without owning them?** diff --git a/README.md b/README.md index fcd7b8f..554038a 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,17 @@ -# repo-seed +# railiance-forge -A git repository template to bootstrap coulomb projects from. \ No newline at end of file +Railiance forge and artifact infrastructure. + +This repository is being founded to separate source forge, registry, and +automation runner responsibilities from `railiance-apps` and +`railiance-enablement`. + +Start with: + +1. `INTENT.md` +2. `SCOPE.md` +3. `AGENTS.md` +4. `workplans/` + +Current implementation status: founding. No live Gitea files have been migrated +from `railiance-apps` yet. diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..9ca067c --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,196 @@ +# SCOPE + +This file defines what `railiance-forge` owns, when to use it, and where its +boundaries stop. + +Last reviewed: 2026-06-05 + +--- + +## One-liner + +Forge and artifact infrastructure for Railiance: current Gitea operation, +future Forgejo migration, container and package registries, Actions runner +substrate, artifact lifecycle, and forge operational evidence. + +--- + +## Core Idea + +`railiance-forge` separates forge responsibilities from S4 developer +enablement and S5 application releases. + +The practical contract is: + +1. lower layers provide servers, Kubernetes runtime, databases, storage, and + secret custody; +2. this repo owns the source forge runtime and artifact publication surface; +3. `railiance-enablement` owns reusable CI/CD templates and developer paved + paths; +4. `railiance-apps` consumes forge artifacts and deploys user-facing workloads. + +No live Gitea files have been migrated here yet. This repo is being founded as +the future home for that operational surface. + +--- + +## In Scope + +- Current Gitea operation and future Forgejo migration/cutover planning. +- Source forge deployment configuration and runbooks. +- Container registry and package registry enablement. +- Registry storage posture, cleanup, retention, and restore readiness. +- Forge-backed Actions runner substrate: + - runner deployment ownership; + - runner labels and placement; + - runner credential and secret-access boundaries. +- Artifact publication evidence used by downstream release workflows: + - image tags; + - package versions; + - commit SHA provenance; + - promotion and smoke evidence. +- Forge observability and operator checks: + - web endpoint health; + - Git SSH health; + - registry/package endpoint health; + - runner health; + - storage growth inspection. +- Fabric declarations for forge capabilities, interfaces, and dependencies. +- Repo-local workplan files under `workplans/`. + +--- + +## Out of Scope + +- OS provisioning and host hardening: `railiance-infra`. +- Kubernetes runtime primitives, ingress controllers, and cluster addon + installation: `railiance-cluster`. +- Shared databases, object storage, caches, and runtime secret custody: + `railiance-platform`. +- Generic CI/CD templates, SDKs, buildpacks, and developer portal surfaces: + `railiance-enablement`. +- User-facing application release charts, app runbooks, migrations, and smoke + tests: `railiance-apps`. +- Application source code, package metadata, and image build definitions in + source repos. +- Secret value custody. This repo may reference secret names and approved + delivery paths, but it must not commit decrypted secret material. + +--- + +## Relevant When + +- Operating or upgrading Gitea as the current Railiance forge. +- Planning or executing a Forgejo migration or cutover. +- Enabling or debugging container/package registry behavior. +- Defining artifact retention, cleanup, provenance, or restore posture. +- Deploying or operating forge-backed Actions runners. +- Deciding whether a workflow issue is runner substrate, reusable template, or + app-specific release logic. +- Declaring forge capabilities in Railiance Fabric. + +--- + +## Not Relevant When + +- The work is an application release chart or app-specific runbook. +- The work is a generic workload template or SDK. +- The work is platform database provisioning or object-storage operation. +- The work is Kubernetes runtime installation or ingress controller ownership. +- The work is application source-code behavior. +- The work requires live secret values outside approved custody paths. + +--- + +## Current State + +- Status: founding. +- Implementation: repository contract and first workplan are being created. +- Stability: emerging. +- Usage: intended as the new home for forge responsibilities currently + visible in `railiance-apps`. + +Known starting point: + +- `railiance-apps` currently owns Gitea Helm values, registry overlays, ingress, + Gitea Makefile targets, and registry docs. +- `railiance-enablement` owns the intent for delivery templates and developer + paved paths, but not forge runtime operation. +- `railiance-forge` should absorb forge runtime and artifact infrastructure + without moving S5 app release ownership. + +--- + +## How It Fits + +- Upstream dependencies: + `railiance-infra`, `railiance-cluster`, and `railiance-platform`. +- Adjacent collaborators: + `railiance-enablement` for reusable CI/CD paths and `railiance-apps` for + consuming release artifacts in app deployments. +- Downstream consumers: + source repos, app release repos, operators, and Railiance users relying on + source hosting and published artifacts. + +--- + +## Terminology + +- Preferred terms: + forge, source forge, artifact registry, package registry, runner substrate, + release evidence. +- Also known as: + Gitea/Forgejo operations, release infrastructure. +- Potentially confusing terms: + "workflow template" belongs in S4 enablement; "runner substrate" belongs + here; "app release workflow" belongs near the app or S5 release surface. + +--- + +## Related / Overlapping Repositories + +- `railiance-apps` - currently hosts Gitea deployment files and registry docs; + should become a consumer after extraction. +- `railiance-enablement` - owns reusable CI/CD templates, SDKs, buildpacks, and + developer portal paths. +- `railiance-platform` - provides database, storage, backup, and runtime secret + services consumed by forge workloads. +- `railiance-cluster` - provides Kubernetes runtime and cluster-level addons. +- `railiance-fabric` - should model forge capabilities, interfaces, providers, + and consumers. + +--- + +## Getting Oriented + +1. Read `AGENTS.md` for session protocol and State Hub conventions. +2. Read `INTENT.md` for stable purpose. +3. Read this file for scope and boundaries. +4. Read active files in `workplans/`. +5. For migration context, read + `/home/worsch/railiance-apps/workplans/RAILIANCE-WP-0006-railiance-forge-extraction.md`. + +--- + +## Provided Capabilities + +```capability +type: infrastructure +title: Railiance source forge operation +description: Operate the current Gitea source forge and plan future Forgejo migration/cutover as dedicated Railiance forge infrastructure. +keywords: [railiance, forge, gitea, forgejo, source-hosting, git] +``` + +```capability +type: infrastructure +title: Railiance artifact registry operation +description: Own container and package registry enablement, retention, restore posture, and release artifact evidence for Railiance consumers. +keywords: [registry, container-image, python-package, artifact, retention, provenance] +``` + +```capability +type: operations +title: Forge automation runner substrate +description: Define and operate forge-backed runner infrastructure, runner labels, runner placement, and credential boundaries used by CI/CD workflows. +keywords: [actions, runner, ci, gitops, automation, credentials] +``` diff --git a/docs/current-forge-asset-inventory.md b/docs/current-forge-asset-inventory.md new file mode 100644 index 0000000..edc566f --- /dev/null +++ b/docs/current-forge-asset-inventory.md @@ -0,0 +1,102 @@ +# Current Forge Asset Inventory + +Date: 2026-06-05 + +This inventory covers forge-related assets currently visible in +`/home/worsch/railiance-apps`. It supports `FORGE-WP-0001-T03` and the +coordinating `RAILIANCE-WP-0006` extraction plan. + +No files have been moved yet. This document assigns each candidate asset a +target disposition for the first migration plan. + +## Summary + +| Disposition | Meaning | +|-------------|---------| +| Move | Canonical file should move to `railiance-forge`. | +| Copy pointer | Copy canonical content to `railiance-forge`, leave a short pointer in `railiance-apps` temporarily. | +| Leave | Keep in `railiance-apps`; it is S5 app-release surface. | +| Adapt | Keep local behavior, but update references after forge extraction. | +| Supersede | Historical or transitional content should be replaced by new forge-owned docs/workplans. | + +## Move To `railiance-forge` + +| Asset | Current role | Target disposition | Notes | +|-------|--------------|--------------------|-------| +| `helm/gitea-values.sops.yaml` | SOPS-encrypted Gitea Helm values. | Move | Must preserve secret boundary; move without decrypting. | +| `helm/gitea-registry-values.yaml` | Non-secret overlay enabling Gitea package/container registry behavior. | Move | This is forge runtime config, not S5 app config. | +| `manifests/gitea-ingress.yaml` | Registry-facing Gitea ingress for `/v2`. | Move | Forge owns Gitea/registry exposure; cluster ingress primitives remain S2. | +| `releases/gitea/values.yaml` | Legacy/plain Gitea release values reference. | Move or supersede | Likely keep only as historical migration reference if still useful. | +| `Makefile` variables `GITEA_*` | Gitea release/chart/value/ingress defaults. | Move | Recreate in `railiance-forge/Makefile`; remove from S5 after compatibility window. | +| `make gitea-deploy` | Deploy/upgrade current Gitea release. | Move | Should become `railiance-forge` operator target. | +| `make gitea-ingress-deploy` | Apply Gitea registry ingress. | Move | Should become `railiance-forge` operator target. | +| `make gitea-status` | Check Gitea pod/service/ingress and `gitea-db` status. | Move | Keep database status as consumer evidence; S3 still owns DB implementation. | + +## Copy With Compatibility Pointer + +| Asset | Current role | Target disposition | Notes | +|-------|--------------|--------------------|-------| +| `docs/gitea-container-registry.md` | Canonical operator recipe for container registry host, auth, pull secrets, storage note. | Copy pointer | Copy to `railiance-forge/docs/`; leave S5 pointer for app consumers. | +| `docs/gitea-package-registry.md` | Python package registry publishing/install recipe and `issue-core` handoff. | Copy pointer | Forge owns endpoint/registry posture; app/source repos own package release details. | +| `workplans/RAIL-AP-WP-0001-gitea-container-registry.md` | Historical implementation evidence for enabling Gitea registry in S5. | Copy pointer or archive | Keep historical record in S5, but create forge follow-up for storage/retention/restore posture. | +| `workplans/RAILIANCE-WP-0006-railiance-forge-extraction.md` | Cross-repo coordination plan. | Leave plus pointer | Remains in `railiance-apps` as extraction coordinator; forge work proceeds in `FORGE-WP-*`. | + +## Leave In `railiance-apps` + +| Asset | Current role | Target disposition | Notes | +|-------|--------------|--------------------|-------| +| `.gitea/workflows/manifest-server-dry-run.yaml` | S5 manifest dry-run workflow for app charts/manifests. | Leave | Runner substrate belongs in forge; this app-release check remains S5. | +| `make k8s-server-dry-run` | Server-side dry-run for S5 charts/manifests. | Leave | Document runner/cluster prerequisites in forge, but keep app release check here. | +| `tools/k8s-server-dry-run.sh` | Implements S5 dry-run. | Leave | Consumes runner/cluster access; does not operate forge runtime. | +| `charts/vergabe-teilnahme/**` | S5 app chart. | Leave | Application release ownership. | +| `helm/vergabe-teilnahme-values.yaml` | S5 app values, including registry image reference. | Leave | Consumes forge registry; does not own registry. | +| `manifests/vergabe-teilnahme-ingress.yaml` | S5 app ingress. | Leave | Application endpoint ownership. | +| `docs/vergabe-teilnahme.md` | S5 app runbook. | Leave | Update links to point at forge-owned registry docs after migration. | +| `docs/django-on-railiance.md` | Framework-specific S5 app recipe. | Leave | Should reference forge registry capabilities as upstream infrastructure. | +| `docs/operator-recipes.md` | S5 operator recipes. | Leave | Keep only app-release recipes here. | +| `docs/operator-setup.md` | S5 operator setup. | Leave | May need forge cross-link for registry credentials and runner expectations. | +| `tools/build-database-url-secret.sh` | App DB secret helper. | Leave | S5 app data/secret consumer behavior. | +| `tools/smoke-service.sh` | App smoke helper. | Leave | S5 verification. | +| `make apps-pg-status` | Checks shared app database cluster. | Leave or move to platform later | Not forge; keep while S5 needs consumer readiness evidence. | +| `make vergabe-*` targets | App release operations. | Leave | S5 app surface. | + +## Adapt In Place + +| Asset | Current role | Target disposition | Notes | +|-------|--------------|--------------------|-------| +| `SCOPE.md` | Currently lists Gitea as S5-owned workload. | Adapt | After migration, describe forge as upstream release infrastructure. | +| `INTENT.md` | Mentions Gitea/current forge as S5 workload/learning surface. | Adapt | Keep S5 intent but remove long-term forge ownership language. | +| `AGENTS.md` | Repo identity still says application Helm releases, Gitea, coulomb services. | Adapt | Update after Gitea files move. Also update task status examples to State Hub canon. | +| `Makefile` `SOPS_SENTINEL ?= $(GITEA_VALUES)` | `check-sops` currently validates Gitea SOPS values. | Adapt | Once Gitea values move, choose an S5 sentinel or make the check no-op when no SOPS file exists. | +| `tools/check-sops.sh` | Generic SOPS sentinel check. | Leave/adapt | Useful beyond forge, but current default must change after move. | +| `.custodian-brief.md` | Generated State Hub brief. | Generated | Do not edit manually; consistency sync updates it. | + +## Supersede Or Re-home Planning Content + +| Asset | Current role | Target disposition | Notes | +|-------|--------------|--------------------|-------| +| `RAILIANCE-WP-0005-T04` | App data backup/restore handoffs includes Gitea package blobs. | Split | App DB handoff stays S5; Gitea package blob durability moves to forge. | +| `RAILIANCE-WP-0005-T06` | Gitea package registry storage and retention posture. | Re-home | Should become forge-owned follow-up, likely under `FORGE-WP-*`. | +| `railiance-apps-WP-0004` I03 | PyPI issue-core blocker references Gitea package registry. | Adapt | Source/package publication remains source repo; forge owns registry endpoint and credentials posture. | +| `railiance-apps-WP-0002` registry references | Historical app deployment evidence. | Leave/adapt | Keep as app deployment history; cross-link to forge docs for current registry operation. | + +## First Safe Move Candidate + +The first migration should avoid live service changes and move documentation +before deployment configuration: + +1. Copy `docs/gitea-container-registry.md` and + `docs/gitea-package-registry.md` into `railiance-forge/docs/`. +2. Replace the originals in `railiance-apps` with short compatibility pointers. +3. Add a `railiance-forge/Makefile` with read-only/status targets first. +4. Move deploy-capable Gitea targets only after the operator path is reviewed. + +This gives operators a new canonical forge home while keeping current S5 app +runbooks discoverable. + +## Remote Creation Note + +Creating `coulomb/railiance-forge` on the current Gitea instance is blocked: +the configured `tea` login `coulomb` exists, but the stored token is invalid as +of 2026-06-05. The local repo is initialized and State Hub-registered, but +`origin` should not be added until the remote repository exists. diff --git a/docs/first-migration-plan.md b/docs/first-migration-plan.md new file mode 100644 index 0000000..e80ff6c --- /dev/null +++ b/docs/first-migration-plan.md @@ -0,0 +1,130 @@ +# First Migration Plan + +Date: 2026-06-05 + +This plan starts the extraction of forge ownership from `railiance-apps` into +`railiance-forge` without changing the live Gitea deployment. + +The rule for the first migration is simple: move knowledge and read-only +operator entry points before moving deploy-capable configuration. + +## Goals + +- Make `railiance-forge` the canonical place to look for forge and registry + operation. +- Keep `railiance-apps` usable for current S5 app operators during transition. +- Preserve all secret boundaries; do not decrypt or copy live secret values. +- Avoid any Helm release or Kubernetes apply during the first migration. +- Keep future Forgejo cutover separate from current Gitea ownership transfer. + +## Non-Goals + +- No live Gitea upgrade. +- No Forgejo deployment or cutover. +- No registry retention cleanup. +- No Actions runner deployment. +- No app release changes. +- No SOPS decryption. + +## Phase 1 - Documentation Canonicalization + +Move registry operation knowledge first. + +Steps: + +1. Copy `railiance-apps/docs/gitea-container-registry.md` to + `railiance-forge/docs/gitea-container-registry.md`. +2. Copy `railiance-apps/docs/gitea-package-registry.md` to + `railiance-forge/docs/gitea-package-registry.md`. +3. Replace the originals in `railiance-apps` with short compatibility pointers + to the new canonical files. +4. Update `railiance-apps/docs/vergabe-teilnahme.md` and other app docs to + refer to forge-owned registry docs. + +Validation: + +- `git diff --check` in both repos. +- No commands require Gitea credentials. +- No live cluster changes. + +## Phase 2 - Read-Only Operator Targets + +Add forge-side operator entry points that inspect current state before owning +deployment. + +Initial `railiance-forge/Makefile` targets: + +- `gitea-status`: current Gitea pod, service, ingress, and `gitea-db` consumer + status, copied/adapted from `railiance-apps`. +- `registry-docs`: print canonical docs to inspect. +- `check-tools`: minimal local tool check for `kubectl`, `helm`, `sops`, and + optional `tea`. + +Do not add `gitea-deploy` in this phase. + +Validation: + +- Targets are read-only. +- Targets either succeed or fail with clear missing-tool messages. +- `railiance-apps` still owns deploy-capable Gitea targets during the + transition. + +## Phase 3 - Deploy-Capable Target Review + +Move deploy-capable Gitea ownership only after Phase 1 and Phase 2 are reviewed. + +Candidate moves: + +- `helm/gitea-values.sops.yaml`; +- `helm/gitea-registry-values.yaml`; +- `manifests/gitea-ingress.yaml`; +- `make gitea-deploy`; +- `make gitea-ingress-deploy`. + +Review gates: + +- `railiance-forge` remote exists and is pushed. +- State Hub workplans are synced in both repos. +- Operator confirms the Gitea token/remote creation issue is fixed. +- `railiance-apps` has compatibility pointers for old paths. +- The plan distinguishes current Gitea operation from future Forgejo cutover. + +Validation: + +- `helm template` or dry-run equivalent can render from the new path without + decrypting secrets into Git. +- No decrypted SOPS material appears in diffs. +- Existing live service stays untouched until an explicit deploy command is run. + +## Phase 4 - S5 Scope Cleanup + +After deploy-capable assets move, update `railiance-apps`: + +- remove long-term Gitea ownership language from `SCOPE.md`; +- keep app release and app runbook ownership; +- keep app registry consumption references; +- update `RAILIANCE-WP-0005` to split Gitea package storage posture into + forge-owned work; +- keep app database and app backup handoffs in S5/platform coordination. + +Validation: + +- `railiance-apps` no longer claims forge runtime ownership. +- App operators can still find registry instructions through pointers. + +## Open Blocker + +The local `tea` login named `coulomb` is configured but currently fails with +`invalid username, password or token`. This blocks creation of the remote +`coulomb/railiance-forge` repository through the Gitea API. + +Until refreshed credentials are available: + +- keep `railiance-forge` local and State Hub-registered; +- do not add an `origin` remote that points to a missing repository; +- avoid claiming remote publication is complete. + +## Next Recommended Action + +Proceed with Phase 1 documentation canonicalization after the operator confirms +that compatibility pointers in `railiance-apps` are acceptable. diff --git a/workplans/FORGE-WP-0001-repository-foundation.md b/workplans/FORGE-WP-0001-repository-foundation.md new file mode 100644 index 0000000..8f9c046 --- /dev/null +++ b/workplans/FORGE-WP-0001-repository-foundation.md @@ -0,0 +1,131 @@ +--- +id: FORGE-WP-0001 +type: workplan +title: "railiance-forge repository foundation" +domain: railiance +repo: railiance-forge +status: active +owner: codex +topic_slug: railiance +planning_priority: high +created: "2026-06-05" +updated: "2026-06-05" +state_hub_workstream_id: "4280f3d2-3d4c-4caf-946b-521fb8fb1494" +--- + +# railiance-forge repository foundation + +## Context + +`railiance-forge` is being created after the Railiance intent review identified +forge responsibilities as the main cross-layer smell. The current Gitea and +registry surface is still in `railiance-apps`; this workplan establishes the new +repo as the owner for forge runtime and artifact infrastructure before any live +deployment files move. + +This workplan implements the opening tasks from +`railiance-apps/workplans/RAILIANCE-WP-0006-railiance-forge-extraction.md`. + +## T01 - Define repository contract + +```task +id: FORGE-WP-0001-T01 +status: done +priority: high +state_hub_task_id: "8ebc1457-f681-4cad-9ca9-119246b0063c" +``` + +Create the initial repository contract: + +- `INTENT.md`; +- `SCOPE.md`; +- `AGENTS.md`; +- `README.md`; +- repo-local workplan convention. + +Done when the repo purpose, boundaries, State Hub integration, and workplan +prefix are explicit. + +--- + +## T02 - Register with State Hub + +```task +id: FORGE-WP-0001-T02 +status: done +priority: high +state_hub_task_id: "cb2346cf-b4e5-47ad-a587-65d6e95e89c8" +``` + +Register the repo with State Hub and sync the first workplan. + +Steps: + +- register `railiance-forge` under domain `railiance`; +- register the local host path `/home/worsch/railiance-forge`; +- run `make fix-consistency REPO=railiance-forge`; +- verify State Hub created a workstream and task rows. + +Done when State Hub can index this repo independently. + +--- + +## T03 - Inventory current forge assets in `railiance-apps` + +```task +id: FORGE-WP-0001-T03 +status: done +priority: high +state_hub_task_id: "6957ebd3-321c-41e5-ad28-8d30b0bc1155" +``` + +Inventory all current Gitea, registry, package, and runner-related files and +operator commands in `railiance-apps`. + +Done when each candidate file has a target disposition: move, copy with +compatibility pointer, leave in S5, or supersede. + +--- + +## T04 - Draft first migration plan + +```task +id: FORGE-WP-0001-T04 +status: done +priority: high +state_hub_task_id: "6894dfb4-5641-45c1-8259-201801e6aede" +``` + +Draft the first migration plan for moving forge runtime ownership without +touching live service state. + +The plan must preserve: + +- secret boundaries; +- current Gitea deployment stability; +- operator discoverability during transition; +- future Forgejo cutover separation. + +Done when `railiance-apps` and `railiance-forge` can agree on the first safe +file move. + +--- + +## T05 - Define initial forge operating contracts + +```task +id: FORGE-WP-0001-T05 +status: todo +priority: medium +state_hub_task_id: "a5924b97-ccf7-4da0-acea-4f6017fef278" +``` + +Create first draft contracts for: + +- artifact retention and provenance; +- runner substrate ownership; +- backup and restore handoff with `railiance-platform`; +- secret custody boundaries; +- basic forge observability. + +Done when follow-on implementation work can be split into focused workplans.