docs: correct CI/platform documentation that was stale or wrong #8

2026-09-29T07:16:03Z

gitea-admin commented

2026-09-29 07:16:03 +00:00

The 2026-09-29 session found the merge gate did not exist — no branch protection, no runner
— while the tree confidently asserted both. This corrects the documents that carried, and in
several cases caused, that belief.

The important one

CLAUDE.md gains §2b: never infer platform state from this repository. It carries the
specific API and kubectl checks for protection, runners, CI status, workloads and Flux
revisions, and the rule that a green tick is not proof anything ran (a skipped Gitea job
reports success). This is the rule whose absence produced every other finding in the session.

Stale plans read as statements of fact

.gitea/workflows/README.md and merge-gate.yaml both said "there is no remote git host,
this file is dormant." Gitea had been live for weeks. Both were written as plans and never
revisited once the plan completed. Transition is now marked COMPLETE, and says what genuinely
remains (CLUSTER_AVAILABLE unset → L2/L3 never runs in CI).
DECISIONS-LOG.md 2026-08-31 annotated in place. Reading chronologically, you previously
hit "required status check; runner incluster-dind online" with nothing marking it false
until a month later. The correction now sits on the bullet itself.
ci/README.md, clusters/README.md and both conformance READMEs get a status banner. They
speak as though no cluster exists, which makes a live L2/L3 coverage gap read as an expected
phase. That framing is why the gap went unexamined.

Doc/reality mismatches

gitea-actions-runner-secret.sops.yaml — wrong path; advice to sops -d into a terminal
(which CLAUDE.md forbids) replaced with the rotation script; records that a fresh token
alone does not re-register a runner holding a stale /data/.runner.
plex-claim-secret.sops.yaml — header claimed the file ships the placeholder. It hasn't since
the claim; it holds the spent token, inert and deliberately left.
catalog/plex.yaml + the plex secret — both asserted a "~4-minute TTL" as fact. Uncited,
upstream documents no expiry, and it was the basis for a since-disproven claim that the
pipeline was too slow to fit. Measured: ~2m45s.

Verification

Both .sops.yaml files confirmed to still decrypt after the comment edits
(sops -d > /dev/null — nothing printed), and render==golden confirms the catalog comment
does not propagate into the rendered manifest.

Gate: PASS, rc 0, 79s.

Co-Authored-By: Claude Opus 5 (1M context) [email protected]

🤖 Generated with Claude Code

The 2026-09-29 session found the merge gate did not exist — no branch protection, no runner — while the tree confidently asserted both. This corrects the documents that carried, and in several cases **caused**, that belief. ### The important one **`CLAUDE.md` gains §2b: *never infer platform state from this repository*.** It carries the specific API and `kubectl` checks for protection, runners, CI status, workloads and Flux revisions, and the rule that **a green tick is not proof anything ran** (a skipped Gitea job reports `success`). This is the rule whose absence produced every other finding in the session. ### Stale plans read as statements of fact - `.gitea/workflows/README.md` and `merge-gate.yaml` both said *"there is no remote git host, this file is dormant."* Gitea had been live for weeks. Both were written as plans and never revisited once the plan completed. Transition is now marked COMPLETE, and says what genuinely remains (`CLUSTER_AVAILABLE` unset → L2/L3 never runs in CI). - **`DECISIONS-LOG.md` 2026-08-31 annotated in place.** Reading chronologically, you previously hit *"required status check; runner incluster-dind online"* with nothing marking it false until a month later. The correction now sits on the bullet itself. - `ci/README.md`, `clusters/README.md` and both conformance READMEs get a status banner. They speak as though no cluster exists, which makes a **live L2/L3 coverage gap read as an expected phase**. That framing is why the gap went unexamined. ### Doc/reality mismatches - `gitea-actions-runner-secret.sops.yaml` — wrong path; advice to `sops -d` into a terminal (which `CLAUDE.md` forbids) replaced with the rotation script; records that a fresh token alone does **not** re-register a runner holding a stale `/data/.runner`. - `plex-claim-secret.sops.yaml` — header claimed the file ships the placeholder. It hasn't since the claim; it holds the spent token, inert and deliberately left. - `catalog/plex.yaml` + the plex secret — both asserted a **"~4-minute TTL" as fact**. Uncited, upstream documents no expiry, and it was the basis for a since-disproven claim that the pipeline was too slow to fit. Measured: **~2m45s**. ### Verification Both `.sops.yaml` files confirmed to **still decrypt** after the comment edits (`sops -d > /dev/null` — nothing printed), and `render==golden` confirms the catalog comment does not propagate into the rendered manifest. Gate: **PASS, rc 0, 79s**. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> 🤖 Generated with [Claude Code](https://claude.com/claude-code)

gitea-admin added 1 commit 2026-09-29 07:16:03 +00:00

docs: correct CI/platform documentation that was stale, wrong, or load-bearing

gate / gate (push) Successful in 1m37s

Details

gate / gate (pull_request) Successful in 1m36s

Details

gate / conformance (push) Has been skipped

Details

gate / conformance (pull_request) Has been skipped

Details

e72050c690

The 2026-09-29 session found the merge gate did not exist -- no branch protection, no
runner -- while the tree asserted both. This corrects the documents that carried, and in
several cases CAUSED, that belief.

CLAUDE.md gains section 2b: never infer platform state from this repository. It carries
the specific API and kubectl checks for protection, runners, CI status, workloads and
Flux revisions, and the rule that a green tick is not proof anything ran (a skipped Gitea
job reports success). This is the rule whose absence produced every other finding.

.gitea/workflows/README.md and merge-gate.yaml both said "there is no remote git host,
this file is dormant". Gitea had been live for weeks. Both were written as plans and never
revisited once the plan completed. The Transition section is now marked COMPLETE and says
what is genuinely still outstanding (CLUSTER_AVAILABLE unset, so L2/L3 never runs in CI).

DECISIONS-LOG 2026-08-31 is annotated IN PLACE. Anyone reading chronologically previously
hit "required status check; runner incluster-dind online" with nothing marking it false
until a month later. The correction now sits on the bullet itself.

ci/README.md, clusters/README.md and both conformance READMEs carry a status banner: they
speak as though no cluster exists, which makes a live L2/L3 coverage gap read as an
expected phase. That framing is why the gap went unexamined.

apps/wave-1/gitea-actions-runner-secret.sops.yaml: fixed a wrong path, replaced advice to
`sops -d` into a terminal (which CLAUDE.md forbids) with the rotation script, and recorded
that a fresh token alone does not re-register a runner holding a stale /data/.runner.

apps/wave-0/plex-claim-secret.sops.yaml: the header claimed the file ships the placeholder.
It has not since the claim -- it holds the spent token, which is inert and deliberately
left in place.

catalog/plex.yaml and the plex secret both asserted a "~4-minute TTL" as fact. It was
uncited, upstream documents no expiry, and it was the basis for a since-disproven claim
that the pipeline was too slow to fit inside it. Measured: ~2m45s.

Both .sops.yaml files were verified to still decrypt after the comment edits
(`sops -d > /dev/null`), and render==golden confirms the catalog comment does not
propagate into the rendered manifest.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

jakman85 merged commit ce271225de into main

2026-09-29 07:20:48 +00:00

jakman85 referenced this issue from a commit

2026-09-29 07:20:49 +00:00

Merge pull request 'docs: correct CI/platform documentation that was stale or wrong' (#8) from docs/ci-reality-vs-phase-0 into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Home-Network/home-network-k3s-impl#8