railiance-platform/history/2026-08-12-intent-scope-gap-analysis.md

# INTENT vs SCOPE Gap Analysis — Railiance

Date: 2026-08-12
Method: for each `railiance-*` repo, compare **INTENT** (declared aspiration)
against **SCOPE** (declared current state) against **verified reality** (live
clusters, git, filesystem). A gap is where the three disagree.
Status: analysis. The prioritized backlog derived from it is
`workplans/RAILIANCE-WP-0016-architecture-cleanup-backlog.md`.

---

## Why this is possible now and was not before

Three things had to land first: the architecture had to be coherently defined
(the six-dimension model, 2026-08-11), the SCOPE files had to describe verified
rather than assumed reality (2026-08-12, after cluster access was restored), and
the INTENT files had to state current intent rather than copied intent.

Until then a "gap" could not be distinguished from a stale document.

---

## Per-repo gaps

### `railiance-infra` (S1)

| | |
| --- | --- |
| INTENT | "Declarative and Reproducible — no irreproducible, hand-tuned hosts"; "Hardened by Default"; "Verified Before Handoff" |
| SCOPE | baseline active on both hosts; proven in production |
| Reality | the single most important network control — the k3s API source restriction — was hand-applied and **absent from the declaration**; `2224/tcp` is open to Anywhere and declared nowhere |

**Gap:** the aspiration is "no hand-tuned hosts" and the security-critical parts
were exactly the hand-tuned parts. Partially closed (`RAIL-HO-WP-0009` T01);
**not yet converged**, so the live host still diverges from the declaration.

### `railiance-cluster` (S2)

| | |
| --- | --- |
| INTENT | "self-evidencing, auditable runtime state"; "continuous health verification" |
| SCOPE | two clusters managed; transition debt pending `rail-kubernetes` extraction |
| Reality | verified accurate as of 2026-08-12; no health verification runs continuously; nothing evidences runtime state |

**Gap:** aspiration is continuous verification; reality is manual inspection.
This is Q2/Q7, not an S2 defect — S2 cannot self-evidence without somewhere to
emit and something to check.

### `railiance-platform` (S3)

| | |
| --- | --- |
| INTENT | Q1 custody (implemented); "Operable and Observable"; "versioned service interfaces" |
| SCOPE | cnpg live, OpenBao live, Valkey + legacy postgresql-ha extraction in progress |
| Reality | Q1 genuinely mature. **Observable is false** — no monitoring exists. Service interfaces are not versioned |

**Gap:** the smallest of the layer repos, and mostly inherited: S3 cannot be
observable until Q2 exists. Own gaps are Valkey extraction, legacy
postgresql-ha retirement, and the un-versioned consumer interfaces.

### `railiance-enablement` (S4)

| | |
| --- | --- |
| INTENT | pipeline templates, SDKs, portal, promotion conventions, forge handoff — the richest Direction of Evolution in the family |
| SCOPE | emerging; now owns the forge layer responsibility |
| Reality | **25 commits, zero workplans**; owns one thing on paper and has built none of it |

**Gap:** the widest aspiration-to-reality gap in Railiance. Now non-trivial,
because the forge layer responsibility was assigned to a layer with no delivery
history.

### `railiance-apps` (S5)

| | |
| --- | --- |
| INTENT | reusable release checklist, promotion patterns, backup/restore handoffs with S3 |
| SCOPE | corrected 2026-08-12 (Forgejo, not Gitea) |
| Reality | apps deploy by Makefile; `core-hub` was pulling images from the frozen CoulombCore registry until 2026-08-12 |

**Gap:** the S3 backup/restore handoff is declared but not exercised — nobody
has restored an app's data end to end. That is Q3.

### `railiance-forge`

**Gap:** placement decided (`d151d817`), migration not started. Neither
`rapp-forgejo` nor the S4 layer transfer exists yet. ~31 files still carry Gitea
prose. Live work (`RAILIANCE-WP-0002`) continues in a repo scheduled to be split.

### `railiance-telemetry` (Q2)

**Gap:** total. INTENT and SCOPE are complete and accurate; the implementation
is zero and the cluster has **no monitoring namespace**. This is the purest
gap in the family — perfectly declared, entirely unbuilt.

### `railiance-bootstrap`

**Gap:** intent corrected 2026-08-11; inherited S2-era content in `ansible/`,
`helm/`, `docs/`, `wiki/` is unsorted. `QUICKSTART.md` exists in both this repo
and `railiance-cluster` and needs consolidating. Unknown whether the bootstrap
path has ever been walked end to end — which is precisely what its INTENT says
must be provable.

### `railiance-hosts`

**Gap:** superseded, bannered, **not retired**. Still holds a live State Hub
goal ("Secure Single-Server Bootstrap at HostEurope") that will keep resurfacing
as unstarted S1 work.

### `railiance-master`

**Gap:** owns the taxonomy and has **five ratifications pending** — telemetry
Q2, conformance-loop owner, hosts retirement, rapp schema, dimension model. It
is the bottleneck for the largest number of downstream items, and the work is
decision-making rather than building.

### `railiance-fabric`

**Gap:** quiet since 2026-07-30; non-standard `INTENT.md`; its concern
(Capability dimension) overlaps State Hub, `reuse-surface`, and `railiance-master`
without an explicit boundary statement (contradiction C4).

---

## Cross-cutting gaps

These belong to no single repo and are the reason per-repo cleanup alone will
not close the distance.

| Gap | Dimension | Note |
| --- | --- | --- |
| No observability | Q2 | zero monitoring namespaces, verified |
| No conformance loop | Q7 | why the firewall drift went undetected |
| No proven restore | Q3 | blocked on an **escalated, unmade** object-storage decision (`9c21c0e0`) |
| Cost boundary undeclared | Q6 | `resource-control`/`fin-hub` outside the family |
| Hub capability drift | Capability | ~11 capabilities misattributed to S3 (C1) |
| Ecosystem modelling split four ways | Capability | C4 |
| No rapp schema or validator | — | three rapps, three shapes |
| Deployable coverage unknown | — | ~17 live workloads, 3 rapps |

---

## The pattern worth naming

Almost every gap is one of three kinds:

1. **Declared but unbuilt** — telemetry, S4, conformance loop. Honest documents,
   absent implementation.
2. **Built but undeclared** — the firewall restriction, Q1 custody, the Plane
   dimension. Real work the documents did not know about.
3. **Decided but unmoved** — forge placement, hosts retirement, rapp schema.
   Waiting on ratification rather than effort.

Kind 3 is the cheapest to clear and blocks the most. Kind 2 is the most
dangerous, because it is invisible until something breaks — the firewall case
was found by accident, and nothing guarantees the next one will be.