diff --git a/history/2026-08-12-intent-scope-gap-analysis.md b/history/2026-08-12-intent-scope-gap-analysis.md new file mode 100644 index 0000000..1148825 --- /dev/null +++ b/history/2026-08-12-intent-scope-gap-analysis.md @@ -0,0 +1,156 @@ +# 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. diff --git a/workplans/RAILIANCE-WP-0016-architecture-cleanup-backlog.md b/workplans/RAILIANCE-WP-0016-architecture-cleanup-backlog.md new file mode 100644 index 0000000..ea61337 --- /dev/null +++ b/workplans/RAILIANCE-WP-0016-architecture-cleanup-backlog.md @@ -0,0 +1,160 @@ +--- +id: RAILIANCE-WP-0016 +type: workplan +title: "Architecture cleanup backlog, WSJF-prioritized" +domain: financials +repo: railiance-platform +status: active +owner: codex +topic_slug: railiance +created: "2026-08-12" +updated: "2026-08-12" +related_repos: + - railiance-master + - railiance-infra + - railiance-cluster + - railiance-enablement + - railiance-telemetry + - railiance-forge +--- + +# RAILIANCE-WP-0016 - Architecture cleanup backlog, WSJF-prioritized + +## Goal + +Turn the INTENT/SCOPE gap analysis into an ordered backlog, so cleanup happens +highest-value-least-effort first rather than in the order things were noticed. + +Source: `history/2026-08-12-intent-scope-gap-analysis.md`. + +## Boundary — read before working this + +This workplan **coordinates and orders**; it does not execute. Every item below +belongs to another repo, and each carries its owning repo in the table. S3 does +not own fleet architecture cleanup — `railiance-master` does. + +This backlog lives here because the analysis was done here. **It should be +adopted by `railiance-master`**, and this workplan closed, once master has a +place for it. Until then it is better recorded than lost. S3 executes only the +items marked `railiance-platform`. + +## Scoring method + +WSJF = **Cost of Delay ÷ Job Size**, where Cost of Delay = Value + Time +Criticality + Risk Reduction. Each component 1–10, job size 1–10. + +Two honesty notes. These are **judgments, not measurements** — their value is +the relative ordering and the explicit reasoning, not the arithmetic. And job +sizes for unbuilt things (telemetry, the conformance loop) are the least +reliable numbers here, because nobody has scoped them yet. + +## The backlog + +| # | Item | Owner | V | TC | RR | Size | **WSJF** | +| --- | --- | --- | --- | --- | --- | --- | --- | +| 1 | Converge the firewall allowlist; prune two stale grants | `railiance-infra` | 6 | 9 | 10 | 1 | **25.0** | +| 2 | Ratify the five pending decisions | `railiance-master` | 8 | 7 | 5 | 1 | **20.0** | +| 3 | Move the S1 goal off `railiance-hosts`, then retire it | `railiance-master` | 5 | 5 | 4 | 1 | **14.0** | +| 4 | Settle ArgoCD: adopt, retire, or relocate | `railiance-master` | 6 | 6 | 6 | 2 | **9.0** | +| 5 | Audit base role for further declared-vs-live drift | `railiance-infra` | 5 | 6 | 9 | 3 | **6.7** | +| 6 | `rapp.yaml` schema + family declaration validator | `railiance-master` | 8 | 5 | 7 | 3 | **6.7** | +| 7 | Reconcile hub capability attribution (C1) | `railiance-master` | 5 | 4 | 6 | 3 | **5.0** | +| 8 | Deployable coverage check: every deployable → one rapp | `railiance-master` | 7 | 4 | 7 | 4 | **4.5** | +| 9 | Telemetry MVP: metrics + alerting for one real expectation | `railiance-telemetry` | 9 | 6 | 8 | 5 | **4.6** | +| 10 | Conformance loop MVP: declared-vs-live firewall check | `railiance-telemetry` / Q7 owner | 8 | 6 | 9 | 5 | **4.6** | +| 11 | Consolidate the bootstrap path; sort inherited S2 content | `railiance-bootstrap` | 5 | 3 | 4 | 4 | **3.0** | +| 12 | Forge migration: `rapp-forgejo` + S4 layer transfer | `railiance-forge` / S4 | 6 | 4 | 4 | 5 | **2.8** | +| 13 | Prove a restore end to end | `railiance-platform` | 9 | 5 | 9 | 8 | **2.9** | +| 14 | Valkey extraction + legacy postgresql-ha retirement | `railiance-platform` | 5 | 4 | 4 | 5 | **2.6** | +| 15 | Sweep remaining Gitea prose (~31 files each) | `railiance-forge`, `railiance-apps` | 3 | 2 | 2 | 3 | **2.3** | +| 16 | Declare the Q6 cost boundary with `resource-control`/`fin-hub` | `railiance-master` | 4 | 3 | 3 | 4 | **2.5** | +| 17 | Version S3 consumer service interfaces | `railiance-platform` | 6 | 3 | 5 | 6 | **2.3** | +| 18 | Resolve the C4 ecosystem-modelling overlap | `railiance-master` / `railiance-fabric` | 4 | 3 | 4 | 5 | **2.2** | +| 19 | S4 build-out: pipeline templates, SDKs, portal | `railiance-enablement` | 7 | 3 | 4 | 9 | **1.6** | + +## Reading the order + +**Items 1–3 are nearly free and should happen first.** All three are "decided +but unmoved" — waiting on ratification or a single command, not on effort. +Item 1 in particular is a live security exposure: two standing firewall grants +point at addresses the ISP has since reassigned, and the fix is one convergence +run. + +**Item 2 is the highest-leverage thing on the list.** Five pending +ratifications in `railiance-master` block items 6, 7, 8, 12 and parts of 9 and +10. It is a day of decisions that unblocks a quarter of the backlog. + +**Items 9 and 10 are the strategic core** despite mid-table WSJF. They are Q2 +and Q7 — the two halves of the self-evidencing thread that five layers +independently asked for. Their size scores are guesses. Scoping them into +smaller slices would likely move both up sharply, and **that rescoping is itself +worth doing before committing to the order below them.** + +**Item 13 is blocked, not deprioritized.** Proving a restore needs the object +storage decision (`9c21c0e0`), which is escalated and awaiting human approval on +commercial terms. Its WSJF understates it; treat the blocker as the real item. + +**Item 19 is last and that is deliberate.** S4 build-out is the widest gap in +the family, but it is large, and item 12 gives S4 a smaller first +responsibility to prove delivery on. Building the portal before the forge +transfer would be starting at the hard end. + +## Tasks + +```task +id: RAILIANCE-WP-0016-T01 +status: done +priority: high +``` + +Produce the INTENT/SCOPE gap analysis across all `railiance-*` repos, comparing +declared aspiration against declared state against verified reality. + +Delivered: `history/2026-08-12-intent-scope-gap-analysis.md`. Named the pattern +that organizes the backlog — every gap is *declared but unbuilt*, *built but +undeclared*, or *decided but unmoved*, and the third kind is cheapest to clear +while blocking the most. + +```task +id: RAILIANCE-WP-0016-T02 +status: done +priority: high +``` + +Score and order the backlog by WSJF, recording owner and reasoning per item so +the ordering can be argued with rather than merely followed. + +```task +id: RAILIANCE-WP-0016-T03 +status: todo +priority: high +``` + +Route the backlog to `railiance-master` for adoption, with the recommendation +that it takes items 2, 3, 4, 6, 7, 8, 16 and 18 — the ratification and taxonomy +items — and that this workplan closes once adopted. + +```task +id: RAILIANCE-WP-0016-T04 +status: todo +priority: medium +``` + +Rescope items 9 and 10 (telemetry MVP, conformance loop MVP) into deliverable +slices before committing to their position. Their size scores are the least +reliable on the list, and both are strategically central. A first slice of item +10 could be as small as a Goss check comparing declared UFW state to live state +on one host. + +```task +id: RAILIANCE-WP-0016-T05 +status: todo +priority: medium +``` + +Execute the S3-owned items in WSJF order — 13 (blocked on `9c21c0e0`), 14, 17 — +and keep this table current as items complete or their sizes become known. + +## Outcome + +Pending. T01 and T02 delivered; the backlog is ordered and awaiting adoption.