Gap analysis and WSJF-prioritized cleanup backlog
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>
This commit is contained in:
codex
parent
28f445fa89
commit
e61de17b0d
2 changed files with 316 additions and 0 deletions
156
history/2026-08-12-intent-scope-gap-analysis.md
Normal file
156
history/2026-08-12-intent-scope-gap-analysis.md
Normal file
|
|
@ -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.
|
||||
160
workplans/RAILIANCE-WP-0016-architecture-cleanup-backlog.md
Normal file
160
workplans/RAILIANCE-WP-0016-architecture-cleanup-backlog.md
Normal file
|
|
@ -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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue