e61de17b0d
Compares INTENT (declared aspiration) against SCOPE (declared state) against verified reality for every railiance-* repo. This was only possible now: a gap could not be distinguished from a stale document until the architecture was coherently defined, the SCOPE files described verified rather than assumed reality, and the INTENT files stated current rather than copied intent. Names the pattern that organizes the work: every gap is declared-but-unbuilt (telemetry, S4, conformance loop), built-but-undeclared (the firewall restriction, Q1 custody, the Plane dimension), or decided-but-unmoved (forge placement, hosts retirement, rapp schema). The third kind is cheapest to clear and blocks the most; the second is most dangerous, because it stays invisible until something breaks - the firewall case was found by accident. RAILIANCE-WP-0016 orders 19 items by WSJF with owner and reasoning per item. Top three are nearly free and all decided-but-unmoved. Item 1, converging the firewall allowlist, is a live exposure: two standing grants point at addresses the ISP has reassigned. Item 2, five pending ratifications in railiance-master, blocks a quarter of the backlog for a day of decisions. Flags honestly that the size scores for telemetry and the conformance loop are guesses, that item 13 is blocked rather than deprioritized, and that this backlog belongs to railiance-master rather than S3 - it lives here only because the analysis was done here. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
6.5 KiB
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:
- Declared but unbuilt — telemetry, S4, conformance loop. Honest documents, absent implementation.
- Built but undeclared — the firewall restriction, Q1 custody, the Plane dimension. Real work the documents did not know about.
- 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.